Diagram Bundle Laravel Package

Getting Started

Minimal Setup for Laravel (Symfony-Compatible)

Since Laravel doesn’t natively support Symfony bundles, you’ll need to adapt this package for Laravel using Symfony’s Bridge or Laravel’s Service Provider pattern. Here’s how:

1. Install the Package

   composer require benmacha/diagram-bundle
   

2. Register the Bundle (Laravel Equivalent) Create a custom service provider to load the bundle’s routes and assets:

   // app/Providers/DiagramServiceProvider.php
   namespace App\Providers;
   
   use Illuminate\Support\ServiceProvider;
   use BenMacha\DiagramBundle\DiagramBundle;
   
   class DiagramServiceProvider extends ServiceProvider
   {
       public function register()
       {
           // Load bundle config (if needed)
           $this->mergeConfigFrom(__DIR__.'/../../vendor/benmacha/diagram-bundle/config/config.yml', 'diagram');
       }
   
       public function boot()
       {
           // Register routes
           $this->loadRoutesFrom(__DIR__.'/../../vendor/benmacha/diagram-bundle/Resources/config/routing/routes.yml');
   
           // Publish assets (Symfony-style)
           $this->publishes([
               __DIR__.'/../../vendor/benmacha/diagram-bundle/Resources/public' => public_path('bundles/diagram'),
           ], 'diagram-assets');
       }
   }
   

   Register it in config/app.php:

   'providers' => [
       // ...
       App\Providers\DiagramServiceProvider::class,
   ],
   

3. Publish Assets

   php artisan vendor:publish --provider="App\Providers\DiagramServiceProvider" --tag="diagram-assets"
   

   Link assets in public/index.php:

   $app->register(new \Symfony\Bundle\FrameworkBundle\FrameworkBundle());
   $app->register(new \BenMacha\DiagramBundle\DiagramBundle());
   

4. First Use Case: Generate an Entity Diagram Add a route in routes/web.php:

   Route::get('/diagram', function () {
       return view('diagram.index'); // Create this view to render the bundle's JS/CSS
   });
   

   Visit /diagram to see the generated diagram (requires Doctrine ORM for entity metadata).

Implementation Patterns

Workflow: Integrating with Laravel’s Doctrine (if used)

1. Doctrine Setup Ensure you have Doctrine installed (doctrine/orm) and configured in Laravel. The bundle relies on Doctrine’s metadata to generate diagrams.

2. Customizing Diagram Output The bundle generates diagrams dynamically. To tweak output:

   • Override Twig Templates: Copy vendor/benmacha/diagram-bundle/Resources/views to resources/views/vendor/diagram and modify templates.
   • Extend Diagram Logic: Use Symfony’s event system (if available) or Laravel’s service container to inject custom logic. Example:

     // app/Providers/DiagramServiceProvider.php
     public function boot()
     {
         $this->app->afterResolving('diagram.generator', function ($generator) {
             $generator->addCustomStyle('my-class', ['fill' => '#ff0000']);
         });
     }
     

3. API-Driven Usage If you need to fetch diagrams via API (e.g., for SPAs), create a controller:

   // app/Http/Controllers/DiagramController.php
   use BenMacha\DiagramBundle\Generator\DiagramGenerator;
   
   class DiagramController extends Controller
   {
       public function __construct(private DiagramGenerator $generator)
       {}
   
       public function show(string $entityClass)
       {
           $diagram = $this->generator->generate($entityClass);
           return response()->json($diagram);
       }
   }
   

4. Scheduled Diagram Updates Use Laravel’s scheduling to regenerate diagrams periodically:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule)
   {
       $schedule->command('diagram:generate')->daily();
   }
   

   (Note: You’d need to create a custom Artisan command for this.)

Integration Tips

• Laravel Mix/Webpack: If using Laravel Mix, add the bundle’s CSS/JS to your webpack.mix.js:

  mix.copy('public/bundles/diagram', 'public/js/diagram');
  

• Authentication: Protect the /diagram route with Laravel’s middleware:

  Route::get('/diagram', function () {
      return view('diagram.index');
  })->middleware('auth');
  

• Caching: Cache generated diagrams to avoid regenerating on every request:

  $diagram = Cache::remember("diagram:{$entityClass}", now()->addHours(1), function () use ($generator, $entityClass) {
      return $generator->generate($entityClass);
  });
  

Gotchas and Tips

Pitfalls

1. Doctrine Dependency

   • The bundle requires Doctrine ORM. If you’re not using Doctrine, this package won’t work. For Eloquent users, consider alternatives like laravel-erd.
   • Fix: Skip installation if not using Doctrine, or mock the MetadataFactory interface.

2. Symfony-Specific Assumptions

   • The bundle assumes Symfony’s autoloading and kernel structure. In Laravel:
     • Routes are defined in routes.yml (Symfony) but must be manually loaded in Laravel’s web.php.
     • Asset paths (e.g., @DiagramBundle/Resources/public) must be symlinked or copied manually.

3. Entity Namespace Issues

   • The bundle expects fully qualified entity names (e.g., App\Entity\User). If your entities are in a non-standard namespace, configure the diagram key in config/diagram.php:

     'entity_namespace' => 'App\Models\\',
     

4. JavaScript Dependencies

   • The bundle relies on external libraries (e.g., D3.js). Ensure these are loaded in your layout:

     <!-- resources/views/layouts/app.blade.php -->
     <script src="https://d3js.org/d3.v7.min.js"></script>
     @vite(['resources/js/diagram/diagram.js'])
     

Debugging

1. Blank Diagram?

   • Check if Doctrine metadata is loaded. Run:

     php artisan doctrine:schema:update --dump-sql
     

   • Verify the entity class exists and is annotated correctly.

2. 404 on /diagram

   • Ensure assets are published and symlinked:

     php artisan vendor:publish --tag=diagram-assets
     php artisan storage:link
     

   • Check public/bundles/diagram exists.

3. CSS/JS Not Loading

   • Laravel’s asset pipeline may interfere. Use @vite or @mix directives in your Blade templates:

     <link href="{{ mix('css/diagram/diagram.css') }}" rel="stylesheet">
     

Extension Points

1. Custom Diagram Types Extend the bundle’s generator to support custom diagram types (e.g., sequence diagrams). Override the DiagramGenerator service:

   // app/Providers/DiagramServiceProvider.php
   public function register()
   {
       $this->app->extend('diagram.generator', function ($generator) {
           $generator->addDiagramType('sequence', new CustomSequenceDiagram());
           return $generator;
       });
   }
   

2. Database-Agnostic Support If using a non-Doctrine database (e.g., MySQL via Query Builder), create a wrapper to expose entity-like metadata to the bundle.

3. Localization The bundle uses Symfony’s translation system. For Laravel, override translations in resources/lang/en/diagram.php:

   return [
       'diagram.title' => 'Custom Diagram Title',
   ];
   

Performance Tips

• Lazy-Load Diagrams: Generate diagrams on-demand (e.g., via AJAX) instead of pre-rendering.
• Minify Assets: Use Laravel Mix to minify the bundle’s CSS/JS:

  mix.copy('public/bundles/diagram/js', 'public/js', (file) => {
      return file.replace(/diagram\//, 'js/');
  });