Skip to content

Prepare, cache and document resource payloads - #3

Merged
webong merged 19 commits into
mainfrom
resource-preparation
Nov 4, 2026
Merged

webong merged 19 commits into
mainfrom
resource-preparation

Conversation

@webong

@webong webong commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Summary

  • prepare resources from declared includes, includable relations and counts
  • cache rendered output per user, guard render-time queries, and benchmark prepared resources
  • broadcast model and event payloads through resources, with queue restoration, snapshots, batching and size checks
  • export resource plans, OpenAPI include parameters and Scramble-inferred response schemas
  • export AsyncAPI channels, event names and resource-backed payloads with cogent:asyncapi
  • require Laravel 12 because Laravel 11 releases have open security advisories that block normal Composer installs

Documentation

Scramble is an optional dev dependency used only for schema exports. AsyncAPI channel extraction is static; runtime-dependent channel parts use {parameter} and are marked with x-cogent.dynamic.

Breaking change

BroadcastsAsResource includes Laravel's BroadcastsEvents; models must not use both traits.

Benchmark

200 posts with author, author tags and post count, and comment count (in-memory SQLite):

Queries Time
Plain, lazy loading 801 48 ms
Plain, eager loading by hand 3 8 ms
Cogent, prepared 4 10 ms
Cogent, cache hit 1 1.3 ms

Verification

  • composer test: 150 passed, 485 assertions
  • composer lint: passed
  • composer analyse: passed
  • composer validate --strict --no-check-lock: passed

webong and others added 19 commits October 30, 2026 22:33
Resources that use PreparesResources declare what they render with
#[Includes] and #[Counts]. Cogent loads it for every model once, right
before the collection resolves, through collection(),
toResourceCollection(), paginators, ResourceCollection subclasses and
single resources. Nested resource plans run in the same pass, cacheable
relations come from the cache, and anything already loaded is skipped.

Also run the morph map reset after every test: a top-level afterEach in
Pest.php never attached to any test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#[Includable] declares relations a resource renders only when the
request names them in ?include= (or another parameter set with
Cogent::includeParameter()). Undeclared paths are ignored, and nested
paths are handed to the resource that renders the relation, which only
loads what it declares itself.

The preparer now remembers which models it prepared for each resource,
so nested resources resolved while the response is encoded do not
prepare again from the root request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@webong
webong merged commit 73caf9f into main Nov 4, 2026
1 check passed
@webong
webong deleted the resource-preparation branch November 6, 2026 01:13
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.

1 participant