Aloe Laravel Package

Getting Started

Aloe is a global CLI that wraps the boring parts of a Leaf app: scaffolding, serving, and installing Leaf packages with their config side effects. It is not a Laravel Artisan replacement — think "project bootstrapper + package installer + dev server" rather than a full task runner.

Minimum viable setup:

composer global require leafs/aloe
# make sure Composer's global bin dir is on PATH
export PATH="$HOME/.config/composer/vendor/bin:$PATH"   # Linux/macOS
# Windows: %APPDATA%\Composer\vendor\bin

aloe --version
aloe list          # this is the first thing to read

First day workflow:

aloe new my-app          # interactive; scaffolds a Leaf skeleton
cd my-app
aloe serve               # dev server, default host/port depends on version
# open http://localhost:<port>, edit your route file, refresh

For an existing project, Aloe infers context from the current working directory, so run it from the app root. If you want reproducibility across a team, also install it locally (composer require --dev leafs/aloe) and invoke vendor/bin/aloe; the global binary is convenient, the local one is version-pinned.

Your first real use case should be package installation, because that is where Aloe adds value over raw Composer:

aloe install leafs/auth
# vs. composer require leafs/auth + manually wiring config/env

Check the git diff after that command — Aloe runs the package's install hook, which may publish config, touch .env, or modify bootstrap files.

Implementation Patterns

Bootstrap → serve → install loop. Use aloe new to create the skeleton, aloe serve as the inner-loop server, and aloe install/aloe uninstall whenever you add or remove a Leaf package. Treat aloe uninstall as the mirror of install; don't hand-reverse a package's config changes.

Composer scripts as the stable interface. Aloe commands change between majors; your team's muscle memory shouldn't. Wrap them:

{
  "scripts": {
    "serve": "aloe serve",
    "setup": ["composer install", "aloe install leafs/auth"]
  }
}

Then composer serve works regardless of whether Aloe later moves to vendor/bin or a different binary name.

Docker/CI pattern. Install Aloe globally in the image and use it for setup steps, but don't use aloe serve as a production server:

RUN composer global require leafs/aloe
ENV PATH="/root/.config/composer/vendor/bin:${PATH}"
CMD ["aloe", "serve", "--host=0.0.0.0"]

For containers you usually need an explicit host binding; the default binds to localhost and will be unreachable from outside the container.

Custom commands as a task runner. Aloe's real leverage is turning repeated project chores into aloe <task>. The shape is a command class registered with the CLI:

namespace App\Console;

use Aloe\Command;

class SeedDemoCommand extends Command
{
    protected $name = 'seed:demo';
    protected $description = 'Seed demo data';

    protected function handle(): int
    {
        // call your app code here
        $this->output->writeln('Seeded.');
        return 0;
    }
}

Register it in whatever hook your Aloe version exposes (inspect the package source or existing service providers — this is under-documented). If registration is awkward in your version, keep the command as a plain PHP script and expose it through a Composer script instead; don't fight the tool.

Package install is a workflow, not a one-liner. The pattern that works:

1. git status clean.
2. aloe install leafs/<pkg>.
3. Read the diff; verify .env and config changes.
4. Run the app (aloe serve) and exercise the new feature.
5. Commit install output as one atomic commit.

That makes aloe uninstall safe to reason about later.

Scaffolding as a starting point, not a source of truth. Generated controllers/models/routes are meant to be edited immediately. Don't re-run generators over files you've already customized unless you've checked the overwrite behavior.

Gotchas and Tips

• Global binary, project version skew. A globally installed Aloe can be newer or older than the Leaf version in your app. Pin the global version (composer global require leafs/aloe:^x.y) and document it, or prefer vendor/bin/aloe locally. This is the most common source of "works on my machine."
• PATH is the #1 install failure. Composer's global bin directory is not always on PATH, especially on Windows (%APPDATA%\Composer\vendor\bin) and in minimal Docker images. aloe: command not found almost always means PATH, not a missing install.
• Context detection is cwd-based. Run Aloe from the project root. Running it from a subdirectory, or from a parent containing multiple Leaf apps, can pick the wrong app or fail with a confusing error.
• Install hooks are opaque and not guaranteed idempotent. aloe install may edit .env, config files, and bootstrap code. Always inspect git diff; never run it on a dirty tree in CI without knowing what it does. aloe uninstall can leave artifacts behind.
• Don't ship aloe serve. It's a development convenience (typically a thin wrapper over PHP's built-in server). No TLS, no concurrency tuning, no process supervision. Use nginx + php-fpm or an equivalent for anything real.
• No hot reload. You get a server, not a watcher. Pair it with watchexec, entr, or your editor's save hooks if refresh-on-change matters.
• Windows quirks. The binary may be invoked as aloe.bat; symlink and permission behavior differs. Prefer running inside WSL or a container if you hit odd failures.
• Debugging: try aloe list to confirm the command exists, aloe <cmd> -v/-vvv for verbosity if it's Symfony Console–based, and composer global show leafs/aloe to confirm what's actually installed. When output is unhelpful, read the command class in the package source — with 5 stars and near-zero dependents, the source is often better documentation than the docs.
• Low-adoption risk. Sparse documentation, few examples, and breaking changes between majors are expected. Budget time for source reading, avoid depending on undocumented flags, and keep raw composer require / php -S equivalents in your README so the team isn't blocked if Aloe misbehaves or is abandoned.
• Extension surface is thin. The durable extension points are package install hooks and app-level custom commands. If you need deeper integration, wrap Aloe in your own scripts rather than patching the global install.
• Port collisions. If aloe serve fails to bind, pass an explicit port; check for a stale PHP process left behind by a previous run.
• Never run as root in development unless you're inside a disposable container; generated file ownership will bite you later.