HTML Cache

Package docs status

This page is generated from package source documentation in the Capell packages repository and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

Field	Value
Composer package	`capell-app/html-cache`
Package slug	`html-cache`
Product group	Capell Foundation
Tier	free
Bundle	`foundation`
Runtime contexts	`admin`, `frontend`
Capell version	`^1.0`
Catalogue role	extension
Release channel	Released
Source repository	`capell-app/packages`
Source path	`packages/html-cache`
Docs source	`packages/html-cache/docs`
Manifest	`capell.json`

What This Plugin Adds

HTML Cache is an Available, Schema-owning Capell package in the Capell Foundation product group. It ships as capell-app/html-cache and extends these surfaces: admin, frontend.

Full-page static HTML cache for Capell with dependency-indexed invalidation, scheduled stale-regeneration, and public-output safety guarantees. It stores full public HTML responses, indexes their model dependencies, and supports immediate or scheduled stale regeneration.

Administrators inspect coverage, dependency maps, and stale work, then clear, warm, or regenerate cached pages. Anonymous visitors receive cached public HTML without authoring markers or session cookies.

Status details:

Status: Available
Tier: free
Bundle: foundation
Composer package: capell-app/html-cache
Namespace: Capell\HtmlCache
Theme key: not applicable

Why It Matters

For developers: Middleware eligibility rules and dependency-indexed Actions keep cache writes, invalidation, stale claims, and atomic refresh behavior explicit and testable.

For teams: Teams can see whether important URLs are cached, recover from stale output, and diagnose unsupported node-local multi-node deployments without weakening the rule that admin and authoring details stay out of public files.

Screens And Workflow

Screenshot contract: docs/screenshots.json.

HTML Cache maintenance cache page

Cached model URLs resource index

HTML Cache maintenance cache page (admin, required evidence).
Cached model URLs resource index (admin, supplementary evidence).
HTML Cache dashboard widgets (admin, supplementary evidence).
HTML Cache site health cache map (admin, supplementary evidence).
Page table cache indicator (admin, supplementary evidence).
Anonymous public cache hit (frontend, supplementary evidence).
Public maintenance page (frontend, supplementary evidence).
HTML Cache maintenance cache page with admin sidebar menu open (admin, supplementary evidence).
Cloudflare anonymous public HTML cache rule (admin, supplementary evidence).
Cloudflare cache rule activation (admin, supplementary evidence).
Cloudflare Edge TTL and Browser TTL settings (admin, supplementary evidence).

Technical Shape

Service providers

Capell\HtmlCache\Providers\HtmlCacheServiceProvider

Config files

packages/html-cache/config/capell-html-cache.php

Migrations

packages/html-cache/database/migrations/2026_05_10_190854_01_create_cached_model_urls_table.php
packages/html-cache/database/migrations/2026_05_14_000001_create_stale_cached_urls_table.php
packages/html-cache/database/migrations/2026_06_07_000001_add_telemetry_to_cached_model_urls_table.php
packages/html-cache/database/migrations/2026_07_18_000001_create_html_cache_generation_runs_table.php
packages/html-cache/database/migrations/2026_08_22_000001_add_scope_to_html_cache_generation_runs_table.php

Models

CachedModelUrl
HtmlCacheGenerationRun
StaleCachedUrl

Filament classes

PageCachedIconColumn
HasPageCacheNotification
PageCachePageTableExtender
MaintenanceSiteHeaderActionExtender
MaintenanceCachePage
UncachedPagesPage
CachedModelUrlResource
ListCachedModelUrls
CachedModelUrlsTable
HtmlCacheDashboardSettingsContributor
CacheCoverageUrlsFilamentWidget
HtmlCacheOverviewFilamentWidget
HtmlCacheStaleQueueFilamentWidget

Livewire components

SiteHealthCacheMap

Extension contracts

CachePurger
PageCacheNotifiable

Actions

AssertHtmlCacheInvalidationTopologyAction
BuildCacheMapOverviewAction
BuildCachedModelUrlDiagnosticsAction
BuildHtmlCacheEligibilityReportAction
BuildHtmlCacheOriginDecisionAction
BuildHtmlCachePublicOutputSafetyDiagnosticsAction
BuildMaintenanceCacheOverviewAction
BuildUncachedPagesAction
CanClearHtmlCachePortCopyAction
ClaimStaleCachedUrlAction
ClearAllHtmlCacheAction
ClearCachedPageUrlsAction
ClearCachedUrlAction
ClearCachedUrlsForModelAction
ClearCachedUrlsForSurrogateKeysAction
BuildHtmlCacheDashboardStatsAction
BuildHtmlCacheStaleQueueRowsAction
BuildHtmlCacheUrlRowsAction
DeleteCachedUrlArtefactsAction
DeletePageCacheAction
DisableGlobalMaintenanceAction
DisableSiteMaintenanceOverrideAction
EnableGlobalMaintenanceAction
EnableSiteMaintenanceOverrideAction
EnsureHtmlCachePermissionsAction
ForgetCachedUrlAction
GenerateStaticSiteAction
GenerateStaticSitesAction
InspectEdgeCachePurgeReadinessAction
ListCacheMapResourceOptionsAction
MarkAllCachedUrlsStaleAction
MarkCachedUrlStaleAction
MarkCachedUrlsForModelStaleAction
MarkCachedUrlsForSiteStaleAction
NotifyClearCachedPagesAction
PlanEditorHtmlCacheConsequencesAction
PrepareMaintenanceCacheAction
PrepareSiteMaintenanceCacheAction
ProcessStaleHtmlCacheAction
PruneHtmlCacheMetadataAction
PurgeEdgeCacheAction
QueueMaintenancePageGenerationAction
RecordCachedModelUrlsAction
RecordHtmlCacheHitAction
RefreshCachedUrlAtomicallyAction
RefreshOriginStaleCachedUrlAction
RenderCoalescedHtmlCacheMissAction
ResolveCachedUrlsForModelAction
ResolveCachedUrlsForSurrogateKeysAction
ResolveEdgeCacheTagsAction
RetireCachedUrlAction
ScheduleOriginStaleCachedUrlRefreshAction
SelectStaleHtmlCacheCandidatesAction
WriteRefreshedHtmlCacheFileAction

Data objects

CacheMapModelSummaryData
CacheMapOverviewData
CacheMapResourceSummaryData
HtmlCacheDashboardStatsData
EdgeCachePurgeData
EdgeCachePurgeReadinessData
HtmlCacheClearResult
HtmlCacheEligibilityReportData
HtmlCacheHitBatchData
HtmlCacheOriginDecisionData
MaintenanceCacheDomainData
MaintenanceCacheOverviewData
MaintenanceSiteStatusData
StaleHtmlCacheProcessResultData
UncachedPageData
UncachedPagesData

Jobs

FlushHtmlCacheHitBatchJob
GenerateMaintenancePagesJob
RefreshOriginStaleCachedUrlJob
RegisterCachedModelUrlsJob

Command signatures

capell:html-cache:clear
capell:html-cache:diagnose
capell:html-cache:edge-purge:verify
capell:html-cache:process-stale
capell:static-site

Scheduled commands

capell:html-cache:process-stale (package registered)

Console command classes

ClearHtmlCacheCommand
DiagnoseHtmlCacheCommand
ProcessStaleHtmlCacheCommand
StaticSiteCommand
VerifyEdgeCachePurgeCommand

Manifest contributions

admin-page: Capell\HtmlCache\Manifest\HtmlCacheAdminPagesContribution
admin-resource: Capell\HtmlCache\Manifest\HtmlCacheAdminResourcesContribution
console-command: Capell\HtmlCache\Manifest\HtmlCacheConsoleCommandsContribution
dashboard-widget: Capell\HtmlCache\Manifest\HtmlCacheDashboardFilamentWidgetsContribution
model: Capell\HtmlCache\Manifest\HtmlCacheModelsContribution
route: Capell\HtmlCache\Manifest\HtmlCacheFrontendRoutesContribution
scheduled-job: Capell\HtmlCache\Manifest\HtmlCacheStaleProcessingScheduleContribution

Health checks

Capell\HtmlCache\Health\HtmlCacheHealthCheck

Blade views

packages/html-cache/resources/views/filament/pages/maintenance-cache.blade.php
packages/html-cache/resources/views/filament/pages/partials/uncached-pages-table.blade.php
packages/html-cache/resources/views/filament/pages/uncached-pages.blade.php
packages/html-cache/resources/views/livewire/site-health-cache-map.blade.php

Cache tags

html-cache

Data Model

Required tables: cached_model_urls, html_cache_generation_runs, stale_cached_urls.
Models: CachedModelUrl, HtmlCacheGenerationRun, StaleCachedUrl.
Core record references in migrations: sites via site_id, languages via language_id, site domains via site_domain_id.
Migration files: 2026_05_10_190854_01_create_cached_model_urls_table.php, 2026_05_14_000001_create_stale_cached_urls_table.php, 2026_06_07_000001_add_telemetry_to_cached_model_urls_table.php, 2026_07_18_000001_create_html_cache_generation_runs_table.php, 2026_08_22_000001_add_scope_to_html_cache_generation_runs_table.php.
Migration impact: run host migrations through the package install flow before opening package surfaces.
Deletion/retention behaviour: migrations declare null-on-delete relationships; no timed pruning or retention schedule is declared in capell.json.

Install Impact

Required packages: capell-app/admin, capell-app/core, capell-app/discovery-foundation, capell-app/frontend.
Admin navigation: declares admin-page: HtmlCacheAdminPagesContribution, admin-resource: HtmlCacheAdminResourcesContribution; each Filament page or resource controls its own navigation visibility.
Admin/editor extensions: dashboard-widget: HtmlCacheDashboardFilamentWidgetsContribution.
Permissions: capell-html-cache.view, capell-html-cache.clear, capell-html-cache.maintenance.manage.
Public routes: registers HtmlCacheFrontendRoutesContribution.
Database changes: package migrations are declared.
Config: config/capell-html-cache.php.
Settings: no package settings declared.
Queues or schedules: scheduled commands capell:html-cache:process-stale (package registered); queue jobs FlushHtmlCacheHitBatchJob, GenerateMaintenancePagesJob, RefreshOriginStaleCachedUrlJob, RegisterCachedModelUrlsJob.
Cache tags: html-cache.
Commands: capell:html-cache:clear, capell:html-cache:diagnose, capell:html-cache:edge-purge:verify, capell:html-cache:process-stale, capell:static-site.

Common Pitfalls

Keep required Capell packages on compatible v4 releases: capell-app/admin, capell-app/core, capell-app/discovery-foundation, capell-app/frontend.
Run migrations before opening package resources or public routes.
Review package configuration before production-like verification: config/capell-html-cache.php.
Keep the host Laravel scheduler running so package-registered schedules can execute: capell:html-cache:process-stale (package registered).
Keep public Blade and cached HTML free of authoring markers, model IDs, permissions, signed editor URLs, and lazy database queries.
Custom write integrations must preserve invalidation for html-cache cache tags.

Troubleshooting

Symptom	Likely cause	Check	Fix
Package surface is missing after install	Provider or manifest is not loaded	Confirm `capell.json`, package `composer.json`, and provider registration	Reinstall the package, refresh Composer autoload, and clear host caches
Admin screen or command fails on missing table	Package migrations have not run	Check the tables listed in `Data Model`	Run host migrations and rerun the focused package test
Background work does not run	Queue worker or declared schedule is not active	Check the jobs and scheduled commands listed in `Technical Shape`	Start the queue worker or host scheduler, then run the focused command or package test
Public output leaks unexpected state	Render data, cache variation, or authoring boundary has regressed	Check public Blade, cache tags, and public-output safety tests	Move data loading out of Blade and rerun the package public-output tests

Quick Start

Install the package: composer require capell-app/html-cache.
Open the package admin surface at /admin/html-cache/maintenance-cache and confirm HTML Cache is available.

Next Steps

Package docs
Overview
Worked extension examples
Admin guide
Configuration files: config/capell-html-cache.php.
Troubleshooting
Screenshot contract
Marketplace assets
Capell content language plan
Capell documentation design system
Capell and package ERD notes
Related packages: Discovery Foundation, Site Discovery.