Installer Laravel Package

Getting Started

The installer is a scaffolding tool, not a runtime dependency — it exists so you can type one command instead of remembering a composer create-project incantation. Install it once, globally, and forget about it:

composer global require laravel-zero/installer

Then make sure Composer's global bin directory is on your PATH (~/.composer/vendor/bin, ~/.config/composer/vendor/bin, or %APPDATA%\Composer\vendor\bin on Windows). Verify with laravel-zero list — you should see a new command and little else.

Scaffold your first app:

laravel-zero new my-app
cd my-app
php my-app

That last line is the important one: the project root contains a single executable named after your application. It behaves exactly like artisan, but it's the artifact you'll ship. Your first use case should be confirming the whole loop end-to-end: create a command, register it, run it, and build a PHAR.

php my-app make:command HelloCommand
# register in config/commands.php
php my-app hello
php my-app app:build
./builds/my-app hello

If anything in this flow surprises you, look at config/app.php (name, version, providers) and config/commands.php (command registration) — those two files explain 90% of Laravel Zero behavior.

First thing to read in the repo: the installer's NewCommand. It's small, and it tells you exactly which skeleton version it pulls and which post-install steps it runs. If you don't want a global install at all, the equivalent is composer create-project laravel-zero/laravel-zero my-app — reach for that whenever you need reproducibility.

Implementation Patterns

Scaffold-once, then never touch the installer again. The realistic day-to-day usage of this package is zero invocations after day one. Treat it like laravel new: a convenience wrapper. It has no config file, no plugin hooks, and no ongoing role in your app's lifecycle.

Pin for reproducible builds. The installer resolves the latest skeleton, which means two developers scaffolding on different days get different dependency trees. For anything that goes into CI, prefer:

composer create-project laravel-zero/laravel-zero my-app "10.*" --no-interaction

and keep the installer for local exploration only.

Rename immediately. The application name in config/app.php drives the binary filename. Scaffolding as my-app and later wanting deployer means editing config and renaming the executable. Decide the name before you scaffold; changing it later is annoying but not hard.

Post-scaffold checklist as a habit. The installer does not initialize git, add a license, configure a test runner beyond the default, or set up CI. Immediately after laravel-zero new:

1. git init and first commit (so you can diff your changes against the pristine skeleton).
2. Bump PHP constraint in composer.json to match your deployment target, not your dev machine.
3. Adjust the version in config/app.php — it's used by app:build and app:version.
4. Add a Box config if your build needs to exclude dev files.

Shared code across apps. Because each Laravel Zero app is standalone, extract reusable command logic into a private Composer package and composer require it into each scaffolded app. Don't try to share via the installer — it has no mechanism for custom skeletons.

Use it as a version-compatibility oracle. If you're unsure whether a PHP version is supported by the current skeleton, just run laravel-zero new and read the failure. It fails fast on unsupported PHP, which is faster than reading release notes.

Gotchas and Tips

• The installer shells out to Composer. If composer isn't on PATH in the environment where you run laravel-zero new, you'll get an opaque failure. This bites hardest in Docker and CI images.
• Global Composer dir permissions. In containers or on shared hosts, composer global require can land in a root-owned directory. Prefer COMPOSER_HOME pointed at a writable path, or skip the installer entirely.
• Name collisions. The app name becomes a binary name. Avoid names that shadow existing system binaries (test, make, node) or generic words. Also avoid names Composer would reject — use kebab-case.
• Interactive prompts hang in CI. The installer is interactive by default. Always check laravel-zero new --help for the non-interactive path before wiring it into a pipeline, or just use create-project --no-interaction.
• Stale global install. composer global update laravel-zero/installer periodically. A very old installer may not understand the newest skeleton layout — but note that updating it does not pin the skeleton; you still get whatever is latest.
• PHP version mismatch on older targets. The installer itself may require a newer PHP than the skeleton version you're targeting. If you need an older Laravel Zero, use composer create-project with an explicit version constraint and skip the installer.
• Debugging failures. It's a Symfony Console app, so -v, -vv, -vvv work. The underlying Composer output is usually where the real error is; the installer's own messages are terse.
• Extension points: essentially none. There is no config file, no environment variables, no custom-skeleton flag. If you need customization — private skeleton, extra post-install steps, org defaults — the correct answer is to fork laravel-zero/laravel-zero into your own skeleton repo and use composer create-project your-org/skeleton. Don't fight the installer.
• It's not the framework. Bugs in command registration, app:build, or provider bootstrapping live in laravel-zero/framework, not here. Route your issues accordingly — the installer's surface area is tiny.
• Low maintenance activity. With 22 stars this is a thin convenience layer maintained alongside the main project. Don't design architecture around it; a five-line composer create-project alias in your shell covers the same ground and survives upstream changes.