Skip to content

Loader cache: build-command tests, discovery timing, and runtime resilience#36

Open
rleeson wants to merge 6 commits into
fix/issue-30-autoloader-cache-refreshfrom
feature/loader-tests-and-timing
Open

Loader cache: build-command tests, discovery timing, and runtime resilience#36
rleeson wants to merge 6 commits into
fix/issue-30-autoloader-cache-refreshfrom
feature/loader-tests-and-timing

Conversation

@rleeson

@rleeson rleeson commented Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown

Description of the Change

Stacked on top of #35 (branches from fix/issue-30-autoloader-cache-refresh); this PR targets that branch, not develop. It adds test coverage that #35 was missing, surfaces discovery timing on the loader debug page, and hardens the runtime read path.

  • Build-command tests — integration tests that run tenup-framework-generate-class-cache end-to-end (generate, no-args usage, missing-directory-continues, multi-directory), backed by small example loader dirs under tests/examples/.
  • Debug-page coverage — tests for the previously-untested legacy_files(), every cache_state() variant, format_duration(), cache_detail(), and the staleness up-to-date path; replaced a vacuous assertGreaterThanOrEqual(0, …) with a real contract assertion; reset the ModuleInitialization singleton between tests (the suite is not process-isolated).
  • Loader timing — init_classes() records class-discovery time (a cache read when cached, a live scan otherwise) and class-lookup time using the monotonic hrtime(). The debug page shows both per loader, and the staleness check reports how long its live scan took, so the cache's saving is measurable.
  • Cache detail — now shows Built <age> ago · <size> · <YYYY-MM-DD HH:MM:SS UTC> (UTC via gmdate(), timezone-independent).
  • Resilience / performance — a corrupt or truncated shipped cache is caught at runtime and falls back to a live scan instead of fataling every request; loader recording bails on wp_doing_ajax(); records dedupe by directory.
  • Debug page layout — a loader card grows to fit an expanded class list (capped at the admin content width) and long paths wrap, rather than overflowing the card's right edge.
  • Docs — opcache in-place-deploy staleness caveat, the corrupt-cache fallback, mono-repo generation guidance for differing framework versions, and debug-page limitations.

Refs #30

How to test the Change

  1. composer install, then composer lint, composer static (PHPStan level 10), and composer test — all green (60 tests).
  2. Build a cache for a directory: composer generate-class-cache -- <dir> (or the shipped vendor/bin/tenup-framework-generate-class-cache <dir>); confirm a class-loader-cache/class-loader-cache-v2.php is written.
  3. In wp-admin, visit admin.php?page=tenup-framework-loaders: cached loaders show Cache in use with the build age/size/UTC time and a fast discovery time; uncached loaders show Uncached — live discovery. Use Check this cache for staleness to compare live vs. cached timing, and expand a classes loaded list to confirm the card grows to fit it.
  4. Corrupt the cache file and reload the front end — the site keeps working (falls back to a live scan) rather than fataling.

Also manually validated on a multi-package install where several plugins each require the framework: the build command cached real classes, the runtime read path matched a live scan, and the debug page aggregated all loaders.

Here's an example of the revised debug display with timing information:

image

Changelog Entry

  • Developer - Build-command tests plus example loader fixtures, and coverage for the loader debug diagnostics.
  • Developer - Loader debug page reports class discovery and lookup timing, and the cache detail shows the build size and absolute UTC build time.
  • Developer - A corrupt or truncated class-loader cache now falls back to live discovery instead of fataling the request.

Credits

Props @rleeson, @darylldoyle

Checklist:

  • I agree to follow this project's Code of Conduct.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.

rleeson and others added 5 commits July 7, 2026 12:20
@rleeson @claude
test: cover the build command and debug diagnostics; add loader timing
0696419 
Testing:
- Add tests/Bin/GenerateClassCacheTest: shells out to the actual
  tenup-framework-generate-class-cache script (as CI would) and covers the
  generate path, no-args usage/exit-1, a missing directory failing while valid
  ones still cache, and multi-directory runs. Backed by small, salient example
  loader directories under tests/examples/ (a real ModuleInterface module, a
  plain support class, and a second directory).
- Cover the previously untested LoaderDebug branches: legacy_files() detection,
  every cache_state() variant, and the staleness "up to date" path.
- Replace the vacuous assertGreaterThanOrEqual(0, ...) in
  test_it_can_find_classes_to_register with an assertion that the registered set
  is non-empty and contains only ModuleInterface implementations.

Loader timing:
- ModuleInitialization::init_classes() now times discovery (cache read or live
  scan) and class lookup (reflection/instantiation/registration) separately and
  records both on the loader debug record.
- The debug page shows both timings per loader, and the staleness check reports
  how long its live discovery ran — so the cache's saving on a given site is
  measurable. New format_duration() helper picks a sensible unit.

phpcs, phpstan (level 10) and phpunit all green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@rleeson @claude
test: address code-review feedback on timing and diagnostics
90a3956 
- format_duration(): reject non-finite input (INF/NAN) alongside non-positive,
  so a misbehaving contributor to the tenup_framework_debug_loaders filter can
  no longer render "inf s" / "nan s". Makes the "untrusted mixed input" contract
  in the docblock actually hold. Cover with negative, NAN and INF data cases.
- FrameworkTestSetup: reset the ModuleInitialization singleton in setUp(). The
  trait-level @runTestsInSeparateProcesses annotation does not take effect
  (PHPUnit ignores it on a used trait; confirmed by suite wall-time and the
  author's explicit method-level @runInSeparateProcess on the two define()
  tests), so the singleton's accumulated $classes previously leaked between
  tests. Prevents order-dependent flakiness as more tests are added.

phpcs, phpstan (level 10) and phpunit all green (57 tests / 148 assertions).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@rleeson @claude
harden cache resilience, fix timing correctness/tests, document mono-…
3fcfa84 
…repo & opcache

Addresses a Fable re-review of the build-time-cache PR plus the timing addition,
targeting mono-repo flexibility, genuine live-timing measurement, and security/perf.

Resilience (security/perf):
- get_classes() now catches a corrupt/truncated shipped cache (the cache is
  executable PHP loaded via `require`) and falls back to a live discovery instead
  of fataling every request until redeploy. Same spirit as #30: a bad cache must
  never take the site down. Covered by a new test.
- record_loader_debug() bails on wp_doing_ajax(): is_admin() is also true on
  admin-ajax.php, and the debug page re-records on its own GET, so ajax recording
  was pure waste (often front-end triggered).

Timing correctness:
- Switch discovery/lookup timing from microtime(true) to the monotonic
  hrtime(true), so an NTP adjustment mid-request cannot skew a delta.
- Rewrite the timing tests that were vacuous (assertGreaterThanOrEqual(0.0) passed
  the never-wired 0.0 default; the staleness string also matched the "took —."
  failure rendering). Now: the no-cache case asserts cache_used===false and
  strictly-positive live discovery time; a new cached case asserts cache_used===true
  and positive cache-read time; the staleness checks assert a real duration via
  regex.

Mono-repo dedupe:
- LoaderDebug::record() keeps one record per directory, so a repeated init_classes()
  for the same directory refreshes rather than duplicating a card.

Docs:
- Build-and-Deployment: opcache in-place-deploy staleness caveat, corrupt-cache
  fallback behaviour, and mixed-framework-version generation guidance for mono-repos.
- Debugging: known limitations (per-request visibility, oldest-UI renders on mixed
  versions). CHANGELOG: fallback note; "identifier" -> "filename" wording fix.

phpcs, phpstan (level 10) and phpunit all green (59 tests / 153 assertions).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@rleeson @claude
show absolute UTC build time in the loader cache detail
0fac09c 
Cache detail now reads "Built <age> ago · <size> · <YYYY-MM-DD HH:MM:SS UTC>",
using gmdate() so the build timestamp is unambiguous regardless of site or server
timezone. Covered by a cache_detail() test asserting the size and trailing UTC
segment.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@rleeson @claude
grow the loader card to fit an expanded class list
1c5ed6f 
The class table's long file paths pushed it past the card's right border. The card
now sizes to its content (min 60em, capped at the admin content width) so it widens
when a class list is expanded, and long paths in the meta/class tables wrap
(overflow-wrap: anywhere) so nothing spills once the width cap is reached.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@rleeson rleeson requested a review from darylldoyle July 10, 2026 21:59
@rleeson rleeson mentioned this pull request Jul 10, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@darylldoyle darylldoyle Awaiting requested review from darylldoyle

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@rleeson