Installer Laravel Package

Getting Started

pug/installer is a minimal Composer-side utility for the pug-php ecosystem. It is not a template engine — it exists to make Composer aware of Pug-related packages/assets so they can be placed and wired correctly during composer install/update. Treat it as plumbing, not a runtime dependency you call directly.

Minimal steps:

composer require pug/installer
# almost always alongside the engine itself
composer require pug-php/pug

1. Look at the package's own composer.json first. For a package this small, the manifest is the documentation: check its type (likely composer-plugin or composer-installer), its extra block, and any scripts/class wiring. That tells you exactly what it hooks into.
2. Then look at your root composer.json. Any installer util is governed by top-level config — extra, scripts, config.allow-plugins, and install paths. Most "it doesn't work" reports come from here, not the package.
3. Confirm the plugin is actually enabled. With Composer 2.2+ you must explicitly allow Composer plugins:

{
  "config": {
    "allow-plugins": {
      "pug/installer": true
    }
  }
}

First realistic use case: you are adding Pug templating to a PHP/Laravel app, and you want the Pug package's assets or config surfaced through Composer rather than copied by hand. Add pug/installer and pug-php/pug, run composer update, and verify the installer's effect landed where you expect (vendor path, config stub, or asset dir). If nothing visibly changes, the package is a no-op helper for a sibling package and you should read the sibling's docs for the actual behavior.

Implementation Patterns

Keep it as a transitive/composer-time dependency. You will rarely use classes from this package in application code. The normal pattern is:

• Require pug-php/pug for rendering.
• Let pug/installer (pulled in or added explicitly) handle Composer-level packaging concerns.
• Never call installer internals from controllers/services; if you find yourself needing to, you have the wrong abstraction.

Allow-plugins as project policy. Because it is an installer util, encode the allow-list in composer.json and commit it. In CI, run composer install --no-interaction and fail the build if Composer prompts for plugin approval — a prompt means the allow-list is missing.

Lock-file discipline. With a package last released in 2020 and near-zero adoption, treat composer.lock as your safety net. Pin exact versions in composer.json if you must keep it:

"require": { "pug/installer": "0.1.*" }

and review composer.lock diffs. Avoid ^ ranges on a 2-star, unmaintained package unless a sibling package constrains it anyway.

Laravel integration shape. In a Laravel app the practical workflow is:

1. composer require pug-php/pug pug/installer
2. Configure Pug's cache/compiled path inside config/view.php (or a dedicated config/pug.php published from the engine package).
3. Render via a thin service or view adapter; keep Pug out of Blade.
4. Expose a composer script for cache warm-up so deployment clears compiled templates:

"scripts": {
  "post-autoload-dump": ["@php artisan view:clear"]
}

Debug/verbose invocation. When the installer appears to do nothing:

composer install -vvv
composer diagnose

-vvv shows installer plugin class resolution and any path decisions. composer why pug/installer confirms whether it is direct or transitive.

Extension points. Installer utils typically expose behavior through extra in the root manifest and through Composer events (post-install-cmd, post-autoload-dump). If you need custom placement or post-install steps, do it in your root composer.json scripts rather than forking the package.

Gotchas and Tips

• Abandonment risk is the headline. Last release 2020-10-31, 2 stars, 0 dependents. Do not build core architecture on it; use it only if a sibling pug-php package requires it, and document the pin. Have a migration note for dropping it.
• Composer 2.2+ plugin approval is the #1 silent failure. Without config.allow-plugins, Composer skips or prompts for the plugin — your installer "works" in dev and fails in CI/Docker. Always commit the allow-list.
• "Installer" ≠ "installation of your app." This package does not install the Pug binary, does not compile templates, and does not register Laravel service providers. If you expect composer require alone to give you working Pug rendering, add pug-php/pug and read its docs.
• No dependents means no community-tested edge cases. Assume path resolution, Windows separators, and non-standard vendor-dir are less exercised than in popular Composer installers. Test in Docker/CI early.
• Autoload quirks. Check the package's autoload section before referencing any class. A "minimal util" may ship a single class via classmap or files; a wrong use statement will fail only at runtime.
• Plugin ordering. If you also use other installers (e.g., asset installers), install order in require can matter. Keep Composer plugins listed explicitly so the resolution order is deterministic.
• Extension points to prefer: root composer.json scripts and extra, plus config.allow-plugins. Avoid editing the package in vendor/ — it will be clobbered on the next composer update.
• Debug checklist when it misbehaves: composer diagnose → confirm plugin allowed → composer show pug/installer (version, type) → composer install -vvv (installer class and paths) → inspect vendor/pug/installer/composer.json for intended hooks. If the package has no observable effect, that is expected: its job is to support a sibling package, and your bug is almost always in the sibling's config or your root extra.
• License is MIT — fine for commercial use, but MIT says nothing about maintenance. Pair the pin with a scheduled review.