Fixtures Documentation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adlarge/fixtures-documentation-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   Adlarge\FixturesDocumentationBundle\AdlargeFixturesDocumentationBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=adlarge-fixtures-documentation-config
   

   Update config/adlarge_fixtures_documentation.php with your fixture paths and routes.

3. First Use Case Generate documentation for a single fixture class:

   use Adlarge\FixturesDocumentationBundle\Generator\FixtureGenerator;
   
   $generator = new FixtureGenerator();
   $generator->generate('App\Fixtures\UserFixture', 'users');
   

   Access the generated JSON at /fixtures-documentation/data.json and Twig template at /fixtures-documentation.

Implementation Patterns

Workflow Integration

1. Fixture Generation

   • Manual Entity Processing:

     $generator->generateEntity($entity, 'section_name');
     

   • Automatic Fixture Processing (for Doctrine fixtures):

     $generator->generateFixture('App\Fixtures\UserFixture');
     

   • Full Automatic (scans all fixtures in configured paths):

     $generator->generateAll();
     

2. Route Configuration Add to routes/web.php (Symfony) or routes.php (Laravel):

   use Adlarge\FixturesDocumentationBundle\AdlargeFixturesDocumentationBundle;
   
   $bundle->addRoutes($router);
   

3. Twig Integration Extend the default Twig template (templates/AdlargeFixturesDocumentationBundle/default/index.html.twig) to customize rendering:

   {% extends 'base.html.twig' %}
   {% block body %}
       {{ include('AdlargeFixturesDocumentationBundle::default/_fixtures.html.twig', {
           fixtures: fixtures,
           sections: sections
       }) }}
   {% endblock %}
   

4. Reload Action Configure a reload route in config/adlarge_fixtures_documentation.php:

   reload:
       enabled: true
       route: 'fixtures_reload'
       method: 'POST'
   

   Add a controller to handle reloads:

   use Adlarge\FixturesDocumentationBundle\Service\FixtureReloader;
   
   public function reloadFixtures(FixtureReloader $reloader)
   {
       $reloader->reload();
       return redirect()->route('fixtures_documentation');
   }
   

5. Laravel-Specific Bridge Use the adlarge/laravel-fixtures-documentation-bridge to integrate with Laravel’s service container:

   $this->loadViewsFrom(__DIR__.'/resources/views', 'fixtures-documentation');
   $this->app->register(\Adlarge\FixturesDocumentationBundle\Bridge\Laravel\ServiceProvider::class);
   

Gotchas and Tips

Pitfalls

1. Fixture Path Configuration

   • Ensure fixtures_paths in config includes all directories containing your fixture classes.
   • Example:

     fixtures_paths:
         - '%kernel.project_dir%/tests/Fixtures'
         - '%kernel.project_dir%/vendor/acme/fixtures'
     

2. Entity vs. Fixture Data

   • The bundle prioritizes fixture data over raw entity data. If a fixture doesn’t define getData(), it falls back to entity properties, which may not match test expectations.
   • Fix: Override getData() in your fixture:

     public function getData()
     {
         return [
             'email' => $this->faker->unique()->email,
             'role'  => 'admin',
         ];
     }
     

3. Caching Issues

   • Generated JSON is cached by default. Clear cache after fixture updates:

     php artisan cache:clear
     

   • Disable caching in config/adlarge_fixtures_documentation.php for development:

     cache:
         enabled: false
     

4. Doctrine Fixtures Only

   • The bundle assumes Doctrine fixtures. For custom fixtures, implement Adlarge\FixturesDocumentationBundle\Generator\FixtureInterface:

     class CustomFixture implements FixtureInterface
     {
         public function getData(): array
         {
             return [...];
         }
     }
     

5. Twig Template Overrides

   • If overriding templates, ensure you extend the base template (default/index.html.twig) to retain functionality.
   • Tip: Use {{ dump(fixtures) }} in Twig to inspect the generated data structure.

Debugging

1. Verify JSON Output Check /fixtures-documentation/data.json for errors or missing data. Use:

   curl http://localhost/fixtures-documentation/data.json | jq
   

2. Log Generation Enable debug mode in config:

   debug: true
   

   Logs will appear in var/log/adlarge_fixtures_documentation.log.

3. Fixture Loading Order Fixtures are processed alphabetically. Use explicit section names to control ordering:

   $generator->generateFixture('App\Fixtures\AdminFixture', 'Admins (Priority)');
   

Extension Points

1. Custom Data Processors Add a service to transform fixture data before rendering:

   # config/services.yaml
   Adlarge\FixturesDocumentationBundle\Generator\DataProcessorInterface:
       class: App\Service\CustomFixtureDataProcessor
       tags: [adlarge.fixtures_documentation.data_processor]
   

2. Dynamic Sections Generate sections dynamically based on entity metadata:

   use Doctrine\ORM\Mapping\ClassMetadata;
   
   public function getSection(ClassMetadata $metadata): string
   {
       return $metadata->getReflectionClass()->getShortName();
   }
   

3. API Endpoint Expose the JSON endpoint for API consumers:

   Route::get('/api/fixtures', function () {
       return response()->json(file_get_contents(public_path('fixtures-documentation/data.json')));
   });