Getting Started

laradox wraps Docker Compose orchestration into Artisan commands, so the mental model is: your docker-compose.yml is the source of truth, and every command reads service state from it.

Minimal path to first value:

Install and publish config — the package needs to know where your compose file lives and what your service names are (app, web, db, redis, queue, octane, etc.):
```
composer require laradox/laradox
php artisan vendor:publish --tag=laradox-config
```
Look at config/laradox.php first. Everything downstream — health gates, deploy steps, in-container command execution — resolves service names from this file. Getting the mapping right here saves you from debugging "container not found" later.
First use case — see what you actually have running:
```
php artisan laradox:status
```
This is the best onboarding command because it reports every service in the compose file, including ones with no container yet, so it doubles as a "did I forget to start something?" check on a fresh clone. Add --stats when something feels slow — per-container CPU/memory/network shows you immediately whether the queue worker or MySQL is the problem.
Then wire the same command into your muscle memory with --watch --interval=5 while bringing a stack up, and --json once you start scripting against it.

Implementation Patterns

CI / pre-deploy health gate. laradox:status exits non-zero when anything is not running or not healthy, which makes it a drop-in gate with no parsing:

php artisan laradox:status --json > status.json || { echo "stack unhealthy"; exit 1; }

Use --json when you want the artifact for the CI log; use the plain exit code when you just want to fail fast.

Deploy pipeline as a single command. laradox:deploy is the composed happy path: pull → maintenance mode → build → start → health gate → composer install → assets → migrate → cache warm-up → back out of maintenance. The value is that a failure takes the app back out of maintenance mode and tells you where to look, which is the part hand-rolled deploy scripts usually get wrong.

Recommended shape for a real pipeline:

php artisan laradox:deploy --dry-run          # in PR / review, prints the plan
php artisan laradox:deploy --force           # in CI, non-interactive

Trim steps per environment rather than maintaining separate scripts:

# workers-only host, app already deployed elsewhere
php artisan laradox:deploy --force --no-build --no-assets --no-migrate

# frontend already built in CI
php artisan laradox:deploy --force --no-assets

--dry-run is the right thing to run first on any new project — it surfaces step ordering problems (e.g. migrations before the container is healthy) before they cost you a deploy window.

Optimize as a deploy step and as a local toggle. laradox:optimize is opinionated in a useful way: it dumps a class-map-authoritative autoloader, caches config/routes/views/events, and then reloads Octane workers so the new bootstrap cache is actually picked up. That last step is the one people forget when doing this by hand.

php artisan laradox:optimize                 # production
php artisan laradox:optimize --clear        # back to dev
php artisan laradox:optimize --skip-reload  # no Octane in this env

Because laradox:deploy already calls it (--no-optimize to skip), you shouldn't need to invoke it manually in the deploy path — keep the manual invocation for hotfixes and local "does this behave like prod?" checks.

Benchmark to compare releases, not to chase absolute numbers. Run from the host against published ports, capture --json, and diff the numbers between tags:

php artisan laradox:benchmark --json > bench-$(git describe --tags).json

The useful signals are p95/p99 latency and success rate; throughput on a shared dev machine is mostly noise. Warm-up requests are already excluded, so consecutive runs are comparable without you warming the app yourself.

Watch mode in local dev. laradox:status --watch --interval=5 is the "why did my queue stop" command. Because it lists services with no container too, adding a new service to the compose file and forgetting to up -d shows up immediately instead of as a confusing missing-queue bug.

Build your own commands on InspectsContainers. The new shared concern (container inspection, resource sampling, health polling, in-container exec) is the real extension point of this release. If you have project-specific orchestration — seeding demo data, rotating logs, running a profiler inside the app container — implement against this concern rather than shelling out to docker yourself, and you inherit the same health/state semantics the first-party commands use.

Scheduling. laradox:status --json fits naturally into routes/console.php / the scheduler as a recurring heartbeat, with a notification on non-zero exit.

Gotchas and Tips

--force is required for non-interactive deploys. Without it, laradox:deploy assumes interactive and will hang a CI job rather than fail. Same class of issue with laradox:optimize in a development environment — it asks for confirmation first, so any scripted dev-environment optimize needs to account for the prompt.
--no-dev is only passed to Composer in the production environment, by design. Don't expect to force dev-dependency pruning in staging via a flag; it won't happen, and that's usually correct.
Don't --clear on production casually. It reverts the class-map autoloader and all bootstrap caches. On an Octane host this is the difference between a working and a very slow/odd app until you re-optimize.
Class-map-authoritative autoload means dynamically generated classes can 404. If you use runtime class generation, package discovery tricks, or eval-based factories, a plain composer dump-autoload in your pipeline and laradox:optimize will diverge. Test the optimized path before shipping, not after.
--skip-reload exists for environments without Octane. If cache changes appear not to take effect, the first question is whether Octane workers were reloaded — if you skipped the reload, they're still serving the old bootstrap.
Health gating needs a real healthcheck. laradox:status reports healthcheck result; a service with no healthcheck defined in compose can't be "healthy", so your exit-code gate will be weaker than you think. Define healthchecks for app, db and redis at minimum.
Services without containers are reported, not ignored. That's a feature for spotting forgotten services — but in scripts, filter on state rather than assuming every entry in --json is a live container.
Benchmarking from the host requires published ports. Containers reachable only on the internal Docker network can't be load-tested by laradox:benchmark. Also expect container CPU/memory limits (visible via laradox:status --stats) to dominate results long before your concurrency setting does.
Pipe --json carefully. If a command emits warnings or notices to stdout, | jq will choke. Capture to a file and validate before parsing, especially in deploy scripts that run other commands first.
Debugging a stuck deploy: the failure message tells you where to look, but the state you most need is whether maintenance mode was exited — check that first, then laradox:status, then the step's own logs. A deploy that fails before the health gate leaves the app in maintenance mode only if it got that far.
Ordering assumption to verify on your project: the deploy runs migrate and cache warm-up after the health gate. If your app can't boot without a pending migration, laradox:status will never go healthy and the deploy will stall — either pre-migrate or gate on container-running rather than app-healthy for that project.
--dry-run doesn't validate the steps, only prints the plan. A clean dry-run is not a rehearsal; treat it as a documentation aid.

Laradox Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips