# Action-Contracts Architecture

How every piece of business logic sits behind a contract in `src/Contracts/` with a default action in `src/Actions/`, and how a host application swaps any of them.

- [Quick Reference](#quick-reference)
- [Introduction](#introduction)
- [How It Works](#how-it-works)
  - [Controllers](#controllers)
  - [Default Bindings](#default-bindings)
  - [Consumer Override](#consumer-override)
- [All Contracts](#all-contracts)
  - [User Management](#user-management)
  - [Social Login](#social-login)
  - [Team Management](#team-management)
  - [Two-Factor Authentication](#two-factor-authentication)
  - [OTP / Phone Verification](#otp--phone-verification)
- [Override Pattern](#override-pattern)
- [Published Stubs](#published-stubs)
- [Action Implementation Guide](#action-implementation-guide)
- [Related Documentation](#related-documentation)

## Quick Reference

```php
// app/Providers/AppServiceProvider.php
use AnilcanCakir\MagicStarter\Contracts\CreatesUsers;

public function register(): void
{
    $this->app->bind(CreatesUsers::class, \App\Actions\MagicStarter\CreateUser::class);
}
```

| To do this | Do this |
|:-----------|:--------|
| Replace a default action | Bind the contract to your own class in `AppServiceProvider::register()`. |
| Start from a stub | `php artisan vendor:publish --tag=magic-starter-stubs`; a published stub throws until you implement it. |
| Keep the default and add to it | Inject the default action into yours and delegate to it. |
| Know what a contract must return | The return type of the contract method, exactly. |

## Introduction

Magic Starter uses a **contract-action pattern** inspired by Laravel Jetstream. Every unit of
business logic is expressed as a PHP interface (a _contract_) in `src/Contracts/` and shipped with
a working default implementation (an _action_) in `src/Actions/`. Controllers depend exclusively on
contracts: they never reference concrete action classes.

This separation gives consuming applications full control: swap any action by binding a custom class
in their own `AppServiceProvider` without touching package source or forking controllers.

> [!NOTE]
> The pattern follows Laravel's service-container philosophy. `$this->app->bind(Contract, Action)`
> means every `app(Contract::class)` call inside the package resolves to your custom class once you
> register the override.

---

## How It Works

### <a name="controllers"></a>Controllers

Controllers resolve contracts at call time using `app()`:

```php
public function store(RegisterRequest $request): JsonResponse
{
    $user = app(CreatesUsers::class)->create($request->validated());
    // ...
}
```

No constructor injection, no direct references to `CreateUser::class`. The controller does not know, and does not care, which implementation is active.

### <a name="default-bindings"></a>Default Bindings

`MagicStarterServiceProvider::register()` binds every contract to its default action:

```php
$this->app->bind(Contracts\CreatesUsers::class,           Actions\CreateUser::class);
$this->app->bind(Contracts\UpdatesUserProfiles::class,    Actions\UpdateUserProfile::class);
$this->app->bind(Contracts\UpdatesUserPasswords::class,   Actions\UpdateUserPassword::class);
$this->app->bind(Contracts\DeletesUsers::class,           Actions\DeleteUser::class);
$this->app->bind(Contracts\SchedulesUserDeletion::class,  Actions\ScheduleUserDeletion::class);
$this->app->bind(Contracts\ReleasesUserBilling::class,    Actions\ReleaseUserBilling::class);
$this->app->bind(Contracts\CreatesTeams::class,           Actions\CreateTeam::class);
$this->app->bind(Contracts\UpdatesTeams::class,           Actions\UpdateTeam::class);
$this->app->bind(Contracts\DeletesTeams::class,           Actions\SubscriptionGuardedDeleteTeam::class);
$this->app->bind(Contracts\TrashesTeams::class,           Actions\SubscriptionGuardedTrashTeam::class);
$this->app->bind(Contracts\AddsTeamMembers::class,        Actions\AddTeamMember::class);
$this->app->bind(Contracts\RemovesTeamMembers::class,     Actions\RemoveTeamMember::class);
$this->app->bind(Contracts\InvitesTeamMembers::class,     Actions\InviteTeamMember::class);
$this->app->bind(Contracts\AcceptsTeamInvitations::class, Actions\AcceptTeamInvitation::class);
$this->app->bind(Contracts\UpdatesTeamMemberRoles::class, Actions\UpdateTeamMemberRole::class);
$this->app->bind(Contracts\CreatesGuestUsers::class,      Actions\CreateGuestUser::class);
$this->app->bind(Contracts\SendsOtpCodes::class,          Actions\LogOtpProvider::class);
$this->app->bind(Contracts\VerifiesOtpCodes::class,       Actions\CacheOtpVerifier::class);
$this->app->bind(Contracts\EnablesTwoFactorAuthentication::class,  Actions\EnableTwoFactorAuthentication::class);
$this->app->bind(Contracts\ConfirmsTwoFactorAuthentication::class, Actions\ConfirmTwoFactorAuthentication::class);
$this->app->bind(Contracts\DisablesTwoFactorAuthentication::class, Actions\DisableTwoFactorAuthentication::class);
$this->app->bind(Contracts\GeneratesNewRecoveryCodes::class,       Actions\GenerateNewRecoveryCodes::class);
$this->app->bind(Contracts\ResolvesSocialUsers::class,            Actions\ResolveSocialUser::class);
$this->app->bind(Contracts\CreatesUsersFromProvider::class,       Actions\CreateUserFromProvider::class);
$this->app->bind(Contracts\ConnectsSocialAccounts::class,         Actions\ConnectSocialAccount::class);
$this->app->bind(Contracts\DisconnectsSocialAccounts::class,      Actions\DisconnectSocialAccount::class);
$this->app->bind(Contracts\SetsUserPasswords::class,              Actions\SetUserPassword::class);
```

All bindings use `bind()` (not `singleton()`), so a fresh instance is created per resolution.
`TwoFactorAuthenticationProvider` and `Social\AppleProviderFactory` are the only singletons in the
package.

### <a name="consumer-override"></a>Consumer Override

Override any action by calling `bind()` **after** the package provider has run. Because
`AppServiceProvider` registers last, your binding wins:

```php
// app/Providers/AppServiceProvider.php
use App\Actions\MagicStarter\CreateUser;
use AnilcanCakir\MagicStarter\Contracts\CreatesUsers;

public function register(): void
{
    $this->app->bind(CreatesUsers::class, CreateUser::class);
}
```

> [!TIP]
> You only need to override the contracts where your business logic differs. Every other contract
> continues to use the package default silently.

---

## All Contracts

### <a name="user-management"></a>User Management

#### `CreatesUsers`

Namespace: `AnilcanCakir\MagicStarter\Contracts\CreatesUsers`
Default action: `Actions\CreateUser`

```php
public function create(array $input): Authenticatable;
```

Creates a newly registered user. `$input` contains the raw registration payload; the action is
responsible for validation, hashing, feature-gated fields (locale, timezone, newsletter), and
sending email verification when enabled.

---

#### `CreatesGuestUsers`

Namespace: `AnilcanCakir\MagicStarter\Contracts\CreatesGuestUsers`
Default action: `Actions\CreateGuestUser`

```php
public function create(array $input): Authenticatable;
```

Creates **or retrieves** a guest user keyed by `device_id`. Guest users have `null` email and
`null` password. Use `firstOrCreate` semantics: calling this twice with the same device ID must
return the same user.

> [!NOTE]
> Always null-check email and password fields on users that may be guests. The `HasGuestSupport`
> trait provides helper methods for this.

---

#### `UpdatesUserProfiles`

Namespace: `AnilcanCakir\MagicStarter\Contracts\UpdatesUserProfiles`
Default action: `Actions\UpdateUserProfile`

```php
public function update(Authenticatable $user, array $input): void;
```

Validates and persists profile changes (name, email, avatar, locale, timezone) for the given user.

---

#### `UpdatesUserPasswords`

Namespace: `AnilcanCakir\MagicStarter\Contracts\UpdatesUserPasswords`
Default action: `Actions\UpdateUserPassword`

```php
public function update(Authenticatable $user, array $input): void;
```

Validates `current_password` / `password` / `password_confirmation` and persists the new hashed
password.

---

#### `DeletesUsers`

Namespace: `AnilcanCakir\MagicStarter\Contracts\DeletesUsers`
Default action: `Actions\DeleteUser`

```php
public function delete(Authenticatable $user): void;
```

Permanently deletes the user and all associated data. It is the irreversible end of the scheduled
deletion pipeline, so it runs from `magic-starter:purge-deleted-users` once the grace period is over,
not from `DELETE user`. The default action deletes the user's owned teams through `DeletesTeams`
(so its billing guard runs on each), detaches memberships, removes the linked social identities and
tokens, and, after the outermost transaction commits, revokes the Apple grants and deletes the
profile photo. It refuses a user who owns a shared team or whom a subscription bills; the purge
hands a shared team on first (always for an orphan, and for any user with
`account_deletion.hand_on_shared_teams` on). Any additional teardown belongs here.

---

#### `SchedulesUserDeletion`

Namespace: `AnilcanCakir\MagicStarter\Contracts\SchedulesUserDeletion`
Default action: `Actions\ScheduleUserDeletion`

```php
public function schedule(Authenticatable $user, bool $orphan = false, bool $immediately = false): array;
```

The one entry point to the deletion pipeline, for a user's own request and for an identity provider
reporting the account deleted (`$orphan = true`). It refuses a user who owns a shared team (unless
`account_deletion.hand_on_shared_teams` is on) or a billing team, or whom a subscription bills
directly unless `account_deletion.billing` is `release` (422 `owns_shared_teams`,
`team_has_active_subscription` or `subscription_active`), then releases the user's billing through
`ReleasesUserBilling` when that is on, revokes every token, drops the push devices, stamps
`deletion_scheduled_at` and dispatches `UserDeletionScheduled`. Nothing is deleted in the request:
with `$immediately` a queued `PurgeUserNow` purges the account right away instead of after the
grace period. It returns the billing report, `['cancelled' => [], 'store' => []]` unless billing is
released and something bills the user; `ProfileController` puts it in the 202 body as
`data.billing`. An implementation of this contract has to return it. See
[Account Deletion](https://anilcancakir.com/magic-starter-laravel/docs/basics/account-deletion.md).

---

#### `ReleasesUserBilling`

Namespace: `AnilcanCakir\MagicStarter\Contracts\ReleasesUserBilling`
Default action: `Actions\ReleaseUserBilling`

```php
public function release(Authenticatable $user): array;
```

Ends what bills a user before their account is locked, when `account_deletion.billing` is
`release`. The default action cancels every Stripe subscription the user has that could still bill
or activate, through `TrialCardGateway::cancel()` (no proration, no final invoice), and reports a
store subscription (which only the customer can cancel, in the store) without touching it. A
subscription it cancels is ended in the local Cashier row too, because the purge and `DeletesUsers`
hold an account while a card subscription is valid and neither releases anything. Returns
`['cancelled' => [['provider' => 'stripe', 'id' => 'sub_...']], 'store' => [['provider' =>
'app_store', 'manage_url' => null]]]`, both lists empty for a user nothing bills. Throws
`Support\BillingReleaseFailed` when a rail refuses or cannot be reached; the scheduler answers that
with 422 `billing_release_failed` and locks nothing. It runs before the scheduler's own lock
transaction, so it may make remote calls; a caller that schedules inside a transaction of its own
(the Apple `account-deleted` handler) holds it open across them. See
[Releasing Billing](https://anilcancakir.com/magic-starter-laravel/docs/basics/account-deletion.md#releasing-billing).

---

### <a name="social-login"></a>Social Login

These contracts are bound whatever the `social-login` feature says, and only exercised while it is on.
A refusal is a `SocialSignInRefused` carrying a stable `code`.

| Contract | Default action | Role |
|---|---|---|
| `ResolvesSocialUsers` | `Actions\ResolveSocialUser` | `resolve(VerifiedIdentity, Request): Authenticatable`. Maps an identity to its linked user, or creates one. Never links by email. |
| `CreatesUsersFromProvider` | `Actions\CreateUserFromProvider` | `create(VerifiedIdentity, Request): Authenticatable`. Writes a new password-less user and its link atomically. |
| `ConnectsSocialAccounts` | `Actions\ConnectSocialAccount` | `connect(Authenticatable, VerifiedIdentity, ?string $refreshToken, ?string $clientId, ?bool $ownerConfirmed): Model`. Refuses rather than moves a link. |
| `DisconnectsSocialAccounts` | `Actions\DisconnectSocialAccount` | `disconnect(Authenticatable, string $provider): void`. Refuses the last sign-in method of a password-less user. |
| `SetsUserPasswords` | `Actions\SetUserPassword` | `set(Authenticatable, array $input): void`. Writes a first password only. |

A replacement `ConnectsSocialAccounts` has to honour `$ownerConfirmed`: a link is provisional
(`owner_confirmed = false`) when it came with an unverified provider email, and a proof of mailbox
control (a password reset, an email verification) deletes it. See
[Social Login](https://anilcancakir.com/magic-starter-laravel/docs/basics/social-login.md#provisional-links).

---

### <a name="team-management"></a>Team Management

All team contracts are only exercised when `Features::hasTeamFeatures()` returns `true`. Routes and
controllers for teams are conditionally registered.

#### `CreatesTeams`

Namespace: `AnilcanCakir\MagicStarter\Contracts\CreatesTeams`
Default action: `Actions\CreateTeam`

```php
public function create(Authenticatable $user, array $input): Model;
```

Validates and creates a new team owned by `$user`. Returns the persisted team model.

---

#### `UpdatesTeams`

Namespace: `AnilcanCakir\MagicStarter\Contracts\UpdatesTeams`
Default action: `Actions\UpdateTeam`

```php
public function update(Authenticatable $user, Model $team, array $input): void;
```

Validates and applies name/settings changes to `$team`. `$user` is the authenticated actor for
authorization checks.

---

#### `DeletesTeams`

Namespace: `AnilcanCakir\MagicStarter\Contracts\DeletesTeams`
Default action: `Actions\SubscriptionGuardedDeleteTeam`

```php
public function delete(Model $team): void;
```

Permanently deletes the team: the purge. It removes the photo, the memberships and the invitations,
and on a team model that uses `SoftDeletes` it force deletes rather than trashes. The default is
`Actions\SubscriptionGuardedDeleteTeam`, which refuses while a store subscription or a valid Stripe
subscription is billing the team, for `DELETE teams/{team}` and the account purge alike. With the
[restorable delete](https://anilcancakir.com/magic-starter-laravel/docs/basics/teams.md#restorable-delete) on, `DELETE teams/{team}` goes through
`TrashesTeams` instead, and this contract is what the `magic-starter:purge-trashed-teams` command and
the account purge call. A host that bound or extended the earlier `StoreSubscriptionGuardedDeleteTeam`
has to switch to it.

---

#### `TrashesTeams`

Namespace: `AnilcanCakir\MagicStarter\Contracts\TrashesTeams`
Default action: `Actions\SubscriptionGuardedTrashTeam`

```php
public function trash(Model $team, ?int $restoreDays = null): void;
public function restore(Model $team): void;
```

The restorable half of a team delete, used only with the `restorable-teams` feature on. `trash()` clears
`current_team_id` for everyone on the team, cancels its pending invitations, writes `restore_until`
(`$restoreDays`, else `magic-starter.teams.restore_days`) and soft deletes it; members stay attached. `restore()` clears
`deleted_at` and `restore_until`, and throws a `ValidationException` once `restore_until` is not in the
future. Both throw a `LogicException` for a team model that does not use `SoftDeletes`. The default
refuses to trash a team a payment rail is still billing, with the same sentences as `DeletesTeams`; a
host that needs more, such as a plan limit on restoring, extends `Actions\TrashTeam` or the guarded
class and rebinds the contract.

---

#### `AddsTeamMembers`

Namespace: `AnilcanCakir\MagicStarter\Contracts\AddsTeamMembers`
Default action: `Actions\AddTeamMember`

```php
public function add(Authenticatable $user, Model $team, string $email, string $role): void;
```

Attaches an existing application user (looked up by `$email`) directly to the team pivot with the
given `$role`. Does not send an invitation; use `InvitesTeamMembers` for email-based flows.

---

#### `RemovesTeamMembers`

Namespace: `AnilcanCakir\MagicStarter\Contracts\RemovesTeamMembers`
Default action: `Actions\RemoveTeamMember`

```php
public function remove(Authenticatable $user, Model $team, Model $teamMember): void;
```

Detaches `$teamMember` from `$team`. `$user` is the actor for authorization. The implementation
must prevent team owners from removing themselves.

---

#### `InvitesTeamMembers`

Namespace: `AnilcanCakir\MagicStarter\Contracts\InvitesTeamMembers`
Default action: `Actions\InviteTeamMember`

```php
public function invite(Authenticatable $user, Model $team, string $email, string $role): Model;
```

Creates a `TeamInvitation` record with a random token and sends `TeamInvitationNotification` to
`$email`. Returns the invitation model. Acceptance is `AcceptsTeamInvitations`.

---

#### `AcceptsTeamInvitations`

Namespace: `AnilcanCakir\MagicStarter\Contracts\AcceptsTeamInvitations`
Default action: `Actions\AcceptTeamInvitation`

```php
public function accept(Authenticatable $user, Model $invitation): void;
```

Joins the invitation's team as `$user` and deletes the invitation. The endpoint
(`POST invitations/{token}/accept`) looks the token up and checks that `$user`'s email is the
invitation's, then calls this; the default action holds the rest. It returns only after a join,
and refuses everything else:

- `Support\TeamInvitationRefused` (a `ValidationException`) with `refusal()` of `expired` or
  `already_joined`. The invitation is deleted either way. The endpoint answers these with its own
  410 and 200.
- Whatever `ensureCanJoin()` throws, which the endpoint lets through as the validation error it is.

The join runs in one `DB::transaction` with the team row read `FOR UPDATE`, so two accepts for the
same team are serialised. To gate who may join (a member cap, say), extend the default action and
override its `protected function ensureCanJoin(Model $team, Authenticatable $user): void`. It is
empty by default, runs inside that transaction with `$team` locked and freshly read, after the
already-a-member check and before the attach, and is not called for an expired invitation or a
user who already belongs. Throw a `ValidationException` (with a stable `code`, as
`RemoveTeamMember` does) to refuse: the transaction rolls back and the invitation stays.

```php
class CappedAcceptTeamInvitation extends AcceptTeamInvitation
{
    protected function ensureCanJoin(Model $team, Authenticatable $user): void
    {
        if ($team->users()->count() >= 5) {
            throw ValidationException::withMessages(['invitation' => 'This team is full.']);
        }
    }
}
```

---

#### `UpdatesTeamMemberRoles`

Namespace: `AnilcanCakir\MagicStarter\Contracts\UpdatesTeamMemberRoles`
Default action: `Actions\UpdateTeamMemberRole`

```php
public function update(Authenticatable $user, Model $team, Model $teamMember, string $role): void;
```

Changes the pivot `role` for `$teamMember` on `$team`. `$user` is the actor for authorization.

---

### <a name="two-factor-authentication"></a>Two-Factor Authentication

2FA contracts work against the `TwoFactorAuthenticatable` trait on the user model. The
`TwoFactorAuthenticationProvider` singleton (`Support\TwoFactorAuthenticationProvider`) handles
TOTP secret/QR generation and code verification underneath.

#### `EnablesTwoFactorAuthentication`

Namespace: `AnilcanCakir\MagicStarter\Contracts\EnablesTwoFactorAuthentication`
Default action: `Actions\EnableTwoFactorAuthentication`

```php
public function enable(mixed $user): array;
```

Generates a TOTP secret and recovery codes, stores them on the user (encrypted), and returns
`['secret' => ..., 'qr_code' => ..., 'recovery_codes' => [...]]`. 2FA is not active until
`ConfirmsTwoFactorAuthentication` succeeds.

---

#### `ConfirmsTwoFactorAuthentication`

Namespace: `AnilcanCakir\MagicStarter\Contracts\ConfirmsTwoFactorAuthentication`
Default action: `Actions\ConfirmTwoFactorAuthentication`

```php
public function confirm(mixed $user, string $code): void;
```

Verifies the TOTP `$code` against the user's unconfirmed secret. On success, marks 2FA as
confirmed. Throws a validation exception if the code is invalid.

---

#### `DisablesTwoFactorAuthentication`

Namespace: `AnilcanCakir\MagicStarter\Contracts\DisablesTwoFactorAuthentication`
Default action: `Actions\DisableTwoFactorAuthentication`

```php
public function disable(mixed $user): void;
```

Clears the TOTP secret, recovery codes, and confirmed-at timestamp from the user model.

---

#### `GeneratesNewRecoveryCodes`

Namespace: `AnilcanCakir\MagicStarter\Contracts\GeneratesNewRecoveryCodes`
Default action: `Actions\GenerateNewRecoveryCodes`

```php
public function generate(mixed $user): array;
```

Generates a fresh set of recovery codes, stores them (encrypted) on the user, and returns the
plain-text codes to be displayed once to the user.

---

### <a name="otp--phone-verification"></a>OTP / Phone Verification

These contracts are **intentionally thin stubs** in the default package: the default
implementations log to disk or use a cache. Production deployments must override both contracts with
real SMS/OTP-service integrations.

#### `SendsOtpCodes`

Namespace: `AnilcanCakir\MagicStarter\Contracts\SendsOtpCodes`
Default action: `Actions\LogOtpProvider` _(logs to Laravel log, development only)_

```php
public function send(string $phone, string $code): void;
```

Delivers `$code` to `$phone` (E.164 format). Override with Twilio, Vonage, AWS SNS, or any other
SMS gateway.

---

#### `VerifiesOtpCodes`

Namespace: `AnilcanCakir\MagicStarter\Contracts\VerifiesOtpCodes`
Default action: `Actions\CacheOtpVerifier` _(cache-backed, suitable for single-server setups)_

```php
public function verify(string $phone, string $code): bool;
```

Returns `true` when `$code` is the valid, unexpired code for `$phone`. The default implementation
stores codes in the Laravel cache. Override for distributed environments or third-party OTP
verification services.

> [!NOTE]
> Phone numbers must always be passed in **E.164 format** (e.g. `+14155552671`). Use the
> `E164Phone` validation rule in form requests to enforce this before the contract is called.

---

## Override Pattern

To replace any action, create your class, implement the corresponding contract, then bind it in
`AppServiceProvider::register()`:

```php
<?php

namespace App\Providers;

use App\Actions\MagicStarter\CreateUser;
use App\Actions\MagicStarter\SendsOtpViaTwilio;
use AnilcanCakir\MagicStarter\Contracts\CreatesUsers;
use AnilcanCakir\MagicStarter\Contracts\SendsOtpCodes;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(CreatesUsers::class, CreateUser::class);
        $this->app->bind(SendsOtpCodes::class, SendsOtpViaTwilio::class);
    }
}
```

Your custom `CreateUser` must implement `AnilcanCakir\MagicStarter\Contracts\CreatesUsers`: that
is the only contract. Method signatures must match exactly.

> [!TIP]
> If your custom action only needs to extend the default behavior (e.g., fire an extra event after
> user creation), inject `Actions\CreateUser` via constructor and delegate to it rather than
> re-implementing validation from scratch.

---

## Published Stubs

The package ships pre-generated stub files for the most commonly customized actions. Publish them
with:

```bash
php artisan vendor:publish --tag=magic-starter-stubs
```

This copies the following files into `app/Actions/MagicStarter/`:

| Stub file | Contract |
|---|---|
| `CreateUser.php` | `CreatesUsers` |
| `CreateTeam.php` | `CreatesTeams` |
| `UpdateUserProfile.php` | `UpdatesUserProfiles` |
| `UpdateUserPassword.php` | `UpdatesUserPasswords` |
| `DeleteUser.php` | `DeletesUsers` |
| `AddTeamMember.php` | `AddsTeamMembers` |
| `RemoveTeamMember.php` | `RemovesTeamMembers` |
| `InviteTeamMember.php` | `InvitesTeamMembers` |
| `UpdateTeam.php` | `UpdatesTeams` |
| `UpdateTeamMemberRole.php` | `UpdatesTeamMemberRoles` |
| `DeleteTeam.php` | `DeletesTeams` |

After publishing, register each stub in `AppServiceProvider::register()` as shown in the
[Override Pattern](#override-pattern) section above. Stubs are skipped for `SendsOtpCodes` and
`VerifiesOtpCodes` because those require an external service and cannot be stubbed generically.

---

## Action Implementation Guide

Follow these conventions when writing custom action classes to stay consistent with the package
patterns.

### 1. Implement exactly one contract

```php
class CreateUser implements CreatesUsers
{
    public function create(array $input): Authenticatable { ... }
}
```

One class, one contract. Do not implement multiple contracts in a single class.

### 2. Validate inline with `Validator::make`

Validation belongs inside the action, not in the caller:

```php
$validated = Validator::make($input, [
    'name'     => ['required', 'string', 'max:255'],
    'email'    => ['required', 'string', 'email', 'max:255'],
    'password' => ['required', 'string', 'min:8'],
])->validate();
```

`validate()` throws `ValidationException` automatically, which Laravel converts to a 422 response.

### 3. Resolve models via `MagicStarter::*Model()`

Never hardcode `App\Models\User` or `App\Models\Team`:

```php
$userModel = MagicStarter::userModel();   // resolves configured user model
$teamModel = MagicStarter::teamModel();   // resolves configured team model
$user = $userModel::query()->create($attributes);
```

This ensures the action works regardless of which model class the consumer has configured.

### 4. Gate feature-specific logic with `Features`

```php
if (Features::hasTeamFeatures()) {
    // team-related side effects
}

if (Features::hasNewsletterSubscriptionFeatures()) {
    // newsletter side effects
}
```

Never assume a feature is active. Guard every feature-specific branch.

### 5. Use numbered inline comments

Document flow steps with sequential inline comments so the action reads like a recipe:

```php
public function create(array $input): Authenticatable
{
    // 1. Validate input.
    $validated = Validator::make($input, $rules)->validate();

    // 2. Build attributes.
    $attributes = [...];

    // 3. Persist the user.
    $user = MagicStarter::userModel()::query()->create($attributes);

    // 4. Handle side effects.
    if (Features::hasNewsletterSubscriptionFeatures() && ...) { ... }

    return $user;
}
```

### 6. Use `Arr::get` for optional fields

```php
use Illuminate\Support\Arr;

$locale = Arr::get($validated, 'locale', 'en');
```

`Arr::get` is null-safe and accepts a default, avoiding `isset` chains.

### 7. Return types must match the contract exactly

If the contract declares `array`, return `array`. If it declares `Model`, return a `Model` (or
subclass). Do not widen or narrow the return type.

## Related Documentation

- [Service Provider](https://anilcancakir.com/magic-starter-laravel/docs/architecture/service-provider.md): where every default binding is registered.
- [Installation](https://anilcancakir.com/magic-starter-laravel/docs/getting-started/installation.md): publishing the action stubs.
- [Account Deletion](https://anilcancakir.com/magic-starter-laravel/docs/basics/account-deletion.md): the deletion contracts in use.
- [Teams](https://anilcancakir.com/magic-starter-laravel/docs/basics/teams.md): the team contracts in use.
