S3M Laravel Package

Getting Started

This release (v3.0.0) is primarily a compatibility release, not a feature release. The day-to-day surface area of the package is unchanged; what changed is who can install it. So the first step is a compatibility check, not a code read.

Check you are eligible before anything else:

Laravel 11 is dropped deliberately, not incidentally — the release notes cite CVE-2026-48019 (CRLF injection in the default email validation rule), which has no patched 11.x release, and Laravel 11 is out of security support. Treat "we can't upgrade the framework yet" as a genuine blocker here, not an inconvenience to work around.

Minimal upgrade path:

# 1. Confirm the framework/PHP floor first — this is the actual blocker
composer show laravel/framework | grep versions
php -v

# 2. Then bump the package
composer require mreduar/s3m:^3.0

# 3. Re-run your own suite, not just the package's
php artisan test

Because the constraint moved to illuminate/contracts: ^12.0|^13.0, a failed upgrade will surface at composer update time rather than at runtime — if Composer resolves cleanly, the hard part is already done.

Where to look first: the package README/CHANGELOG for the 2.x → 3.x diff. The release notes for v3.0.0 list only framework/PHP drops, the Laravel 13 addition, and a dev-toolchain bump (Pest 4, larastan ^3.10, collision ^8.8, testbench ^10|^11). There are no API, config, or behaviour changes advertised. That means your first use case is simply: re-run your existing 2.x integration tests against Laravel 12 or 13 and confirm they still pass. If they do, you are done — there is nothing new to adopt.

Implementation Patterns

Pin the package alongside the framework in CI. Since support is now a two-version window (12 and 13), mirror the package's own matrix so you catch a future drop before it reaches production:

# .github/workflows/test.yml
matrix:
  php: ['8.3', '8.4']
  laravel: ['12.*', '13.*']

This is exactly what the maintainers now run, and it means a future v4.0.0 dropping Laravel 12 will fail your matrix loudly instead of surprising you at deploy time.

Use composer why-not during the upgrade, not guesswork. The most common real-world failure is a transitive conflict, not the package itself:

composer why-not mreduar/s3m ^3.0

This will tell you immediately whether the blocker is laravel/framework, php, or some other package still holding you on illuminate/contracts ^11.0.

Keep the 2.x line as an explicit escape hatch. The release notes state this plainly: PHP 8.2 / Laravel 11 users can stay on 2.x. If you maintain multiple applications on different framework versions, encode that as a constraint per application rather than trying to force one version everywhere:

// legacy app, Laravel 11
"require": { "mreduar/s3m": "^2.0" }

// current app, Laravel 13
"require": { "mreduar/s3m": "^3.0" }

Treat Laravel 13 as verified, not merely "allowed." The notes name concrete tested versions (13.10.0 and 13.15.0). When you add Laravel 13 to your own matrix, start by pinning one of those in at least one job so you are testing a combination the maintainer actually exercised, then widen.

Leave Composer's security-advisory blocking on. The notes explicitly call out that no bypass is needed now that Laravel 11 is gone, and that prefer-lowest resolves to 12.60.0 / 13.10.0 — the first non-advisory releases of each line. Do not add composer config audit.abandoned ignore or --no-audit to work around a resolution failure; that failure is the CVE talking.

Gotchas and Tips

The PHP 8.2 drop is a toolchain consequence, not a runtime one. The stated reason is that Pest 4 (required for the Laravel 13 test toolchain) needs PHP 8.3+. So the package may well run on 8.2, but it can no longer be tested there — which is why the constraint is hard. Do not "fix" this by loosening your own php constraint or using --ignore-platform-reqs; you would be running an untested combination against a security-flagged framework.

A clean composer update is not the same as a clean upgrade. With no advertised API changes, there is a temptation to skip regression testing. Resist it — the framework jump from 11 to 12/13 carries its own deprecations that have nothing to do with this package, and any of them can surface through the package's service provider or config loading. Run your full suite.

Config publishing is worth re-checking after a major bump, even when the changelog says nothing changed. If you previously published the package's config file, diff it against the newly shipped one — a config key that silently gains a default is easy to miss and hard to debug. If you did not publish it, now is a reasonable time, since you are touching the dependency anyway.

CI caching can mask a stale lockfile. After bumping, clear Composer's cache in CI once (composer clear-cache) or bump your cache key. A cached vendor/ from a 2.x run can produce a green build that does not reflect the new constraint.

prefer-lowest now behaves differently than you may expect. It resolves to 12.60.0 / 13.10.0 rather than the true lowest version, because Composer's audit blocks the advisory-affected releases. If you have a prefer-lowest job and it suddenly reports different versions than you remember, that is the security advisory doing its job — not a bug, and not something to pin around.

Extension points are the safe harbour. If you have customised behaviour via the package's published config, service bindings, or by extending its classes, those are the places most likely to break silently across a major version — framework-version drops rarely touch them, but Laravel 12/13's own container and lifecycle changes can. Prioritise smoke tests around any custom binding or overridden class.

Watch the changelog link. The notes point at v2.0.2...v3.0.0; given the breadth of the toolchain bump, read the actual commit range if anything behaves unexpectedly. A "compatibility-only" release is a claim worth verifying when you are debugging something odd.