Plantuml Laravel Package

Getting Started

Install the package with composer require jawira/plantuml. The first call to PlantUml::generate() will auto-download the PlantUML JAR into storage/app/plantuml. Ensure Java 8+ is installed (java -version), as the package relies on the JRE at runtime. Your first quick win: generate a PNG from inline PlantUML:

use Jawira\PlantUml\PlantUml;

$uml = "@startuml\nAlice -> Bob: Hello\n@enduml";
$png = PlantUml::generate($uml);
file_put_contents('public/diagram.png', $png);

Start by checking storage/app/plantuml/ for the JAR and inspecting log files if generation fails.

Implementation Patterns

• Admin Dashboard Integration: Create a simple Artisan command (php artisan plantuml:render) that reads .puml files from resources/diagrams/ and outputs SVG/PNG to public/diagrams/. Useful for internal architecture visualization.
• Laravel Service Binding: In a service provider, bind a reusable PlantUml instance with custom options (e.g., format, timeout), injected into jobs or controllers:

  $this->app->singleton(\Jawira\PlantUml\PlantUml::class, function () {
      return (new \Jawira\PlantUml\PlantUml)
          ->setFormat('svg')
          ->setOption('-timeout', '120');
  });
  

• CI/CD Pipeline: Add a build step in phpunit.xml or GitHub Actions:

  php artisan plantuml:generate-all # custom command
  

  Commit generated assets or deploy them as part of docs.
• Blade Component Wrapper: Build a reusable @plantuml Blade directive that caches and renders diagrams on-demand using Illuminate\Support\Facades\Cache.
• Diff-Aware Rendering: Compare hash of PlantUML source (md5($uml)) before regenerating—ideal for reducing CI compute time.

Gotchas and Tips

• Java is non-negotiable: The package does not bundle a JRE. Without java in PATH, exec() calls fail silently or throw cryptic errors—always validate which java in CLI and web SAPI contexts.
• Config not auto-published: Run php artisan vendor:publish --provider="Jawira\PlantUml\PlantUmlServiceProvider" (if defined) or manually copy config/plantuml.php from the package to set JAR path, format defaults, or Java opts.
• Path escaping: On Windows, avoid spaces in paths (e.g., C:\Program Files\Java\...)—PlantUML fails to quote arguments correctly. Symlink to a simple path like C:\plantuml\java.exe.
• Output validation: generate() returns binary content. Use getRawOutput() to catch PlantUML stderr (e.g., syntax errors, Graphviz missing). Wrap in try/catch for PlantUmlException.
• Memory limits: Diagrams with >1k nodes may exhaust PHP memory. Increase memory_limit or offload to queued jobs (Dispatchable, InteractsWithQueue).
• Debugging flow: Temporarily override getExecutablePath() to log full command lines (e.g., java -jar ... -graphvizdot /usr/bin/dot ...) using Laravel’s Log::debug().