Rendering Laravel Package

Getting Started

gcego/rendering v1.0.0 is the first stable cut of GCEGO Studio's rendering layer, extracted into a standalone package. It is the piece that turns a component blueprint into escaped, renderable output — so treat it as the layer between your component definitions (gcego/components) and whatever surface you're rendering into (Blade views, Livewire components, HTTP responses).

Install and verify the stack first. The dependency floor is unusually strict for a first stable release: PHP 8.3+, Laravel 13, plus gcego/core ^1.0, gcego/registry ^1.1, gcego/blueprints ^1.0, gcego/runtime ^0.2 and gcego/components ^0.1. Because gcego/runtime is still pre-1.0, expect its minor bumps to be the most likely source of friction; pin it deliberately and read its changelog alongside this one.

composer require gcego/rendering:^1.0

Where to look first. Open RenderEngine — it is the whole public surface in one class: render(), renderAuthorized(), authorizedBlueprint(), identityOf(), canRender(), operation(). Read those six methods before touching anything else. Then look at Renderers\RendererRegistry (the component-to-renderer map) and Output\RenderResult (the value object you'll actually be handling in controllers and views). Ignore StylingResolver, StateCoordinator and RenderingInspector on day one; they are depth you'll grow into.

Your first use case should be the smallest possible one: resolve the engine, render a single known component, and echo the result. Use the auto-aliased Rendering facade for brevity, and confirm you get escaped output by rendering a component whose content includes <script> or an ampersand. If that round-trips safely, the pipeline is wired correctly.

$result = Rendering::render($blueprint);

return view('page', ['html' => $result]); // RenderResult is lazy + escaped

In Blade, the <x-gcego-rendering::render> component is the fastest path to a working integration and exercises the same authorization gate as the facade — start there if you're rendering inside existing templates rather than from a controller.

Implementation Patterns

Default to renderAuthorized() in request paths. The package ships fail-closed authorization: GateRenderAuthorizer checks the gcego-rendering.render ability for public entry points and for the <x-gcego-rendering::render> Blade component. Plain render() appears to be the unguarded primitive — appropriate inside jobs, console commands, tests and internal composition, not on anything a user can reach. Make renderAuthorized() your muscle memory and treat bare render() as a deliberate, reviewable choice.

Register renderers rather than branching in views. RendererRegistry maps components to renderers, with ContainerRenderer built in and Blade\BladeRenderer as the base class for your own. The healthy pattern is one renderer class per component family, registered once in a service provider, so that "how does this component look" lives in one place instead of being spread across @if chains. Extend BladeRenderer when the output is a template; use ContainerRenderer for structural wrappers that mostly delegate to children.

Lean on Children and RenderResult for composition. RenderResult and Output\Children are lazy and escaped, which means you can build a tree of components and let the final echo do the work. Compose results into Children and return a parent RenderResult; don't flatten to strings early. Flattening kills laziness and forces you to reason about escaping manually at every join point.

Confine raw HTML to one seam. RenderResult::trustedHtml() is the only sanctioned escape hatch. Wrap it — a tiny helper or a dedicated renderer method — so grep for trustedHtml returns a short, auditable list. Any place that calls it should have a comment saying where the HTML came from and why it is trusted, because that's exactly the line a security review will ask about.

Wire into the runtime kernel, not around it. The render operation category (Contracts\RenderHandler, Execution\RenderOperationHandler) exists so rendering participates in gcego/runtime's execution kernel alongside other operations. If your application already dispatches work through the kernel, register the handler and let rendering be one operation among many; you get consistent authorization, error handling and diagnostics for free. Calling RenderEngine::render() directly from deep inside domain code bypasses operation() and its kernel semantics, and you'll notice the inconsistency later.

Use identityOf() for cache keys and telemetry. It gives you a stable identity for a render, which is the right ingredient for memoisation keys, ETags and log correlation. canRender() is the cheap pre-flight check — useful for deciding whether to show a component at all before paying the cost of rendering it.

Reach for Livewire state primitives when components are interactive. StatefulComponent, StatePath and StateCoordinator are the package's answer to "this component has state that must survive a round trip." Use StatePath to address state within the structure rather than hand-rolling dot-notation strings; the coordinator assumes a consistent path scheme, and mixing your own keys into it is how you get state that disappears after a Livewire update.

Apply styling through StylingResolver and style slots. Resolve styles rather than hard-coding classes in renderers. It keeps theme changes out of PHP and makes it possible to override presentation without subclassing a renderer.

Instrument with RenderingInspector / RenderingReport from the start. Add a report to your local dev toolbar or a debug route early. When a component quietly renders as the production placeholder instead of throwing, the report is how you find out which one failed and why.

Gotchas and Tips

The production error boundary will hide your bugs. Outside production, a failing component throws — loud and obvious. In production, the package reports the failure and substitutes an accessible placeholder, so a broken renderer degrades into a missing box rather than a 500. That's excellent for users and terrible for your observability: make sure the report actually reaches your log aggregation, and consider alerting on placeholder frequency. GCEGO_RENDERING_STRICT overrides the behaviour, which is how you reproduce a production-shaped failure locally — set it when you need the placeholder path, unset it when you want the exception.

Fail-closed authorization is a feature that looks like a bug. If renders mysteriously return nothing or are denied, the first thing to check is the gcego-rendering.render ability on the current user. It's especially easy to trip in tests and seeders where no authenticated user exists.

Escaping is the default, so "my HTML is showing as text" is expected. Do not fix it by sprinkling trustedHtml() — that converts a display quirk into an injection risk. Fix the renderer so it emits a structured RenderResult instead of a pre-built string.

Strict requirements mean a strict upgrade path. Laravel 13 and PHP 8.3 are hard floors, and six interdependent gcego/* packages must all resolve together. Upgrade them as a set, not individually. When gcego/runtime moves past ^0.2, budget real time for it — a pre-1.0 dependency in an otherwise 1.0 package is the most probable source of future breakage.

Laziness has ordering consequences. Because RenderResult and Children are lazy, exceptions may surface at echo time rather than construction time, which puts stack traces in odd places (inside Blade compilation, mid-response). When debugging, force evaluation early — stringify the result in a test — so failures point at the renderer rather than at the view layer.

Check the renderer registry before blaming the engine. "Component rendered as nothing" is almost always a missing or mis-keyed registry entry, not an engine fault. The registry is the first place to look for anything mapping-related.

Keep the operation handler and direct calls consistent. If you use Execution\RenderOperationHandler in some paths and RenderEngine directly in others, authorization and diagnostics will diverge between them. Pick the kernel path for anything request-driven and stick to it.

Version-pin the whole family in CI. With this many interlocking pre-1.0 dependencies, composer update on a green build is a false signal. Lock the set, and run your render tests against the placeholder boundary as well as the strict one — GCEGO_RENDERING_STRICT toggling in a test matrix costs little and catches the class of bug that otherwise only appears in production.