Alice Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dag-io/alice-extra-bundle
   

   Register the bundle in config/app.php under providers:

   Dag\AliceExtraBundle\AliceExtraBundle::class,
   

2. Basic Usage The package extends Laravel's Faker and Alice capabilities. Start by publishing the config (if needed) and reviewing the default providers:

   php artisan vendor:publish --provider="Dag\AliceExtraBundle\AliceExtraBundle" --tag="config"
   

3. First Use Case: Custom Faker Providers Extend Faker with custom providers (e.g., for domain-specific data):

   use Dag\AliceExtraBundle\Faker\Provider\CustomProvider;
   
   Faker::addProvider(new CustomProvider($faker));
   

Implementation Patterns

Workflow: Data Seeding with Alice

1. Define Fixtures Use Alice's YAML/JSON format to define complex relationships:

   # database/fixtures/users.yml
   App\Entity\User:
     user_{1..10}:
       email: '<email>'
       roles: '<randomElement($roles)>'
       posts: '@post*'
   

2. Load Fixtures Load fixtures via a custom Artisan command or directly in a test:

   use Dag\AliceExtraBundle\Loader\Loader;
   
   $loader = new Loader();
   $loader->loadFromYaml(file_get_contents(__DIR__.'/fixtures/users.yml'));
   

3. Dynamic Data Generation Leverage Faker's custom providers for domain-specific logic:

   // Extend Faker for a "Company" provider
   Faker::addProvider(new CompanyProvider($faker));
   $company = $faker->companyName; // Uses custom logic
   

Integration Tips

• Laravel Events: Trigger events during fixture loading (e.g., AliceExtraEvents::POST_LOAD).
• Database Transactions: Wrap fixture loading in a transaction for rollback safety:

  DB::transaction(function () use ($loader) {
      $loader->loadFromYaml($fixtures);
  });
  

• Custom Factories: Combine with Laravel's factories for hybrid seeding:

  $user = User::factory()->create(['email' => $faker->unique()->safeEmail]);
  

Gotchas and Tips

Pitfalls

1. Provider Conflicts

   • Ensure custom Faker providers don’t override existing ones. Use unique namespaces:

     class CustomProvider extends \Faker\Provider\Base {
         public static function register() { /* ... */ }
     }
     

2. Circular References

   • Alice may fail on circular relationships (e.g., User references Post, which references User). Use @post? (optional) or @post* (many-to-many) sparingly.

3. Database Constraints

   • Unique fields (e.g., email) may fail. Use Faker's unique() or unique()->safeEmail:

     email: '<unique()->safeEmail>'
     

Debugging

• Enable Debug Mode Set ALICE_DEBUG=true in .env to log fixture loading details:

  ALICE_DEBUG=true
  

• Validate Fixtures Use Alice's --validate flag for YAML/JSON syntax checks:

  php artisan alice:load --validate database/fixtures/users.yml
  

Extension Points

1. Custom Loaders Extend Dag\AliceExtraBundle\Loader\Loader to add pre/post-processing:

   class CustomLoader extends Loader {
       protected function postLoad(array $objects) {
           // Modify objects after loading
       }
   }
   

2. Event Listeners Subscribe to Alice events (e.g., AliceExtraEvents::PRE_LOAD) to inject logic:

   Event::listen(AliceExtraEvents::PRE_LOAD, function ($event) {
       $event->setFixtures($this->modifyFixtures($event->getFixtures()));
   });
   

3. Faker Extensions Add domain-specific providers to config/alice_extra.php:

   'faker_providers' => [
       Dag\AliceExtraBundle\Faker\Provider\CustomProvider::class,
   ],
   

Performance

• Batch Loading For large datasets, chunk fixtures to avoid memory issues:

  $loader->setBatchSize(100); // Load 100 objects at a time