Graphviz Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require graphp/graphviz
   

   Ensure graphviz CLI tools are installed on your system (Linux/macOS: brew install graphviz or apt-get install graphviz; Windows: via Graphviz binaries).

2. Basic Usage

   use Graphp\Graphviz\Graphviz;
   
   $graph = new Graphviz();
   $graph->addNode('A');
   $graph->addNode('B');
   $graph->addEdge('A', 'B');
   $graph->render('png')->save('output.png');
   

3. First Use Case Visualize a simple Laravel route hierarchy or dependency graph:

   $graph = new Graphviz();
   $graph->addNode('routes/web.php', ['label' => 'Web Routes']);
   $graph->addNode('routes/api.php', ['label' => 'API Routes']);
   $graph->addEdge('routes/web.php', 'routes/api.php', ['label' => 'Included']);
   $graph->render('png')->save(storage_path('app/graphs/routes.png'));
   

Implementation Patterns

Common Workflows

1. Dynamic Graph Generation Useful for debugging Laravel service containers or Eloquent relationships:

   $graph = new Graphviz();
   $graph->setAttribute('graph', ['rankdir' => 'LR']); // Left-to-right layout
   
   foreach (app()->getBindings() as $id => $binding) {
       $graph->addNode($id, ['shape' => 'box']);
   }
   foreach (app()->getServiceProviders() as $provider) {
       $graph->addEdge($provider, $provider . '.register');
   }
   

2. Integration with Laravel Events Generate graphs on-demand (e.g., after model creation):

   use Graphp\Graphviz\Graphviz;
   
   Event::listen('eloquent.created: App\Models\User', function ($user) {
       $graph = new Graphviz();
       $graph->addNode('User', ['label' => 'User Model']);
       $graph->addNode('Database', ['label' => 'DB']);
       $graph->addEdge('User', 'Database', ['label' => 'Saves To']);
       $graph->render('svg')->save(storage_path("app/graphs/user_{$user->id}.svg"));
   });
   

3. Custom Styling for Readability Leverage Graphviz attributes for clarity:

   $graph->setAttribute('node', ['fontname' => 'Arial', 'fontsize' => '12']);
   $graph->setAttribute('edge', ['fontcolor' => 'gray', 'penwidth' => '2']);
   $graph->addNode('Controller', ['style' => 'filled', 'color' => 'lightblue']);
   

Integration Tips

• Laravel Artisan Commands Create a custom command for graph generation:

  use Graphp\Graphviz\Graphviz;
  use Illuminate\Console\Command;
  
  class GenerateGraphCommand extends Command
  {
      protected $signature = 'graph:generate {--format=png}';
      protected $description = 'Generate a system graph';
  
      public function handle()
      {
          $graph = new Graphviz();
          // ... add nodes/edges ...
          $graph->render($this->option('format'))
                ->save(storage_path("app/graphs/system.{$this->option('format')}"));
          $this->info('Graph generated!');
      }
  }
  

• API Response Visualization For debugging API payloads:

  $graph = new Graphviz();
  $graph->addNode('Request', ['label' => 'GET /api/users']);
  $graph->addNode('Response', ['label' => json_encode($response->data)]);
  $graph->addEdge('Request', 'Response');
  $graph->render('svg')->save(storage_path("app/graphs/api_debug.svg"));
  

Gotchas and Tips

Pitfalls

1. Graphviz CLI Dependency

   • Issue: graphp/graphviz requires the system-installed dot binary. Forgetting this causes RuntimeExceptions.
   • Fix: Verify with dot -V in your terminal. Use Docker if local installation is problematic.

2. Memory Limits

   • Issue: Large graphs (e.g., full Laravel service container) may hit PHP memory limits.
   • Fix: Use ini_set('memory_limit', '512M') or generate graphs in chunks.

3. Edge Cases in Node Labels

   • Issue: Special characters (e.g., &, ") in labels break DOT syntax.
   • Fix: Escape labels or use htmlLabel for HTML content:

     $graph->addNode('Node & Edge', ['htmlLabel' => '<&gt;Node & Edge&lt;/>']);
     

Debugging

• Validate DOT Syntax Use Graphviz::getDot() to inspect the generated DOT code before rendering:

  $dotCode = $graph->getDot();
  file_put_contents('debug.dot', $dotCode);
  

  Validate with dot -Tplain debug.dot (should output clean text).

• Fallback Formats If PNG fails (e.g., missing libraries), try SVG or plain DOT:

  $graph->render('svg')->save('fallback.svg');
  

Extension Points

1. Custom Renderers Extend Graphp\Graphviz\Renderer\RendererInterface to support additional formats (e.g., PDF via dot -Tpdf).

2. Subgraphs for Hierarchy Group related nodes (e.g., Laravel components):

   $graph->addSubgraph('cluster_0')
         ->addNode('AuthServiceProvider')
         ->addNode('RouteServiceProvider');
   

3. Dynamic Layouts Adjust layouts per graph type:

   $graph->setAttribute('graph', ['rankdir' => 'TB']); // Top-to-bottom
   $graph->setAttribute('graph', ['splines' => 'ortho']); // Orthogonal edges
   

Performance Tips

• Reuse Graph Instances Instantiate Graphviz once and reuse it for multiple graphs (e.g., in a service class).
• Cache Rendered Graphs Store generated images in storage/app/graphs and serve via Laravel’s filesystem:

  return response()->file(storage_path("app/graphs/system.png"));