Repository navigation
Add Head for Blade and Inertia metadata management - #68
Merged
Merged
Conversation
Allow packages to inspect the prepared exception response without replacing the application response callback. Invoke boot-registered observers after request-local response callbacks and before respondUsing, ignoring observer return values. Expose beforeResponding through exception configuration and the facade, document its worker lifetime, and cover ordering, response identity, arguments, and ignored return values in the handler tests. This lets metadata integrations observe the actual error status before an Inertia error page renders. Validation: formatting and source/types analysis passed; FoundationExceptionsHandlerTest passed with 78 tests and 230 assertions. The complete framework run had no behavioral failures; its sole facade metadata failure was corrected and verified separately.
Read the optional response exception through null coalescing before rethrowing it. Plain Symfony responses have no exception property, so invalid JSON previously raised an undefined-property error instead of the intended assertion failure. Keep stored exception identity and the existing response proxy behavior unchanged. Add an exact-message regression alongside the stored-exception coverage. Validation: TestResponseTest passed with 259 tests and 1,030 assertions; formatting and source/types analysis passed.
Port Laravel Head metadata builders, routing macros, structured data, facades, and rendering into the optional hypervel/head split package. Keep request data scoped and replicable while reusing worker-safe services and bounded metadata caches. Add boot-registered runtime defaults, error, and canonical-origin resolvers for request-specific metadata. Preserve eager upstream configuration, isolate copied schemas, and retain lazy Inertia sharing and partial reload behavior. Decorate SSR responses without mutating their readonly contents or changing the JavaScript protocol, and forward gateway capabilities. Correct canonical query and fragment handling, independent Open Graph fallback media, literal zero metadata, manifest replacement, title ownership, and shared schema-factory lookup. Capture actual exception response status before final customization. Wire split and development metadata, optional test cleanup, editor signatures, generated facade metadata, and PHPStan macro support using public reflection APIs. Validation: formatting and complete source/types analysis passed, including routing and facade fixtures. Head passed 180 tests and 640 assertions; facade metadata checks passed 2 tests and 16,228 assertions. Package-mode and dogfood checks passed. The initial full framework run completed with one facade metadata failure, subsequently fixed and verified by focused checks.
Convert every applicable upstream Pest case to PHPUnit while preserving the upstream layout and fixture coverage. Record the intentional Livewire exclusion and use the shared Hypervel test lifecycle for static cleanup. Add focused coverage for concurrent requests, copied contexts, mutable builder lifetimes, lazy runtime resolvers, canonical origins, independent media fallback, manifest ownership, schema factories, and literal zero values. Exercise optional provider discovery, early handler and kernel resolution, actual exception status, SSR capability forwarding, custom props, partial reloads, and both Blade SSR ordering paths. Validation: all 180 Head cases passed with 640 assertions. Test files were checked during porting, and the complete framework run exposed no Head failures. No external services or new test framework are required for these tests.
Port the upstream Head guide with Hypervel installation, routing, Blade, structured data, and Inertia setup. Add request-specific defaults, error metadata, canonical origins, worker-lifetime guidance, context copying, and PHPStan integration using generic team examples. Explain serverHead setup for client and SSR entry points, static globals, partial reload behavior, and application-owned settings retrieval. Add Head in the package navigation, link from Inertia, and describe the worker configuration adaptation in the Laravel porting guide. Retain the completed implementation plan as the design reference. Documentation and comments were reviewed against the source, upstream coverage, and supported integration paths; diff whitespace checks passed.
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configuration
You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PR Summary by QodoAdd worker-safe Head metadata management for Blade and Inertia
AI Description
Diagram
High-Level Assessment
Files changed (119)
|
Code Review by Qodo
1. Custom error views miss error metadata
|
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Comment on lines
+108
to
+111
| return array_map(function (SchemaObject|array $schema) use ($head): array { | ||
| $schemaData = $schema instanceof SchemaObject ? $schema->toJsonLd() : $schema; | ||
|
|
||
| $head->validateSchema($schemaData); |
There was a problem hiding this comment.
3. Nested invalid schemas pass validation 🐞 Bug ≡ Correctness
Schemas::toHeadArray() validates raw array schemas without normalizing embedded SchemaObject values, and SchemaValidator::containsEmptyValue() descends only into arrays. A raw schema array containing a nested object with a null or empty property therefore passes validation and renders that object through jsonSerialize(), which also adds an unwanted nested @context.
Agent Prompt
## Issue description
Raw schema arrays can conceal invalid nested schema values and render nested contexts.
## Fix Focus Areas
- src/head/src/Tags/Schemas.php[106-114]
- src/head/src/Schema/SchemaValidator.php[54-64]
## Recommended Fix
Recursively normalize embedded `SchemaObject` values to their context-free arrays before validating and rendering raw schema arrays. Test an embedded object containing an empty property.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Member
Author
There was a problem hiding this comment.
Fixed the validation gap in 42ffae1. The validator now descends into nested SchemaObject values through toArray(), and a regression covers invalid nested properties. Raw schema serialization stays unchanged: nested JSON-LD contexts are valid, and validation does not need to rewrite application-owned schema data.
Comment on lines
+135
to
+137
| return static::$types[static::class] = $attributes === [] | ||
| ? Str::headline($reflection->getShortName()) | ||
| : $attributes[0]->newInstance()->name; |
There was a problem hiding this comment.
5. Custom schema types gain spaces 🐞 Bug ≡ Correctness
SchemaObject::typeFromAttribute() falls back to Str::headline() for a class without its own SchemaType attribute. A custom subclass such as NewsArticle consequently emits `"@type":"News Article"` rather than a schema type identifier, and a subclass of an attributed built-in schema also loses its parent's type.
Agent Prompt
## Issue description
The fallback formats custom schema class names as readable headlines rather than schema identifiers.
## Fix Focus Areas
- src/head/src/Schema/SchemaObject.php[124-137]
## Recommended Fix
Use a type-compatible class-name fallback and preserve an attributed parent type for subclasses that do not override it. Test both an unattributed custom class and a subclass of an attributed built-in type.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Member
Author
There was a problem hiding this comment.
Fixed in 42ffae1. Type inference now preserves the concrete class short name, so names such as JobPosting remain valid schema identifiers. Explicit types and SchemaType attributes still take precedence. Regression coverage includes a multiword class name. Parent attributes are intentionally not inherited: a NewsArticle subclass should infer NewsArticle, not silently become Article.
Comment on lines
+72
to
+78
| public function except(array|string $paths): void | ||
| { | ||
| if (! $this->gateway instanceof ExcludesSsrPaths) { | ||
| throw new LogicException('The configured SSR gateway does not support excluding paths from server-side rendering.'); | ||
| } | ||
|
|
||
| $this->gateway->except($paths); |
There was a problem hiding this comment.
7. Custom ssr gateways crash inertia requests 🐞 Bug ☼ Reliability
UniqueHeadGateway always implements ExcludesSsrPaths, DisablesSsr, ConfiguresSsrRequests, and HasHealthCheck, so instanceof checks pass even when its forwarding methods will throw LogicException because the wrapped gateway lacks the capability. With a custom dispatch-only gateway, configured withoutSsr paths make Inertia middleware call except() on every request, while inertia:check-ssr calls isHealthy() instead of taking its unsupported-capability branch; HeadServiceProvider is auto-registered, so this also affects apps that do not use Head.
Agent Prompt
## Issue description
`UniqueHeadGateway` advertises optional SSR capabilities even when the wrapped gateway does not support them. This causes middleware configured with `withoutSsr` paths to throw instead of skipping exclusions, and causes `inertia:check-ssr` to throw instead of taking its unsupported-capability branch.
## Fix Focus Areas
- src/head/src/Inertia/UniqueHeadGateway.php[19-104]
- src/head/src/Inertia/Integration.php[59-66]
## Recommended Fix
Make the base decorator implement only `Gateway`, and use capability-specific subclasses or decorator variants that expose each optional interface only when the wrapped gateway implements it. Select the appropriate variant in `Integration::decorateSsrGateway` using `instanceof` checks, while retaining forwarding for supported capabilities. Verify that middleware skips exclusions for a dispatch-only gateway and that the SSR check command takes its unsupported-capability branch for that gateway.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Member
Author
There was a problem hiding this comment.
Keeping the existing capability forwarding. Supported operations are delegated; asking a custom gateway to exclude paths or configure requests when it does not support that operation raises a clear error instead of silently ignoring the setting. Unsupported health checks report that capability is unavailable rather than incorrectly saying the server is down. No changes to the SSR response protocol are needed. Head is an optional split package. The root Composer provider entries are for monorepo development and do not install or enable Head in every application.
 [Medium impact] The PR appears safe to merge; all seven previous findings are addressed and no new actionable issues were found. SummaryAdds
Reviews (2) · Last reviewed commit: "Document canonical fallbacks and event s..." · Reviewed by Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Use the supplied magic setter value regardless of its argument name, preserving explicit null instead of replacing it with true. Infer schema types from the concrete class name without inserting spaces or inheriting a parent type. Restore numeric array keys to string labels in bulk breadcrumb and FAQ helpers. Descend into nested SchemaObject values during validation while preserving raw schema serialization and reference behavior. Extend schema regressions for named and null values, multiword class names, numeric labels, and invalid nested objects. Formatting, source and type analysis, and the Head suite pass.
Recognize HTTP and HTTPS schemes without regard to case and keep protocol-relative URLs on their explicit host. Resolve their scheme from forced HTTPS or the current request, retaining the protocol-relative form when neither applies. Keep origin callbacks limited to automatic and relative page URLs. Existing path, query, fragment, and trailing-slash normalization remains intact. Cover uppercase schemes and protocol-relative URLs with and without a request. Canonical tests, formatting, and static analysis pass.
Include the attribute in the ownership identity when a meta tag explicitly uses a different name or property attribute from the inferred default. This prevents Inertia deduplication from dropping distinct tags with the same key. Retain semantic ownership keys and aliases for normal tags so generic metadata continues to override dedicated builders. Media-specific tags keep their full identity. Add focused cases for description, Open Graph, and aliased theme metadata. Meta rendering tests, the Head suite, and static analysis pass.
Return an already registered custom builder before checking route-attribute conflicts. Repeated registration no longer conflicts with its own keys or invalidates the cached attribute map. Continue rejecting built-in builders, invalid extension classes, and keys owned by another builder. Extend the existing route integration regression to register the same builder twice and render its metadata. The focused extension tests, Head suite, formatting, and static analysis pass.
Replace pagination relations as one complete set so moving to a last or single page cannot retain stale links. Accept cursor paginator contracts alongside ordinary paginators, regenerate facade metadata, and stop advertising pagination as a route attribute. Accept bare feed URLs and lists as untitled RSS feeds while retaining titled maps and structured definitions. Treat omitted or null structured titles as untitled, omit empty title attributes, and continue rejecting other non-string titles. Reject ambiguous URL-to-string resource-hint maps through the existing route validation path instead of rendering the value as a URL. Preserve supported scalar and structured list inputs. Add focused rendering and route regressions for replacement, cursors, feed forms, and invalid inputs. Affected tests, the Head suite, facade checks, formatting, and source and type analysis pass.
Register lazy Head sharing before global middleware so Inertia error responses include metadata when maintenance handling rejects the request. Recognize registered Inertia provider subclasses while keeping discovery-disabled applications free of the integration. Register exception status callbacks only when the bound handler supports each hook. Use the exception handler contract and callable checks so contract-only handlers and forwarding fakes remain supported without adding runtime lookup machinery. Cover maintenance errors, a custom Inertia provider with a custom prop, and a handler without rendering hooks. Existing tests retain early kernel and handler resolution, SSR, and partial-reload coverage. Focused tests, the Head suite, formatting, and static analysis pass.
Explain complete pagination replacement, ordinary and cursor paginator support, accepted feed route forms, and omission of an empty fluent feed title. Clarify that automatic exception status capture uses the framework exception handler. Keep correctness fixes and additive support in the feature guide without adding compatibility warnings to the Laravel porting guide. Update the active port plan to reflect the completed correction design and the remaining release checkpoint.
Resolve an omitted og:url from the existing canonical builder when Open Graph metadata is present. Preserve explicit Open Graph URLs and leave output unchanged when no canonical or Open Graph builder exists. Port the implementation and regression cases from laravel/head#14 while retaining null and empty-string checks. Also port the split-defaults regression from laravel/head#16; the existing per-media provenance flags already provide the fix. The Head suite, source and type analysis, facade checks, and formatting pass. The change adds no cross-request state or cache.
Port the Event location, image, performer, status, and attendance-mode helpers from laravel/head#15, together with Place and the two schema.org enums. Preserve the proposed signatures and string-location conversion to a named Place, following existing typed schema conventions. Register Place in the schema factory and regenerate its facade metadata. All schema builders continue to support raw values through set(), and nested values use the existing coercion path. Copy and convert every upstream Event schema test to PHPUnit, covering rendering, location conversion, enums, related schemas, and factory resolution. Formatting, source and type analysis, the Head suite, and facade checks pass.
Extend the Open Graph fallback guidance to include the canonical URL and record the public output difference in the package README. Document Event and Place authoring with a structured address, status and attendance enums, string-location behavior, and raw schema values through set(). Add the Events navigation entry and Place factory to the feature guide. Record the agreed upstream additions and remaining PR workflow in the active port plan. Keep upstream source references there rather than in the package README.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds
hypervel/head, a port of Laravel Head for managing document titles, metadata, canonical URLs, social cards, links, and structured data from PHP. It supports Blade and optional Inertia integration, including SSR.The fluent builders, route macros, named arguments, schema APIs, and eager configuration methods follow upstream. The main adaptation is state ownership: Hypervel serves concurrent requests in long-lived workers, so metadata for one page must never become another request's defaults.
Request state and runtime configuration
Page data and error status are coroutine-scoped. Copying a coroutine context copies its Head data and schema objects, so child work can change its metadata without changing the parent. Mutable builders and schema objects resolve as fresh instances; managers, renderers, registries, and factories reuse worker-safe services.
Three optional hooks let applications configure request-dependent metadata during provider boot:
Head::resolveDefaultsUsing()builds defaults from the current request or application context.Head::resolveErrorsUsing()builds error metadata from the actual response status.Head::resolveCanonicalOriginUsing()supplies the preferred origin for automatic and relative canonical URLs, useful when a site has aliases or custom domains.These hooks preserve the existing eager
defaults(),errors(), andinertiaGlobals()APIs. Runtime values are resolved afresh, with precedence from defaults through route groups, route metadata, page data, and error metadata. Head does not fetch settings or add database queries. Applications can reuse settings they have already loaded.flush()clears the current coroutine's page data and status when generating independent pages sequentially. Boot configuration remains intact. Public configuration methods explain their worker lifetime, and the guide uses team settings to show safe runtime configuration.Blade and Inertia
Blade receives the
@headdirective. Inertia integration is enabled only when its provider is registered; having its classes available does not enable it. The package declares its own dependencies and discovery metadata for standalone installation.Head remains a lazy shared prop, preserving partial reload behavior. It is registered before global middleware so early error responses also receive metadata. Registered Inertia provider subclasses enable the integration too. Initial documents and subsequent Inertia visits use stable ownership keys. The SSR decorator removes duplicate page-managed tags while preserving other SSR tags and the rendered body. It creates a new immutable response instead of modifying Hypervel's readonly SSR result, and forwards request configuration, disabling, path exclusions, and health checks to the wrapped gateway.
There is no Inertia JavaScript protocol change. The guide covers
serverHeadconfiguration in both client and SSR entry points, custom prop names, static globals, and moving overlapping client metadata into Head. Livewire integration is intentionally omitted; Blade and Inertia are the supported rendering paths.Rendering fixes
"0"titles and descriptions survive rendering and array conversion, including Open Graph and Twitter fallbacks.titlehave separate Inertia ownership, so both survive deduplication.nameandpropertyattributes keep separate Inertia identities, while normal generic tags retain their ability to override dedicated builders.The port also includes the canonical-to-Open-Graph URL fallback and Event/Place helpers proposed upstream. An unset
og:urlfollows the resolved canonical when Open Graph metadata is present, with explicit URLs taking precedence. Event builders gain location, image, performer, status and attendance-mode helpers, plus a Place builder and schema.org enums. Their typed conventions follow the existing schema builders;set()remains available for raw schema values.The Open Graph fix replaces its single protected default-media flag with per-type flags. Public fluent methods are unchanged. An SSR gateway without health-check support now reports that unsupported capability instead of incorrectly reporting that the server is down.
Shared framework support
The exception handler gains
beforeResponding(), exposed through exception configuration and the facade. It observes the prepared response before the application's final response customization without replacing that callback. Head uses it to capture the actual status before an Inertia error page renders, including exceptions with embedded responses or custom renderers. The early status callback remains for ordinary Blade error views. Head registers these hooks only when the bound handler supports them, preserving custom exception handlers.TestResponsealso correctly reports invalid JSON from a plain Symfony response when no stored exception exists. Stored exceptions are still rethrown unchanged.Performance and tooling
Route-attribute lookup and inferred schema types are cached by registered builder or loaded class, keeping worker memory bounded. Request values and rendered output are not cached across requests. JSON-LD is encoded once per render, and non-cryptographic content identifiers use deterministic
xxh128hashes.Editor declarations and a package PHPStan extension cover every
withHeadrouting surface without loading runtime macros or replacing existing routing types. The extension follows the framework's existing layout and uses public PHPStan reflection APIs. Generated facade metadata retains rich callback and generic types through the existing mixin support. Optional static cleanup integrates with the framework test lifecycle.Validation
Applicable upstream tests are ported to PHPUnit, with additional coverage for coroutine isolation, context copying, runtime configuration, rendering fixes, exception responses, and SSR integration. Formatting, source and type analysis, Head tests, facade checks, package-mode tests, and dogfood checks pass.
The full framework suite was also exercised, with affected checks repeated after corrections. External-service tests without configured services were skipped.
The upstream Head guide is included and adapted for Hypervel, with package navigation, an Inertia link, and guidance for porting worker-shared configuration.
Note
Add Head package for Blade and Inertia head metadata management
withHeadroute macro across all routing surfaces.@headdirective and with Inertia via theShareHeadmiddleware andUniqueHeadGatewaySSR decorator, so PHP-managed metadata renders into the initial document and is shared with Inertia navigation.Exceptions::beforeRespondingcallbacks on the exception handler so Head can capture the HTTP status for error-page metadata, plus PHPStan extensions and IDE helpers for the route macro.HeadManagervia the newbeforeRespondinghook in Handler.php; route head metadata rejects unknown names or invalid values withInvalidArgumentExceptioninstead of ignoring them.Macroscope summarized 54414c4.