Delivery Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/delivery baks-dev/delivery-transport
   

   Ensure baks-dev/core (v7.4+) is installed as a dependency.

2. Asset & DB Setup

   php artisan baks:assets:install  # Publishes configs/views/assets
   php artisan migrate             # Runs migrations for delivery tables
   

3. First Use Case Create a basic order delivery:

   use Baks\Delivery\OrderDelivery;
   use Baks\Delivery\Transport\Transport;
   
   // Inject dependencies (via DI container)
   $orderDelivery = new OrderDelivery(
       transport: new Transport(),
       order: $yourOrderModel,
       user: auth()->user()
   );
   
   $result = $orderDelivery->create(); // Returns Delivery instance or throws exception
   

Key Entry Points

• Console Commands: baks:assets:install, baks:delivery:... (check vendor/baks-dev/delivery/src/Command/).
• Configuration: Published at config/delivery.php (modify after baks:assets:install).
• Entities: Core models in src/Entity/ (e.g., Delivery, DeliveryStatus).

Implementation Patterns

Core Workflows

1. Order Delivery Creation

   // Service layer pattern
   public function assignDelivery(Order $order, User $user)
   {
       $delivery = app(OrderDelivery::class)
           ->setOrder($order)
           ->setAssignedUser($user)
           ->setTransport($this->transportService->getAvailable())
           ->create();
   
       return $delivery;
   }
   

2. Status Transitions Use the DeliveryStatus enum (or service) to handle state changes:

   $delivery->updateStatus(DeliveryStatus::IN_TRANSIT);
   // Triggers events/hooks (see "Events" below)
   

3. Transport Integration

   // Fetch available transports
   $transports = app(TransportRepository::class)->getAvailable();
   
   // Assign to delivery
   $delivery->setTransport($transports->first());
   

Integration Tips

• Events: Listen for DeliveryCreated, StatusChanged, etc. (see src/Event/).

  event(new DeliveryCreated($delivery));
  

• API Layer: Use DeliveryResource (if included) or build custom DTOs:

  return new DeliveryResource($delivery);
  

• Validation: Extend DeliveryValidator for custom rules:

  use Baks\Delivery\Validator\DeliveryValidator;
  
  $validator = new DeliveryValidator();
  $validator->addRule('custom_rule', fn($value) => /* ... */);
  

Common Extensions

1. Custom Delivery Types

   // Extend base Delivery entity
   class CustomDelivery extends Delivery
   {
       public function getCustomField(): string
       {
           return $this->custom_field;
       }
   }
   

   Register in config/delivery.php:

   'delivery_types' => [
       'custom' => CustomDelivery::class,
   ],
   

2. Transport Providers Implement TransportProviderInterface:

   class MyTransportProvider implements TransportProviderInterface
   {
       public function getAvailable(): Collection
       {
           return Transport::query()->where('provider', 'my_provider')->get();
       }
   }
   

   Bind in service provider:

   $this->app->bind(TransportProviderInterface::class, MyTransportProvider::class);
   

Gotchas and Tips

Pitfalls

1. Missing delivery-transport

   • Error: Class 'Transport' not found.
   • Fix: Install baks-dev/delivery-transport as a dependency.

2. Database Schema Mismatch

   • Error: Column not found after migrations.
   • Fix: Run php artisan migrate:fresh or check CHANGELOG.md for breaking changes.

3. Event Listeners Not Triggered

   • Cause: Forgetting to register listeners in EventServiceProvider.
   • Fix:

     protected $listen = [
         DeliveryCreated::class => [
             DeliveryNotificationHandler::class,
         ],
     ];
     

4. Transport Assignment Logic

   • Gotcha: Hardcoding transport IDs bypasses availability checks.
   • Tip: Always use TransportRepository::getAvailable() or the service layer.

Debugging

• Log Delivery Events

  // In config/delivery.php
  'debug' => env('APP_DEBUG', false),
  

  Enables verbose logging for status transitions.

• Dump Delivery Data

  dd(app(DeliverySerializer::class)->serialize($delivery));
  

Configuration Quirks

1. Default Transport Provider Configure in config/delivery.php:

   'default_transport_provider' => 'baks_delivery.transport_provider.default',
   

   Override via service binding if needed.

2. Status Machine The package uses a state machine for DeliveryStatus. Custom transitions require:

   // In config/delivery.php
   'status_transitions' => [
       'pending' => ['can_cancel' => true],
       'in_transit' => ['can_return' => true],
   ],
   

Extension Points

1. Custom Fields Add to Delivery entity and update migrations:

   // src/Entity/Delivery.php
   #[ORM\Column(nullable: true)]
   private ?string $customField = null;
   

   Publish new migrations:

   php artisan baks:assets:install --force
   

2. Hooks for Business Logic Use the DeliveryEvents facade:

   DeliveryEvents::listen('before_create', function ($delivery) {
       // Add pre-create logic (e.g., validate stock)
   });
   

3. API Resources Extend DeliveryResource:

   class CustomDeliveryResource extends DeliveryResource
   {
       public function toArray($request)
       {
           return array_merge(parent::toArray($request), [
               'custom_field' => $this->resource->getCustomField(),
           ]);
       }
   }