Installer Laravel Package

Getting Started

The installer is a Composer plugin, not a Laravel package you php artisan into — its job is to intercept installation of packages whose type field is one of three custom values and place them at project-root paths instead of vendor/. Minimal path to a working setup:

1. Require it as a dev dependency alongside spora-ai/spora-core:

   composer require --dev spora-ai/installer
   

   It ships as a composer-plugin type, so Composer will run it during install/update once the plugin is allowed (see Gotchas — Composer 2.2+ prompts).

2. Confirm the plugin is active:

   composer show spora-ai/installer
   

   and check composer diagnose doesn't flag the plugin as blocked.

3. Look first at the package composer.json of any Spora package you pull in. The routing decision is driven entirely by "type":

   • spora-plugin → plugins/{vendor-or-name}/
   • spora-frontend → public/spora/
   • spora-plugin-frontend → public/plugins/{slug}/

4. First real use case: composer require some-vendor/some-spora-plugin and watch the output. If the package declared "type": "spora-plugin", you should see it land in plugins/some-spora-plugin/ rather than vendor/some-vendor/some-spora-plugin/. That single observation tells you whether the installer is wired correctly for the rest of the stack.

If nothing lands outside vendor/, the culprit is almost always one of: plugin not allowed, package type not set correctly by the package author, or the installer not required at all in the root project (it must be in the root composer.json, not a dependency's).

Implementation Patterns

Understand the two consumers of this package. One is you, the app developer, requiring Spora packages. The other is the package author who declares type in their composer.json. You can't fix routing from the app side if the upstream package didn't declare a Spora type — you can only patch the package's composer.json (bad idea) or fork it.

Co-locate the installer with spora-core. The clean pattern is a Laravel app whose root composer.json has:

{
  "require": { "spora-ai/spora-core": "^x" },
  "require-dev": { "spora-ai/installer": "^x" }
}

Core provides the runtime (autoloading of plugins/, bootstrapping of the plugin manager); the installer provides the placement. Splitting them is why the installer is a separate package — it's a Composer-time concern, core is a runtime concern.

Plugin + frontend split pattern. A typical Spora plugin will ship as two Composer packages: a spora-plugin package containing PHP/backend code (lands in plugins/{name}/) and a spora-plugin-frontend package containing JS/CSS (lands in public/plugins/{slug}/). Both are pulled in the same composer require, and the installer routes each to the right tree. This is the workflow you'll repeat for every plugin you add — expect to see paired -frontend packages in the docs of whatever plugin you're installing.

Shared frontend assets. Packages typed spora-frontend (no -plugin- qualifier) land at public/spora/ — these are shared/vendor-level frontend assets (think a design system, shared JS runtime) as opposed to per-plugin bundles. If you're building your own Spora package, use spora-frontend for anything multiple plugins consume and spora-plugin-frontend for the plugin's own assets.

Asset building / Vite integration. Because these packages land under public/ rather than vendor/, they're directly web-servable. A frontend build step in your Laravel app can treat public/plugins/{slug}/ as a source directory. Be intentional about whether you compile from there or copy into a Vite entry — the installer does not (and cannot) run a build for you.

CI / Docker pattern. Since install locations are deterministic, add plugins/ and public/spora/, public/plugins/ to .gitignore when doing local dev, and rely on composer install in CI to repopulate them. This mirrors how you'd treat vendor/. If you'd rather commit them (some teams do for deploy simplicity), the paths are stable enough to check in — but you lose the "composer is the source of truth" property.

Upgrading. Because these are Composer-tracked, composer update some-vendor/some-spora-plugin will re-run the installer and replace the existing directory. There's no separate "plugin update" command.

Gotchas and Tips

• Composer 2.2+ plugin allow-list. Composer blocks plugins by default until you explicitly allow them. First install will prompt interactively; in CI (non-interactive) you'll need:

  "config": { "allow-plugins": { "spora-ai/installer": true } }
  

  in the root composer.json. Forgetting this is the #1 reason "the plugin isn't doing anything."

• Root-project only. The installer must be required in the root composer.json. If you require it only as a transitive dependency of some plugin, its Composer plugin hook may not fire the way you expect. Treat it as an app-level dependency.

• Paths are project-root relative and hardcoded. Based on the package description, the destination paths (plugins/, public/spora/, public/plugins/) are fixed. There is no env var or config to relocate them. If you run a non-standard Laravel skeleton (e.g. custom public_path), verify the actual output paths by running composer install -vvv and reading the installer's log lines. If they don't match your layout, you'll need to patch/fork — don't assume a config option exists.

• Debugging silently failing routing. Use composer install -vvv (three v's) or composer dump-autoload -vvv. The installer's plugin will emit routing messages. If you see the package going into vendor/, either (a) the plugin isn't loaded, or (b) the package's type isn't one the installer recognizes. Check both with composer show --all vendor/package | grep type and composer show spora-ai/installer.

• Autoload timing. Packages installed to plugins/ still have their own composer.json autoload rules, but they now live outside vendor/. Whether their autoload block is honored depends on the installer registering a Composer autoload path for the custom location (most custom installers do, but check). If Class not found errors appear for a plugin that "installed fine," inspect vendor/composer/autoload_psr4.php (or autoload_static.php) to see if the path was registered.

• Stale directories after rename. If a package renames itself or changes its slug, the installer writes a new directory but won't delete the old one at plugins/old-name/. Clean manually with rm -rf plugins/old-name public/plugins/old-slug.

• No artisan / no runtime extension points. Unlike a Laravel service provider, there's no register() or config file here. Extension happens entirely through the package's composer.json type field. If you want to override where something lands, the supported lever is upstream: ask the package author to change the type, or fork and change it yourself. Don't try to add a Laravel service provider to override paths — no such hook exists.

• Zero stars / zero dependents risk. With no dependents listed, treat the exact path conventions (plugins/{$name}, public/spora/, etc.) as possibly in flux across versions. Pin spora-ai/installer and spora-ai/spora-core to compatible minor versions and bump together. Read the CHANGELOG before composer update in production.

• Interaction with composer install --no-dev. If the installer is in require-dev (recommended) and you run composer install --no-dev in production, the plugin won't be present and your Spora packages will fail to route — they'll likely error out or land in vendor/ unbootstrapped. Either keep the installer in require for deploy, or run deploys with --no-dev but keep the installer explicitly required (its dependency footprint is tiny). This is the operational trap teams hit on first deploy.