Delivery Transport Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require baks-dev/delivery-transport
   

2. Publish assets and configure (Symfony-style console command):

   php artisan vendor:publish --provider="Baks\DeliveryTransport\DeliveryTransportServiceProvider"
   

   Note: Laravel’s vendor:publish may not work directly; use Symfony’s baks:assets:install via a custom Artisan command wrapper.

3. Run migrations (Doctrine format; convert to Laravel Eloquent migrations if needed):

   php artisan doctrine:migrations:migrate
   

   Alternative: Manually adapt Doctrine migrations to Laravel’s migrations/ directory.

4. First use case: Create a vehicle via Tinker or a controller:

   use Baks\DeliveryTransport\Entity\Vehicle;
   
   $vehicle = new Vehicle();
   $vehicle->setType('van');
   $vehicle->setCapacity(100); // kg or items
   $vehicle->setLicensePlate('ABC123');
   $vehicle->setStatus('active'); // 'active', 'maintenance', 'retired'
   
   // Save via Doctrine (requires bridge or custom repository)
   $entityManager->persist($vehicle);
   $entityManager->flush();
   

Implementation Patterns

Core Workflows

1. Vehicle Management

• CRUD Operations: Use Symfony’s EntityManager (wrap in a Laravel service):

  // services/VehicleService.php
  namespace App\Services;
  
  use Baks\DeliveryTransport\Entity\Vehicle;
  use Doctrine\ORM\EntityManagerInterface;
  
  class VehicleService {
      public function __construct(private EntityManagerInterface $em) {}
  
      public function createVehicle(array $data): Vehicle {
          $vehicle = new Vehicle();
          $vehicle->setType($data['type']);
          $vehicle->setCapacity($data['capacity']);
          // ... other fields
          $this->em->persist($vehicle);
          $this->em->flush();
          return $vehicle;
      }
  }
  

• Status Transitions: Leverage Symfony’s StateMachine (if available) or implement custom logic:

  $vehicle->changeStatusTo('maintenance'); // Hypothetical method
  

2. Order-Vehicle Assignment

• Linking Deliveries: Create a many-to-many relationship (Doctrine-style):

  // Assuming Order and Vehicle entities exist
  $order->addVehicle($vehicle);
  $vehicle->addOrder($order);
  $entityManager->flush();
  

• Capacity Checks: Validate before assignment (custom logic):

  if ($vehicle->getCapacity() >= $order->getWeight()) {
      $this->assignOrderToVehicle($order, $vehicle);
  }
  

3. Console Commands

• Wrap Symfony Commands for Laravel:

  // app/Console/Commands/InstallAssets.php
  namespace App\Console\Commands;
  
  use Illuminate\Console\Command;
  use Symfony\Component\Console\Application;
  
  class InstallAssets extends Command {
      protected $signature = 'baks:assets:install';
      protected $description = 'Install delivery transport assets';
  
      public function handle() {
          $symfonyApp = new Application();
          $symfonyApp->add(new \Baks\DeliveryTransport\Command\AssetsInstallCommand());
          $symfonyApp->run(new \Symfony\Component\Console\Input\ArrayInput([]));
      }
  }
  

4. Event Listeners

• Symfony Events → Laravel Events: Convert Symfony events to Laravel’s Event facade:

  // Example: Listen for vehicle status changes
  event(new VehicleStatusChanged($vehicle, 'maintenance'));
  

Integration Tips

Doctrine ↔ Eloquent Bridge

• Use fruitcake/laravel-doctrine to share entities:

  composer require fruitcake/laravel-doctrine
  

• Configure in config/doctrine.php:

  'orm' => [
      'entity_managers' => [
          'default' => [
              'mappings' => [
                  'BaksDeliveryTransport' => [
                      'type' => 'annotation',
                      'dir' => __DIR__.'/../vendor/baks-dev/delivery-transport/src/Entity',
                      'prefix' => 'Baks\DeliveryTransport\Entity',
                      'alias' => 'BaksDeliveryTransport',
                  ],
              ],
          ],
      ],
  ],
  

Hybrid Database Approach

• Option 1: Dual-write to both Doctrine and Eloquent tables.
• Option 2: Use Doctrine for transport module, Eloquent for core app.

Testing

• Extend PHPUnit tests for Laravel:

  // tests/Feature/DeliveryTransportTest.php
  namespace Tests\Feature;
  
  use Baks\DeliveryTransport\Entity\Vehicle;
  use Tests\TestCase;
  
  class DeliveryTransportTest extends TestCase {
      public function test_vehicle_creation() {
          $vehicle = new Vehicle();
          $vehicle->setType('van');
          $this->assertEquals('van', $vehicle->getType());
      }
  }
  

Gotchas and Tips

Pitfalls

1. Symfony-Laravel Conflicts:

   • Doctrine ORM: Laravel’s Eloquent and Symfony’s Doctrine may clash. Use a single ORM or isolate the transport module.
   • Console Commands: Symfony’s Application won’t work directly in Laravel. Wrap commands as shown above.
   • Service Container: Symfony’s DI container (ContainerInterface) differs from Laravel’s. Use abstract factories or manual binding.

2. Migration Issues:

   • Doctrine migrations won’t run in Laravel by default. Convert them to Eloquent migrations or use a hybrid setup.
   • Schema changes: Test in staging first—Doctrine’s schema tool may not play well with Laravel’s migrations.

3. Undocumented APIs:

   • Assume no public API. Internal methods (e.g., Vehicle::setStatus()) may change without notice.
   • Russian documentation: Prioritize code exploration over docs.

4. PHP 8.4 Features:

   • Named arguments or attributes may cause issues in older Laravel versions. Backport if needed.

5. No Frontend:

   • The package provides no UI. Plan for custom admin panels (e.g., Laravel Nova, Filament).

6. Abandonware Risk:

   • No updates since 2026. Fork immediately and monitor for breakages.

Debugging Tips

1. Doctrine Logging: Enable SQL logging in config/doctrine.php:

   'orm' => [
       'logging' => true,
       'logging_params' => true,
   ],
   

2. Symfony Command Debugging: Run Symfony commands directly for debugging:

   php vendor/bin/symfony console baks:assets:install --verbose
   

3. Entity Lifecycle: Use Doctrine’s lifecycle callbacks (e.g., prePersist) for validation:

   /** @ORM\PrePersist */
   public function prePersist() {
       if (empty($this->licensePlate)) {
           throw new \InvalidArgumentException('License plate required');
       }
   }
   

4. Hybrid ORM Debugging:

   • Log queries from both Eloquent and Doctrine to avoid N+1 queries.
   • Use DB::enableQueryLog() for Eloquent and Doctrine’s EventListener for SQL logging.

Extension Points

1. Custom Vehicle Types: Extend the Vehicle entity with traits or inheritance:

   namespace App\Entities;
   
   use Baks\DeliveryTransport\Entity\Vehicle;
   
   class ElectricVehicle extends Vehicle {
       private ?float $batteryCapacity;
   
       public function setBatteryCapacity(float $capacity): self {
           $this->batteryCapacity = $capacity;
           return $this;
       }
   }
   

2. Routing Integration: Add a routeOptimizer field to Vehicle and integrate with a routing API (e.g., GraphHopper):

   $vehicle->setRouteOptimizer('graphhopper');
   

3. IoT Support: Extend Vehicle with telemetry fields (e.g., lastGpsUpdate, fuelLevel) and sync with a device API.

4. API Endpoints: Create Laravel API resources for vehicles:

   // routes/api.php
   Route::apiResource('vehicles', \App\Http\Controllers\VehicleController::class);
   

5. Event-Driven Workflows: Dispatch Laravel events for vehicle status changes:

   event(new VehicleStatusUpdated($vehicle, 'maintenance'));
   

   Listen in a service provider:

   public function boot() {
       event(VehicleStatusUpdated::class, function ($event) {
           // Send notification, update UI, etc.
       });
   }
   

Configuration Quirks

1. Doctrine Configuration: Ensure config/doctrine.php