Plantuml Client Laravel Package

Getting Started

Begin by installing via Composer: composer require jawira/plantuml-client. Next, configure the PlantUML server endpoint—either public (e.g., https://www.plantuml.com/plantuml) or your own self-hosted instance. Create a client instance using new Jawira\PlantUml\Client(), passing the server URL, and then generate an image by calling ->generatePng($pumlContent) or ->generateSvg($pumlContent). The simplest first use case: render a UML diagram in a Laravel Blade view by generating SVG inline in a <div> or saving to storage/app/plantuml/ and linking in HTML.

Implementation Patterns

A common pattern is wrapping the client in a service class (e.g., PlantUmlDiagramService) for centralized logic and easy dependency injection. Use method chaining to switch between PNG/SVG output and to set encoding (default is raw, but URL-encoding is supported via withUrlEncoding(true)). Cache results—especially for frequently used diagrams—using Laravel’s cache facade to avoid repeated HTTP requests. In Laravel, register the client as a singleton in a service provider, or bind it via a custom facade. Handle dynamic diagram generation (e.g., from DB-stored .puml strings) by passing validated content to the client—always sanitize or validate inputs to prevent injection. For batch processing (e.g., converting many diagrams), dispatch jobs to avoid blocking web requests.

Gotchas and Tips

• The default timeout is 30s; for large diagrams or slow servers, set custom timeout (e.g., new Client('https://...', 10, 60) for 10s connect / 60s read).
• Server errors (5xx) throw a PlantUmlException—always wrap calls in try/catch.
• The package supports only png, svg, and txt formats by default. Adding support for other types (e.g., pdf) requires extending the Client and overriding getFormat().
• PlantUML public servers may throttle or reject long/complex diagrams—use self-hosted PlantUML for production reliability.
• Diagnostics tip: Call ->getLastRequestUrl() to inspect the generated PlantUML URL for debugging (e.g., copy-paste into browser to verify server behavior).
• For Laravel deployments behind a proxy, ensure allow_url_fopen is enabled or configure guzzle options (via ->withOptions(['proxy' => ...])) if the default stream wrapper fails.
• The last release was in 2022; verify compatibility with newer PHP/Laravel versions before adopting. Check GitHub issues for activity or consider a fork if maintenance is critical.