Add generic postcode/address lookup with pluggable drivers

README.md

@@ -1,38 +1,117 @@
-# Rapidez :package_name_without_prefix
-<!--delete-->
-This repository can be used as template for a new Rapidez package.
+# Rapidez Postcode
 
-- Click on "Use this template" on the top of this Github repo page
-- Run `php ./configure.php`
+Generic postcode/address lookup for Rapidez, with pluggable drivers. Listens to the
+`postcode-change` Vue event already wired into Rapidez's own address form, so it works
+out of the box without needing to change any checkout/address form Blade templates.
 
-Credits to [`spatie/package-skeleton-laravel`](https://github.com/spatie/package-skeleton-laravel) for the inpiration for this template.
+Dutch (NL) addresses only for now; postcode validation and all three drivers' APIs are
+NL-specific.
 
-Keep in mind that if you contribute to this template; it should work for official and unofficial packages!
-- `rapidez/something`
-- `someone/rapidez-something`
-<!--/delete-->
-:package_description
+Ships with three drivers out of the box, each calling its own API directly - no Magento
+configuration required:
+
+- `postcodeeu` - [Postcode.eu](https://www.postcode.eu/)
+- `pro6pp` - [Pro6pp](https://pro6pp.nl/)
+- `postcodeservice` - [Postcodeservice](https://www.postcodeservice.com/)
+
+## Requirements
+
+- PHP ^8.2
+- `rapidez/core` ^5.0
 
 ## Installation
 
 ```
-composer require :vendor_slug/:package_slug
+composer require rapidez/postcode
 ```
 
 ## Configuration
 
-You can publish the config with:
+Publish the config with:
+```
+php artisan vendor:publish --tag=rapidez-postcode-config
+```
+
+This adds `config/rapidez/postcode.php`, which picks the active driver via `POSTCODE_DRIVER` and
+holds each driver's credentials. Pick one driver and fill in its `.env` values:
+
+```env
+POSTCODE_DRIVER=postcodeeu
+POSTCODE_EU_API_KEY=
+POSTCODE_EU_API_SECRET=
+```
+
+```env
+POSTCODE_DRIVER=pro6pp
+PRO6PP_API_KEY=
+```
+
+```env
+POSTCODE_DRIVER=postcodeservice
+POSTCODESERVICE_CLIENT_ID=
+POSTCODESERVICE_SECURE_CODE=
 ```
-php artisan vendor:publish --tag=rapidez-:package_slug_without_prefix-config
+
+Test credentials for `postcodeservice` are documented at
+[developers.postcodeservice.com](https://developers.postcodeservice.com/#authenticating-requests)
+if you want to try that driver without your own account; they're not hardcoded as a default here
+since the docs note they may change without prior notice.
+
+Switching drivers is purely a `.env`/config change; no code changes, and no changes to the
+route, controller or JavaScript.
+
+## Response shape
+
+The `/api/postcode` endpoint (and each driver's `lookup()` method) returns:
+
+```json
+{
+    "found": true,
+    "street": "Dam",
+    "city": "Amsterdam",
+    "province": "Noord-Holland",
+    "postcode": "1012JS",
+    "houseNumber": "1",
+    "houseNumberAddition": "",
+    "houseNumberAdditions": [""]
+}
 ```
 
-## Views
+`found` is `false` (with all other fields `null` or empty) for an invalid or non-existent
+postcode/house number combination.
+
+## Adding a driver
 
-You can publish the views with:
+A driver is a class implementing `Rapidez\Postcode\Contracts\PostcodeDriver`:
+
+```php
+class MyServiceDriver implements PostcodeDriver
+{
+    public function lookup(string $postcode, string $houseNumber, ?string $addition = null): PostcodeResult
+    {
+        // Call the external API and return a PostcodeResult.
+    }
+}
 ```
-php artisan vendor:publish --tag=rapidez-:package_slug_without_prefix-views
+
+Register it from your own project or package; no changes to this package needed; by extending
+the manager, e.g. in a service provider's `boot()` method:
+
+```php
+$this->app->make(\Rapidez\Postcode\PostcodeManager::class)->extend(
+    'myservice',
+    fn () => new MyServiceDriver(config('rapidez.postcode.drivers.myservice.key')),
+);
 ```
 
+Then select it as usual with `POSTCODE_DRIVER=myservice`. No changes to the route, controller or
+JavaScript are needed either way; they're entirely driver-agnostic.
+
+To contribute a new driver to this package itself instead, add a `create<Name>Driver()` method to
+`PostcodeManager` (the name maps to the `drivers.<name>` config key and the `POSTCODE_DRIVER`
+value, e.g. `createMyserviceDriver()` for `myservice`) and a matching `drivers.<name>` section to
+`config/rapidez/postcode.php`.
+
 ## License
 
 GNU General Public License v3. Please see [License File](LICENSE) for more information.

composer.json

@@ -1,17 +1,19 @@
 {
-    "name": ":vendor_slug/:package_slug",
-    "description": ":package_description",
+    "name": "rapidez/postcode",
+    "description": "Generic postcode/address lookup for Rapidez, with pluggable drivers for Postcode.eu, Pro6pp and Postcodeservice",
     "keywords": [
         "rapidez",
-        ":package_slug"
+        "postcode",
+        "address-lookup"
     ],
-    "homepage": "https://github.com/:vendor_slug/:package_slug",
+    "homepage": "https://github.com/rapidez/postcode",
     "license": "GPL-3.0-or-later",
     "authors": [
         {
-            "name": ":author_name",
-            "email": "author@domain.com",
-            "role": "Developer"
+            "name": "Claudio Ferraro",
+            "email": "claudio@justbetter.nl",
+            "homepage": "https://justbetter.nl",
+            "role": "Developer at JustBetter"
         }
     ],
     "minimum-stability": "dev",
@@ -22,7 +24,7 @@
     },
     "autoload": {
         "psr-4": {
-            "VendorName\\Skeleton\\": "src"
+            "Rapidez\\Postcode\\": "src"
         }
     },
     "config": {
@@ -34,12 +36,12 @@
     "extra": {
         "laravel": {
             "providers": [
-                "VendorName\\Skeleton\\SkeletonServiceProvider"
+                "Rapidez\\Postcode\\PostcodeServiceProvider"
             ]
         }
     },
     "require-dev": {
         "larastan/larastan": "^3.9",
-        "rapidez/coding-standards": "^1.0"
+        "rapidez/coding-standards": "^1.0.1"
     }
 }

config/rapidez/postcode.php

@@ -0,0 +1,22 @@
+<?php
+
+return [
+    'driver' => env('POSTCODE_DRIVER', 'postcodeeu'),
+
+    'drivers' => [
+        'postcodeeu' => [
+            'key' => env('POSTCODE_EU_API_KEY'),
+            'secret' => env('POSTCODE_EU_API_SECRET'),
+        ],
+
+        'pro6pp' => [
+            'key' => env('PRO6PP_API_KEY'),
+        ],
+
+        'postcodeservice' => [
+            // Test credentials are documented at https://developers.postcodeservice.com/#authenticating-requests
+            'client_id' => env('POSTCODESERVICE_CLIENT_ID'),
+            'secure_code' => env('POSTCODESERVICE_SECURE_CODE'),
+        ],
+    ],
+];