# Site Stats ## 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/site-stats` | | Package slug | `site-stats` | | Product group | Capell Foundation | | Tier | free | | Bundle | `foundation` | | Runtime contexts | `shared` | | Capell version | `^1.0` | | Catalogue role | extension | | Release channel | Released | | Source repository | `capell-app/packages` | | Source path | `packages/site-stats` | | Docs source | `packages/site-stats/docs` | | Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/site-stats/capell.json) | ## What This Plugin Adds Site Stats is an **Available**, **No package-owned schema** Capell package in the **Capell Foundation** product group. It ships as `capell-app/site-stats` and extends these surfaces: shared. Site Stats registers privacy-safe current-day page and site totals with Capell's typed metrics pipeline. Authorized global administrators can inspect retained content-inventory trends through a consuming Core metrics surface without collecting visitor analytics. The retained series is stored by Core, not by Site Stats. Evidence: [`src/Metrics/ContentTotalsMetricsCollector.php`](src/Metrics/ContentTotalsMetricsCollector.php), [`src/Providers/SiteStatsServiceProvider.php`](src/Providers/SiteStatsServiceProvider.php), [`tests/Unit/Metrics/ContentTotalsMetricsCollectorTest.php`](tests/Unit/Metrics/ContentTotalsMetricsCollectorTest.php), [`docs/screenshots/site-stats-metrics-dashboard.png`](screenshots/site-stats-metrics-dashboard.png), [`src/Health/SiteStatsHealthCheck.php`](src/Health/SiteStatsHealthCheck.php), [`tests/Feature/ScreenshotFixtureRouteTest.php`](tests/Feature/ScreenshotFixtureRouteTest.php). Status details: - Status: Available - Tier: free - Bundle: foundation - Composer package: `capell-app/site-stats` - Namespace: `Capell\SiteStats` - Theme key: not applicable ## Why It Matters **For developers:** The collector uses Core metric definitions, scopes, governance, and daily rollups rather than introducing a package-specific reporting store. Core persists samples in `metric_daily_rollups` and retains them for 365 days by default, bounded to a configured range of 30-3650 days. Core rolls up at 00:20 UTC and prunes expired rollups at 00:50 UTC; the host scheduler must be running for these jobs to execute. **For teams:** Teams get a simple retained view of content growth without page-view tracking, request logging, or a second analytics dashboard. Evidence: [`src/Metrics/ContentTotalsMetricsCollector.php`](src/Metrics/ContentTotalsMetricsCollector.php), [`tests/Unit/ManifestRequirementsTest.php`](tests/Unit/ManifestRequirementsTest.php), [`tests/Feature/ScreenshotFixtureRouteTest.php`](tests/Feature/ScreenshotFixtureRouteTest.php). ## Screens And Workflow Screenshot contract: `docs/screenshots.json`. ![Site Stats content totals in the Core metrics dashboard](screenshots/site-stats-metrics-dashboard.png) - Site Stats content totals in the Core metrics dashboard (admin, optional diagnostic host-integration capture). ## Technical Shape - Service providers: `Capell\SiteStats\Providers\SiteStatsServiceProvider`. - Manifest contributions: `health-check: Capell\SiteStats\Health\SiteStatsHealthCheck`. - Health checks: `Capell\SiteStats\Health\SiteStatsHealthCheck`. - Cache tags: `site-stats`. ## Data Model - Required source tables: `pages`, `sites`. - Migration impact: Site Stats declares no migrations. Core owns the `metric_daily_rollups` and metric collection-run tables used for retained samples; run Core migrations through the host install flow before opening package surfaces. - Deletion/retention behaviour: Site Stats has no deletion or retention command. Core's `capell:metrics:prune` deletes daily rollups and their provenance runs older than the configured `capell.analytics.daily_rollup_retention_days` (365 days by default; accepted range 30-3650). Core registers that command daily at 00:50 UTC, after the 00:20 UTC rollup; a running host scheduler is required. ## Install Impact - Required packages: `capell-app/core`. - Admin navigation: no admin page or resource contribution is declared. - Admin/editor extensions: none declared. - Permissions: none declared in `capell.json`. - Public routes: none declared. - Database changes: no package migrations declared. - Config: no package config files. - Settings: no package settings declared. - Queues or schedules: none declared by Site Stats; Core owns and schedules the shared metrics rollup and retention jobs. - Cache tags: `site-stats`. - Commands: none declared. ## Common Pitfalls - Keep required Capell packages on compatible v4 releases: `capell-app/core`. - Custom write integrations must preserve invalidation for `site-stats` 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 | ## Quick Start 1. Install the package: `composer require capell-app/site-stats`. 2. No package-specific setup command, migrations, retention command, or schedule is declared; Core supplies the shared persistence and schedule. 3. Open the Site Stats content totals in the Core metrics dashboard and confirm the admin workflow loads. ## Next Steps - [Package docs](README.md) - [Overview](overview.md) - [Troubleshooting](#troubleshooting) - [Screenshot contract](screenshots.json) - [Marketplace assets](assets/marketplace/) - [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md) - [Capell documentation design system](../../docs/DESIGN_SYSTEM.md) - [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md) - Focused tests: `vendor/bin/pest packages/site-stats/tests --configuration=phpunit.xml`.