Novaposhta Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require byhaskell/novaposhta-bundle
   

   Register the bundle in config/bundles.php (Symfony Flex handles this automatically).

2. Configuration Create config/packages/byhaskell_nova_poshta.yaml:

   byhaskell_nova_poshta:
       api_key: '%env(NP_API_KEY)%'
       base_url: 'https://api.novaposhta.ua/v2.0/json/'
   

   Add NP_API_KEY to .env (generate at Nova Poshta Developer Dashboard).

3. First Use Case Inject the NovaPoshta service into a controller/service:

   use byhaskell\NovaPoshtaBundle\NovaPoshta;
   
   public function getAddressList(NovaPoshta $novaPoshta) {
       $response = $novaPoshta->getAddressList();
       return json_encode($response);
   }
   

Implementation Patterns

Core Workflows

1. Address Operations

   • Fetch addresses:

     $addresses = $novaPoshta->getAddressList(['CityName' => 'Kyiv']);
     

   • Get address details:

     $address = $novaPoshta->getAddressDetails(['AddressID' => 12345]);
     

2. Delivery Services

   • List available services:

     $services = $novaPoshta->getDeliveryServices();
     

   • Check service availability:

     $availability = $novaPoshta->getServiceAvailability([
         'AddressFrom' => 12345,
         'AddressTo' => 67890,
         'ServiceTypeID' => 1
     ]);
     

3. Order Tracking

   • Track order:

     $track = $novaPoshta->getOrderTracking(['OrderNumber' => '123456789']);
     

Integration Tips

• Dependency Injection: Prefer constructor injection for NovaPoshta service.
• Error Handling: Wrap API calls in try-catch:

  try {
      $data = $novaPoshta->getSomething();
  } catch (\byhaskell\NovaPoshtaBundle\Exception\NovaPoshtaException $e) {
      // Log or handle error
  }
  

• Caching: Cache responses for static data (e.g., services, cities):

  $services = $novaPoshta->getDeliveryServices(['Cache' => true]);
  

• Async Processing: Use Symfony Messenger for long-running tasks (e.g., bulk address validation).

Common Use Cases

1. Checkout Flow

   • Validate delivery address during checkout.
   • Fetch available services for the selected address.
   • Calculate delivery cost dynamically.

2. Admin Dashboard

   • Display real-time tracking for orders.
   • Pre-populate address fields using Nova Poshta autocomplete.

3. Data Migration

   • Sync existing addresses with Nova Poshta’s database.

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never commit .env or expose NP_API_KEY in client-side code.
   • Use Symfony’s %env() syntax for sensitive data.

2. Rate Limiting

   • Nova Poshta enforces rate limits (~100 requests/minute). Implement exponential backoff for retries:

     use Symfony\Component\Stopwatch\Stopwatch;
     use Symfony\Component\Stopwatch\StopwatchEvent;
     
     $stopwatch = new Stopwatch();
     $event = $stopwatch->start('novaposhta_request');
     
     try {
         $response = $novaPoshta->getSomething();
     } catch (\byhaskell\NovaPoshtaBundle\Exception\RateLimitException $e) {
         $event->stop();
         $duration = $event->getDuration();
         sleep(max(1, $duration / 1000)); // Retry after delay
         retry();
     }
     

3. Deprecated Methods

   • Some methods may change with Nova Poshta API updates. Check the official API docs for breaking changes.

4. Character Encoding

   • Ukrainian addresses often use Cyrillic characters. Ensure your database and frontend support UTF-8.

Debugging

• Enable Debug Mode Set debug: true in config:

  byhaskell_nova_poshta:
      debug: true
  

  Logs raw API requests/responses to var/log/dev.log.

• Validate Parameters Use getMethodInfo() to inspect required parameters:

  $methodInfo = $novaPoshta->getMethodInfo('getAddressList');
  dd($methodInfo['parameters']); // Check expected params
  

Extension Points

1. Custom Responses Override response handling by extending the bundle’s NovaPoshta class:

   namespace App\Service;
   
   use byhaskell\NovaPoshtaBundle\NovaPoshta as BaseNovaPoshta;
   
   class CustomNovaPoshta extends BaseNovaPoshta {
       protected function processResponse($response) {
           // Custom logic (e.g., transform data)
           return parent::processResponse($response);
       }
   }
   

   Register the service in services.yaml:

   services:
       App\Service\CustomNovaPoshta: '@byhaskell_nova_poshta.nova_poshta'
   

2. Event Listeners Subscribe to novaposhta.response events to intercept responses:

   use Symfony\Component\EventDispatcher\GenericEvent;
   
   $dispatcher->addListener('novaposhta.response', function (GenericEvent $event) {
       $response = $event->getSubject();
       // Modify or log response
   });
   

3. Testing Mock the NovaPoshta service in tests:

   $this->container->set('byhaskell_nova_poshta.nova_poshta', $this->createMock(NovaPoshta::class));
   

Configuration Quirks

• Base URL: Override base_url for sandbox testing:

  base_url: 'https://sandbox.novaposhta.ua/v2.0/json/'
  

• Timeouts: Adjust HTTP client timeout in config/packages/http_client.yaml:

  framework:
      http_client:
          timeout: 30 # seconds