Alice Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require hautelook/alice-bundle
   

   Ensure Hautelook\AliceBundle\HautelookAliceBundle::class is registered in config/bundles.php.

2. Configure Database Support Add Fidry\AliceDataFixtures\Bridge\Doctrine\ORM\AliceDataFixturesLoader to your doctrine/orm/fixtures.yaml:

   services:
       Fidry\AliceDataFixtures\Bridge\Doctrine\ORM\AliceDataFixturesLoader:
           arguments:
               $entityManager: '@doctrine.orm.entity_manager'
   

3. Create Your First Fixture Define a fixture in src/DataFixtures/ORM/LoadUserData.php:

   use Hautelook\AliceBundle\Fixtures\Loader;
   use Hautelook\AliceBundle\Fixtures\DataFixturesProviderInterface;
   
   class LoadUserData implements DataFixturesProviderInterface
   {
       public function getFixtures(): array
       {
           return [
               __DIR__.'/user.yml',
           ];
       }
   }
   

4. Define Fixture Data (user.yml)

   App\Entity\User:
       user_{1..10}:
           email: '<email>'
           roles: ['ROLE_USER']
           plainPassword: 'password'
   

5. Load Fixtures

   php bin/console hautelook:fixtures:load
   

   Or via PHP:

   $loader = new Loader();
   $loader->load();
   

Implementation Patterns

Workflow: Fixture Development

1. Organize Fixtures by Domain Group fixtures in directories (e.g., src/DataFixtures/ORM/Users/, src/DataFixtures/ORM/Products/). Use DataFixturesProviderInterface to aggregate them:

   class LoadUserFixtures implements DataFixturesProviderInterface
   {
       public function getFixtures(): array
       {
           return [
               __DIR__.'/users/*.yml',
           ];
       }
   }
   

2. Reuse Fixtures with Parameters Pass runtime parameters via Loader:

   $loader = new Loader();
   $loader->load([], ['environment' => 'test']);
   

   Access in YAML:

   App\Entity\User:
       user_{1..5}:
           email: '<email>@{{ environment }}.com'
   

3. Dependency-Based Loading Use orderBy: [ { property: 'createdAt', direction: 'ASC' } ] in hautelook_alice.yaml to enforce load order:

   hautelook_alice:
       fixtures:
           order_by: true
   

4. Custom Fixture Classes Extend Hautelook\AliceBundle\Fixtures\AbstractFixture for dynamic logic:

   class CustomUserFixture extends AbstractFixture
   {
       protected function getObjects(): array
       {
           return [
               new User('admin@example.com', 'admin'),
           ];
       }
   }
   

Integration Tips

• Symfony Events Trigger fixture loading post-migration:

  # config/packages/doctrine.yaml
  doctrine:
      orm:
          event_listeners:
              Hautelook\AliceBundle\EventListener\FixturesListener: ~
  

• Testing Use Hautelook\AliceBundle\Test\FixturesTrait in PHPUnit:

  use Hautelook\AliceBundle\Test\FixturesTrait;
  
  class UserTest extends TestCase
  {
      use FixturesTrait;
  
      protected function setUp(): void
      {
          $this->loadFixtures([LoadUserData::class]);
      }
  }
  

• Environment-Specific Fixtures Override fixtures per environment via hautelook_alice.yaml:

  hautelook_alice:
      fixtures:
          test:
              path: '%kernel.project_dir%/config/fixtures/test'
  

Gotchas and Tips

Pitfalls

1. Database Compatibility

   • Ensure your DB driver is supported by FidryAliceDataFixtures.
   • Fix: Use SQLite for local development if MySQL/PostgreSQL causes issues.

2. Circular References

   • Alice may fail if fixtures reference each other without proper ordering.
   • Fix: Explicitly set order_by in config or use after/before in YAML:

     App\Entity\Order:
         order_1:
             user: '@user_1'
             after: ['App\Entity\User']
     

3. Faker Locale Mismatch

   • Faker generates locale-specific data (e.g., emails). Ensure your Faker\Factory is configured:

     Faker\Factory::create('en_US');
     

4. Doctrine Proxy Conflicts

   • Fixtures may clash with Doctrine proxies if loaded in dev mode.
   • Fix: Disable proxies in config/packages/dev/doctrine.yaml:

     doctrine:
         orm:
             proxy_dir: null
             proxy_namespace: null
     

Debugging

1. Dry Run Mode Use --dry-run to preview loaded data:

   php bin/console hautelook:fixtures:load --dry-run
   

2. Verbose Output Enable debug mode for detailed logs:

   php bin/console hautelook:fixtures:load -vvv
   

3. Fixture Validation Validate YAML syntax with:

   php bin/console hautelook:fixtures:validate
   

Extension Points

1. Custom Faker Providers Register providers in services.yaml:

   services:
       App\Fixtures\CustomFakerProvider:
           tags: [faker.provider]
   

2. Post-Load Callbacks Use Symfony events to run logic after loading:

   // src/EventListener/FixturePostLoadListener.php
   class FixturePostLoadListener
   {
       public function onFixturesLoaded(FixturesLoadedEvent $event)
       {
           // Custom logic here
       }
   }
   

3. Dynamic Fixture Generation Override Hautelook\AliceBundle\Fixtures\Loader to inject runtime data:

   $loader = new class($container) extends Loader {
       public function __construct(private ContainerInterface $container) {}
       protected function getParameters(): array {
           return ['app_name' => $this->container->getParameter('app.name')];
       }
   };
   

Configuration Quirks

1. Default Namespace Fixtures default to App\Entity\. Override in hautelook_alice.yaml:

   hautelook_alice:
       namespace: 'Your\Custom\Namespace'
   

2. Excluding Fixtures Use exclude in DataFixturesProviderInterface:

   public function getFixtures(): array
   {
       return [
           __DIR__.'/users/*.yml',
       ];
   }
   // Exclude specific files via CLI:
   php bin/console hautelook:fixtures:load --exclude=admin.yml
   

3. Performance

   • Disable purge_mode in hautelook_alice.yaml for large datasets:

     hautelook_alice:
         purge_mode: false
     

   • Use --no-purge flag to skip truncation:

     php bin/console hautelook:fixtures:load --no-purge