Unified Asset Installer Laravel Package

Product Decisions This Supports

• Customizable Documentation Workflows: Enables teams to maintain non-standard directory structures for phpDocumentor templates/plugins, reducing friction in monorepos or legacy systems where /vendor is inaccessible or undesirable.
• Build vs. Buy: Justifies internal development of custom Composer installers only if this package fails to meet specific needs (e.g., support for phpdocumentor-plugin type or advanced asset routing). Otherwise, avoids reinventing the wheel.
• Roadmap for Documentation Tools: Critical for projects relying on phpDocumentor (e.g., API docs, SDKs) to standardize asset installation without manual post-install scripts or hacky symlinks.
• Developer Experience (DX): Reduces onboarding time for contributors by automating template/plugin setup, aligning with goals to improve DX for open-source maintainers.

When to Consider This Package

• Adopt if:

  • Your project uses phpDocumentor templates/plugins and requires installation outside /vendor (e.g., /data/template, /opt/docs).
  • You’re maintaining a monorepo or have strict directory conventions that conflict with Composer’s default behavior.
  • You want to avoid post-install scripts or manual symlink management for documentation assets.
  • Your team prioritizes consistency in documentation tooling across multiple projects.

• Look elsewhere if:

  • You don’t use phpDocumentor (this is niche to its ecosystem).
  • Your needs are limited to /vendor installations (default Composer behavior suffices).
  • You require plugin support (currently unsupported; see TODO in README).
  • You need advanced asset routing (e.g., per-environment overrides) beyond this package’s scope.
  • Composer’s Custom Installers are already handled by another solution (e.g., proprietary tools).

How to Pitch It (Stakeholders)

For Executives: "This package solves a technical debt problem for our documentation workflows. Currently, maintaining phpDocumentor templates in non-standard locations requires manual workarounds (symlinks, scripts), which slows down releases and onboarding. By adopting this Composer installer, we’ll automate asset placement—saving ~2 hours/quarter in maintenance—while keeping our docs tooling aligned with industry standards. The risk is low: it’s a battle-tested solution for phpDocumentor’s ecosystem, and we can fallback to custom scripts if needed."

For Engineering: *"The phpdocumentor/unified-asset-installer lets us ditch hacky post-install steps for templates/plugins. Here’s how it works:

• What it does: Adds a phpdocumentor-template Composer type that installs assets to /data/template (configurable) instead of /vendor.
• Why it’s better: No more fighting Composer’s defaults or writing one-off scripts. Just update composer.json with the type and dependency, and it ‘just works.’
• Limitations: No plugin support yet (track TODO), but we can assess that gap later.
• Migration path: Low effort—replace any manual symlinks with this installer and update composer.json for affected packages.
• Alternatives: Only consider if we need plugin support or advanced routing; otherwise, this is the simplest solution."*

For Developers: *"If you’re tired of ln -s /vendor/... /data/template or editing composer.json after every install, this package automates it. Just:

1. Add "type": "phpdocumentor-template" to your template’s composer.json.
2. Require phpdocumentor/unified-asset-installer.
3. Run composer install—assets go to /data/template automatically. Pro tip: Check the FAQ for the naming quirk (must be alphabetically after ‘template’)."*