Admin Panel
The optional Filament plugin that gives your own staff a back office over users, teams, subscriptions, newsletter subscribers and the audit trail.
On this page
Quick Reference#
composer require filament/filament
php artisan magic-starter:filament:install
[email protected],[email protected]
MAGIC_STARTER_ADMIN_HOST=admin.example.com
| Setting | Meaning |
|---|---|
magic-starter.admin.emails |
The allowlist (MAGIC_STARTER_ADMIN_EMAILS). An empty list admits nobody. |
magic-starter.admin.host |
Optional host (MAGIC_STARTER_ADMIN_HOST); empty serves the panel on /admin. |
FilamentUser and AuthorizesAdminPanel |
The interface and trait your user model adds. |
Introduction#
The package ships an optional Filament plugin that gives staff a panel over users, teams, subscriptions, newsletter subscribers and the audit trail. It is a back office for your own team, not part of the mobile API.
Nothing requires Filament at runtime. filament/filament (^4.13.3|^5.8.3), laravel/horizon, laravel/pulse and laravel/telescope are suggested packages; install only the ones you use. The package declares a composer conflict with the Filament 4 and 5 releases below those floors, which carry multi-factor bypass and XSS advisories; an app whose own panel runs Filament 3 and only uses the API is not blocked.
Installation#
composer require filament/filament
php artisan magic-starter:filament:install
The command writes app/Providers/Filament/AdminPanelProvider.php and lists it in bootstrap/providers.php. The panel id is admin, it serves from config('magic-starter.admin.host') or the /admin path, uses Filament's ->login() and mounts MagicStarterPlugin::make(). Running it again changes nothing unless you pass --force, which overwrites the provider.
The command never touches your user model, because it is your own file. Add the interface and the trait yourself:
use Filament\Models\Contracts\FilamentUser;
use AnilcanCakir\MagicStarter\Filament\Concerns\AuthorizesAdminPanel;
class User extends Authenticatable implements FilamentUser
{
use AuthorizesAdminPanel;
}
The model also needs MustVerifyEmail (the package's trait and Laravel's contract), because the gate requires a verified address. Without FilamentUser, the plugin refuses to register and throws a LogicException, rather than leave Filament's own default in charge.
Then set the environment:
[email protected],[email protected]
MAGIC_STARTER_ADMIN_HOST=admin.example.com
MAGIC_STARTER_ADMIN_HOST is optional; leave it empty to serve the panel on /admin. The command also prints the HORIZON_*, PULSE_* and TELESCOPE_* keys described under Operations Tools.
Who Can Enter#
AuthorizesAdminPanel answers true only when all of these hold:
- The panel carries the Magic Starter plugin. Any other panel is denied, so it has to state its own rule.
- The user's email, lowercased and trimmed, is in
magic-starter.admin.emails(the comma-separatedMAGIC_STARTER_ADMIN_EMAILS). - The email is verified.
An empty list admits nobody, and a user without an email never passes. To use your own rule instead, replace the allowlist:
MagicStarterPlugin::make()->authorizeUsing(
fn (User $user, Panel $panel): bool => $user->is_staff === true,
)
The callback decides alone and admits only on true.
Two-factor authentication at sign in#
A user who turned on two-factor authentication through the API is asked for a code after the password, or for one of their recovery codes. The panel reads the same secret and recovery codes as the API and applies the same rule: the twoFactorAuthentication feature is on and the user confirmed a code. A user without two-factor signs in with the password alone.
A code is accepted once: after it signs in, through the API or the panel, that code and every earlier one are refused. A recovery code is spent under a row lock, so two concurrent sign-ins cannot both use it.
The panel never writes a secret. Two-factor is turned on in the app. It is turned off there, or by an admin with "Reset two-factor" on the Users resource, which also removes that user's panel challenge.
The plugin mounts this challenge (AnilcanCakir\MagicStarter\Filament\Auth\TwoFactorAuthentication) only when the panel has no multi-factor setup of its own while it is being built. A Closure provider list counts as a setup only if it returns providers at that point, before any request is authenticated. To combine the challenge with Filament's providers, or to require a second factor, configure the panel yourself before ->plugin():
->multiFactorAuthentication([TwoFactorAuthentication::make()], isRequired: true)
->plugin(MagicStarterPlugin::make())
With isRequired: true, a user who has not turned on two-factor in the app is stopped on Filament's set-up page after signing in and cannot continue until they do: the panel cannot set it up for them.
Configuring the Plugin#
Set every option before ->plugin(). Filament registers the plugin the moment it is passed in, so an option chained afterwards is ignored.
->plugin(
MagicStarterPlugin::make()
->withoutResources(['newsletter_subscribers'])
->navigationGroup('Back office')
->horizon()
->pulse()
->telescope()
->sentryUrl('https://sentry.io/organizations/acme/projects/api/'),
)
| Method | Purpose |
|---|---|
userResource($class), teamResource($class) |
Replace the Users or Teams resource |
resource($key, $class) |
Register or replace a resource. The keys users, teams, subscriptions, newsletter_subscribers and audits keep their feature gate; any other key is always registered |
withoutResources($keys) |
Leave the listed keys out |
navigationGroup($group) |
Put every package resource under one group instead of its own (see Navigation below) |
authorizeUsing($callback) |
Replace the email allowlist |
horizon(), pulse(), telescope() |
Put the tool behind the panel gate and link it |
sentryUrl($url) |
Link an external Sentry project; null removes the link |
horizon(), pulse() and telescope() throw a LogicException when their package is not installed.
Navigation#
Each package resource names its own group and place, from AdminNavigationGroup (case order is the sidebar order):
| Group | Entries, in order |
|---|---|
| Customers | Users, Teams |
| Support | Support inbox, Feedback |
| Billing | Subscriptions, Manual plans, Campaigns, Billing events, Webhook deliveries |
| AI | AI runs, AI prompts |
| Communication | Releases, Newsletter subscribers |
| Operations | Audit trail, then the Horizon, Pulse, Telescope and Sentry links |
Sorts step by 10, so an application resource joins a group between them:
protected static string|UnitEnum|null $navigationGroup = AdminNavigationGroup::Customers;
protected static ?int $navigationSort = 30;
navigationGroup('Back office') puts every package resource under that one name instead; the Operations links keep their group.
Time zone#
The panel shows times in the signed-in staff user's timezone attribute. A user whose timezone is empty, UTC (the column's default) or magic-starter.defaults.timezone (the registration fallback), none of which says anything was chosen, sees magic-starter.admin.timezone (MAGIC_STARTER_ADMIN_TIMEZONE), and without that, app.timezone. Stored timestamps stay in UTC. An explicit ->timezone() on a column still wins.
What the Panel Contains#
Every resource sits behind the feature that owns its data.
| Resource | What staff can do | Needs |
|---|---|---|
| Users | Edit profile fields; reset two-factor, revoke API tokens, resend the verification mail, schedule account deletion (optionally immediately) or cancel it. Tabs for tokens, social accounts, push devices, teams and audits |
each tab needs its own feature: sessions, social-login, onesignal, teams, audit |
| Teams | Rename; delete; add, re-role and remove members; make a member the owner; invite, resend and cancel invitations | teams |
| Subscriptions | Read every customer a billing rail has touched, whether it was a card, an App Store or Google Play purchase or a manual plan, with its plan, status, rail, store product and period end; filter by plan, status and rail; open a row's Billing tab to grant, revoke, cancel, resume, refund or sync; run "Reconcile now"; "Grant a plan" to a customer picked by name or email | billing |
| Manual plans | Read every manual grant, open or ended; "Grant a plan" to a customer picked by name or email (revoke stays on the customer's Billing tab) | billing |
| Newsletter subscribers | Read the list and each row's consent record; deactivate an active subscriber; export CSV | newsletter-subscription |
| Audits | List and view | audit |
| Campaigns | Create and edit a time-boxed campaign: window, products, copy per locale and the Stripe promotion code, which is checked in Stripe on save. Switch one off to stop it; there is no delete. The list shows the stored discount and a "Campaign checkouts" count of completed checkouts that redeemed the code (a $0 trial checkout counts) | campaigns and billing |
The dashboard lives at /dashboard and shows headline counts, plus Horizon and Pulse summaries when those tools are enabled.
Newsletter subscribers is read-mostly. The one write is "Deactivate", which withdraws an active subscription as via staff and records unsubscribed_at. No action turns a row back on: re-activating needs the person's own consent, which only they can give through the profile toggle. The list shows consented_at, consent_version, consent_source and unsubscribed_at, and the CSV export carries the same columns beside email, is_active, source and created_at. The unsubscribe token is never listed or exported.
Writes Go Through Contracts#
Every write in the panel calls the same action contract the API calls (UpdatesUserProfiles, DeletesTeams, TransfersTeamOwnership and so on). That keeps validation, refusals and side effects identical in both places, and it means an overridden action applies to the panel too.
When a contract refuses with a validation error, the panel shows it as a notification, rolls the change back and stays on the page. Any other exception is a bug and propagates. After a successful write the panel dispatches AdminActionPerformed; with the audit trail enabled it becomes one admin.* row naming the staff member.
Adding Your Own Resource#
Extend MagicStarterResource instead of Filament's Resource, then send every write through a contract.
use AnilcanCakir\MagicStarter\Filament\Resources\MagicStarterResource;
use AnilcanCakir\MagicStarter\Filament\Support\ContractAction;
class ProjectResource extends MagicStarterResource
{
protected static function resolveModel(): string
{
return Project::class;
}
public static function updateRecordUsing(Model $record, array $data, Authenticatable $actor): Model
{
ContractAction::run(
null,
static fn () => app(UpdatesProjects::class)->update($actor, $record, $data),
'project.updated',
$record,
);
return $record->refresh();
}
// form(), table() and getPages() as in any Filament resource.
}
- Header and row actions call
ContractAction::run($action, $call, $event, $subject, $context). Passnullas the subject on a create; the model the contract returns becomes the subject. - An edit or create page uses the
WritesThroughContractstrait, which sends Filament's save to the resource'supdateRecordUsing()andcreateRecordUsing(). - Link to pages with
Action::make()->url(). ACreateAction,EditActionorDeleteActionneeds->using(...). - Register the resource with
->resource('projects', ProjectResource::class)on the plugin, or let your own panel discover it.
Customizing a Package Resource#
php artisan magic-starter:filament:eject Users
Accepts Users, Teams, Subscriptions, NewsletterSubscribers or Audits. The files are copied to app/Filament/Resources/<Name> under the App\Filament\Resources\<Name> namespace, and the command prints the line to add to the plugin, for example:
->plugin(MagicStarterPlugin::make()->userResource(\App\Filament\Resources\Users\UserResource::class))
The copy still extends MagicStarterResource and still calls the contracts. An existing copy is kept unless you pass --force.
Guarding Your Resources in Tests#
Filament's stock actions write straight to the model and skip the contracts. Add one test to catch them:
use AnilcanCakir\MagicStarter\Testing\AssertsAdminWritesUseContracts;
public function test_admin_writes_use_contracts(): void
{
AssertsAdminWritesUseContracts::assertAdminWritesUseContracts([app_path('Filament')]);
}
It fails on a DeleteAction, DeleteBulkAction, ForceDeleteAction, EditAction or CreateAction without ->using(, and on an EditRecord or CreateRecord page that does not use WritesThroughContracts. It also fails when the path holds no PHP file, so a typo cannot pass.
Operations Tools#
horizon(), pulse() and telescope() link each tool under an "Operations" group and replace its access rule with the panel's, so the same allowlist decides. The rule is written after the application has booted, so your own HorizonServiceProvider or a published TelescopeServiceProvider cannot overwrite it.
The tools keep their own routes. Mount them on the admin host:
HORIZON_DOMAIN=admin.example.com
HORIZON_PATH=horizon
PULSE_DOMAIN=admin.example.com
PULSE_PATH=pulse
TELESCOPE_DOMAIN=admin.example.com
TELESCOPE_PATH=telescope
Never use an empty path: the panel owns the host's root.
Telescope also masks the starter's secrets (token, id_token, code, code_verifier, recovery_code, two_factor_token, confirmation_token, passwords, and the authorization, cookie and x-xsrf-token headers) in every environment, and outside local it keeps only batches worth reading: a reportable exception, a failed job, a scheduled task, a slow query or a monitored tag.
Each tool has one global auth closure, so with more than one panel the last to enable a tool wins.
Limits#
- No tenancy: the panel is global staff access.
- No bulk delete on Users or Teams. An account leaves through scheduled deletion, a team through
DeletesTeams. - No direct model writes where a contract exists.
- A custom
RemovesTeamMembersorUpdatesTeamMemberRolesbinding must keep the team-owner guards (RemoveTeamMember::ensureRemovable(),UpdateTeamMemberRole::ensureAssignable()). The API controllers enforce them whatever is bound; the panel calls only the contract. A customRemovesTeamMembersalso owns clearing the removed member'scurrent_team_idwhen it points at the team, as the default action does; the leave endpoint no longer does it.
Gotchas#
| Mistake | Fix |
|---|---|
Leaving FilamentUser off the user model |
The plugin refuses to register and throws a LogicException. Implement the interface and add AuthorizesAdminPanel. |
Expecting an empty MAGIC_STARTER_ADMIN_EMAILS to admit everyone |
An empty list admits nobody, and an unverified address never passes. |
Chaining plugin options after ->plugin() |
Filament registers the plugin the moment it is passed in, so a later option is ignored. Set every option first. |
Re-running magic-starter:filament:install to refresh the provider |
It changes nothing unless you pass --force, which overwrites the provider. |
| Pointing Horizon, Pulse or Telescope at an empty path | The panel owns the host's root. Give each tool its own path. |
| Using a Filament release below the floor | The package conflicts with Filament 4 and 5 releases below 4.13.3 and 5.8.3. |
Related Documentation#
- Audit Trail: the admin actions the panel records.
- Billing: the Billing tab and manual grants.
- Account Deletion: why the panel has no bulk delete.
- Action Contracts: the contracts every panel write goes through.