Fixtures Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require callers/fixtures-bundle
   

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

   Callers\FixturesBundle\FixturesBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Callers\FixturesBundle\FixturesBundle" --tag="config"
   

   Update config/fixtures.php with your fixture paths (e.g., database/fixtures).

3. First Fixture Load Define a fixture file (e.g., database/fixtures/users.yml):

   users:
     user_1:
       name: 'John Doe'
       email: 'john@example.com'
   

   Load fixtures via Artisan:

   php artisan fixtures:load
   

   Or load a specific fixture:

   php artisan fixtures:load users
   

4. Verify Data Check the database to confirm fixtures were loaded.

Implementation Patterns

Workflow: Fixture Management

1. Organize Fixtures Structure fixtures by domain (e.g., database/fixtures/users/, database/fixtures/roles/). Use YAML/JSON for readability or PHP arrays for dynamic logic.

2. Dependency Handling Load fixtures in order using --order flag:

   php artisan fixtures:load --order=roles,users
   

   Or define dependencies in fixture files:

   _meta:
     depends: roles
   

3. Reusable Fixtures Use references to avoid duplication:

   users:
     admin:
       name: 'Admin User'
       role: '@roles.admin'  # Reference another fixture
   

4. Environment-Specific Fixtures Override fixtures per environment (e.g., database/fixtures/dev/users.yml). Use the --env flag:

   php artisan fixtures:load --env=dev
   

5. Custom Fixture Classes Extend Callers\FixturesBundle\Loader\FixtureInterface for complex logic:

   namespace App\Fixtures;
   
   use Callers\FixturesBundle\Loader\FixtureInterface;
   
   class CustomUserFixture implements FixtureInterface {
       public function load(array $data) {
           // Custom logic (e.g., hashing passwords)
       }
   }
   

   Register in config/fixtures.php:

   'fixtures' => [
       'users' => App\Fixtures\CustomUserFixture::class,
   ],
   

Integration Tips

• Testing: Use fixtures in PHPUnit tests:

  public function setUp(): void {
      $this->artisan('fixtures:load')->run();
  }
  

• Seeding: Combine with Laravel’s DatabaseSeeder:

  public function run() {
      $this->call(FixturesCommand::class);
  }
  

• Migrations: Load fixtures after migrations in post-migrate hooks.

Gotchas and Tips

Pitfalls

1. Duplicate Data

   • Issue: Running fixtures:load multiple times may duplicate records.
   • Fix: Use --truncate to clear tables first or implement unique constraints.

2. Missing Dependencies

   • Issue: Fixtures with unmet dependencies fail silently.
   • Fix: Always define _meta.depends or use --order.

3. File Permissions

   • Issue: Artisan can’t read fixture files due to permissions.
   • Fix: Ensure storage/ and database/ are writable:

     chmod -R 775 storage/ database/
     

4. Namespace Collisions

   • Issue: Fixture keys clash with existing database records.
   • Fix: Use UUIDs or prefixed keys (e.g., user_1_ → user_1_2023).

5. Large Fixtures

   • Issue: Slow performance with thousands of records.
   • Fix: Batch inserts or use --chunk=100 (if supported).

Debugging

• Verbose Output: Enable debug mode:

  php artisan fixtures:load --verbose
  

• Dry Run: Preview changes without loading:

  php artisan fixtures:load --dry-run
  

• Logs: Check storage/logs/laravel.log for errors.

Extension Points

1. Custom Loaders Override the loader service in config/fixtures.php:

   'loader' => App\Services\CustomFixtureLoader::class,
   

2. Event Listeners Listen for fixtures.loaded events:

   public function handle(FixturesLoaded $event) {
       // Post-load logic (e.g., cache warming)
   }
   

3. Dynamic Fixtures Generate fixtures at runtime by extending FixtureInterface:

   public function load(array $data) {
       return Factory::new(User::class)->count(10)->create();
   }
   

4. Validation Add validation rules to fixture files:

   _meta:
     validate: 'email|required'