Supaapps Laravel Api Kit Laravel Package

Getting Started

This package generates the Docker scaffolding for a Laravel application — Dockerfile, compose file, container entrypoint/startup script, and .dockerignore — from a selected PHP branch. v0.6.1 is a patch release that changes what the generator emits, not the API you call, so existing installs keep working but regenerated files will differ.

Minimal path:

1. composer require --dev <vendor>/<package> — it's a scaffolding tool, so it belongs in require-dev.
2. Publish the config in the same step if the package ships one; otherwise check the package's config/ directory in vendor/ first.
3. Find the command name with php artisan list (look for a docker/scaffold namespace), then run it against a throwaway Laravel app to see the output before touching a real project.
4. Inspect the generated Dockerfile — v0.6.1 emits a multi-stage build with two digest-pinned base images, e.g. a php:<branch>-cli (or -dev) build stage carrying Composer and build tooling, and a slimmer php:<branch>-fpm/-cli runtime stage, both pinned as image@sha256:… rather than floating tags.
5. docker compose build && docker compose up to confirm the generated stack boots — the release also bundles the startup and ignore templates, so a fresh generate should be self-contained with no missing stubs.

First real use case: run the generator on a new Laravel service to get a reproducible, digest-pinned image instead of hand-rolling a Dockerfile. The second use case is retrofitting an existing repo — generate into a temp directory, diff against your current Dockerfile, and cherry-pick.

Where to look first: the bundled templates directory inside the package (startup script and .dockerignore are now shipped rather than fetched), the PHP-branch argument validation, and the CI workflow that builds the generated image — that workflow is the best documentation of what "correct" output looks like.

Implementation Patterns

Regenerate, then diff — always. Because generated output changed in this release, treat the generated files as build artifacts you review:

git stash list   # clean tree first
php artisan <scaffold-command> --php=8.3 --force
git diff -- Dockerfile docker-compose.yml .dockerignore

Keep generated files in version control (you want reviewable Dockerfile changes), but never hand-edit and then re-run with --force without a diff.

Pin PHP branch explicitly. The release adds branch validation, so pass a real branch string (8.3, 8.4) rather than a tag fragment or 83. Validation now fails fast instead of emitting a Dockerfile referencing a nonexistent image — good, but it means any script that previously "worked" with a sloppy value will now error. Grep your CI and Makefiles for the invocation.

Separate build vs runtime images is the core pattern to lean into. Composer, php-dev, and docker-php-ext-install belong in the build stage; copy the resulting vendor/ and compiled extension .so files into the runtime stage:

FROM php:8.3-cli@sha256:<build-digest> AS build
# composer, node, build deps
RUN composer install --no-dev --optimize-autoloader

FROM php:8.3-fpm@sha256:<runtime-digest> AS runtime
COPY --from=build /app /app

If you add extensions, install them in the build stage and COPY --from=build /usr/local/lib/php/extensions/... into runtime — don't assume docker-php-ext-install works in runtime, because it won't without the toolchain.

Digest bumps as a scheduled chore. Pinned digests are correct but they don't self-update. Either wire Dependabot/Renovate to the Dockerfile, or add a quarterly task to re-run the generator and refresh digests. Do it in one PR so the build and runtime digests move together.

Template overrides. With templates now bundled, prefer the package's publish/override mechanism over editing files in vendor/. Publish once into resources/... or stubs/, commit them, and point the config at your path. That survives composer update.

Mirror the package's CI verification. The release adds CI verification of generated images. Reproduce it in your own pipeline: generate scaffolding into a scratch app, docker build it, and assert the image runs (php artisan --version inside the container). This catches a broken template upgrade before it reaches a real service.

Local vs production compose. Use the generated compose file for local dev with bind mounts and a build: context; for deploys, build once in CI and push by digest to your registry, referencing image: rather than build:.

Gotchas and Tips

• Digests are architecture-specific. A digest from a manifest list (multi-arch index) and a digest from a single-platform image behave differently; pinning the platform-specific digest silently breaks arm64 builds (Apple Silicon developers hitting no matching manifest for linux/arm64). Pin the multi-arch index digest unless you know you need otherwise.
• Runtime stage lacks the toolchain. The most common failure after this change is a runtime stage that tries to compile something. Everything build-time goes in the build stage.
• Regeneration clobbers local edits. Generated Dockerfile, .dockerignore, and the entrypoint script are all in scope. If you need a custom entrypoint, publish/override the template rather than editing the generated file.
• Old published stubs can shadow new bundled templates. If you published stubs on an earlier version, the new bundled startup/ignore templates won't be used until you re-publish or delete the stale copies. Check the published directory before assuming the upgrade took effect.
• .dockerignore gets swallowed by .gitignore. Many repos ignore dotfiles or .dockerignore by accident; after regenerating, confirm it's actually tracked. A missing .dockerignore silently ships vendor/, node_modules/, and .env into the build context.
• Stale digests fail confusingly. docker build errors with "manifest unknown" on pull rather than a clear "digest is stale". If the build breaks unexpectedly on a pinned base image, suspect a digest that was garbage-collected or moved, and re-run the generator.
• Debugging generated builds: docker build --progress=plain --no-cache . and docker history <image> to see which stage produced what. Check ARG/ENV defaults in the generated Dockerfile — the PHP branch is usually substituted there, and it's the fastest place to spot a wrong branch.
• Composer layer caching: order the generated Dockerfile so composer.json/composer.lock are copied before app source; if the generator's ordering changed, verify you're not invalidating composer install on every source change.
• CI caching on pinned digests: buildkit cache keys include the base image digest, so a digest bump invalidates the whole layer cache. Expect one slow build per upgrade and don't misattribute it to a regression.
• Extension points worth knowing: custom template path in config, the PHP branch default, and the startup script hook (where you'd add php artisan migrate --force or a storage-permissions fixup). Setting these in config is more upgrade-stable than post-processing generated files.