Skip to content

Release 1.17.0: safe fixes, faster bulk invalidation, opt-in deserialization hardening - #59

Merged
iazaran merged 5 commits into
mainfrom
claude/admiring-albattani-iur6n6
Oct 29, 2026
Merged

iazaran merged 5 commits into
mainfrom
claude/admiring-albattani-iur6n6

Conversation

@iazaran

@iazaran iazaran commented Oct 29, 2026

Copy link
Copy Markdown
Owner

Pull Request

Description

Release 1.17.0: fixes and performance improvements from a full audit of 1.16.0, with nothing for users to change.

  • The SmartCache contract is unchanged, and no default changes.
  • One opt-in config key is added: serializable_classes, default null.
  • 1.16 and 1.17 read each other's entries during a rolling deploy. One queue-ordering note applies (below).

Performance

  • Bulk invalidation writes the managed-key index at most once. Every 10 removed keys used to rewrite the whole _sc_managed_keys index under a lock. A tag flush covering thousands of keys rewrote an index of tens of thousands of keys hundreds of times. This covers flushTags(), tags()->flush(), flushPatterns(), invalidateModel(), invalidate(), deleteMultiple(), and flushNamespace(). Small removals keep the old schedule: a model save that flushes one tag writes the index no more often than in 1.16.
  • remember() serializes large values less. It no longer re-serializes the value for the cost-aware size and the write metric. That saves about 3 ms per miss on a 2 MB payload, and the recorded numbers are the same.
  • The dashboard page (GET /smart-cache) no longer runs getStatistics() and healthCheck() on every view. Both read every managed value and their results were discarded; healthCheck() also pruned and evicted entries on a GET.
  • memo() LRU eviction no longer sorts on every new key once the memo layer is full. 50,000 distinct reads went from 2.3 s to 0.2 s.
  • Glob patterns are converted once per call.
  • A shared circuit breaker no longer writes on every healthy success.

Fixes

  • Orphan chunks. A cleanup pass wrote back a stale registry snapshot, which dropped chunks registered meanwhile, and those chunks leaked forever. It now applies only its own changes. registerChunks() and unregisterChunks() merge into the stored registry, and setCleanupService() is deprecated.
  • Lazy loading.
    • Turning lazy_loading off now applies to existing entries.
    • materialize() keeps the collection class (for example Eloquent\Collection).
    • LazyChunkedCollection is JsonSerializable.
    • slice() accepts negative arguments.
  • Unserializable values (a Closure on the non-serializing array store) no longer make put() throw while it measures, hashes for dedup, or sizes the value for chunking.
  • store('x')->refreshAsync() and asyncSwr() write to store x, not the default store.
  • flushNamespace() starts from the stored index.
  • Metadata locks no longer re-run an update when only the lock release failed.
  • SWR and stampede timestamps use the framework clock, so Carbon::setTestNow() and travel() work as they do with Laravel's Cache::flexible().
  • Console.
    • clear --force now clears non-managed keys when every managed key had expired.
    • Numeric managed keys ('123') are recognized by clear, status, and the dashboard's clear command.
    • clear --force continues past a key it cannot read.
    • warm warns about unknown warmer names.
  • Pattern invalidation forgets and counts a key matched by several patterns once.
  • Smaller fixes.
    • Memo-layer stale miss after remember().
    • Shared circuit-breaker getStats(): recovery time and a stale opened_at.
    • Cost-aware scores re-read between requests and jobs, instead of a worker writing back hours-old copies.
    • A warning for invalid encryption regex patterns, which silently stored values unencrypted. It is logged at most once an hour per pattern.
    • Clear errors for non-array chunks.
    • Division-by-zero guards.

Security (opt-in)

smart-cache.serializable_classes applies Laravel's unserialize class restriction to the values SmartCache compresses, encrypts, or serializes itself; Laravel's cache.serializable_classes never reached them. Set it to 'cache' to follow Laravel's setting, to false, or to a list of allowed classes.

It is opt-in on purpose. The Laravel 13 application skeleton sets cache.serializable_classes => false, so honoring it by default would turn large cached objects into __PHP_Incomplete_Class for apps that rely on today's behavior.

Upgrade notes (also in CHANGELOG)

  • Rolling deploy: a refresh queued from store('name') by 1.17 but run by a 1.16 worker still writes to the default store. The worker ignores the new job property; I verified this on Laravel 8 and 13. Upgrade workers with or before web servers.
  • clear --force now also clears non-managed keys when every managed key had expired.
  • materialize() returns the collection subclass.
  • flushPatterns() and invalidateModel() count overlapping matches once.
  • If lazy_loading was turned off, entries written while it was on now come back eagerly.
  • A non-array chunk now counts as corruption, so self-healing evicts it instead of returning partial data with a warning.
  • json_encode() of a lazy collection now gives a list instead of {}.
  • flushNamespace() reads the index first and also flushes keys other processes tracked.
  • Long-running processes re-read cost-aware scores at most once a minute.

Left out on purpose (need a decision)

  • Guarding the terminate hooks with resolved(). It would skip building the singleton on requests that never use it. Under Octane it changes which container instance gets reset(), and I couldn't test that here.
  • A chunk-size cap for 1–10 MB values under smart_sizing. On Redis or the file store it would split today's single chunk into many, which means more round trips per read.
  • Matching _sc_ only as a key prefix in the console commands. clear --force would then delete user keys that merely contain _sc_.
  • Counting array keys in the chunking size estimate. It would change which strategy some values get.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

How Has This Been Tested?

  • vendor/bin/phpunit passes: 725 tests, 2,611 assertions, with the 2 skips that were already there (678 before).
  • tests/Unit/V117FixesTest.php adds 47 tests. All 37 non-guard tests fail on 1.16.0; I checked this by running the file against the 1.16 source.
  • There are 10 guard tests, which pin behavior that must not change. 9 pass on 1.16. The 10th calls the new CostAwareCacheManager::refresh(), so it can't run there.
  • 3 of the guards fail on this PR's first code commit. They were added for the defects Fable found in its review.
  • The full suite also passes on Laravel 8 (PHPUnit 9) and Laravel 10 (PHPUnit 10). The extra skips there are the native-memo tests, which need Laravel 12.9+.

Test Configuration:

  • PHP version: 8.3
  • Laravel version: 13.39, 10.x, 8.x

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

Reviews

  • Audit. Two audit agents went through the strategies and chunking, and through the services, console, HTTP and traits; I read SmartCache.php myself. I reproduced every finding before adopting it. The ones that would change behavior are under "Left out on purpose".
  • Fable, first pass (code).
    • One P1, a regression I had introduced. Batching wrote the managed-key index after every bulk call, so a model save that flushes one tag wrote it far more often than 1.16. It now keeps the 1.16 schedule for small removals, and a guard test pins that.
    • Two P2s, both fixed.
      • The invalid-pattern warning would have logged once per request on PHP-FPM. It is now throttled through the store to once an hour per pattern.
      • Cost-aware scores would have been re-read on every Octane request. They are now re-read at most once a minute.
    • P3s acted on.
      • Dashboard subclasses that override renderDashboard() still receive statistics and health.
      • The rolling-deploy test now replays a real 1.16 job payload.
      • The remaining behavior fixes are listed as upgrade notes.
    • P3s kept as in 1.16, on purpose. A metadata-lock callback that itself throws is still re-run without the lock.
  • Fable, second pass (fixes and all docs).
    • No P1/P2 in the code.
    • Docs P2: chunking. The README overstated when chunking applies: it also needs more than chunk_size items. Fixed.
    • Docs P2: Laravel 13 claim. Fable couldn't reach the laravel/laravel skeleton to check the serializable_classes default. I had checked it: 13.x config/cache.php ships 'serializable_classes' => false, and the docs now cite the skeleton.
    • Its P3 wording fixes are applied: encryption config nesting, the cache_locks table, what clear --force deletes, the full internal-key list, and PHP 8.5 in TESTING.md.

Docs

  • The README is rewritten to be shorter and to lead with why teams adopt SmartCache and what makes it production-ready, with details linked to the full docs.
  • docs/index.html gains a "New in 1.17.0" note, an upgrade section, and updates to the lazy loading, encryption and deserialization, queued refresh, dashboard, workers, and config reference sections.
  • Also updated: CHANGELOG (1.17.0, plus the missing 1.15/1.16/1.17 compare links), SECURITY.md (maintained line 1.17.x), TESTING.md (test counts, PHP 8.5), and the config comments.

Generated by Claude Code

Bulk invalidation (flushTags, flushPatterns, invalidateModel,
deleteMultiple, flushNamespace, clearManaged) now writes the managed-key
index once instead of every 10 keys. flushNamespace() starts from the
stored index. Metadata locks never re-run an update whose lock release
failed. remember*() no longer serializes the value again for cost-aware
scoring, and unserializable values no longer break put() through the
metrics or deduplication hash.

Orphan-chunk cleanup applies its changes to the stored registry instead
of writing back a stale copy, so chunks registered meanwhile no longer
leak. Turning lazy loading off applies to existing entries, materialize()
keeps the collection class, lazy collections are JSON-serializable, and
slice() accepts negative arguments. Async refreshes write to the store
they were queued from. The dashboard page no longer runs healthCheck()
and getStatistics() on every view. clear --force handles numeric keys,
expired indexes, and keys it cannot read. SWR and stampede metadata use
the framework clock. Plus memo, circuit breaker, cost-aware, and
strategy robustness fixes, and an opt-in smart-cache.serializable_classes
setting that applies Laravel's unserialize restriction to the payloads
SmartCache decodes itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QhHekNUGyMR5yVX6UcshtR
Rewrite the README to lead with why teams adopt SmartCache and what makes
it production-ready, keeping the essentials and linking the full docs for
details. Add the 1.17.0 changelog entry with upgrade notes and the
missing 1.15-1.17 compare links, document serializable_classes and the
1.17 behavior in docs/index.html, and list 1.17.x as the maintained line
in SECURITY.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QhHekNUGyMR5yVX6UcshtR
Keep the managed-key index debounce for small bulk removals: batching
now writes the index at the end only once 10 changes are pending
(clearManaged() still writes it unconditionally, as before), so a model
save that flushes one tag writes it no more often than 1.16 did.
invalidate() is batched the same way.

Throttle the invalid encryption pattern warning through the cache store
to once an hour per pattern, since the strategy is rebuilt per request.
Re-read cost-aware scores between requests and jobs only when the copy
is older than a minute. Keep passing statistics and health to dashboard
subclasses that override renderDashboard(). Replay a real 1.16 job
payload in the rolling-deploy guard test, and correct the changelog:
a 1.16 worker ignores the job's new property rather than logging a
deprecation. List the remaining behavior fixes as upgrade notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QhHekNUGyMR5yVX6UcshtR
README: chunking needs more than chunk_size items as well as 100 KB;
the encryption snippet lives under strategies; clear() is the main (not
the only) intentional difference; note the cache_locks table for the
database driver and what clear --force deletes. Cite the Laravel 13
application skeleton for the serializable_classes default. List the
smaller public API additions in the changelog, complete the internal
key list in the docs, fix a stale sample version, and add PHP 8.5 and
the PHPUnit 10 verbose flag to TESTING.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QhHekNUGyMR5yVX6UcshtR
Composer now blocks installing package versions with published security
advisories during update/require, and every Laravel 8-11 release has
one, so those matrix jobs failed while resolving dependencies, before
any test ran (main's last run predates the change). Set
COMPOSER_NO_BLOCKING (current name) and COMPOSER_NO_SECURITY_BLOCKING
(Composer 2.9's name) on the install step. This only selects the
framework version under test; package users are unaffected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QhHekNUGyMR5yVX6UcshtR

iazaran commented Oct 29, 2026

Copy link
Copy Markdown
Owner Author

CI note: the first run went red at P8.3 - L11.* - prefer-stable, and fail-fast then cancelled the other Laravel 8–11 jobs. Nothing ran yet, so no test had failed. Composer refused to install any laravel/framework 11.x release, because each one now has published security advisories and current Composer blocks those during update (PKSA-b41t-wbzk-9q51 and others). The Laravel 12/13 jobs and Coverage passed.

This isn't caused by the 1.17 changes. main's last green run (Oct 20) came before the blocking applied, and main would fail the same way now.

Fixed in 8bd69e9 by setting COMPOSER_NO_BLOCKING and COMPOSER_NO_SECURITY_BLOCKING on the install step of tests.yml, so the matrix can still install the end-of-life Laravel lines it tests. It only affects CI dependency resolution; package users are unaffected.


Generated by Claude Code

@iazaran
iazaran merged commit da85af0 into main Oct 29, 2026
24 checks passed
@iazaran
iazaran deleted the claude/admiring-albattani-iur6n6 branch October 29, 2026 20:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants