Products Supply Laravel Package

Getting Started

Minimal Setup Steps

1. Install the Package

   composer require baks-dev/products-supply
   

2. Run Asset Installation

   php artisan baks:assets:install
   

   • Publishes config files, migrations, and any necessary assets to config/baks/ and database/migrations/.
3. Apply Database Migrations

   php artisan doctrine:migrations:diff
   php artisan doctrine:migrations:migrate
   

4. Verify Installation
   • Check the suppliers, products, and supply_logs tables in your database.
   • Test basic CRUD operations via Tinker:

     php artisan tinker
     

     $supplier = \Baks\Supply\Models\Supplier::create([...]);
     $product = \Baks\Supply\Models\Product::create([...]);
     $supply = \Baks\Supply\Models\Supply::create([...]);
     

First Use Case: Supplier Onboarding

1. Create a Supplier

   use Baks\Supply\Models\Supplier;
   
   $supplier = Supplier::create([
       'name' => 'Acme Corp',
       'contact_email' => 'contact@acme.com',
       'contract_start_date' => now(),
       'contract_end_date' => now()->addYear(),
       'risk_score' => 1, // 1-5 scale
   ]);
   

2. Link a Product to the Supplier

   use Baks\Supply\Models\Product;
   
   $product = Product::create([
       'name' => 'Widget Pro',
       'sku' => 'WIDGET-1000',
       'supplier_id' => $supplier->id,
   ]);
   

3. Record a Supply Entry

   use Baks\Supply\Models\Supply;
   
   $supply = Supply::create([
       'product_id' => $product->id,
       'supplier_id' => $supplier->id,
       'quantity' => 100,
       'unit_price' => 9.99,
       'supply_date' => now(),
       'warehouse_id' => 1, // Assuming you have a warehouses table
   ]);
   

4. Check Stock Levels

   $currentStock = Supply::where('product_id', $product->id)
       ->sum('quantity');
   

Key Configuration

• Publish Config

  php artisan vendor:publish --tag=baks-supply-config
  

  • Edit config/baks/supply.php to adjust:
    • Default warehouse IDs.
    • Low-stock thresholds.
    • Supplier risk scoring rules.

Implementation Patterns

Core Workflows

1. Supplier Management

• Onboarding Flow:

  // Create supplier with contract
  $supplier = Supplier::create([
      'name' => 'Supplier X',
      'contract' => [
          'start_date' => now(),
          'end_date' => now()->addYears(2),
          'terms' => 'Standard SLA',
      ],
  ]);
  
  // Attach documents (e.g., certificates)
  $supplier->documents()->create([
      'type' => 'certificate',
      'path' => 'storage/certificates/supplier_x.pdf',
      'expiry_date' => now()->addYear(),
  ]);
  

• Performance Tracking:

  // Log a delivery delay
  $supplier->performanceLogs()->create([
      'delay_hours' => 24,
      'reason' => 'Logistics strike',
      'resolved' => false,
  ]);
  
  // Auto-update risk score
  $supplier->updateRiskScore(); // Triggered by event listener
  

2. Inventory Supply Chain

• Multi-Warehouse Sync:

  // Record supply across warehouses
  $warehouses = [1, 2, 3]; // IDs
  foreach ($warehouses as $warehouseId) {
      Supply::create([
          'product_id' => $product->id,
          'warehouse_id' => $warehouseId,
          'quantity' => 50, // Distribute evenly
          'supply_date' => now(),
      ]);
  }
  
  // Sync stock levels (e.g., via queue job)
  Supply::syncStockLevels();
  

• Low-Stock Alerts:

  // Configure threshold in config/baks/supply.php
  'low_stock_threshold' => 10,
  
  // Trigger alert (via observer or event)
  event(new LowStockAlert($product, $currentStock));
  

3. Compliance and Auditing

• Certificate Expiry Tracking:

  // Check for expiring certificates
  $expiredCertificates = SupplierDocument::where('type', 'certificate')
      ->where('expiry_date', '<', now())
      ->with('supplier')
      ->get();
  
  // Notify admins (e.g., via Laravel Notifications)
  foreach ($expiredCertificates as $doc) {
      Notification::route('mail', $doc->supplier->contact_email)
                  ->notify(new CertificateExpiryNotification($doc));
  }
  

• Audit Logs:

  // Log supply chain events
  SupplyEvent::create([
      'supply_id' => $supply->id,
      'action' => 'received',
      'user_id' => auth()->id(),
      'metadata' => ['notes' => 'Partial shipment'],
  ]);
  

Integration Tips

Laravel Ecosystem

• Service Providers: Bind interfaces to package services in AppServiceProvider:

  public function register()
  {
      $this->app->bind(
          \Baks\Supply\Contracts\SupplyRepository::class,
          \Baks\Supply\Repositories\SupplyRepository::class
      );
  }
  

• Events: Listen for supply chain events in EventServiceProvider:

  protected $listen = [
      \Baks\Supply\Events\SupplyUpdated::class => [
          \App\Listeners\UpdateInventory::class,
          \App\Listeners\NotifyLowStock::class,
      ],
  ];
  

• Commands: Extend existing commands or create custom ones:

  php artisan make:command GenerateSupplyReport
  

  public function handle()
  {
      $report = \Baks\Supply\Services\SupplyReport::generate(
          $this->option('start-date'),
          $this->option('end-date')
      );
      // Export to CSV/PDF
  }
  

API Integration

• RESTful Endpoints: Use Laravel’s API resources to expose supply data:

  // routes/api.php
  Route::apiResource('suppliers', \Baks\Supply\Http\Controllers\SupplierController::class)
      ->middleware('auth:api');
  

• GraphQL: Integrate with Laravel GraphQL (e.g., nwidart/laravel-graphql) to query supplies:

  query {
      supplies(filter: { productId: 1 }) {
          id
          product { name }
          quantity
          supplyDate
      }
  }
  

Testing

• Unit Tests: Test repository/services in isolation:

  public function test_supply_creation()
  {
      $supply = Supply::factory()->create();
      $this->assertDatabaseHas('supplies', [
          'id' => $supply->id,
          'quantity' => 100,
      ]);
  }
  

• Feature Tests: Test HTTP endpoints and workflows:

  public function test_supplier_creation()
  {
      $response = $this->postJson('/api/suppliers', [
          'name' => 'Test Supplier',
          'contact_email' => 'test@example.com',
      ]);
  
      $response->assertCreated();
      $this->assertDatabaseHas('suppliers', [
          'name' => 'Test Supplier',
      ]);
  }
  

• Migration Tests: Test schema changes:

  public function test_migrations()
  {
      Artisan::call('migrate:fresh');
      $this->assertSchemaHasTable('suppliers');
      $this->assertSchemaHasColumn('suppliers', 'risk_score');
  }
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • Issue: The package’s migrations may conflict with existing ones (e.g., supplies table already exists).
   • Fix: Manually merge migrations or use a migration service like laravel-migrations-generator.
   • Tip: Run php artisan doctrine:migrations:diff before applying to preview changes.

2. Doctrine vs. Eloquent

   • Issue: The package uses Doctrine ORM, which may clash with Eloquent models if not abstracted.
   • Fix: Wrap Doctrine entities in a service layer:

     class SupplyService {
         public function __construct(private SupplyRepository $repository) {}
     
         public function get