Postcodes per Laravel: ricerca di codici postali GB e dati geografici

Postcodes for Laravel è il client di Joshua Dovey per la GB Postcodes API. Restituisce oggetti tipizzati per la ricerca di codici postali, per la geografia e per le ricerche di prossimità, con una regola di validazione Laravel e un fake per i test. Se hai già usato il precedente wrapper Laravel per Postcodes.io, questo pacchetto si connette a un servizio di codici postali diverso e include dati sui confini e sulla popolazione.

Cercare codici postali e dati geografici

La facade restituisce un oggetto Postcode anziché un array. Questo esempio usa M16 0RA, il codice postale dello stadio Old Trafford del Manchester United. get() restituisce null per un codice postale che non viene risolto; getOrFail() lancia una NotFoundException.

use JoshDovey\Postcodes\Facades\Postcodes;

$postcode = Postcodes::get('M16 0RA');

$postcode?->latitude();
$postcode?->longitude();
$postcode?->geography->localAuthorityName;
$postcode?->geography->wardName;

L'oggetto geography include aree amministrative come i collegi parlamentari, gli integrated care board del NHS e le aree delle forze di polizia. Il pacchetto espone anche i dati del censimento e le stime di popolazione. Per i form, autocomplete() restituisce una collection Laravel di corrispondenze per un codice postale parziale, mentre search() risolve più codici postali in batch fino a 100 per ogni richiesta API.

Validare un codice postale rispetto al dataset

Le regole di validazione di Laravel possono usare ValidPostcode per verificare se un codice postale esiste, invece di controllarne soltanto il formato. unit() richiede un codice postale completo come M16 0RA.

use JoshDovey\Postcodes\Rules\ValidPostcode;

$request->validate([
'postcode' => ['required', ValidPostcode::unit()],
]);

I valori con una struttura non valida falliscono localmente, senza alcuna richiesta API. Per impostazione predefinita, un valore formalmente valido passa se il controllo API genera un errore. Per rifiutarlo invece, chiama (new ValidPostcode)->strict() oppure imposta postcodes.validation.strict su true nella configurazione pubblicata.

Ricerca per distanza o per confine

Per un'area di consegna o un bacino d'utenza, radius() trova i codici postali vicini a un determinato codice postale. within() accetta un poligono, un multipoligono o una feature GeoJSON. Puoi anche calcolare la distanza tra due codici postali, richiedere una matrice di distanze o eseguire il reverse geocoding delle coordinate.

$nearby = Postcodes::radius('M16 0RA', radius: 2, limit: 100);

foreach ($nearby as $result) {
echo $result->postcode.' '.$result->distance;
}

La distanza è espressa in chilometri per impostazione predefinita, con le miglia disponibili per singola chiamata o per il client. Le ricerche restituiscono la geometria dei confini per impostazione predefinita; withoutBoundaries() o una selezione fields riduce la risposta quando ti servono solo coordinate o nomi.

Installazione e test

Il pacchetto richiede PHP 8.2 o successivo e Laravel 12 o 13. Installalo con Composer, poi imposta la chiave API per la GB Postcodes API:

composer require joshdovey/postcodes

POSTCODES_API_KEY=your-key

Le risposte API andate a buon fine vengono messe in cache per un giorno per impostazione predefinita. Il client ritenta due volte, per impostazione predefinita, in caso di timeout, errori di connessione, limiti di frequenza temporanei ed errori del server. Non ritenta quando la quota del piano è esaurita.

Per i test, Postcodes::fake() sostituisce il client con risposte stub e registra le richieste:

use JoshDovey\Postcodes\Testing\Fixtures;

$fake = Postcodes::fake([
'v1/postcodes/validate*' => Fixtures::validation('M16 0RA'),
]);

$result = Postcodes::validate('M16 0RA');

$fake->assertSent('v1/postcodes/validate*');

Il repository Postcodes for Laravel contiene il riferimento completo dell'API, le opzioni di configurazione e gli esempi per i confini e il testing.