maeandrew / novaposhta-address-resolver-laravel

v0.4.1 2026-09-09 22:45 UTC

Requires

• php: ^8.2
• illuminate/cache: ^11.0 || ^12.0 || ^13.0
• illuminate/console: ^11.0 || ^12.0 || ^13.0
• illuminate/contracts: ^11.0 || ^12.0 || ^13.0
• illuminate/queue: ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^11.0 || ^12.0 || ^13.0
• maeandrew/novaposhta-address-resolver: ^0.2 || ^0.3 || ^0.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• orchestra/testbench: ^9.17 || ^10.11 || ^11.2
• phpstan/phpstan: ^1.12
• phpunit/phpunit: ^10.5 || ^11.3 || ^12.0 || ^13.0

MIT

Published on Packagist.org on 2026-09-09 22:45 UTC

README

English · Українська

This package is an optional Laravel integration. The framework-free resolver core remains a separate dependency and does not import Laravel classes.

Install

composer require maeandrew/novaposhta-address-resolver-laravel

The package supports Laravel 11, 12, and 13 on PHP 8.2+. Laravel package discovery registers the service provider automatically. In this standalone repository, composer install resolves the core dependency from Packagist.

When developing the package inside the parent monorepo, run ddev exec bash scripts/install-laravel.sh from the monorepo root. That helper belongs to the parent repository and is not included in this package.

Configure a provider

Bind a provider in the host application's service provider:

use MaeAndrew\NovaPoshtaAddressResolver\Contracts\LocationProvider;

$this->app->bind(LocationProvider::class, fn ($app) => new MyLocationProvider(
    // host-owned SDK or HTTP client
));

Publish the optional configuration:

php artisan vendor:publish --tag=novaposhta-address-resolver-config

The default custom driver resolves LocationProvider::class from the container. Applications can configure parser, matching strategy, policy, and AI interpreter class names in the published file.

Use the service

use MaeAndrew\NovaPoshtaAddressResolver\DTO\AddressInput;
use MaeAndrew\NovaPoshtaAddressResolver\Laravel\AddressResolutionService;

$result = app(AddressResolutionService::class)->resolve(
    AddressInput::fromText($message),
);

Caching is disabled by default. Enable it only after choosing an appropriate store and TTL for the host application. Cache keys contain a hash of the input; raw messages are not used as cache keys. By default only resolved and ambiguous results are cached. Transient not_found and invalid_input results are resolved again on the next request; the cache.statuses option can be changed when the host has a different freshness policy.

AddressResolved and AddressNeedsReview events are dispatched for fresh resolutions when events are enabled. Cached results do not dispatch duplicate events.

Queue and Artisan

use MaeAndrew\NovaPoshtaAddressResolver\Laravel\Jobs\ResolveAddressJob;

ResolveAddressJob::dispatch(AddressInput::fromText($message));

Resolve an address without persisting a host model:

php artisan novaposhta:resolve "Київ, відділення №285" --json --dry-run

The bridge never assumes an Order model or database columns. To persist a resolved result, use an explicit host-owned mapper and keep the review state when the result is ambiguous:

use MaeAndrew\NovaPoshtaAddressResolver\DTO\AddressInput;
use MaeAndrew\NovaPoshtaAddressResolver\DTO\ResolutionResult;

$result = app(AddressResolutionService::class)->resolveAndMap(
    AddressInput::fromText($message),
    function (AddressInput $input, ResolutionResult $result) use ($order): void {
        $order->forceFill([
            'settlement_ref' => $result->settlement?->ref,
            'warehouse_ref' => $result->warehouse?->ref,
        ])->save();
    },
);

The callback runs only for a resolved result. The host application decides how to store ambiguous candidates and diagnostics.