Vendor Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require carguru/vendor-bundle
   

   Add the bundle to config/app.php under providers:

   JanWebdev\VendorBundle\VendorBundle::class,
   

2. Publish Config (if needed)

   php artisan vendor:publish --provider="JanWebdev\VendorBundle\VendorBundle" --tag="config"
   

   Check config/vendor.php for default settings.

3. First Use Case: Domain Isolation Define a vendor-specific entity (e.g., app/Domain/Vendor/Entities/Customer.php) and map it to the bundle’s repository:

   use JanWebdev\VendorBundle\Repositories\BaseRepository;
   
   class CustomerRepository extends BaseRepository
   {
       protected $entity = \JanWebdev\VendorBundle\Entities\Customer::class;
   }
   

4. Register Repository Bind the repository in a service provider (e.g., App\Providers\VendorServiceProvider):

   $this->app->bind(
       \JanWebdev\VendorBundle\Repositories\CustomerRepository::class,
       function ($app) {
           return new \App\Domain\Vendor\Repositories\CustomerRepository(
               $app->make(\JanWebdev\VendorBundle\Repositories\BaseRepository::class)
           );
       }
   );
   

Implementation Patterns

1. Domain Logic Separation

• Use Case: Isolate vendor-specific logic (e.g., pricing, inventory) from core Laravel models.
• Pattern:

  // Core Laravel model (e.g., Product)
  class Product extends Model {}
  
  // Vendor-specific extension
  class VendorProduct extends \JanWebdev\VendorBundle\Entities\Product
  {
      public function calculateVendorDiscount(): float
      {
          return $this->price * $this->vendor->discount_rate;
      }
  }
  

2. Repository Layer Integration

• Workflow:
  1. Extend BaseRepository for vendor-specific queries:

     class VendorOrderRepository extends BaseRepository
     {
         public function getActiveOrdersForVendor(int $vendorId): Collection
         {
             return $this->scopeQuery(function ($query) use ($vendorId) {
                 return $query->where('vendor_id', $vendorId)->where('status', 'active');
             })->get();
         }
     }
     

  2. Inject into services:

     public function __construct(VendorOrderRepository $orderRepo) {}
     

3. Event-Driven Extensions

• Pattern: Listen to bundle events (if supported) or dispatch custom events:

  // Example: Trigger after vendor entity update
  event(new \JanWebdev\VendorBundle\Events\VendorUpdated($vendor));
  

4. API Resource Wrapping

• Tip: Use Laravel’s Resource classes to transform bundle entities:

  namespace App\Http\Resources;
  
  use JanWebdev\VendorBundle\Entities\Vendor;
  use Illuminate\Http\Resources\Json\JsonResource;
  
  class VendorResource extends JsonResource
  {
      public function toArray($request): array
      {
          return [
              'id' => $this->id,
              'name' => $this->name,
              'custom_field' => $this->whenLoaded('customField'),
          ];
      }
  }
  

5. Service Container Binding

• Advanced: Override bundle services in AppServiceProvider:

  $this->app->singleton(
      \JanWebdev\VendorBundle\Services\VendorService::class,
      \App\Services\CustomVendorService::class
  );
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • The bundle uses JanWebdev\VendorBundle; avoid naming conflicts by prefixing custom classes (e.g., App\Domain\Vendor\...).

2. Missing Dependency Injection

   • If repositories aren’t bound, Laravel will throw BindingResolutionException. Always register them in a provider.

3. Entity Inheritance Pitfalls

   • Extending bundle entities (e.g., extends \JanWebdev\VendorBundle\Entities\Customer) may break migrations if the parent schema changes. Prefer composition over inheritance.

4. Configuration Overrides

   • Published config (config/vendor.php) may not auto-load. Manually merge it in AppServiceProvider:

     $this->mergeConfigFrom(__DIR__.'/../../../vendor/janwebdev/vendor-bundle/config/vendor.php', 'vendor');
     

Debugging Tips

1. Repository Queries

   • Enable Laravel’s query logging in .env:

     DB_LOG_QUERIES=true
     

   • Check logs for raw SQL from BaseRepository queries.

2. Event Debugging

   • If events fire silently, add a listener to log:

     Event::listen(\JanWebdev\VendorBundle\Events\VendorUpdated::class, function ($event) {
         Log::debug('Vendor updated:', ['vendor' => $event->vendor]);
     });
     

3. Service Binding Issues

   • Use php artisan container:dump to inspect bindings:

     php artisan container:dump | grep Vendor
     

Extension Points

1. Custom Repositories

   • Override BaseRepository methods (e.g., find(), create()) in your app’s repository layer.

2. Entity Observers

   • Add observers to bundle entities (if supported) in AppServiceProvider:

     \JanWebdev\VendorBundle\Entities\Vendor::observe(\App\Observers\VendorObserver::class);
     

3. API Middleware

   • Protect vendor endpoints with middleware:

     Route::middleware(['vendor.auth'])->group(function () {
         Route::apiResource('vendors', \App\Http\Controllers\VendorController::class);
     });
     

4. Testing

   • Mock bundle repositories in tests:

     $this->app->instance(
         \JanWebdev\VendorBundle\Repositories\CustomerRepository::class,
         Mockery::mock()
     );