# Admin Panel

The optional Filament plugin that gives your own staff a back office over users, teams, subscriptions, newsletter subscribers and the audit trail.

- [Quick Reference](#quick-reference)
- [Introduction](#introduction)
- [Installation](#installation)
- [Who Can Enter](#who-can-enter)
- [Configuring the Plugin](#configuring-the-plugin)
- [What the Panel Contains](#what-the-panel-contains)
- [Writes Go Through Contracts](#writes-go-through-contracts)
- [Adding Your Own Resource](#adding-your-own-resource)
- [Customizing a Package Resource](#customizing-a-package-resource)
- [Guarding Your Resources in Tests](#guarding-your-resources-in-tests)
- [Operations Tools](#operations-tools)
- [Limits](#limits)
- [Gotchas](#gotchas)
- [Related Documentation](#related-documentation)

## Quick Reference

```bash
composer require filament/filament
php artisan magic-starter:filament:install
```

```dotenv
MAGIC_STARTER_ADMIN_EMAILS=you@example.com,colleague@example.com
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](https://filamentphp.com) 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

```bash
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:

```php
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:

```
MAGIC_STARTER_ADMIN_EMAILS=you@example.com,colleague@example.com
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](#operations-tools).

---

## Who Can Enter

`AuthorizesAdminPanel` answers `true` only when all of these hold:

1. The panel carries the Magic Starter plugin. Any other panel is denied, so it has to state its own rule.
2. The user's email, lowercased and trimmed, is in `magic-starter.admin.emails` (the comma-separated `MAGIC_STARTER_ADMIN_EMAILS`).
3. 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:

```php
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()`:

```php
->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.

```php
->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:

```php
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](https://anilcancakir.com/magic-starter-laravel/docs/basics/billing.md#manual-grants), 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](https://anilcancakir.com/magic-starter-laravel/docs/basics/billing.md#campaigns): 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](https://anilcancakir.com/magic-starter-laravel/docs/architecture/action-contracts.md) 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](https://anilcancakir.com/magic-starter-laravel/docs/basics/audit.md) 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.

```php
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)`. Pass `null` as the subject on a create; the model the contract returns becomes the subject.
- An edit or create page uses the `WritesThroughContracts` trait, which sends Filament's save to the resource's `updateRecordUsing()` and `createRecordUsing()`.
- Link to pages with `Action::make()->url()`. A `CreateAction`, `EditAction` or `DeleteAction` needs `->using(...)`.
- Register the resource with `->resource('projects', ProjectResource::class)` on the plugin, or let your own panel discover it.

---

## Customizing a Package Resource

```bash
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:

```php
->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:

```php
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 `RemovesTeamMembers` or `UpdatesTeamMemberRoles` binding 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 custom `RemovesTeamMembers` also owns clearing the removed member's `current_team_id` when 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](https://anilcancakir.com/magic-starter-laravel/docs/basics/audit.md): the admin actions the panel records.
- [Billing](https://anilcancakir.com/magic-starter-laravel/docs/basics/billing.md): the Billing tab and manual grants.
- [Account Deletion](https://anilcancakir.com/magic-starter-laravel/docs/basics/account-deletion.md): why the panel has no bulk delete.
- [Action Contracts](https://anilcancakir.com/magic-starter-laravel/docs/architecture/action-contracts.md): the contracts every panel write goes through.
