Sail Laravel Package

Getting Started

This package is a container-based local runtime for Laravel (Sail-style): it wraps Docker Compose behind a CLI so the whole team runs the same PHP, database, cache, and queue versions without touching host PHP. v3.8.6 is a security-driven runtime release, so treat "upgrade" as "rebuild and redeploy," not "composer update and move on."

Minimal steps for a project already using it:

1. Bump the package constraint to ^3.8.6 and re-publish/refresh the compose file if it's published into the repo.
2. Confirm the selected PHP runtime (8.3–8.5 are the versions moved onto Alpine 3.24).
3. Tear down and rebuild without cache: sail down → docker compose build --no-cache → sail up -d.
4. Verify inside the container: sail php -v and confirm the patch level is at or above the fixed release.
5. Run sail artisan migrate --force (or your normal migrate) and sail test before telling anyone the upgrade is done.

Where to look first: the published compose file (base images, PHP tag, Alpine version), the .env knobs that select runtime and ports, and the CLI wrapper's command list. Then read the v3.8.6 changelog entry itself — the "builds intentionally fail" clause is the single most important sentence in it.

First real use case: on an existing app, the upgrade. On a new app, booting the stack and immediately running the test suite in-container so you're validating against the shipped runtime rather than whatever PHP is on the developer's laptop.

Implementation Patterns

• Wrap everything through the CLI. sail artisan, sail composer, sail npm, sail test. Host-level php/composer calls silently validate against the wrong runtime and defeat the point of the package.
• Pin the package version. Treat the Sail version as infrastructure, not an app dependency. A ^3.x float means a security rebuild can land as a surprise mid-sprint; pin exactly when you have a release window.
• Standardise the upgrade choreography. down → build --no-cache → up -d → version check → test suite. Add it as a documented runbook or a make upgrade target; ad-hoc up --build leaves stale layers behind.
• Cache policy split by environment. v3.8.6 clears caches on local boot instead of baking them at build time. So local dev gets a guaranteed-clean cache every boot; anything that needs warm caches (perf checks, prod-parity smoke tests) must explicitly run sail artisan optimize as a step.
• CI parity. Build the same image in CI with the same pinned tag, then run tests inside it. Do not let CI use a different PHP patch level than developers — that's exactly the drift this release guards against.
• Add a runtime security assertion. A cheap CI step that greps the container's PHP version and fails below the fixed patch keeps the PHP2Shell class of problem from re-entering via a stale image or a rolled-back tag.
• Matrix the PHP versions you actually support. The Alpine 3.24 baseline now covers 8.3, 8.4, and 8.5, so a small matrix build is a realistic way to catch version-specific breakage before a developer hits it.
• Keep static-analysis baseline churn isolated. v3.8.6 tolerates Redis stub differences in the PHPStan baseline; regenerate baselines in their own commits so feature PRs don't drown in analysis noise.

Gotchas and Tips

• A failed image build after this release may be correct behaviour. The build intentionally fails until the configured Alpine repository serves fixed PHP packages. Before you debug your Dockerfile, check whether the failure is the runtime guard doing its job.
• Don't sit on v3.8.5 to unblock. That reintroduces a PHP2Shell-vulnerable runtime. If you must delay, treat it as a time-boxed, documented risk with the stack off any untrusted network path, not as a quiet workaround.
• Rebuild is mandatory, not optional. Existing containers keep running the old base image indefinitely. If only one team member rebuilds, you now have two different PHP patch levels in one codebase — the worst of both worlds.
• down before up. Reusing containers across an image change produces confusing mixed state (old entrypoint, new binary, or vice versa). Volumes are only removed when you explicitly ask for it, so down is cheap.
• musl/Alpine friction is real. Alpine 3.24 means glibc-linked prebuilt binaries and some PECL extensions need build tooling or a different install path; expect first builds to be slower and occasionally to need extra apk packages.
• Don't benchmark the first request after boot. Boot-time cache clearing means the app starts cold by design. Warm it deliberately with artisan optimize if you're measuring anything.
• Beware stale-cache false negatives. Cache clearing at boot fixes the classic "works in container, stale locally" class of bug — but if you've customized the boot entrypoint or added your own startup script, verify it still runs before or after the clear in the order you expect.
• Extension points: prefer project-level compose overrides and .env knobs (PHP version, ports, service selection) over editing vendor-published files, so the next runtime release doesn't conflict with local edits.
• Debugging ladder: sail logs for entrypoint problems, docker compose config to confirm which image tag is actually resolved, then build output for base-package/Alpine repo errors. Most "it broke after upgrade" reports land in one of those three.