README

A CLI that lets you build Laravel packages without a host Laravel app. Run zonda commands from inside a package directory and Zonda transparently boots a Laravel sandbox, links your package into it, and runs artisan against it — so package work feels like working inside a regular Laravel project.

Built on Laravel Zero.

How it works

1. zonda new vendor/name scaffolds a package skeleton (composer.json, ServiceProvider, Pest tests, etc.) and pins it to one or several Laravel majors (9–13).
2. Inside that package, zonda make:* writes files directly into src/, database/, resources/, tests/ — no sandbox round-trip, fast and offline.
3. zonda artisan <anything> lazily creates a sandbox at ~/.zonda/sandboxes/laravel-{N}/ (one per Laravel major), wires the package in via a Composer path repository + symlink, and runs php artisan there. A package pinned to multiple majors uses the highest by default; --laravel=N switches to any other pinned version.
4. zonda test runs Pest/PHPUnit inside the package itself against its own vendor/.

A package is identified by extra.zonda.package: true in its composer.json. Supported Laravel majors live at extra.zonda.laravel as an array (e.g. [10, 11, 12]); a single int is also accepted for backward compatibility. Sandboxes are version-keyed, so a Laravel 10 package and a Laravel 13 package coexist with their own installs and don't fight over composer state.

Requirements

• PHP ^8.2
• Composer on PATH (used to build sandboxes)

Install

Composer global

composer global require laramint/laravel-zonda -W

The -W (--with-all-dependencies) flag is recommended: Composer's global namespace often has other CLIs installed that pin illuminate/* to older majors, and without -W you'll see errors like "fixed to v11.x (lock file version) by a partial update". -W lets Composer upgrade those locked transitive deps to satisfy Zonda's requirements.

Make sure Composer's global bin is on your PATH (usually ~/.composer/vendor/bin or ~/.config/composer/vendor/bin), then:

zonda --help

If you'd rather not touch your global Composer state at all, use the PHAR install below — it's self-contained and won't conflict with anything.

PHAR

Download the latest release directly:

curl -L https://github.com/laramint/laravel-zonda/releases/latest/download/zonda -o zonda
chmod +x zonda
sudo mv zonda /usr/local/bin/zonda
zonda --version

To pin a specific version, replace latest/download with download/vX.Y.Z:

curl -L https://github.com/laramint/laravel-zonda/releases/download/v0.1.0/zonda -o zonda

Or browse the GitHub releases page and grab the zonda asset manually.

Quickstart

zonda new acme/widget --laravel=12     # scaffold a package pinned to Laravel 12
cd widget
zonda make:command SayHello             # writes src/Console/Commands/SayHello.php
zonda make:model Post                   # writes src/Models/Post.php
zonda make:migration create_posts_table # writes database/migrations/<timestamp>_create_posts_table.php
zonda artisan migrate                   # boots the L12 sandbox, links the package, runs artisan migrate
zonda test                              # runs Pest in the package

Commands

Top-level

Generators (make:*)

All generators are run from inside a package directory and write into the package itself. Most accept a single {name} argument and a --force flag to overwrite an existing file. Names like Blog/Post or Blog\Post create subfolders/sub-namespaces.

The generated package

zonda new produces a skeleton with:

acme/widget/
├── composer.json
├── README.md
├── phpunit.xml.dist
├── src/
│   └── WidgetServiceProvider.php
└── tests/
    ├── ExampleTest.php
    ├── Pest.php
    └── TestCase.php

composer.json carries the markers Zonda needs:

{
    "extra": {
        "zonda": { "package": true, "laravel": [10, 11, 12] },
        "laravel": { "providers": ["Acme\\Widget\\WidgetServiceProvider"] }
    }
}

The pinned majors drive:

• which sandbox zonda artisan runs against (highest by default, overridable with --laravel=N)
• the illuminate/support constraint — ^10.0|^11.0|^12.0 for the example above
• the matching orchestra/testbench constraint (union from the version matrix)

A package pinned to a single major still works exactly the same — extra.zonda.laravel: 12 and extra.zonda.laravel: [12] are both accepted, and resolve to a one-element major set.

Testing against every pinned version

Because each pinned major has its own sandbox, you can sanity-check your package end-to-end on the whole matrix:

zonda artisan --laravel=10 list
zonda artisan --laravel=11 list
zonda artisan --laravel=12 list

Each run uses its dedicated ~/.zonda/sandboxes/laravel-{N}/ install with your package linked in.

Auto-loading ServiceProvider

The generated ServiceProvider is conventions-aware: it auto-registers anything it finds on disk, so you can just run make:view, make:config, make:migration, etc. and the loader picks them up without you editing the provider. What gets wired up if it exists:

<shortName> is the package's kebab name (e.g. acme/widget → widget). The provider uses dirname(__DIR__) to find the package root, which is correct because it lives at src/<ProviderClass>.php.

The sandbox

State lives under ~/.zonda/sandboxes/laravel-<N>/:

~/.zonda/sandboxes/
├── laravel-10/         # full Laravel 10 install (only created on first L10 zonda artisan)
│   ├── composer.json   # has a path repo + require pointing at your package
│   └── state.json      # { "linked": "/path/to/the/currently-linked/package" }
├── laravel-12/
└── laravel-13/

zonda artisan ... is the only command that needs the sandbox; make:* and new are offline. Linking is cached in state.json, so repeated artisan calls from the same package don't re-run composer update.

To rebuild from scratch you can use the dedicated command, which is safer than rm -rf because it also re-links the package immediately:

zonda resync --reset              # nuke + rebuild the default-pinned sandbox
zonda resync --reset --all        # do that for every pinned Laravel major

Or, equivalently, the manual route:

rm -rf ~/.zonda/sandboxes/laravel-12   # forces a fresh L12 sandbox on next zonda artisan

What if I move the package directory?

You usually don't need to do anything — zonda artisan ... detects that state.json's cached path no longer matches the current package root, drops the stale path-repo entry from the sandbox's composer.json, writes the new one, runs composer update <vendor/name>, and updates state.json. Next call is back to the fast path.

If that auto-heal doesn't kick in (e.g. you have two clones of the same package and the state happens to match the wrong one, or the sandbox's vendor tree got corrupted), force it explicitly:

cd /new/location/of/the/package
zonda resync                # forces a fresh link from this directory
zonda resync --all          # do it for every pinned Laravel major
zonda resync --reset        # nuke the sandbox first, then re-link

Adding your own top-level commands

Drop a class under app/Commands/ extending LaravelZero\Framework\Commands\Command. Laravel Zero auto-discovers it.

namespace App\Commands;

use LaravelZero\Framework\Commands\Command;

class DoThingCommand extends Command
{
    protected $signature = 'do:thing {name} {--force}';
    protected $description = 'Do a thing.';

    public function handle(): int
    {
        $this->info("Doing {$this->argument('name')}");
        return self::SUCCESS;
    }
}

For new make:* generators, extend App\Support\AbstractMakeCommand and implement stubName(), relativeTargetPath(), and replacements(). Use $this->parseName($name) for free Blog/Post subfolder support, and $this->targetNamespace(...) / $this->targetPath(...) to compose the namespace and file path.

Updating

PHAR install

zonda update          # download and replace the running PHAR
zonda update --check  # just compare current vs. latest, don't download
zonda update --force  # re-download even if already on the latest version

How it works: the command fetches releases/latest from the GitHub API to learn the newest tag, compares it to the version baked into the PHAR (zonda --version), then downloads the zonda asset for that tag into <binary-path>.new, sanity-checks that it's a real PHAR, sets it executable, and renames it over the running binary. The rename is atomic on Unix — the in-memory PHP process keeps running off the old inode, and the next invocation picks up the new file.

If the binary lives somewhere root-owned (/usr/local/bin/zonda is typical), you'll need:

sudo zonda update

Composer global install

composer global update laramint/laravel-zonda -W

Running zonda update on a Composer install will detect that case and print this command for you — it won't try to overwrite Composer-managed files.

Build the PHAR locally

php zonda app:build zonda --build-version=0.1.0
# → builds/zonda

If you get Failed to compile the application., your PHP has phar.readonly=On (the default on most distros and Homebrew). Two ways to fix it:

# Quick: permanently flip it in your loaded php.ini
php -r 'echo php_ini_loaded_file().PHP_EOL;'
# edit that file → set:  phar.readonly = Off

# Or build via box directly (no wrapper subprocess to worry about):
php -d phar.readonly=0 vendor/laravel-zero/framework/bin/box compile --config=box.json

CI doesn't hit this — the release workflow sets phar.readonly=Off explicitly via shivammathur/setup-php.

Development

git clone https://github.com/laramint/laravel-zonda.git
cd laravel-zonda
composer install
./vendor/bin/pest

License

MIT