Throw exceptions when something goes wrong instead of returning null

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,26 +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->latitude;
-    }
-
-    public function getLongitude(): float
-    {
-        return $this->longitude;
-    }
-}
-

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,11 +4,13 @@ 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 string API_URL = "https://nominatim.openstreetmap.org/search";
 
@@ -18,23 +20,23 @@ class Geocoder
      * Convert a postcode into latitude and longitude. Returns null if conversion failed.
      *
      * @param string $postcode
-     * @return null|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);
 
-        if (empty($data)) {
-            return null;
-        }
-
         if (array_key_exists('error', $data)) {
-            return null;
+            throw new ApiErrorException($postcode, $data['error']['message']);
         }
 
-        return $this->createLatLongModel($data);
+        if (empty($data)) {
+            throw new NoResultsFoundException($postcode, "No results found.");
+        }
+
+        return $this->createGeoCoordinates($data);
     }
 
     private function createClient(): HttpClientInterface
@@ -63,12 +65,12 @@ class Geocoder
         return $response->toArray(false);
     }
 
-    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
@@ -81,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,7 +6,9 @@ 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;
@@ -14,7 +16,7 @@ use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
 /**
  * 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 string POSTCODE = 'SW1A 1AA';
@@ -33,17 +35,38 @@ class GeocodeTest extends KernelTestCase
         $this->assertInstanceOf(Geocoder::class, $this->geocoder);
     }
 
-    public function testGeocodePostcodeReturnsNullOnInvalidInput(): void
+    public function testGeocodePostcodeThrowsOnEmptyInput(): void
     {
         sleep(1);
-        $this->assertNull($this->geocoder->geocodePostcode(''));
+        $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->expectException(NoResultsFoundException::class);
-        $this->assertInstanceOf(LatLongModel::class, $result);
+        $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

tests/Trait/MappableTraitTest.php

@@ -8,7 +8,7 @@ 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 COORD = 123.456;