Memento Laravel Package

Getting Started

Start with the version matrix, not the code. The only content of the 3.0.0 release is PR #1 ("added laravel 10, php 8.2, phpunit 10"), so the practical question for day-to-day use is "does my app meet the floor, and does anything I call actually change?"

Minimal steps:

1. composer require esplora/memento:^3.0 inside a Laravel 10 / PHP 8.2 app. If you are still on Laravel 9 or PHP 8.1, stay on ^2.0 — 3.0.0 will not resolve.
2. Read the diff directly, since the release notes carry no migration guide: https://github.com/esplora/memento/compare/2.0.0...3.0.0. It should be short — mostly composer.json, CI workflow, and test-suite edits. Anything touching src/ is a real behaviour change you need to account for.
3. Check the README in vendor/esplora/memento/README.md at the 3.0.0 tag — that is the authoritative usage doc, and a support-matrix bump is exactly the release where examples get refreshed.
4. Look for publishable assets: php artisan vendor:publish --provider="Esplora\Memento\MementoServiceProvider" (confirm the provider FQCN from composer.json's extra.laravel.providers). If the package ships config or migrations, publish them before first use and commit the published files.
5. First use case: wire it into one model in a staging branch, run your existing test suite against PHPUnit 10, and confirm green before rolling it out.

Implementation Patterns

Treat 3.0.0 as a compatibility release, not a feature release. The adoption pattern is therefore a platform upgrade pattern, sequenced like this:

• Upgrade the app first, the package second. Get your Laravel 10 / PHP 8.2 upgrade landed and stable on 2.x-of-everything, then bump memento. Mixing the framework upgrade and the package major in one PR makes bisecting impossible when tests go red.
• Pin explicitly in composer.json. Use "esplora/memento": "^3.0" rather than * or dev-main. Because the major number tracks the framework major here, a caret constraint is a meaningful, readable statement of "this app is Laravel 10".
• CI matrix, not a single job. If you maintain more than one app or a package that depends on memento, test PHP 8.2 × Laravel 10 × PHPUnit 10 as the supported cell and drop the old cells rather than carrying conditionals. A matrix of exactly one row is honest and fast.
• Isolate the integration behind your own seam. Whatever the package does for you (model hooks, a trait, a service you resolve from the container), wrap the call site in a small app-level class or trait of your own. That seam is what made this upgrade cheap, and it is what will make the 4.0 upgrade cheap too.
• PHPUnit 10 migration is part of the work, not an afterthought. If your tests exercise memento behaviour, convert docblock metadata to attributes in the same pass: @dataProvider → #[DataProvider('...')], @covers → #[CoversClass(...)], and make every data provider public static function. Update phpunit.xml to the 10.x schema (the old cacheResultFile/verbose attributes trip validation warnings).
• Feature-flag the rollout if memento affects persisted data or request handling. Ship behind a config toggle defaulting off, enable in staging, then production — a major bump with an undocumented diff deserves a reversible switch.
• Record the upgrade in your dependency notes: date, from-version, to-version, the diff URL, and the one thing that broke. Future-you will need it at the 4.0 bump.

Gotchas and Tips

• The major version number is a support-matrix signal, not an API promise. This release bumps major purely for Laravel 10 / PHP 8.2 / PHPUnit 10. That means you cannot infer "breaking API change" from the 3.0.0 — and equally, you cannot assume "no breaking change". Read the diff; do not guess from the version number. Verify whether the 2.0.0 → 3.0.0 comparison touches src/ at all.
• No upgrade guide was published. For a package of this size that is usually fine, but it means support questions ("why does X behave differently?") have no canonical answer. Capture your own findings in your repo's upgrade notes.
• Transitive constraint conflicts are the likely failure mode. composer require failing on 3.0.0 almost always means another dependency still caps laravel/framework at ^9.0 or php at ^8.1. Run composer why-not esplora/memento 3.0.0 (or composer why-not laravel/framework 10.*) to find the blocker instead of loosening constraints blindly.
• PHP 8.2 specifically surfaces dynamic-property deprecations. If the package (or your subclass of it) assigns undeclared properties, you will now see Creation of dynamic property ... is deprecated. Fix with explicit property declarations or #[AllowDynamicProperties] — do not silence E_DEPRECATED globally to make it go away.
• PHPUnit 10 silently skips docblock metadata. Tests annotated with @dataProvider/@covers that are not converted will not error loudly in every case — they can just stop running the cases you expect. Compare test counts before and after the upgrade, not just pass/fail.
• Config cache and published assets. After publishing config or migrations, php artisan config:clear and re-run config:cache. A stale cached config after a major bump is a classic five-minute mystery.
• Extension points to inspect before writing workarounds: the service provider's register()/boot() (what is bound as singleton vs. fresh), the config/memento.php keys (if present), and any Memento:: facade or trait the README documents. Prefer the documented hook over subclassing internals — internals are exactly what a major bump is free to change.
• Debugging approach: since the changelog is one line, bisect by constraint. Reproduce your failing case with esplora/memento:2.0.0 on the same Laravel 10 / PHP 8.2 stack. If it fails on 2.0.0 too, the problem is the platform upgrade, not memento, and you are debugging the wrong package.
• Watch the issue tracker for a 2.0.x LTS branch. If the maintainer keeps one, Laravel 9 apps get security/compat fixes without a framework upgrade — check before planning a rushed migration.