Es Lib Maker Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev awd-studio/es-lib-maker-bundle
   

   Ensure config/bundles.php includes AwdEs\EsLibMakerBundle\EsLibMakerBundle::class under dev.

2. First Use Case: Generate a basic aggregate root:

   php bin/console make:es:entity "YourNamespace\YourAggregate" -
   

   This creates:

   • Aggregate root class (YourAggregate)
   • Events (WasCreated, WasChanged)
   • Repository, factory, and exceptions.

3. Where to Look First:

   • Command Reference: Run php bin/console make:es:entity --help for options.
   • Generated Code: Check src/YourNamespace/Domain/ for the new structure.
   • ES Lib Bundle: Ensure awd-studio/es-lib-bundle is installed (required for runtime functionality).

Implementation Patterns

Usage Patterns

1. Aggregate Root Creation:

   php bin/console make:es:entity "App\Order\Domain\OrderAggregate" --main-value-type="int" --main-value-name="orderId"
   

   • Use --main-value-type for custom value types (e.g., string, int, IDateTime).
   • Omit -- flags for defaults (e.g., string/value).

2. Child Entity Workflow:

   php bin/console make:es:entity "App\Order\Domain\Entity\OrderItem\OrderItem" "App\Order\Domain\OrderAggregate" --main-value-type="string" --main-value-name="sku"
   

   • Reference the parent aggregate’s FQCN (e.g., "App\Order\Domain\OrderAggregate").
   • Child entities auto-inherit the parent’s namespace structure.

3. Event-Driven Workflows:

   • Extend generated events (e.g., WasCreated) in src/YourNamespace/Domain/Event/.
   • Implement event handlers in the aggregate’s apply() method:

     public function apply(YourEvent $event): void {
         // Handle event logic
     }
     

4. Repository Integration:

   • Use the generated repository interface (YourAggregateRepositoryInterface) to define contracts.
   • Implement with awd-studio/es-lib-bundle (e.g., EventSourcingRepository).

5. Factory Pattern:

   • Use the generated factory (YourAggregateFactory) to create aggregates:

     $factory = new YourAggregateFactory();
     $aggregate = $factory->create($mainValue);
     

Integration Tips

• Symfony Maker Bundle: Leverage make:entity for non-ES entities, then manually integrate with ES Lib.
• Doctrine ORM: If using Doctrine, extend the generated repository to implement DoctrineRepository from es-lib-bundle.
• Testing: Use the factory to create test aggregates:

  $aggregate = (new YourAggregateFactory())->create('test-value');
  $this->assertInstanceOf(YourAggregate::class, $aggregate);
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies:

   • Error: Class 'AwdEs\EsLib\...' not found.
   • Fix: Install awd-studio/es-lib-bundle:

     composer require awd-studio/es-lib-bundle
     

2. Namespace Conflicts:

   • Error: Generated classes clash with existing ones.
   • Fix: Use unique machine names (--machine-name) or manually adjust namespaces.

3. Event Sourcing Runtime:

   • Error: Events aren’t persisted or replayed.
   • Fix: Ensure es-lib-bundle is configured in config/packages/es_lib.yaml:

     es_lib:
         event_store: doctrine # or 'doctrine', 'in-memory', etc.
     

4. Type Safety:

   • Gotcha: Custom main-value-type (e.g., IDateTime) requires the awd-studio/es-lib package’s types.
   • Fix: Install the core library:

     composer require awd-studio/es-lib
     

Debugging

• Generated Code Overrides:

  • Regenerate classes with --force to overwrite existing files (if supported in future versions).
  • Current Workaround: Manually merge changes or use --no-interaction to avoid prompts.

• Event Application:

  • Debug Tip: Add dd($event) in apply() to inspect event payloads during development.

Extension Points

1. Custom Events:

   • Extend generated events by creating new classes in src/YourNamespace/Domain/Event/ and reference them in apply():

     public function apply(CustomEvent $event): void { ... }
     

2. Repository Extensions:

   • Implement custom methods in the repository implementation:

     public function findByCriteria(Criteria $criteria): array { ... }
     

3. Factory Customization:

   • Override the generated factory to add validation or default values:

     public function create(string $value): YourAggregate {
         if (empty($value)) {
             throw new \InvalidArgumentException('Value cannot be empty.');
         }
         return parent::create($value);
     }
     

4. Machine Names:

   • Use --machine-name to enforce consistency in attributes (e.g., ORDER_ROOT for order_id).
   • Note: Machine names are used in event metadata and projections.

Configuration Quirks

• Dev vs. Prod:

  • The bundle is auto-registered for dev only. Manually add it to bundles.php for production if needed (unlikely, as it’s a maker tool).

• PHP 8.3+ Features:

  • Uses named arguments and enums (if applicable). Ensure your IDE supports PHP 8.3+ for full autocompletion.

• Symfony Maker Integration:

  • The bundle extends Symfony’s maker system. Use --dry-run to preview changes:

    php bin/console make:es:entity "YourAggregate" -- --dry-run