Fluent configuration API and object-argument cache keys

[trm42]

What

Two Otwell-flavored improvements to the public surface of CacheDecorator:

1. Fluent, chainable configuration API

• Removed the void setters setTtl() / setEnabled(bool).
• Added a chainable, Laravel-style grammar — all returning static:
  • ttl($ttl) — TTL in seconds / DateInterval / DateTimeInterface / null to bypass
  • enable() / disable() — toggle caching readably
  • prefix(?string), withTags(array), tagCleaners(array), exclude(string ...)
• Each new method is added to the initExcludes() defaults so __call() resolves it on the decorator instead of forwarding to the inner object.

$cached = (new CachedReportingService(new ReportingService))
    ->ttl(600)
    ->prefix('reports')
    ->withTags(['reports'])
    ->exclude('debugDump');

2. Object arguments in cache keys

Resolves the long-standing @todo / "coming in v1.0.0" caveat. Arguments may now be scalars, arrays, or objects, folded into the key through a new overridable normalizeArgument(mixed): string seam:

1. scalars / null / bool — cast as-is (existing keys stay byte-identical)
2. UrlRoutable — getRouteKey()
3. BackedEnum — ->value; Stringable / __toString — string cast
4. anything else — json_encode, falling back to md5(serialize(...))

Subclasses can override normalizeArgument() to customize identity.

Why

The previous surface read like a 2015-era package: void setters that don't chain, and unsupported object arguments. These changes make configuration expressive and self-documenting and let models/enums/value objects be passed as cached method arguments.

Notes

• Breaking: setTtl() / setEnabled() are removed (the package isn't in production use yet). Migration is documented in the README upgrade notes.
• README and CLAUDE.md updated in the same change, per the repo's README-sync rule.

Tests

Full suite green (40 tests / 66 assertions), pint --test passes, phpstan (larastan) clean. New tests cover the fluent setters returning the decorator, enable()/disable()/ttl() behavior, chained-call resolution (regression guard on the exclude-list), and object-argument keying by identity.

🤖 Generated with Claude Code