Statamic Maintenance Mode Laravel Package

Getting Started

Requirements: PHP 8.2+ (8.3 explicitly supported as of v0.3.1), Composer with minimum-stability: stable, and Node/npm if you plan to rebuild the addon's published assets.

1. composer require <vendor>/<addon> — use ^0.3.1 or later if your app runs PHP 8.3 (earlier versions have a route-trimming compatibility bug).
2. Publish config and any frontend assets: php artisan vendor:publish --provider="...\ServiceProvider".
3. If you intend to customise views/CSS/JS, run npm install && npm run build in the package directory or your app, and commit the resulting lockfile.
4. Clear caches: php artisan config:clear && php artisan route:clear && php artisan view:clear. Route-trimming behaviour is cached-route sensitive.

Look here first:

• The package's route registration file (this is where the PHP 8.3 trimming fix lands).
• config/<addon>.php for trimming/normalisation toggles.
• The test suite for route/middleware tests — the best template for your own regression test.

First use case: Install into a Laravel 11 app on PHP 8.3, register the addon, and request a route with a trailing slash (and one with a doubled slash) to confirm normalisation/redirect behaves as expected. That single smoke test exercises the code path that v0.3.1 patched.

Implementation Patterns

Treat trimming as infrastructure, not app logic. Let the addon normalise request URIs and keep your own routes free of trailing-slash variants. Don't add duplicate Route::get('/foo', ...) + Route::get('/foo/', ...) definitions; that's what causes double-registration bugs and makes the trimming fix untestable.

Pin and verify on your PHP matrix. Run CI against both PHP 8.2 and 8.3. The route-trimming change is version-conditional, so a green 8.2 build tells you nothing about 8.3 route resolution. Add at least one feature test asserting a trailing-slash request resolves to the canonical route.

Mirror the package's CI guardrails. The release adds composer audit and npm audit to CI and updates the Vite lockfile to clear advisories. Copy that into your app's pipeline — audit failures in a dependency you're already running are your problem too.

Extend, don't edit vendor. Customise via published views/config or by subclassing/overriding bindings in a service provider. The package is on a 0.x line and moves; local vendor edits will be wiped on the next composer update.

Keep Pint's mb_str_functions rule disabled in any project sharing this package's PHP 8.2 floor. The rule can rewrite code to PHP 8.4-only function signatures, producing a green local build and a fatal error on your 8.2 production target. Add it to pint.json's exclude/disabled list at the repo level, not per-developer.

Frontend workflow: if you consume the addon's JS/CSS, build it in CI (npm ci && npm run build), not on developer machines, and commit the lockfile. Stale built assets are the most common reason a "fixed" dependency advisory is still live in production.

Gotchas and Tips

• Route-trimming regression on PHP 8.3. Fixed in v0.3.1. If you're on 8.3 and seeing 404s or odd redirects for URIs with trailing/duplicate slashes, check your installed version before debugging your own routes.
• Composer minimum-stability: stable. If you previously pulled this package via a VCS/path repository relying on dev stability, you may now need explicit @dev constraints or a tagged release. Watch for "could not be resolved to a stable version" errors after updating.
• Middleware order matters. Trimming/normalisation middleware must run before route matching. If you've added custom global middleware that inspects the URI early, it will see the untrimmed path.
• Cached routes hide fixes. php artisan route:clear after upgrading — a stale bootstrap/cache/routes-*.php can make a patched version behave exactly like the broken one.
• Dependabot auto-merge is gone. Dependency PRs now require manual review. Budget for it, or add your own auto-merge policy for patch-level dev dependencies only.
• npm audit noise. Vite toolchain advisories regularly resolve to "upgrade Vite." Do it in a dedicated PR and rebuild assets in the same commit; splitting them leaves production serving stale bundles.
• Pint drift. Even with mb_str_functions disabled, a Pint upgrade can reintroduce 8.4-only rewrites via other rules. Pin Pint's major version and review formatter diffs for mb_ function changes.
• Extension points: config publish, view/component overrides, route registration via the service provider, and (typically) a middleware you can swap in bootstrap/app.php or Kernel.php. Prefer overriding the binding over copying the class.
• 0.x caveat. Semver is not guaranteed on a 0.x line; read every release note, including maintenance-only ones like this, and pin to ^0.3 rather than *.