Site Discovery

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/site-discovery
Package slug	site-discovery
Product group	Capell Search & SEO
Tier	premium
Bundle	search-seo
Runtime contexts	admin, frontend, console
Capell version	^4.0
Source repository	capell-app/packages
Source path	packages/site-discovery
Docs source	packages/site-discovery/docs
Manifest	capell.json

Site Discovery owns public sitemap and discoverability output for Capell sites.

At A Glance

• Package: capell-app/site-discovery
• Namespace: Capell\SiteDiscovery\
• Surfaces: admin actions/tools, frontend sitemap pages, console
• Service providers: packages/site-discovery/src/Providers/SiteDiscoveryServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/core, capell-app/frontend
• Third-party dependencies: icamys/php-sitemap-generator

Why It Helps Your Capell Workflow

• Resolves public discoverable pages and URLs, then exposes HTML and XML sitemap outputs.
• Provides a discovery-output contract so packages can advertise public machine-readable outputs such as llms.txt without coupling Site Discovery to consumer packages.
• Provides a URL change notification contract so packages can submit public URL changes to IndexNow-style services without hard-coding providers into sitemap generation.
• Includes an optional IndexNow notifier, disabled by default until capell-site-discovery.indexnow.enabled and a key are configured.
• Helps owners and search tools find the pages Capell intends to publish without each package building its own crawler view.
• Gives developers a shared discovery surface that SEO Suite, Blog, Search, and audits can use consistently.

Best Used With

• SEO Suite
• Search
• Blog

What It Adds

• Public discoverable page and URL APIs.
• HTML sitemap page type and frontend component.
• XML sitemap generation with chunking and incremental state.
• Sitemap admin page, admin actions, and generation tool.
• Lifecycle listeners that regenerate sitemap output when pages or sites change.

Built With

• PHP Sitemap Generator - XML sitemap generation.

Code Map

Area	Path	Purpose
Actions	packages/site-discovery/src/Actions	Domain operations. Test these directly where possible.
Data	packages/site-discovery/src/Data	Structured payloads, form state, view models, and integration data.
Enums	packages/site-discovery/src/Enums	Persisted states and Filament option values.
Filament	packages/site-discovery/src/Filament	Admin resources, pages, widgets, and settings UI.
Livewire	packages/site-discovery/src/Livewire	Interactive frontend or admin components.
Providers	packages/site-discovery/src/Providers	Registration, extension hooks, routes, migrations, and resources.
Resources	packages/site-discovery/resources	Views, translations, assets, and package resources.
Tests	packages/site-discovery/tests	Package-level Pest coverage.

Runtime Surface

• Admin: Page and Site Sitemap actions, plus the sitemap generation tool.
• Frontend: /sitemap HTML sitemap and /sitemap-xml XML response.
• Livewire: Sitemap, SitemapTool.

Commands

• capell:xml-sitemap {--site= : Only regenerate sitemaps for this site ID} {--incremental : Skip domains whose pages have not changed since the last run} (packages/site-discovery/src/Console/Commands/XmlSitemapCommand.php)

Data And Persistence

• Data objects live in src/Data/; use them for payloads, form state, and view models.
• PagesSitemap caches serialized page arrays and rebuilds SitemapPageData objects when reading from cache. Do not cache the DTO objects directly; stale serialized objects can come back as __PHP_Incomplete_Class in host apps.

Extension Points

• Contracts: DiscoverableUrlSource, DiscoveryOutputSource, UrlChangeNotifier, Sitemapable.
• IndexNow: enable capell-site-discovery.indexnow.enabled and set capell-site-discovery.indexnow.key to submit URL changes through the built-in notifier.
• Listeners: RegenerateSitemapsOnPageDeleted, RegenerateSitemapsOnPageSaved, RegenerateSitemapsOnSiteCreated.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install And Setup

• Install with composer require capell-app/site-discovery in the host Capell application.
• The core install flow can create the default Sitemap page when this package is installed before capell:install.
• When adding the package to an existing core-only app, create the Sitemap page for each existing site before testing /sitemap; the current extension install flow does not backfill existing sites automatically.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Docs

• docs index
• overview.md
• screenshots.json

Screenshot Coverage

The package screenshot contract covers the package-added Page and Site sitemap actions, the sitemap generation tool, /sitemap, and /sitemap-xml. Keep each capture focused on the added surface; avoid broad admin screenshots that hide which control belongs to this package.

Public sitemap screenshots should be checked for authoring or package identifiers. The public output must not expose capell-site-discovery, capell-sitemap, admin URLs, editor metadata, signed editor links, or unpublished pages.

Testing

Run package tests from the repository root:

vendor/bin/pest packages/site-discovery/tests --configuration=phpunit.xml

Maintenance Notes

• 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.