Alice Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hautelook/alice-bundle
   

   Add to config/bundles.php (Symfony) or config/packages/hautelook_alice.yaml (Laravel via Symfony bridge):

   Hautelook\AliceBundle\HautelookAliceBundle::class => ['all' => true],
   

2. First Use Case: Create a YAML fixture file (e.g., config/fixtures/users.yml):

   App\Entity\User:
     user1:
       email: 'user1@example.com'
       password: '<password()>'
       roles: ['ROLE_USER']
     user2:
       email: 'user2@example.com'
       password: '<password()>'
       roles: ['ROLE_ADMIN']
   

   Load fixtures via CLI:

   php bin/console hautelook:fixtures:load --fixtures=config/fixtures/users.yml
   

3. Laravel Integration: Use symfony/flex or manually bridge Symfony components. For Laravel, leverage spatie/laravel-symfony-messenger or manually invoke:

   $loader = new \Hautelook\AliceBundle\Loader\YamlLoader();
   $faker = \Faker\Factory::create();
   $objectSet = $loader->load('config/fixtures/users.yml', $faker);
   $purger = new \Fidry\AliceDataFixtures\Purger\ORMPurger();
   $executor = new \Fidry\AliceDataFixtures\Executor();
   $executor->execute($objectSet, $purger);
   

Implementation Patterns

Workflows

1. Fixture Development:

   • YAML/JSON/Array: Define fixtures in structured files (e.g., config/fixtures/{module}.yml).
   • Faker Integration: Use Faker placeholders (e.g., <email(), <name()>) for dynamic data.
   • References: Link entities via references:

     App\Entity\Post:
       post1:
         title: 'First Post'
         author: '@user1'  # Reference to user1
     

2. Loading Strategies:

   • CLI: Use Symfony’s CLI for bulk loading:

     php bin/console hautelook:fixtures:load --fixtures=config/fixtures/
     

   • Programmatic: Load fixtures in Laravel’s bootstrap/app.php or service providers:

     $this->loadFixtures('config/fixtures/users.yml');
     

     Helper method:

     protected function loadFixtures(string $path) {
         $loader = new \Hautelook\AliceBundle\Loader\YamlLoader();
         $faker = \Faker\Factory::create();
         $objectSet = $loader->load($path, $faker);
         $purger = new \Fidry\AliceDataFixtures\Purger\ORMPurger();
         $executor = new \Fidry\AliceDataFixtures\Executor();
         $executor->execute($objectSet, $purger);
     }
     

3. Environment-Specific Fixtures:

   • Use separate fixture files for dev, test, etc.:

     config/fixtures/
       dev/
         users.yml
       test/
         users.yml
         posts.yml
     

   • Load conditionally in bootstrap/app.php:

     if (app()->environment('test')) {
         $this->loadFixtures('config/fixtures/test/users.yml');
     }
     

4. Testing:

   • Unit Tests: Load minimal fixtures for isolated tests:

     public function testUserCreation() {
         $this->loadFixtures('config/fixtures/test/users.yml');
         $this->assertDatabaseHas('users', ['email' => 'user1@example.com']);
     }
     

   • Feature Tests: Use DatabaseTransactions trait to reset fixtures after each test.

5. Seeding:

   • Run fixtures as part of Laravel’s Artisan::call('migrate:fresh --seed') by creating a custom seeder:

     class FixtureSeeder extends Seeder {
         public function run() {
             $this->loadFixtures('config/fixtures/dev/*.yml');
         }
     }
     

Gotchas and Tips

Pitfalls

1. Database Compatibility:

   • ORM Support: Ensure your ORM (Doctrine, Eloquent) is supported by FidryAliceDataFixtures. Laravel/Eloquent users may need custom purgers/executors.
   • Foreign Keys: Fixtures must respect referential integrity. Load parent entities (e.g., User) before child entities (e.g., Post).

2. Faker Locale:

   • Faker defaults to English. Set locale in config/faker.php (Symfony) or manually:

     $faker = \Faker\Factory::create('fr_FR'); // French locale
     

3. Fixture Overwriting:

   • By default, fixtures replace existing data. Use Purger\ORMPurger::setPurgeMode() to control behavior:

     $purger->setPurgeMode(\Fidry\AliceDataFixtures\Purger\PurgerInterface::PURGE_MODE_TRUNCATE);
     

4. Circular References:

   • Avoid circular references (e.g., User referencing Post which references User). Use @ syntax sparingly or restructure fixtures.

5. Performance:

   • Large fixtures may time out. Optimize by:
     • Splitting fixtures into smaller files.
     • Disabling transactions for bulk loads:

       $executor->setLogger(new \Monolog\Logger('fixtures'));
       $executor->setLoggerLevel(\Psr\Log\LogLevel::WARNING);
       

Debugging

1. Fixture Validation:

   • Enable verbose logging to debug failed loads:

     php bin/console hautelook:fixtures:load --fixtures=users.yml -v
     

   • Check for missing properties or invalid references.

2. Database State:

   • Use doctrine:schema:validate (Symfony) or schema:dump (Laravel) to verify schema matches fixtures.

3. Faker Issues:

   • Reset Faker’s random seed for reproducibility:

     $faker->seed(1234);
     

Extension Points

1. Custom Loaders:

   • Extend \Hautelook\AliceBundle\Loader\LoaderInterface for custom formats (e.g., JSON API):

     class JsonApiLoader implements LoaderInterface {
         public function load(string $path, \Faker\Generator $faker) {
             // Custom logic
         }
     }
     

2. Post-Processing:

   • Use EventDispatcher to hook into fixture lifecycle (e.g., hash passwords after load):

     # config/packages/hautelook_alice.yaml
     hautelook_alice:
         events:
             post_load: App\EventListener\HashPasswordListener
     

3. Laravel Service Provider:

   • Bind Alice components to Laravel’s container:

     public function register() {
         $this->app->singleton(\Faker\Generator::class, function () {
             return \Faker\Factory::create();
         });
     }
     

4. Custom Faker Providers:

   • Register custom Faker providers for domain-specific data:

     \Faker\Factory::create()->addProvider(new \YourNamespace\CustomFakerProvider());
     

Config Quirks

1. Symfony vs. Laravel:

   • Laravel users must manually bridge Symfony components (e.g., EventDispatcher, Loader). Use spatie/laravel-symfony-messenger for easier integration.

2. Caching:

   • Disable caching for development:

     # config/packages/hautelook_alice.yaml
     hautelook_alice:
         cache: false
     

3. Environment Variables:

   • Use .env for dynamic fixture paths:

     fixtures_path: '%env(FIxtures_DIR)%/config/fixtures'