HTML Cache

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

Static HTML cache, dependency indexing, and cache administration for Capell.

At A Glance

• Package: capell-app/html-cache
• Namespace: Capell\HtmlCache\
• Surfaces: Filament admin, Livewire, console, queue, database
• Service providers: packages/html-cache/src/Providers/HtmlCacheServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/core, capell-app/frontend
• Third-party dependencies: laravel/framework, lorisleiva/laravel-actions, spatie/laravel-data, spatie/laravel-package-tools

Why It Helps Your Capell Workflow

• Adds static HTML cache indexing, dependency tracking, and admin cache controls for Capell public pages.
• Helps operators see stale cached URLs and refresh affected pages without manually clearing broad caches.
• Protects public-output safety by keeping cached HTML suitable for anonymous visitors, admins, crawlers, and static exports.

Best Used With

• Frontend Authoring
• Frontend Optimizer
• Diagnostics

What It Adds

• Static HTML cache, dependency indexing, and cache administration for Capell.
• Admin resources: CachedModelUrlResource.
• Admin page: MaintenanceCachePage.
• Dashboard widgets for cache overview, cache coverage, and stale regeneration queue.
• Livewire components: SiteHealthCacheMap.
• Package setup or maintenance commands.

Code Map

Area	Path	Purpose
Actions	packages/html-cache/src/Actions	Domain operations. Test these directly where possible.
Data	packages/html-cache/src/Data	Structured payloads, form state, view models, and integration data.
Enums	packages/html-cache/src/Enums	Persisted states and Filament option values.
Models	packages/html-cache/src/Models	Eloquent records owned by the package.
Filament	packages/html-cache/src/Filament	Admin resources, pages, widgets, and settings UI.
Livewire	packages/html-cache/src/Livewire	Interactive frontend or admin components.
HTTP	packages/html-cache/src/Http	Controllers, middleware, and request handling.
Jobs	packages/html-cache/src/Jobs	Queued work and async side effects.
Providers	packages/html-cache/src/Providers	Registration, extension hooks, routes, migrations, and resources.
Resources	packages/html-cache/resources	Views, translations, assets, and package resources.
Config	packages/html-cache/config	Package configuration and publishable config.
Database	packages/html-cache/database	Migrations, seeders, and settings migrations.
Tests	packages/html-cache/tests	Package-level Pest coverage.

Admin Surface

• Resources: CachedModelUrlResource.
• Pages: MaintenanceCachePage, ListCachedModelUrls.
• Widgets: HtmlCacheOverviewWidget, CacheCoverageUrlsWidget, HtmlCacheStaleQueueWidget.
• Extenders: page table cache indicator, site header maintenance/cache action, Site Health cache map.

Runtime Surface

• Livewire: SiteHealthCacheMap.
• Jobs: RegisterCachedModelUrlsJob.
• Integration: registers StaticMaintenancePageStore so Capell frontend maintenance pages can use the page_cache disk when this package is installed.

Commands

• capell:static-site {--site=} {--internal : Render URLs through the current Laravel kernel} {--refresh : Delete affected HTML cache files before rendering} (packages/html-cache/src/Console/Commands/StaticSiteCommand.php)

Maintenance Pages

Capell frontend owns maintenance page rendering, the manifest, and the runtime middleware. This package only contributes the page_cache-backed static store plus optional admin actions for generating those files.

Generated files are written under maintenance/ on the page_cache disk. The manifest at storage/framework/capell-maintenance.json maps host/scheme/path combinations to those files. To serve static maintenance HTML during Laravel maintenance mode, wire the frontend frontend.maintenance middleware into the host application’s maintenance path. If this package is not installed, no static store is registered and frontend falls back to Laravel’s plain 503.

Data And Persistence

• Models: CachedModelUrl.
• Migrations: 2026_05_10_190854_01_create_cached_model_urls_table.php.
• Config: packages/html-cache/config/capell-html-cache.php.
• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Contracts: PageCacheNotifiable.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install And Setup

• Install with composer require capell-app/html-cache in the host Capell application.
• Run migrations through the host application package install flow.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Docs

• docs index
• overview.md
• cache-invalidation.md
• screenshots.json

Testing

Run package tests from the repository root:

vendor/bin/pest packages/html-cache/tests --configuration=phpunit.xml

Maintenance Notes

• Cached HTML must be safe for anonymous visitors, signed-in users, admins, crawlers, and static exports.
• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.
• Use package Data classes at boundaries instead of passing anonymous arrays between layers.
• Use backed enums for persisted values and enum labels for Filament options.