Getting Started

Install the package with Composer using its documented Laravel install command, then run the package’s generator/install command from the Laravel application root.
Look first at the generated Dockerfile, docker-compose.yml, .dockerignore, and any generated startup script. In v0.6.1, verify that the Dockerfile uses two separate PHP images: one for the build stage and one for the runtime stage, both pinned by digest.
Set the PHP version/branch in the package config before generating. v0.6.1 validates PHP branch selection, so unsupported values should fail early rather than producing a broken image.
First use case: generate Docker scaffolding for a Laravel app, build the image, start the app locally, and use the same generated files in CI. Commit the generated Docker assets so local and CI behavior stay aligned.
If your package version bundles startup and Docker-ignore templates, you can start without manually copying stubs. Publish templates only when you need to customize them.

Implementation Patterns

Treat generated Docker files as application source: commit them, review diffs on package upgrades, and regenerate them in a dedicated upgrade branch rather than editing generated output by hand.
Use the build/runtime split intentionally. Install Composer dependencies, Node assets, and PHP extensions in the build stage, then keep the runtime image minimal. Both PHP images should remain digest-pinned.
Publish and override only the templates you actually need. Keep overrides small and diff them against the package’s bundled templates after upgrades, especially for the startup script and .dockerignore.
In CI, generate the scaffolding, validate the configured PHP branch, build the image, and run a container smoke test. A matrix build is useful when supporting multiple PHP branches.
Reuse the same generated Dockerfile for local Compose and CI builds to reduce drift. Inject environment-specific values at runtime rather than baking them into the image.
When upgrading PHP, update the configured PHP branch and both PHP image digests together, then regenerate and rebuild. This keeps the build and runtime images on the same intended PHP line.

Digest pinning is deliberate. Avoid replacing pinned images with floating tags such as php:8.x; instead, establish a routine for updating digests through Renovate, Dependabot, or an internal script.
v0.6.1 bundles startup and Docker-ignore templates, so generated files may change after an upgrade. Re-check the startup script permissions, line endings, and .dockerignore rules after regenerating.
PHP branch validation can reject values that previously “worked” by accident. Use the package’s supported branch names rather than arbitrary image tags.
With separate build and runtime images, do not assume build-stage packages exist at runtime. Verify required PHP extensions, users, permissions, and startup behavior in the final runtime stage.
If you customize templates, publish them first; otherwise regeneration may overwrite your edits. Keep custom startup logic in an explicitly published template or a small wrapper.
For debugging, regenerate and inspect the Dockerfile before running docker build. Use no-cache builds and CI logs to distinguish template-generation issues from Docker build or runtime failures. Compare generated files against the package’s bundled templates after each upgrade.