Throw exceptions when something goes wrong instead of returning null

Containerfile

@@ -1,4 +1,4 @@
-FROM php:8.1-alpine
+FROM php:8.3-alpine
 
 WORKDIR /code
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

LICENSE

@@ -1 +1,7 @@
-License
+Copyright (c) 2024 PCM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

composer.json

@@ -14,17 +14,17 @@
         }
     ],
     "require": {
-        "php": "^8.1.0",
-        "symfony/http-client": "^6.1",
-        "symfony/dependency-injection": "^6.1",
-        "symfony/framework-bundle": "^6.1",
-        "symfony/yaml": "^6.1",
+        "php": "^8.3.0",
+        "symfony/http-client": "^7.1",
+        "symfony/dependency-injection": "^7.1",
+        "symfony/framework-bundle": "^7.1",
+        "symfony/yaml": "^7.1",
         "doctrine/orm": "^2.13"
     },
 
     "require-dev": {
         "phpunit/phpunit": "^9.5",
-        "symfony/phpunit-bridge": "^6.1"
+        "symfony/phpunit-bridge": "^7.1"
     },
 
     "autoload": {

src/Exception/ApiErrorException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Exception;
+
+class ApiErrorException extends GeocodeException
+{
+}
+

src/Exception/GeocodeException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Exception;
+
+class GeocodeException extends \RuntimeException
+{
+    public function __construct(string $postcode, string $message)
+    {
+        $formattedMessage = sprintf("Failed to geocode a postcode \"%s\": %s", $postcode, $message);
+
+        parent::__construct($formattedMessage);
+    }
+}
+

src/Exception/NoResultsFoundException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Exception;
+
+class NoResultsFoundException extends GeocodeException
+{
+    private const string MESSAGE = "No results found.";
+
+    public function __construct(string $postcode)
+    {
+        parent::__construct($postcode, self::MESSAGE);
+    }
+}
+

src/Model/GeoCoordinates.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Model;
+
+/**
+ * A model for accessing latitude and longitude values.
+ *
+ * @package Pcm\GeocodeBundle
+ */
+final class GeoCoordinates
+{
+    public function __construct(readonly public float $latitude, readonly public float $longitude) {}
+}
+

src/Model/LatLongModel.php

@@ -1,25 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Pcm\GeocodeBundle\Model;
-
-/**
- * A model for accessing latitude and longitude values
- *
- * @package Pcm\GeocodeBundle
- */
-class LatLongModel
-{
-    public function __construct(private float $latitude, private float $longitude) {}
-
-    public function getLatitude(): float
-    {
-        return $this->getLatitude();
-    }
-
-    public function getLongitude(): float
-    {
-        return $this->getLongitude();
-    }
-}

src/PcmGeocodeBundle.php

@@ -10,7 +10,7 @@ use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigura
 use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
 
-class PcmGeocodeBundle extends AbstractBundle {
+final class PcmGeocodeBundle extends AbstractBundle {
     public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
     {
         $loader = new YamlFileLoader($builder, new FileLocator(__DIR__.'/../config/'));

src/Service/Geocoder.php

@@ -4,30 +4,39 @@ declare(strict_types=1);
 
 namespace Pcm\GeocodeBundle\Service;
 
-use Pcm\GeocodeBundle\Model\LatLongModel;
+use Pcm\GeocodeBundle\Exception\ApiErrorException;
+use Pcm\GeocodeBundle\Exception\NoResultsFoundException;
+use Pcm\GeocodeBundle\Model\GeoCoordinates;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
-class Geocoder
+final class Geocoder
 {
-    private const API_URL = "https://nominatim.openstreetmap.org/search";
+    private const string API_URL = "https://nominatim.openstreetmap.org/search";
 
     public function __construct(private HttpClientInterface $client) {}
 
     /**
-     * Convert a postcode into latitude and longitude
+     * Convert a postcode into latitude and longitude. Returns null if conversion failed.
      *
      * @param string $postcode
-     * @return LatLongModel
+     * @return null|GeoCoordinates
      */
-    public function geocodePostcode(string $postcode): LatLongModel
+    public function geocodePostcode(string $postcode): ?GeoCoordinates
     {
         $client = $this->createClient();
         $response = $this->makeApiRequest($client, $postcode);
         $data = $this->getDataFromResponse($response);
-        $this->throwIfDataIsEmpty($data);
 
-        return $this->createLatLongModel($data);
+        if (array_key_exists('error', $data)) {
+            throw new ApiErrorException($postcode, $data['error']['message']);
+        }
+
+        if (empty($data)) {
+            throw new NoResultsFoundException($postcode, "No results found.");
+        }
+
+        return $this->createGeoCoordinates($data);
     }
 
     private function createClient(): HttpClientInterface
@@ -56,18 +65,12 @@ class Geocoder
         return $response->toArray(false);
     }
 
-    private function throwIfDataIsEmpty(array $data): void
-    {
-        if (empty($data))
-            throw new \Exception("No data was received from API response! Were the arguments valid?");
-    }
-
-    private function createLatLongModel(array $data): LatLongModel
+    private function createGeoCoordinates(array $data): GeoCoordinates
     {
         $lat = $this->getLatitudeFromData($data);
         $long = $this->getLongitudeFromData($data);
 
-        return new LatLongModel($lat, $long);
+        return new GeoCoordinates($lat, $long);
     }
 
     private function getLatitudeFromData(array $data): float
@@ -80,3 +83,4 @@ class Geocoder
         return (float) $data[0]['lon'];
     }
 }
+

tests/AppKernel.php

@@ -9,7 +9,7 @@ use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
 use Symfony\Component\Config\Loader\LoaderInterface;
 use Symfony\Component\HttpKernel\Kernel;
 
-class AppKernel extends Kernel
+final class AppKernel extends Kernel
 {
     /**
      * @return array
@@ -30,3 +30,4 @@ class AppKernel extends Kernel
         $loader->load(__DIR__.'/config_'.$this->getEnvironment().'.yml');
     }
 }
+

tests/Service/GeocodeTest.php

@@ -6,18 +6,20 @@ namespace Pcm\GeocodeBundle\Tests;
 
 use Pcm\GeocodeBundle\Entity\Interface\MappableInterface;
 use Pcm\GeocodeBundle\Entity\Trait\MappableTrait;
-use Pcm\GeocodeBundle\Model\LatLongModel;
+use Pcm\GeocodeBundle\Exception\ApiErrorException;
+use Pcm\GeocodeBundle\Exception\NoResultsFoundException;
+use Pcm\GeocodeBundle\Model\GeoCoordinates;
 use Pcm\GeocodeBundle\Service\Geocoder;
 use Pcm\GeocodeBundle\Tests\AppKernel;
 use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
 
 /**
- * Note we sleep 1s after requests to prevent breaking the API T&Cs
+ * We sleep 1 second after API calls to prevent breaking the API T&Cs.
  */
-class GeocodeTest extends KernelTestCase
+final class GeocodeTest extends KernelTestCase
 {
     // Buckingham Palace
-    private const POSTCODE = 'SW1A 1AA';
+    private const string POSTCODE = 'SW1A 1AA';
 
     private Geocoder $geocoder;
 
@@ -33,18 +35,38 @@ class GeocodeTest extends KernelTestCase
         $this->assertInstanceOf(Geocoder::class, $this->geocoder);
     }
 
-    public function testGeocodePostcodeThrowsOnInvalidInput(): void
+    public function testGeocodePostcodeThrowsOnEmptyInput(): void
     {
         sleep(1);
-        $this->expectException(\Exception::class);
-        $this->geocoder->geocodePostcode('aaaaaaaa');
+        $this->expectException(ApiErrorException::class);
+        $this->expectExceptionMessageMatches("/Nothing to search for.$/");
+        $this->geocoder->geocodePostcode('');
     }
 
-    public function testGeocodePostcodeReturnsLatLonModel(): void
+    public function testGeocodePostcodeThrowsOnInvalidPostcode(): void
     {
         sleep(1);
-        $result = $this->geocoder->geocodePostcode(self::POSTCODE);
-        $this->assertInstanceOf(LatLongModel::class, $result);
+        $this->expectException(NoResultsFoundException::class);
+        $this->expectExceptionMessageMatches("/No results found.$/");
+        $this->geocoder->geocodePostcode('ZZZZZZZZZZZZ');
+    }
+
+    public function testGeocodePostcodeReturnsGeoCoordinates(): GeoCoordinates
+    {
+        sleep(1);
+        $geoCoords = $this->geocoder->geocodePostcode(self::POSTCODE);
+        $this->assertNotNull($geoCoords);
+
+        return $geoCoords;
+    }
+
+    /**
+     * @depends testGeocodePostcodeReturnsGeoCoordinates
+     */
+    public function testCoordinatesAreSet(GeoCoordinates $geoCoordinates): void
+    {
+        $this->assertIsFloat($geoCoordinates->latitude);
+        $this->assertIsFloat($geoCoordinates->longitude);
     }
 
     private function getMappableEntity(): MappableInterface
@@ -55,3 +77,4 @@ class GeocodeTest extends KernelTestCase
         };
     }
 }
+

tests/Trait/MappableTraitTest.php

@@ -8,9 +8,9 @@ use Pcm\GeocodeBundle\Entity\Interface\MappableInterface;
 use Pcm\GeocodeBundle\Entity\Trait\MappableTrait;
 use PHPUnit\Framework\TestCase;
 
-class MappableTraitTest extends TestCase
+final class MappableTraitTest extends TestCase
 {
-    private const FLOAT = 123.456;
+    private const float COORD = 123.456;
 
     private MappableInterface $obj;
 
@@ -21,7 +21,7 @@ class MappableTraitTest extends TestCase
 
     public function testSetLatitude(): void
     {
-        $this->assertInstanceOf(MappableInterface::class, $this->obj->setLatitude(self::FLOAT));
+        $this->assertInstanceOf(MappableInterface::class, $this->obj->setLatitude(self::COORD));
     }
 
     public function testGetLatitudeReturnsNull(): void
@@ -31,13 +31,13 @@ class MappableTraitTest extends TestCase
 
     public function testGetLatitude(): void
     {
-        $this->obj->setLatitude(self::FLOAT);
-        $this->assertSame(self::FLOAT, $this->obj->getLatitude());
+        $this->obj->setLatitude(self::COORD);
+        $this->assertSame(self::COORD, $this->obj->getLatitude());
     }
 
     public function testSetLongitude(): void
     {
-        $this->assertInstanceOf(MappableInterface::class, $this->obj->setLongitude(self::FLOAT));
+        $this->assertInstanceOf(MappableInterface::class, $this->obj->setLongitude(self::COORD));
     }
 
     public function testGetLongitudeReturnsNull(): void
@@ -47,8 +47,8 @@ class MappableTraitTest extends TestCase
 
     public function testGetLongitude(): void
     {
-        $this->obj->setLongitude(self::FLOAT);
-        $this->assertSame(self::FLOAT, $this->obj->getLongitude());
+        $this->obj->setLongitude(self::COORD);
+        $this->assertSame(self::COORD, $this->obj->getLongitude());
     }
 
     public function testIsGeocodedReturnsFalse(): void
@@ -58,20 +58,20 @@ class MappableTraitTest extends TestCase
 
     public function testIsGeocodedReturnsFalseIfLatIsSet(): void
     {
-        $this->obj->setLatitude(self::FLOAT);
+        $this->obj->setLatitude(self::COORD);
         $this->assertFalse($this->obj->isGeocoded());
     }
 
     public function testIsGeocodedReturnsFalseIfLonIsSet(): void
     {
-        $this->obj->setLongitude(self::FLOAT);
+        $this->obj->setLongitude(self::COORD);
         $this->assertFalse($this->obj->isGeocoded());
     }
 
     public function testIsGeocodedReturnsTrueIfLatAndLonAreSet(): void
     {
-        $this->obj->setLatitude(self::FLOAT);
-        $this->obj->setLongitude(self::FLOAT);
+        $this->obj->setLatitude(self::COORD);
+        $this->obj->setLongitude(self::COORD);
         $this->assertTrue($this->obj->isGeocoded());
     }
 
@@ -89,5 +89,5 @@ class MappableTraitTest extends TestCase
             use MappableTrait;
         };
     }
-
 }
+