Customer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sylius/customer
   

   Add the bundle to your config/bundles.php (if using Symfony) or register the service provider in Laravel via config/app.php:

   'providers' => [
       // ...
       Sylius\Customer\CustomerBundle::class,
   ],
   

2. Database Migration Publish and run migrations:

   php artisan vendor:publish --provider="Sylius\Customer\CustomerBundle\CustomerBundle" --tag="migrations"
   php artisan migrate
   

3. First Use Case Create a customer via the repository:

   use Sylius\Customer\Model\CustomerRepositoryInterface;
   use Sylius\Customer\Model\CustomerInterface;
   
   $customer = new Customer();
   $customer->setEmail('john@example.com');
   $customer->setFirstName('John');
   $customer->setLastName('Doe');
   
   $customerRepository->add($customer);
   $customerRepository->flush();
   

Key Classes to Know

• Customer (Entity): Core model for customer data.
• CustomerRepositoryInterface: For CRUD operations.
• CustomerEvents: Event system for lifecycle hooks (e.g., CustomerCreatedEvent).

Implementation Patterns

Workflows

1. Customer Registration Use the CustomerEvents::CREATED event to trigger post-registration logic (e.g., sending welcome emails):

   use Sylius\Component\Customer\Model\CustomerEvents;
   
   event(new CustomerCreatedEvent($customer));
   

2. Authentication Integration Link to Laravel’s Auth system by extending the Customer model:

   use Illuminate\Foundation\Auth\User as Authenticatable;
   
   class Customer extends Authenticatable implements CustomerInterface
   {
       use CustomerTrait;
   }
   

3. API Endpoints Use Laravel’s API resources to expose customer data:

   // routes/api.php
   Route::apiResource('customers', CustomerController::class);
   

4. Subscriptions/Traits Extend functionality with traits (e.g., CustomerTrait for common methods):

   use Sylius\Component\Customer\Model\CustomerTrait;
   
   class Customer extends Model implements CustomerInterface
   {
       use CustomerTrait;
   }
   

Integration Tips

• Validation: Use Laravel’s built-in validation for customer fields (e.g., email, first_name).
• Events: Subscribe to CustomerEvents in Laravel’s EventServiceProvider:

  protected $listen = [
      CustomerEvents::CREATED => [
          \App\Listeners\SendWelcomeEmail::class,
      ],
  ];
  

• Testing: Use Laravel’s createCustomer() helper or factories:

  $customer = Customer::factory()->create();
  

Gotchas and Tips

Pitfalls

1. Event Naming Conflicts Ensure event names (e.g., CustomerCreatedEvent) don’t clash with Laravel’s native events. Prefix if needed:

   event(new \App\Events\CustomerRegistered($customer));
   

2. Repository Injection Avoid hardcoding CustomerRepository in controllers. Use dependency injection:

   public function __construct(private CustomerRepositoryInterface $customerRepository) {}
   

3. Missing Traits If extending Customer, ensure all required traits (e.g., CustomerTrait) are included to avoid runtime errors.

4. Database Schema Published migrations may conflict with existing tables. Review sylius_customer migrations before running:

   php artisan vendor:publish --tag="sylius-customer-migrations" --dry-run
   

Debugging

• Event Debugging: Dump dispatched events in a listener:

  public function handle(CustomerCreatedEvent $event)
  {
      \Log::debug('Customer created:', ['customer' => $event->getCustomer()]);
  }
  

• Repository Queries: Use Laravel’s query logging:

  DB_LOG_QUERIES=true
  

Extension Points

1. Custom Fields Add fields via database migrations and update the Customer entity:

   $customer->setCustomField('preferred_language', 'en');
   

   Store as JSON or a separate table.

2. API Filtering Use Laravel’s API resources to filter customer data:

   public function toArray($request)
   {
       return [
           'id' => $this->id,
           'email' => $this->email,
           // Add custom fields here
       ];
   }
   

3. Soft Deletes Enable soft deletes by adding SoftDeletes trait to Customer:

   use Illuminate\Database\Eloquent\SoftDeletes;
   
   class Customer extends Model implements CustomerInterface
   {
       use SoftDeletes, CustomerTrait;
   }
   

4. Testing Mock the repository in tests:

   $this->mock(CustomerRepositoryInterface::class, function ($mock) {
       $mock->shouldReceive('find')->andReturn($customer);
   });