service = new PostcodeService(new ApiLogger); }); // --- Full postcode --- it('resolves a full postcode to coordinates', function (): void { Http::fake([ '*/postcodes/SW1A1AA' => Http::response([ 'status' => 200, 'result' => [ 'postcode' => 'SW1A 1AA', 'latitude' => 51.501009, 'longitude' => -0.141588, ], ]), ]); $result = $this->service->resolve('SW1A 1AA'); expect($result)->toBeInstanceOf(LocationResult::class) ->and($result->displayName)->toBe('SW1A 1AA') ->and($result->lat)->toBe(51.501009) ->and($result->lng)->toBe(-0.141588); }); it('normalises postcode spacing before lookup', function (): void { Http::fake([ '*/postcodes/SW1A1AA' => Http::response([ 'status' => 200, 'result' => [ 'postcode' => 'SW1A 1AA', 'latitude' => 51.501009, 'longitude' => -0.141588, ], ]), ]); $result = $this->service->resolve('sw1a1aa'); expect($result)->not->toBeNull() ->and($result->displayName)->toBe('SW1A 1AA'); }); // --- Outcode --- it('resolves an outcode to coordinates', function (): void { Http::fake([ '*/outcodes/PE7' => Http::response([ 'status' => 200, 'result' => [ 'outcode' => 'PE7', 'latitude' => 52.536397, 'longitude' => -0.210181, ], ]), ]); $result = $this->service->resolve('PE7'); expect($result)->toBeInstanceOf(LocationResult::class) ->and($result->displayName)->toBe('PE7') ->and($result->lat)->toBe(52.536397) ->and($result->lng)->toBe(-0.210181); }); it('resolves a lowercase outcode', function (): void { Http::fake([ '*/outcodes/M1' => Http::response([ 'status' => 200, 'result' => [ 'outcode' => 'M1', 'latitude' => 53.480957, 'longitude' => -2.237428, ], ]), ]); $result = $this->service->resolve('m1'); expect($result)->not->toBeNull() ->and($result->displayName)->toBe('M1'); }); // --- Place name --- it('resolves a city name to coordinates', function (): void { Http::fake([ '*/places*' => Http::response([ 'status' => 200, 'result' => [ [ 'name_1' => 'Manchester', 'latitude' => 53.480957, 'longitude' => -2.237428, ], ], ]), ]); $result = $this->service->resolve('Manchester'); expect($result)->toBeInstanceOf(LocationResult::class) ->and($result->displayName)->toBe('Manchester') ->and($result->lat)->toBe(53.480957) ->and($result->lng)->toBe(-2.237428); }); it('returns null when place name yields no results', function (): void { Http::fake([ '*/places*' => Http::response([ 'status' => 200, 'result' => [], ]), ]); $result = $this->service->resolve('Narnia'); expect($result)->toBeNull(); }); // --- Caching --- it('caches a successful place resolution for 30 days', function (): void { Http::fake([ '*/places*' => Http::response([ 'status' => 200, 'result' => [[ 'name_1' => 'Manchester', 'latitude' => 53.480957, 'longitude' => -2.237428, ]], ]), ]); $this->service->resolve('Manchester'); $this->service->resolve('Manchester'); Http::assertSentCount(1); expect(Cache::get('place:manchester'))->toBeInstanceOf(LocationResult::class); }); it('does not cache postcode resolutions in the Cache store (DB is the cache)', function (): void { Http::fake([ '*/postcodes/SW1A1AA' => Http::response([ 'status' => 200, 'result' => [ 'postcode' => 'SW1A 1AA', 'latitude' => 51.501009, 'longitude' => -0.141588, ], ]), ]); $this->service->resolve('SW1A 1AA'); expect(Cache::get('postcode:sw1a1aa'))->toBeNull() ->and(Postcode::find('SW1A1AA'))->not->toBeNull(); }); it('does not cache failed lookups', function (): void { Http::fake([ '*/postcodes/ZZ99ZZ' => Http::response(['status' => 404], 404), ]); $result = $this->service->resolve('ZZ9 9ZZ'); expect($result)->toBeNull() ->and(Cache::get('postcode:zz99zz'))->toBeNull(); }); it('returns null and does not throw on API failure', function (): void { Http::fake([ '*/outcodes/PE7' => Http::response([], 500), ]); $result = $this->service->resolve('PE7'); expect($result)->toBeNull(); }); // --- Local DB (full postcode) --- it('resolves a full postcode from local DB without calling HTTP', function (): void { Postcode::create([ 'postcode' => 'SW1A1AA', 'outcode' => 'SW1A', 'lat' => 51.501009, 'lng' => -0.141588, ]); Http::fake(); // any HTTP call will be recorded $result = $this->service->resolve('SW1A 1AA'); expect($result)->toBeInstanceOf(LocationResult::class) ->and($result->displayName)->toBe('SW1A 1AA') ->and($result->lat)->toBe(51.501009) ->and($result->lng)->toBe(-0.141588); Http::assertNothingSent(); }); // --- Local DB (outcode) --- it('resolves an outcode from local DB without calling HTTP', function (): void { Outcode::create([ 'outcode' => 'PE7', 'lat' => 52.536397, 'lng' => -0.210181, ]); Http::fake(); $result = $this->service->resolve('PE7'); expect($result)->toBeInstanceOf(LocationResult::class) ->and($result->displayName)->toBe('PE7') ->and($result->lat)->toBe(52.536397) ->and($result->lng)->toBe(-0.210181); Http::assertNothingSent(); }); // --- HTTP fallback persistence --- it('persists a full postcode resolved via HTTP fallback', function (): void { Http::fake([ '*/postcodes/SW1A1AA' => Http::response([ 'status' => 200, 'result' => [ 'postcode' => 'SW1A 1AA', 'latitude' => 51.501009, 'longitude' => -0.141588, ], ]), ]); $this->service->resolve('SW1A 1AA'); $row = Postcode::find('SW1A1AA'); expect($row)->not->toBeNull() ->and($row->outcode)->toBe('SW1A') ->and((float) $row->lat)->toBe(51.501009) ->and((float) $row->lng)->toBe(-0.141588); }); it('persists an outcode resolved via HTTP fallback', function (): void { Http::fake([ '*/outcodes/PE7' => Http::response([ 'status' => 200, 'result' => [ 'outcode' => 'PE7', 'latitude' => 52.536397, 'longitude' => -0.210181, ], ]), ]); $this->service->resolve('PE7'); $row = Outcode::find('PE7'); expect($row)->not->toBeNull() ->and((float) $row->lat)->toBe(52.536397) ->and((float) $row->lng)->toBe(-0.210181); }); // --- Reverse geocoding (area label) --- it('reverse-geocodes coordinates to the admin district', function (): void { Http::fake([ '*/postcodes?*' => Http::response([ 'status' => 200, 'result' => [ ['admin_district' => 'Peterborough', 'region' => 'East of England'], ], ]), ]); expect($this->service->reverseResolve(52.5364, -0.2102))->toBe('Peterborough'); }); it('falls back to a broader area when admin district is missing', function (): void { Http::fake([ '*/postcodes?*' => Http::response([ 'status' => 200, 'result' => [ ['admin_district' => null, 'region' => 'Scotland'], ], ]), ]); expect($this->service->reverseResolve(57.4, -4.2))->toBe('Scotland'); }); it('returns null when reverse geocoding finds no area', function (): void { Http::fake([ '*/postcodes?*' => Http::response(['status' => 200, 'result' => null]), ]); expect($this->service->reverseResolve(0.0, 0.0))->toBeNull(); }); it('returns null when the reverse geocode request fails', function (): void { Http::fake([ '*/postcodes?*' => Http::response([], 500), ]); expect($this->service->reverseResolve(52.5364, -0.2102))->toBeNull(); }); it('caches the reverse-geocoded area per bucket', function (): void { Http::fake([ '*/postcodes?*' => Http::response([ 'status' => 200, 'result' => [['admin_district' => 'Peterborough']], ]), ]); // Two coordinates inside the same ~1km (2dp) bucket → one HTTP call. $this->service->reverseResolve(52.5364, -0.2102); $this->service->reverseResolve(52.5359, -0.2148); Http::assertSentCount(1); }); it('queries postcodes.io with a wide radius so low-density buckets still match', function (): void { Http::fake([ '*/postcodes?*' => Http::response([ 'status' => 200, 'result' => [['admin_district' => 'Peterborough']], ]), ]); $this->service->reverseResolve(52.54, -0.25); // The default 100m radius misses the bucket centroid in rural areas; we send 2000m. Http::assertSent(fn ($request) => str_contains($request->url(), 'radius=2000')); });