Skip to content
Capell CMS

Frontend Page & Site Loading Overview

This document explains how Capell’s frontend resolves a request into a rendered page, the services involved, and the kernel pipeline steps.

High-level flow

Section titled “High-level flow”
  • A request enters the app and the Frontend middleware invokes the Frontend Kernel.
  • The Kernel builds a FrontendWork with the HTTP request and a FrontendState (scoped per request).
  • The Kernel runs a sequence of steps (a Laravel Pipeline) to resolve site/domain/language, page, layout, theme, and build a renderable context.
  • The result is a FrontendBootstrapResult that may contain:
    • redirect: if the request should be redirected (e.g., default site redirect)
    • error: HTTP error details (e.g., 404 for bots)
    • context: a resolved FrontendContext for rendering

Container bindings (service provider)

Section titled “Container bindings (service provider)”

The FrontendServiceProvider registers the key interfaces used by the pipeline:

  • UrlSignatureVerifierInterface → FrontendUrlSignatureService
  • AssetsRegistryInterface → FrontendAssetsService
  • ModelServingInterface → ModelRetrievalTracker
  • FrontendSettingsReaderInterface → FrontendSettingsReader
  • SettingsMigrationProviderInterface → FrontendSettingsMigrationProvider
  • FontMimeTypeResolverInterface → FontMimeTypeResolver

Scoped state:

  • FrontendState (scoped per request)
  • FrontendContextReader resolves to FrontendState

Kernel registration:

  • FrontendKernelInterface is bound to a FrontendKernel with the steps from config('frontend.kernel.steps'). Defaults:
    1. ParseUrlStep
    2. SiteResolveStep
    3. NormalizeDomainPathStep
    4. VerifyRevisionSignatureStep
    5. PageResolveStep
    6. ResolveLayoutStep
    7. ResolveThemeStep
    8. BuildContextStep
    9. CommitContextStep
    10. RegisterThemeViewsStep
    11. NotifySubscribersStep

Aux services:

  • ThemeViewRegistrar (singleton)
  • FrontendCachePolicy (singleton)
  • WidgetRegistry from capell/core for legacy block component aliases
  • OnFrontendContextResolved listener (singleton)
  • Url generator binding switches to SiteUrlGenerator when capell-frontend.use_site_domain_for_urls is true; otherwise Laravel UrlGenerator.

Runtime manifest contributors

Section titled “Runtime manifest contributors”

ResolveFrontendRuntimeAction owns the generic Blade, Livewire, and Inertia runtime decision. Optional packages that need extra public frontend runtime flags should not be referenced directly from capell/frontend; they should implement Capell\Frontend\Contracts\FrontendRuntimeManifestContributor and tag the implementation with FrontendRuntimeManifestContributor::TAG.

Contributors receive the resolved FrontendContextReader and mutable FrontendRuntimeManifestData, letting add-ons contribute runtime flags while frontend remains safe to install on its own.

Pipeline steps (summary)

Section titled “Pipeline steps (summary)”
  • ParseUrlStep: Normalizes the request path (leading slash, index.php → /, trailing slash alignment) and saves it into state.
  • SiteResolveStep: Resolves the site, language, domain, and normalized path from the full URL; optionally issues a redirect to the default site when enabled.
  • NormalizeDomainPathStep: Removes the domain path prefix (e.g., /en) from the effective URL to obtain the page-relative path.
  • VerifyRevisionSignatureStep: Verifies access to a specific page revision when present.
  • PageResolveStep: Resolves the target Page; supports wildcard routes, error page fallback, and returns 404 for bot UA when no page is found.
  • ResolveLayoutStep: Chooses the layout for the resolved page.
  • ResolveThemeStep: Chooses the theme for rendering.
  • BuildContextStep: Builds the FrontendContext (data required for rendering).
  • CommitContextStep: Commits the context to state for later access.
  • RegisterThemeViewsStep: Registers theme view paths for Blade.
  • NotifySubscribersStep: Emits FrontendContextResolved to notify listeners.

Error and redirect handling

Section titled “Error and redirect handling”
  • Redirects short-circuit the pipeline and return immediately from the Kernel.
  • Errors also short-circuit; bots receive an immediate 404 when the page cannot be resolved.

Config toggles

Section titled “Config toggles”
  • capell-frontend.redirect_default_site: When true, unresolved domains redirect to the default enabled SiteDomain.
  • capell-frontend.use_site_domain_for_urls: Switches URL generation to include site domain rules.
  • capell-frontend.debug_log: Adds extra debug logging in resolution steps.

Caching

Section titled “Caching”
  • FrontendCachePolicy and HtmlCacheMiddleware manage cache behavior.
  • Read the Frontend guide for HTML caching details.

Testing coverage

Section titled “Testing coverage”

Unit and integration tests validate the pipeline contracts:

  • Integration: FrontendKernelTest boots the kernel end-to-end.
  • Unit: ResolveLayoutStepTest, ResolveThemeStepTest, VerifyRevisionSignatureStepTest, plus additional tests covering ParseUrlStep, NormalizeDomainPathStep, SiteResolveStep default redirect, and PageResolveStep bot 404.