Laravel Flora Laravel Package

Getting Started

Laravel Flora collapses the "install a fresh app" and "update a deployed app" ritual into two Artisan commands: flora:install and flora:update. Instead of maintaining a shell script full of composer install && cp .env.example .env && php artisan key:generate && npm install && php artisan migrate && php artisan storage:link, you define those steps in config/flora.php and let Flora run them with a single, consistent entry point.

Minimal steps:

1. Install the package. If you intend to use it on production deploys, put it in require, not require-dev — otherwise composer install --no-dev will strip the command before it can run.

   composer require qruto/laravel-flora
   

2. Publish the config:

   php artisan vendor:publish --provider="Qruto\Flora\FloraServiceProvider"
   

3. Look at config/flora.php first. It holds the install and update step lists — this file, not the package source, is where you will spend 95% of your time.
4. First use case: clone your repo on a new machine and run php artisan flora:install in place of the ad-hoc setup readme steps. For an existing checkout, php artisan flora:update re-runs install/update steps idempotently (dependencies, migrations, caches).

Treat the commands as deploy primitives, not as a scaffolder. The package does not create a Laravel app — it assumes laravel/laravel (or your app skeleton) is already there.

Implementation Patterns

Replace readme setup blocks with a config file. Move every step from the "getting started" section of your README into config/flora.php:

// config/flora.php
return [
    'install' => [
        'composer install',
        'cp .env.example .env',
        'php artisan key:generate',
        'php artisan migrate',
        'php artisan storage:link',
        'npm install',
        'npm run build',
    ],
    'update' => [
        'composer install --no-dev --optimize-autoloader',
        'php artisan migrate --force',
        'php artisan optimize:clear',
        'php artisan config:cache',
        'php artisan route:cache',
        'php artisan view:cache',
    ],
];

Keep install idempotent-friendly (fresh clone) and update deploy-safe (non-interactive, --force on migrations).

Split install vs. update by audience. install is for humans onboarding locally and for first-time provisioning of a server. update is for repeat deploys. Do not put key:generate or .env copying in update — regenerating the key on a live app will invalidate encrypted cookies and sessions.

Call Flora programmatically from your own deploy command. The Flora facade exposes the same actions, so you can wrap them inside a custom Artisan command and add your own logging, Slack notification, or maintenance-mode toggling:

use Qruto\Flora\Facades\Flora;

Artisan::command('deploy', function () {
    $this->call('down', ['--retry' => 10]);
    try {
        Flora::update()->run();
        $this->info('Deployed.');
    } finally {
        $this->call('up');
    }
});

This is the most durable pattern: Flora stays the implementation of the step list, your command remains the contract your team runs.

Layer project-specific steps on top. After Flora::update(), append your own actions (seeding feature flags, warming an S3 cache, pinging a health endpoint). Flora is deliberately thin — it is a runner, not a workflow engine.

Wire it into CI/Deployer/Envoyer as a single line. One php artisan flora:update call is easier to audit in a GitHub Actions or Deployer recipe than six chained shell commands, and the step list lives in version control next to the code instead of in YAML.

Use it to make "run the app" one command for new teammates. Document composer install && php artisan flora:install (or simply flora:install after clone) as the onboarding entry point. This is the highest-value day-to-day use: onboarding never drifts because the steps are edited by the same PRs that change the app.

Gotchas and Tips

• Maintenance risk is the headline. Last release is April 2024 and the repo is small (130 stars). Pin the version in composer.json ("qruto/laravel-flora": "^1.0" style) and be prepared to fork or replace it with a custom Artisan command if it stops tracking Laravel's major versions. The API surface you rely on is one facade call plus a config array, so the exit cost is low — design your deploy command so it could be rewritten in an afternoon.

• require-dev will bite you on production. Because Flora typically runs after composer install --no-dev, it must be a runtime dependency. Add it to require even if it feels like tooling.

• Interactive prompts break unattended deploys. composer install and npm install can prompt (auth, package selection). Run flora:update with --no-interaction and ensure COMPOSER_AUTH / npm registry tokens are set in CI. If a step prompts, the deploy hangs, not fails — watch for timeouts.

• Config caching. If you run php artisan config:cache early in the update list, later edits to config/flora.php won't be visible until you clear it. Keep config caching at the end, or run config:clear before invoking Flora when debugging.

• Don't run flora:install on an existing app. It will overwrite .env (or fail trying) and re-run key:generate. Use update for anything that already exists; only use install on a fresh checkout or freshly provisioned box.

• Ordering matters, especially for migrations. Migrations must run after composer install (autoloader needs the app's dependencies) and before config:cache if your migrations touch config. Similarly, storage:link before any step that writes to public/.

• Debug a failing step with verbosity. Re-run with -v / -vvv to see the underlying process output. Because Flora streams subprocess output, the failing sub-command is usually visible in the tail of the log — grab that first before suspecting config parsing.

• Env-specific behavior belongs in .env, not the config array. Conditional steps (if (app()->environment('local')) {...}) inside your own deploy command are cleaner than trying to fork the config per environment.

• Extension point: if you need richer behavior, define your own step classes and reference them in the install/update arrays rather than stuffing multi-line shell into config strings. Strings are fine for one-liners; anything with branching, retries, or error handling should be a dedicated Artisan command called from the list.

• Verify after upgrade. Laravel major upgrades change Artisan command names and flags (optimize:clear, cache commands, migrate --force behavior). After a Laravel upgrade, dry-run flora:update in staging before trusting it in production.