Capell Admin

Package docs status

This page is generated from public package documentation in capell-4 core packages and the package manifest checked into the source repository.

Field	Value
Composer package	capell-app/admin
Package slug	admin
Product group	Capell Foundation
Tier	free
Bundle	foundation
Runtime contexts	admin, console
Capell version	^4.0
Source repository	capell-app/capell
Source path	packages/admin
Docs source	packages/admin/docs
Manifest	capell.json

capell-app/admin is the Filament panel package for Capell CMS. It adds the authenticated editor and operator surface for managing Core records, settings, package state, dashboards, permissions, and admin extension points.

Use this package when a Capell install needs a back-office UI. It depends on capell-app/core and should not be used to render public frontend output.

Package Boundary

Admin owns:

• the Filament panel plugin, resources, pages, dashboard widgets, actions, form/table components, policies, and admin routes
• editor workflows for pages, sites, languages, layouts, themes, blueprints, media, redirects, users, roles, settings, package state, and upgrades
• admin extension points for contributed resources, pages, widgets, header tools, form schemas, table queries, relation managers, and validation hooks
• admin settings migrations and admin-specific cache commands

Admin does not own:

• shared content records and migrations; those are Core records
• public request handling or public HTML safety; that is Frontend and frontend add-ons
• marketplace account linking and catalogue install authorization; that is Marketplace
• backup/import execution; Admin can expose a recovery shell, but the recovery implementation is package-owned

Install

composer require capell-app/admin
php artisan capell:admin-install
php artisan capell:admin-setup

The full foundation installer may call Admin setup for you. On existing apps, use:

php artisan capell:admin-upgrade
php artisan capell:admin-clear-cache

The admin entrypoint is controlled by CAPELL_ADMIN_PATH; CAPELL_ADMIN_DOMAIN can move the panel to a dedicated host. Clear config cache after changing either value.

Runtime Surfaces

• Provider: Capell\Admin\Providers\AdminServiceProvider
• Config: packages/admin/config/capell-admin.php
• Entrypoint helper: Capell\Admin\Support\AdminPanelEntrypoint
• Routes: packages/admin/routes/web.php
• Main resources: ActivityResource, BlueprintResource, LanguageResource, LayoutResource, MediaResource, PageResource, PageUrlResource, RedirectResource, SiteResource, ThemeResource, UserResource
• Main pages: ExtensionsPage, SettingsPage, SiteHealthPage, SitemapPage, UpgradePage
• Main commands: capell:admin-install, capell:admin-setup, capell:admin-upgrade, capell:admin-clear-cache, capell:admin-cache-widgets, capell:admin-cache-configurators

Admin routes include a signed theme preview route and authenticated internal API routes under the configured admin path. Theme preview URLs are temporary admin URLs with signed middleware, site access checks, and no-store response headers; do not embed them into public output, cached HTML, or long-lived editor content.

Extension Points

Use the documented extension points instead of extending Filament resources directly:

Need	Extension point
Contribute a resource or page	CapellAdmin::contributeToAdminSurface(...)
Register a dashboard widget	CapellAdmin::registerDashboardWidget(...)
Add page form fields	PageSchemaExtender::TAG
Add site form fields	SiteSchemaExtender::TAG
Add admin toolbar actions	AdminToolItem::TAG
Adjust tables, edit pages, exports, or relation managers	the matching tagged extender interface
Add settings UI	SettingsSchemaRegistry::register() from the owning package

Do not run php artisan capell:admin-publish-schemas for normal extension work. It copies framework-owned schema files into the app and makes upgrades harder.

Data And Permissions

Admin operates mostly on Core models. Admin-owned persistence is limited to settings migrations and admin-specific operational state.

Policy and permission behavior must be registered globally, not only through a Filament resource. Marketplace contributes additional permission-aware surfaces when it is installed.

All editor-facing labels, notifications, and validation messages should use package translation files. Prefer Filament label method overrides over static label properties.

Verification

Run Admin package tests after changing resources, policies, settings schemas, or panel registration:

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

For resource or schema changes, include the matching focused test file first. For UI behavior, verify the real Filament panel with a disposable admin account rather than stopping at the login screen.

Screenshot capture is run from the monorepo root:

npm run screenshots
npm run screenshots:check

Troubleshooting

• Missing navigation usually means the resource/page contribution was not registered, a permission blocks it, or the package cache is stale.
• Missing fields in an editor form should be checked at the tagged extender and settings schema level before editing first-party resources.
• If Admin appears on the wrong host or path, check CAPELL_ADMIN_PATH, CAPELL_ADMIN_DOMAIN, and cached config.
• If theme preview stops working after an entrypoint change, regenerate preview links against the current admin host/path; signed URLs are host/path-sensitive.
• If cache commands do not affect newly added blocks or configurators, confirm the package registered its block/configurator classes and rerun the matching admin cache command.

Further Reading

Page	Covers
Admin overview	Admin responsibilities and the package docs index.
Admin multi-language	Admin language records, translations, and user preferences.
Admin tool registry	Header tools and admin utility actions.
Dashboard widget customization	Registering and overriding dashboard widgets.
Event registry	Admin lifecycle event subscriptions.
Permissions and approval	Role and approval rules around publishing.
Resource registration	Contributed resources and admin surface lookup.
Schema hooks	Extending admin form schemas.
Settings schema registry	Package settings in the admin settings surface.
User menu registry	User menu item registration.
User resource customization	User form fields, panels, relation managers, and bridges.
Admin documentation index	Host-level admin setup, interface, recovery, media, and dashboard docs.
Package admin extensions	Package-owned admin extension guidance.