Plantuml Bundle Laravel Package

Getting Started

This is a Symfony bundle from an internal French research institute's GitLab, with zero stars, zero dependents and no Packagist presence. As a Laravel developer, your first move is not integration — it's a one-day reconnaissance to decide whether any integration is even possible.

Step 1 — Get the code onto disk.

composer require irstea/plantuml-bundle will almost certainly fail. Add a VCS repository entry instead:

"repositories": [
    { "type": "vcs", "url": "https://gitlab.irstea.fr/pole-is/bundles/plantuml-bundle" }
]

If the project is private you need a gitlab-token composer config or an SSH URL. Expect this check to be a hard blocking gate — an unreachable repo makes every other step moot.

Step 2 — Read before you wire.

In this order:

• README.md — likely sparse and French; still the fastest signal on intent.
• src/Command/ — the console command signature tells you what the generator actually accepts: target path, namespace, output format, whether it is kernel-coupled.
• src/DependencyInjection/Configuration.php — the authoritative config tree; ignore any YAML you find on the web that contradicts it.
• composer.json — PHP range, Symfony version constraints, license. Any of these can veto adoption outright.
• The bundle class in src/ — you need the exact FQCN before you touch config/bundles.php.

Step 3 — Understand the runtime dependency.

PlantUML is Java. The bundle either shells out to a local plantuml.jar (needs JRE, and Graphviz for most diagram types) or HTTP-posts to a PlantUML server. Determine which by grepping for Process, exec, curl, HttpClient, or .puml in the source. This decides whether you need a Java/Graphviz layer in your CI image at all.

Step 4 — First use case: CI sidecar, not an app dependency.

Before registering a bundle or writing a service provider, run the generator as a standalone build-stage step against a single representative module. Generate .puml files, render them, look at the output. That fifteen minutes tells you whether the generation logic understands anything useful, and it keeps the blast radius at zero while you decide.

Step 5 — Only if the output is good, evaluate the install path.

Registering a Symfony bundle in a Laravel app is not supported by the language or the framework. config/bundles.php doesn't exist; bin/console is artisan; there is no bundle loader. If you proceed at all, it is via the fork-and-extract path described below — not via composer require plus a service provider.

Implementation Patterns

Realistically there are three patterns, ordered by how likely they are to keep working. Pick the lowest one that satisfies your need.

Pattern 1 — CI-only sidecar (default recommendation).

Clone the repo in a build stage, run the generator against app/ or src/, emit .puml artifacts, publish them to the repo wiki or a docs folder. The bundle never enters composer.json, so PHP version conflicts, Symfony constraint clashes and license contamination cannot reach your application.

diagrams:
  image: eclipse-temurin:17-jre
  cache:
    key: plantuml-jar
    paths: [ .cache/plantuml.jar ]
  script:
    - git clone --depth 1 $PLANTUML_BUNDLE_URL tools/plantuml-bundle
    - php tools/plantuml-bundle/whatever-the-entrypoint-is --path app/
    - java -jar .cache/plantuml.jar -tpng docs/uml/*.puml
  artifacts:
    paths: [ docs/uml/ ]

Run this on merge to main or on a nightly schedule, not per-PR. Diagram generation is slow and the failure modes (missing JRE, missing Graphviz) are noisy on every pipeline otherwise.

Pattern 2 — Fork and extract the generator.

If the diagrams are genuinely valuable, vendor the generation classes only into app/Support/Uml/ or a private acme/uml package. Replace Symfony service lookups (ContainerInterface, bundles metadata) with Laravel equivalents: app(), Illuminate\Foundation\Application::getProviders(), route/model reflection via ReflectionClass. This is the only path that gives you an artisan command:

// app/Console/Commands/GenerateUml.php
protected $signature = 'uml:generate {path=app} {--out=docs/uml}';

public function handle(UmlGenerator $generator): int
{
    foreach ($generator->classesIn($this->argument('path')) as $class) {
        File::put(
            "{$this->option('out')}/{$class->shortName()}.puml",
            $class->toPlantUml()
        );
    }
    return self::SUCCESS;
}

The cost is real: you now own the code. Budget 1–2 weeks for a Laravel-only team, more if the original is heavily coupled to Symfony metadata (which it likely is, given the "generate UML from code" premise — bundles are the unit of introspection).

Pattern 3 — VCS require plus a wrapper provider.

Only viable if the repo is publicly readable and the license permits redistribution. A ServiceProvider can instantiate the generator manually:

$this->app->singleton(PlantUmlGenerator::class, function ($app) {
    return new PlantUmlGenerator(
        $app['config']->get('plantuml.binary'),
        $app['config']->get('plantuml.output_dir')
    );
});

But bundle bootstrapping, autoconfiguration tags, services.yaml files and Configuration.php validation never run. You are effectively using the bundle as a library while paying the dependency weight. This is the worst of both worlds and should be a last resort.

Integration tips that apply across patterns:

• Pin a specific commit hash, not dev-main. Upstream is institutional and may move, archive, or require new auth without notice.
• Mirror the repo to your own Git — internal, private, pinned. Builds must not depend on a French institute's GitLab staying reachable.
• Cache plantuml.jar in CI. It's ~10MB and re-downloading it on every run is pointless.
• Keep the diagram job non-blocking in CI initially (allow_failure: true). Silently broken diagrams are worse than none, but hard failures will block merges over a dev-tooling concern.
• Emit .puml text artifacts separately from rendered PNGs. The text diffs, the PNGs don't — and reviewing the puml in a merge request is the fastest way to spot "the tool didn't understand this file."

Gotchas and Tips

It is not a Laravel package and will not behave like one. No package discovery, no service provider auto-registration, no config/app.php entry. Any tutorial you find for "install a Symfony bundle in Laravel" either doesn't exist or is wrong. Plan for zero runtime integration or full fork; there is no comfortable middle.

composer require will fail on Packagist. Use the VCS repository entry. If the GitLab is private, expect a token or SSH configuration step before anything else works — and expect that step to break someday when the institute rotates credentials.

The license is unverified. Institutional repos often carry non-standard terms. Check before any code ships beyond an internal spike. Discovering a non-permissive license after a fork has propagated into a deliverable is expensive to undo.

PHP/Symfony version constraints can veto the whole exercise. Open composer.json first. An older Symfony constraint can conflict with a modern Laravel app on PHP 8.2/8.3. If it requires Symfony 4 and you're on Laravel 11, your only options are the CI sidecar or a fork that strips the constraint.

The introspection model is probably Symfony-shaped. The premise is "generate UML from code," but bundle-based tooling usually reflects over bundle metadata, service definitions and tagged services — not Laravel's container, facades or providers. Output that "succeeds" against a Laravel app may silently omit relationships, misreport dependencies, or produce flat, connection-less diagrams. This is the silent staleness failure mode: it looks like it worked. Sanity-check by hand against a class you know is heavily coupled.

Java and Graphviz are real system dependencies. Slim CI images (php:8.3-cli-slim) have neither. Class diagrams need Graphviz for layout in most PlantUML configurations. Fail the job explicitly on missing java or dot (command -v java && command -v dot) rather than emitting empty artifacts and moving on.

Documentation is in French and thin. This narrows the on-call pool and guarantees that every non-obvious question becomes internal investigation. No issue tracker activity, no Stack Overflow corpus, no dependents to google.

The config tree in Configuration.php is the only source of truth. Blog posts and README examples will drift. Read the PHP.

Extension points are Symfony-shaped. If you go the fork route, the places to hook in are the DI extension (DependencyInjection/*Extension.php) and any tagged-compiler-pass behavior. In a Laravel port those become a ServiceProvider::register() plus a small set of container bindings — the concept carries over, the code does not.

Debugging tips:

• Run against one small directory first. If the tool hangs, it's almost always the Java process (waiting on stdin, or missing a server timeout).
• If output is empty, check whether the tool wrote files at all (find . -name '*.puml') before suspecting the render step.
• Add -v or the Symfony verbosity flag to the generator — console commands usually respect it.
• Verify diagrams render outside your pipeline by opening a generated .puml on plantuml.com. If it renders there but not in CI, it's a Graphviz/layout problem, not a bundle bug.

When to walk away. If after a one-day spike the output is flat, misleading, or requires more than a few small patches to run against Laravel, stop. Maintained alternatives (phpDocumentor's class diagrams, PhpUML) or a small in-house reflection-based generator will cost less over a year than owning this one. The honest evaluation is one engineer, one sprint, one verdict — and the default verdict should be "not now."