Add changelog

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [1.0.0] 2024-08-05
+- First major version release
+

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.

README.md

@@ -1 +1,6 @@
-Readme
+# PCM Geocode Bundle
+
+Provides an interface/trait combo to add latitude and longitude fields to an entity.
+
+Also included is a `Geocoder` service which accepts a postcode and attempts to return a `GeoCoordinates` object which contains the latitude and longitude of the postcode.
+

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/Interface/Entity/GeocodeInterface.php

@@ -2,9 +2,12 @@
 
 declare(strict_types=1);
 
-namespace Pcm\GeocodeBundle\Entity\Interface;
+namespace Pcm\GeocodeBundle\Interface\Entity;
 
-interface MappableInterface
+/**
+ * Defines latitude and longitude getters and setters
+ */
+interface GeocodeInterface
 {
     public function getLatitude(): ?float;
 
@@ -14,5 +17,9 @@ interface MappableInterface
 
     public function setLongitude(float $lon): self;
 
+    /**
+     * @return bool True if both latitude and longitude is set
+     */
     public function isGeocoded(): bool;
 }
+

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->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,33 +4,46 @@ 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
+/**
+ * Find the geo-coordinates of a postcode
+ */
+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. Returns null if conversion failed.
+     * Find and return the geo-coordinates of a postcode
      *
      * @param string $postcode
-     * @return null|LatLongModel
+     *
+     * @return GeoCoordinates
+     *
+     * @throws NoResultsFoundException when no results were found for the provided postcode
+     * @throws ApiErrorException when the API response contains an error
      */
-    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)) {
+            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
@@ -59,12 +72,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
@@ -77,3 +90,4 @@ class Geocoder
         return (float) $data[0]['lon'];
     }
 }
+

src/Trait/Entity/GeocodeTrait.php

@@ -2,18 +2,16 @@
 
 declare(strict_types=1);
 
-namespace Pcm\GeocodeBundle\Entity\Trait;
+namespace Pcm\GeocodeBundle\Trait\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
 
 /**
- * Allows an entity to be mapped via latitude and longitude coordinates
- *
- * Use MappableInterface
+ * Implementation of {@see Pcm\GeocodeBundle\Interface\Entity\GeocodeInterface}
  *
  * @package Pcm\GeocodeBundle
  */
-trait MappableTrait
+trait GeocodeTrait
 {
     #[ORM\Column(type: 'decimal', precision: 10, scale: 6, nullable: true)]
     private ?float $latitude = null;
@@ -45,13 +43,9 @@ trait MappableTrait
         return $this;
     }
 
-    /**
-     * Returns true if both latitude and longitude have been set
-     *
-     * @return bool
-     */
     public function isGeocoded(): bool
     {
         return null !== $this->getLatitude() && null !== $this->getLongitude();
     }
 }
+

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

@@ -4,20 +4,22 @@ declare(strict_types=1);
 
 namespace Pcm\GeocodeBundle\Tests;
 
-use Pcm\GeocodeBundle\Entity\Interface\MappableInterface;
-use Pcm\GeocodeBundle\Entity\Trait\MappableTrait;
-use Pcm\GeocodeBundle\Model\LatLongModel;
+use Pcm\GeocodeBundle\Interface\Entity\GeocodeInterface;
+use Pcm\GeocodeBundle\Trait\Entity\GeocodeTrait;
+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,24 +35,46 @@ 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->assertInstanceOf(LatLongModel::class, $result);
+        $this->expectException(NoResultsFoundException::class);
+        $this->expectExceptionMessageMatches("/No results found.$/");
+        $this->geocoder->geocodePostcode('ZZZZZZZZZZZZ');
     }
 
-    private function getMappableEntity(): MappableInterface
+    public function testGeocodePostcodeReturnsGeoCoordinates(): GeoCoordinates
     {
-        return new class implements MappableInterface
+        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 getGeocodableEntity(): GeocodeInterface
+    {
+        return new class implements GeocodeInterface
         {
-            use MappableTrait;
+            use GeocodeTrait;
         };
     }
 }
+

tests/Trait/GeocodeTraitTest.php

@@ -4,15 +4,15 @@ declare(strict_types=1);
 
 namespace Pcm\GeocodeBundle\Tests;
 
-use Pcm\GeocodeBundle\Entity\Interface\MappableInterface;
-use Pcm\GeocodeBundle\Entity\Trait\MappableTrait;
+use Pcm\GeocodeBundle\Interface\Entity\GeocodeInterface;
+use Pcm\GeocodeBundle\Trait\Entity\GeocodeTrait;
 use PHPUnit\Framework\TestCase;
 
-class MappableTraitTest extends TestCase
+final class GeocodeTraitTest extends TestCase
 {
-    private const FLOAT = 123.456;
+    private const float COORD = 123.456;
 
-    private MappableInterface $obj;
+    private GeocodeInterface $obj;
 
     protected function setUp(): void
     {
@@ -21,7 +21,7 @@ class MappableTraitTest extends TestCase
 
     public function testSetLatitude(): void
     {
-        $this->assertInstanceOf(MappableInterface::class, $this->obj->setLatitude(self::FLOAT));
+        $this->assertInstanceOf(GeocodeInterface::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(GeocodeInterface::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());
     }
 
@@ -82,12 +82,12 @@ class MappableTraitTest extends TestCase
         $this->assertTrue($this->obj->isGeocoded());
     }
 
-    private function getTraitObject(): MappableInterface
+    private function getTraitObject(): GeocodeInterface
     {
-        return new class implements MappableInterface
+        return new class implements GeocodeInterface
         {
-            use MappableTrait;
+            use GeocodeTrait;
         };
     }
-
 }
+