Plantuml Encoding Laravel Package

Getting Started

Install the package via Composer:

composer require jawira/plantuml-encoding

Start encoding UML text in seconds — the core use case is generating embeddable PlantUML URLs for diagrams. For example, in a Blade template:

@php
    $uml = "@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi there!
@enduml";
    $encoded = \Jawira\PlantUmlEncoding\PlantUml::encode($uml);
@endphp
<a href="https://www.plantuml.com/plantuml/svg/{{ $encoded }}">View Diagram</a>

First check the README on GitHub (repository link in docs) for the encode() method signature and optional compression/encoding flags.

Implementation Patterns

• Inline URL Generation: Combine with Laravel’s route() or url() helpers to create dynamic diagram URLs for docs, dashboards, or emails:

  $url = "https://www.plantuml.com/plantuml/svg/" . PlantUml::encode($umlSource);
  

• Caching: Leverage deterministic encoding to cache encoded strings in Redis/Redis cache—ideal for CI pipelines where diagrams are reused:

  $cacheKey = 'uml:' . md5($umlSource);
  $encoded = Cache::remember($cacheKey, 600, fn() => PlantUml::encode($umlSource));
  

• Laravel Blade Components: Wrap encoding into a reusable component for clean, consistent diagram rendering:

  @component('components.plantuml', ['uml' => $code])
      <img src="{{ $encodedUrl }}" alt="UML Diagram">
  @endcomponent
  

• Testable Diagrams: Use encoded strings in tests (e.g., snapshot diffs or screenshot verification) since output is deterministic:

  $this->assertEquals($expectedEncodedString, PlantUml::encode($uml));
  

Gotchas and Tips

• Length Limits: PlantUML server enforces ~8k character limits for encoded URLs. For larger diagrams, use the server-side render API (/png/, /svg/) or break diagrams into smaller components.
• UTF-8 Handling: The encoder requires UTF-8 input. Ensure your UML strings aren’t malformed (e.g., invalid byte sequences) or you’ll get cryptic gzdeflate errors.
• URL Safety: The custom base64 alphabet replaces +// with -/_, so don’t use base64_encode() or urlencode() manually—the encode() method handles all normalization and escaping.
• Compression Options: By default, encoding uses deflate. If troubleshooting compatibility with older servers, check for encodeRaw() (no compression) in the docs—but avoid it unless necessary.
• Extensibility: The package exposes encoding classes (e.g., Compressor, Base64Encoder)—you can subclass them for custom behavior (e.g., alternative compression algorithms), though this is rarely needed.