Manufacture Part Laravel Package

Getting Started

Minimal Steps for Laravel Integration

1. Prerequisites:

   • Upgrade to PHP 8.4+ and Laravel 9.x+ (or Symfony 7.x+).
   • Install required dependencies:

     composer require baks-dev/manufacture-part baks-dev/users-table baks-dev/core
     

   • Publish package assets and configure:

     php artisan vendor:publish --provider="BaksDev\ManufacturePart\ManufacturePartServiceProvider"
     

2. Database Setup:

   • Run migrations (adapt for Laravel if needed):

     php artisan migrate
     

   • For Doctrine ORM (if using hybrid approach):

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

3. First Use Case:

   • Create a Batch: Use the package’s CLI or inject the BatchManager service:

     use BaksDev\ManufacturePart\Service\BatchManager;
     
     $batchManager = app(BatchManager::class);
     $batch = $batchManager->create([
         'product_id' => 1,
         'quantity' => 100,
         'serial_prefix' => 'PROD-2024',
     ]);
     

   • Generate Serial Numbers:

     $serials = $batchManager->generateSerials($batch->id, 100);
     

4. Key Configuration:

   • Update .env for batch settings (e.g., MANUFACTURE_PART_SERIAL_FORMAT).
   • Configure user permissions via baks-dev/users-table (if using its auth system).

Implementation Patterns

Core Workflows

1. Batch Creation & Management:

   • Service-Based: Use BatchManager for CRUD operations.

     // Create with custom attributes
     $batch = $batchManager->create([
         'product_id' => 1,
         'expiry_date' => now()->addYear(),
         'notes' => 'Premium batch',
     ]);
     

   • Validation: Extend BatchValidator for custom rules:

     use BaksDev\ManufacturePart\Validator\BatchValidator;
     
     class CustomBatchValidator extends BatchValidator {
         protected function rules(): array {
             return array_merge(parent::rules(), [
                 'custom_field' => 'required|string',
             ]);
         }
     }
     

2. Serial Number Handling:

   • Bulk Generation:

     $batchManager->generateSerials($batchId, 50, 'SERIAL-{YYYYMMDD}-{INCREMENT}');
     

   • Validation:

     if ($batchManager->isValidSerial($batchId, 'INVALID-123')) {
         // Handle invalid serial
     }
     

3. CLI Integration:

   • Symfony Commands: Replace with Laravel Artisan commands:

     // Example: Convert Symfony command to Artisan
     php artisan manufacture:create --product=1 --quantity=100
     

   • Custom Commands:

     php artisan make:command ManufactureBatchReport
     

     // In command handler
     $this->call('manufacture:list', ['--batch-id' => $batchId]);
     

4. Event-Driven Extensions:

   • Listen to batch events (e.g., BatchCreated):

     use BaksDev\ManufacturePart\Event\BatchCreated;
     
     event(new BatchCreated($batch));
     

   • Dispatch custom events:

     event(new CustomBatchEvent($batch));
     

Integration Tips

• Laravel Auth Integration:
  • Override baks-dev/users-table permissions with Laravel’s Gate or Policy:

    Gate::define('manage-batches', function (User $user) {
        return $user->hasRole('admin');
    });
    

• Doctrine vs. Eloquent:
  • Use laravel-doctrine/orm for hybrid ORM or translate models:

    // Example: Convert Doctrine entity to Eloquent
    class Batch extends Model {
        protected $connection = 'doctrine';
    }
    

• API Layer:
  • Expose batch endpoints via Laravel’s Route::apiResource:

    Route::apiResource('batches', BatchController::class)
         ->middleware('auth:sanctum');
    

Gotchas and Tips

Pitfalls

1. Symfony Dependency Hell:

   • Issue: Hard dependency on baks-dev/core may conflict with Laravel’s service container.
   • Fix: Use Symfony\Component\DependencyInjection\ContainerInterface adapter:

     $container = new ContainerBuilder();
     $container->register('batch.manager', BatchManager::class);
     

2. Migration Conflicts:

   • Issue: Doctrine migrations may clash with Laravel’s schema builder.
   • Fix: Run migrations in a separate service or use raw SQL:

     Schema::connection('doctrine')->raw('ALTER TABLE batches ADD COLUMN custom_field VARCHAR(255)');
     

3. CLI Tooling Gaps:

   • Issue: Symfony’s bin/console won’t work in Laravel.
   • Fix: Create Artisan wrappers:

     php artisan manufacture:create --help
     

     // In ArtisanCommand
     protected $signature = 'manufacture:create {product} {quantity}';
     

4. Serialization Format Collisions:

   • Issue: Custom serial formats may conflict with existing data.
   • Fix: Validate formats before bulk generation:

     $batchManager->validateSerialFormat('PROD-{INCREMENT}', 1000);
     

Debugging

1. Doctrine Debugging:

   • Enable SQL logging:

     $doctrineConfig->setSQLLogger(new \Doctrine\DBAL\Logging\EchoSQLLogger());
     

   • Use dd() with Doctrine entities:

     dd($batch->getSerials()->toArray());
     

2. Event Listener Issues:

   • Symptom: Events not firing.
   • Fix: Register listeners in EventServiceProvider:

     protected $listen = [
         BatchCreated::class => [
             BatchCreatedListener::class,
         ],
     ];
     

3. Permission Denied:

   • Symptom: 403 Forbidden on batch operations.
   • Fix: Ensure baks-dev/users-table roles are synced with Laravel’s auth:

     if (!auth()->user()->can('manage-batches')) {
         abort(403);
     }
     

Extension Points

1. Custom Batch Attributes:

   • Extend the Batch entity:

     namespace App\Entity;
     
     use BaksDev\ManufacturePart\Entity\Batch as BaseBatch;
     
     class Batch extends BaseBatch {
         #[ORM\Column]
         private string $customAttribute;
     }
     

2. Validation Rules:

   • Override BatchValidator:

     class ExtendedBatchValidator extends BatchValidator {
         public function validate(array $data, Batch $batch = null): void {
             parent::validate($data, $batch);
             $this->validateCustomRules($data);
         }
     }
     

3. Serial Number Generators:

   • Implement SerialGeneratorInterface:

     class CustomSerialGenerator implements SerialGeneratorInterface {
         public function generate(int $batchId, int $quantity, string $format): array {
             return array_map(fn($i) => str_replace(
                 ['{INCREMENT}'],
                 [$i],
                 $format
             ), range(1, $quantity));
         }
     }
     

4. API Resources:

   • Extend BatchResource (if using API tools like spatie/laravel-api-resources):

     class CustomBatchResource extends BatchResource {
         public function toArray($request) {
             $array = parent::toArray($request);
             $array['custom_field'] = $this->customField;
             return $array;
         }
     }
     

Configuration Quirks

1. Environment Variables:

   • Missing Keys: Defaults may not align with Laravel’s .env structure.
   • Fix: Override in config/manufacture-part.php:

     'serial_format' => env('MANUFACTURE_PART_SERIAL_FORMAT', 'PROD-{INCREMENT}'),
     

2. Doctrine Configuration:

   • Issue: Doctrine may not auto-discover Laravel’s connections.
   • Fix: Configure in config/packages/doctrine.php:

     doctrine:
         dbal:
             connections:
                 default:
                     url: '%env(DATABASE_URL)%'
     

3. Translation Strings:

   • Issue: Russian-only translations may cause UI issues.
   • Fix: Add English translations in `resources/lang/en/