HTML Cache
Package docs status
Section titled “Package docs status”This page is generated from public package documentation in capell-4/packages and the package manifest checked into the source repository.
| 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 | ^4.0 |
| Source repository | capell-app/packages |
| Source path | packages/html-cache |
| Docs source | packages/html-cache/docs |
| Manifest | capell.json |
What This Plugin Adds
Section titled “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.
After install, admins get package-owned management surfaces and public users may see package-owned frontend output or routes.
Status details:
- Status: Available
- Tier: free
- Bundle: foundation
- Composer package:
capell-app/html-cache - Namespace:
Capell\HtmlCache - Theme key: not applicable
Why It Matters
Section titled “Why It Matters”For developers: The package gives developers package-owned service providers, Actions, Data objects, models, Filament classes, and Blade views instead of pushing this behaviour into core or application code.
For teams: Serve Capell pages as static HTML for sub-millisecond responses - with automatic, dependency-aware invalidation that keeps cached pages fresh and never leaks gated or authoring content to anonymous visitors.
Screens And Workflow
Section titled “Screens And Workflow”Screenshot contract: docs/screenshots.json.
- HTML Cache maintenance cache page (admin, required).
- Cached model URLs resource index (admin, required).
- HTML Cache dashboard widgets (admin, required).
- HTML Cache site health cache map (admin, required).
- Page table cache indicator (admin, required).
- Anonymous public cache hit (frontend, required).
- Static maintenance page output (frontend, required).
Technical Shape
Section titled “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. - Models:
CachedModelUrl,StaleCachedUrl. - Filament classes:
PageCachedIconColumn,HasPageCacheNotification,PageCachePageTableExtender,MaintenanceSiteHeaderActionExtender,MaintenanceCachePage,CachedModelUrlResource,ListCachedModelUrls,CachedModelUrlsTable,HtmlCacheDashboardSettingsContributor,CacheCoverageUrlsFilamentWidget,HtmlCacheOverviewFilamentWidget,HtmlCacheStaleQueueFilamentWidget. - Livewire components:
SiteHealthCacheMap. - Actions:
BuildCacheMapOverviewAction,BuildCachedModelUrlDiagnosticsAction,BuildHtmlCacheEligibilityReportAction,BuildHtmlCachePublicOutputSafetyDiagnosticsAction,ClearAllHtmlCacheAction,ClearCachedPageUrlsAction,ClearCachedUrlAction,ClearCachedUrlsForModelAction,ClearCachedUrlsForSurrogateKeysAction,BuildHtmlCacheDashboardStatsAction,BuildHtmlCacheStaleQueueRowsAction,BuildHtmlCacheUrlRowsAction,and 14 more. - Data objects:
CacheMapModelSummaryData,CacheMapOverviewData,CacheMapResourceSummaryData,HtmlCacheDashboardStatsData,HtmlCacheClearResult,HtmlCacheEligibilityReportData. - Jobs:
RegisterCachedModelUrlsJob. - Console command classes:
ClearHtmlCacheCommand,DiagnoseHtmlCacheCommand,ProcessStaleHtmlCacheCommand,StaticSiteCommand. - Manifest contributions:
admin-page: Capell\HtmlCache\Manifest\HtmlCacheAdminPagesContribution,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/livewire/site-health-cache-map.blade.php. - Cache tags:
html-cache.
Data Model
Section titled “Data Model”- Models:
CachedModelUrl,StaleCachedUrl. - 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. - Migration impact: run host migrations through the package install flow before opening package surfaces.
- Deletion/retention behaviour: Docs gap unless the package has an explicit pruning command, retention setting, or tested cascade path.
Install Impact
Section titled “Install Impact”- Admin navigation: adds package-owned Filament classes when registered.
- Permissions:
capell-html-cache.view,capell-html-cache.clear. - Public routes: none detected in package route files.
- Database changes: package migrations are declared.
- Settings: no package settings declared.
- Queues or schedules: review package jobs or schedules before install.
- Cache tags:
html-cache. - Commands: console command classes detected:
ClearHtmlCacheCommand,DiagnoseHtmlCacheCommand,ProcessStaleHtmlCacheCommand,StaticSiteCommand.
Common Pitfalls
Section titled “Common Pitfalls”- Run migrations before opening package resources or public routes.
- Keep public Blade and cached HTML free of authoring markers, model IDs, permissions, signed editor URLs, and lazy database queries.
- Keep
composer.json,composer.local.json,capell.json, docs, screenshots, and tests aligned when the package surface changes.
Troubleshooting
Section titled “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 scheduled command is not active | Check package jobs, commands, and host scheduler configuration | Start the queue or 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
Section titled “Quick Start”- Install the package:
composer require capell-app/html-cache. - Run the required setup:
php artisan migrate. - Open the related Capell admin surface and verify HTML Cache appears.
Next Steps
Section titled “Next Steps”- Package docs
- Overview
- Screenshot contract
- Marketplace assets
- Capell content language plan
- Capell documentation design system
- Capell and package ERD notes
- Related packages: Site Discovery.
- Focused tests:
vendor/bin/pest packages/html-cache/tests --configuration=phpunit.xml.