# Configuration

- [Introduction](#introduction)
- [Publishing the Config File](#publishing-the-config-file)
- [Feature Toggles](#feature-toggles)
- [Programmatic Feature Checking](#programmatic-feature-checking)
- [All Config Keys](#all-config-keys)
- [Authentication Identity](#authentication-identity)
- [Route Prefix](#route-prefix)
- [Storage Disks](#storage-disks)
- [UUID Configuration](#uuid-configuration)
- [Model Resolution](#model-resolution)
- [Two-Factor Authentication Settings](#two-factor-authentication-settings)
- [Billing](#billing)
- [Environment Variables](#environment-variables)

## Introduction

Magic Starter is configured via a single file at `config/magic-starter.php`. This file controls feature flags, model resolution, authentication identity strategy, storage disks, route prefixes, UUID behavior, and two-factor authentication settings.

All configuration keys support environment variable overrides where noted, making it straightforward to manage per-environment settings without modifying the config file directly.

> [!TIP]
> For a full walkthrough of installation and initial setup, see the [Installation Guide](https://magic.fluttersdk.com/packages/starter-laravel/getting-started/installation).

## Publishing the Config File

If you used the install command, the config file is already published. To publish it manually:

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

This copies the package config to `config/magic-starter.php` in your application.

## Feature Toggles

Features follow a toggle pattern inspired by Jetstream. Enable features by adding their corresponding `Features::` method call to the `features` array in `config/magic-starter.php`:

```php
'features' => [
    \FlutterSdk\MagicStarter\Features::teams(),
    \FlutterSdk\MagicStarter\Features::profilePhotos(),
    \FlutterSdk\MagicStarter\Features::sessions(),
    \FlutterSdk\MagicStarter\Features::socialLogin(),
    \FlutterSdk\MagicStarter\Features::newsletterSubscription(),
    \FlutterSdk\MagicStarter\Features::extendedProfile(),
    \FlutterSdk\MagicStarter\Features::notifications(),
    \FlutterSdk\MagicStarter\Features::twoFactorAuthentication(),
    \FlutterSdk\MagicStarter\Features::emailVerification(),
    \FlutterSdk\MagicStarter\Features::guestAuth(),
    \FlutterSdk\MagicStarter\Features::phoneOtp(),
    \FlutterSdk\MagicStarter\Features::timezones(),
],
```

When a feature is disabled (omitted from the array), its routes are not registered and its functionality is unavailable. Core authentication and profile management routes are always active regardless of feature flags.

The main features and their toggle methods:

| Feature Key | Enable Method | Check Method | Description |
|:------------|:--------------|:-------------|:------------|
| `teams` | `Features::teams()` | `Features::hasTeamFeatures()` | Team creation, membership, invitations, and roles |
| `restorable-teams` | `Features::restorableTeams()` | `Features::hasRestorableTeamFeatures()` | Deleting a team hides it for `teams.restore_days` days, and its owner can restore it with `POST teams/{team}/restore` ([details](https://anilcancakir.com/magic-starter-laravel/docs/v0.0/basics/teams.md#restorable-delete)) |
| `profile-photos` | `Features::profilePhotos()` | `Features::hasProfilePhotoFeatures()` | User profile photo upload and management |
| `sessions` | `Features::sessions()` | `Features::hasSessionFeatures()` | Active session listing and revocation |
| `social-login` | `Features::socialLogin()` | `Features::hasSocialLoginFeatures()` | OAuth-based social login via Socialite |
| `newsletter-subscription` | `Features::newsletterSubscription()` | `Features::hasNewsletterSubscriptionFeatures()` | Newsletter opt-in subscription management |
| `extended-profile` | `Features::extendedProfile()` | `Features::hasExtendedProfileFeatures()` | Extended profile fields (phone, timezone, language, locale) |
| `notifications` | `Features::notifications()` | `Features::hasNotificationFeatures()` | Notification preference management |
| `two-factor-authentication` | `Features::twoFactorAuthentication()` | `Features::hasTwoFactorAuthenticationFeatures()` | TOTP-based two-factor authentication with recovery codes |
| `email-verification` | `Features::emailVerification()` | `Features::hasEmailVerificationFeatures()` | Email verification flow after registration |
| `guest-auth` | `Features::guestAuth()` | `Features::hasGuestAuthFeatures()` | Anonymous guest user authentication |
| `phone-otp` | `Features::phoneOtp()` | `Features::hasPhoneOtpFeatures()` | Phone-based OTP verification flow |
| `timezones` | `Features::timezones()` | `Features::hasTimezoneFeatures()` | Timezone detection and per-user timezone storage |
| `releases` | `Features::releases()` | `Features::hasReleaseFeatures()` | Release notes staff curate and clients read from `GET releases` |
| `campaigns` | `Features::campaigns()` | `Features::hasCampaignFeatures()` | Time-boxed Stripe promotion codes staff run from the admin panel, applied at checkout and served at `GET billing/campaign` (needs `billing`) |

## Programmatic Feature Checking

Use the `Features` class to check feature status at runtime in your application code, controllers, or service providers:

```php
use FlutterSdk\MagicStarter\Features;

// Generic check by feature key string
Features::enabled('teams');                          // bool

// Dedicated convenience methods
Features::hasTeamFeatures();                         // bool
Features::hasProfilePhotoFeatures();                 // bool
Features::hasSessionFeatures();                      // bool
Features::hasSocialLoginFeatures();                  // bool
Features::hasNewsletterSubscriptionFeatures();       // bool
Features::hasExtendedProfileFeatures();              // bool
Features::hasNotificationFeatures();                 // bool
Features::hasTwoFactorAuthenticationFeatures();      // bool
Features::hasEmailVerificationFeatures();            // bool
Features::hasGuestAuthFeatures();                    // bool
Features::hasPhoneOtpFeatures();                     // bool
Features::hasTimezoneFeatures();                     // bool

// Composite check — true when either timezones or extended profile is enabled
Features::hasTimezoneOrExtendedProfileFeatures();    // bool

// Authentication identity checks
Features::emailIdentity();                           // bool
Features::phoneIdentity();                           // bool
```

> [!TIP]
> Use the dedicated `has*Features()` methods in conditional logic rather than `enabled()` with raw strings. They are type-safe, IDE-friendly, and survive feature key renames.

## All Config Keys

Every key available in `config/magic-starter.php`:

| Key | Default | Description |
|:----|:--------|:------------|
| `use_uuids` | `true` | When `true`, package migrations use UUID primary keys; when `false`, auto-incrementing integers. `notifications.id` is a UUID either way (see [UUID Configuration](#uuid-configuration)) |
| `features` | `[]` | Array of enabled feature strings (populated via `Features::` method calls) |
| `frontend_url` | `env('MAGIC_STARTER_FRONTEND_URL')` | Base URL for the frontend application, used in email invitation links |
| `models.user` | `env('MAGIC_STARTER_USER_MODEL')` | Custom User model class; falls back to `auth.providers.users.model` via `MagicStarter::userModel()` |
| `models.team` | `Team::class` | Team model class |
| `models.membership` | `TeamUser::class` | Pivot model for team membership |
| `models.team_invitation` | `TeamInvitation::class` | Invitation model class |
| `defaults.locale` | `'en'` | Default locale assigned to new users during registration |
| `defaults.timezone` | `'UTC'` | Default timezone assigned to new users during registration |
| `supported_locales` | `['en', 'tr']` | Locale codes accepted by validation rules during registration and profile updates |
| `profile_photo_disk` | `'public'` | Laravel filesystem disk for user profile photos |
| `team_photo_disk` | `'public'` | Laravel filesystem disk for team photos (defaults to `profile_photo_disk` value) |
| `profile_photo_path` | `'profile-photos'` | Directory path within disk for user profile photos |
| `team_photo_path` | `'team-photos'` | Directory path within disk for team photos |
| `route_prefix` | `'api/v1'` | Global prefix applied to all package-registered routes |
| `route_middleware` | `[]` | Middleware applied to every package-registered route. These routes join NO group on their own |
| `required_ability` | `null` | Ability a Sanctum token must carry to reach a signed-in route; others get 403 `missing_ability`. Null checks nothing |
| `invitation_expiry_days` | `7` | Number of days until a team invitation token expires |
| `invitation_confirm_email_mismatch` | `false` | When `true`, a user with an active Sign in with Apple link or an `@privaterelay.appleid.com` address who accepts an invitation sent to another email is answered `409 email_mismatch` and joins on a repeat request carrying `confirm_email_mismatch: true`; everyone else keeps the `403`. See [Accept Invitation](https://anilcancakir.com/magic-starter-laravel/docs/v0.0/basics/teams.md#accept-invitation) |
| `token_expiration_minutes` | `null` | Sanctum personal access token TTL in minutes; `null` means tokens never expire |
| `auth.email` | `true` | Whether email-based authentication is accepted for login and registration |
| `auth.phone` | `false` | Whether phone-based authentication is accepted for login and registration |
| `two_factor.company_name` | `env('APP_NAME', 'Laravel')` | Company name displayed in authenticator apps (Google Authenticator, Authy, etc.) |
| `two_factor.recovery_codes_count` | `8` | Number of recovery codes generated when a user enables 2FA |
| `two_factor.geoip_db_path` | `null` | Absolute path to MaxMind GeoIP2 `.mmdb` database file; `null` disables location resolution |
| `two_factor.challenge_token_ttl` | `5` | Minutes until a two-factor challenge token expires |
| `billing.billable` | `'user'` | What is billed: `'user'` or `'team'`. `'team'` needs the teams feature |
| `billing.package_subscription_models` | `env('MAGIC_STARTER_PACKAGE_SUBSCRIPTION_MODELS', true)` | Hand Cashier the package's `Subscription` and `SubscriptionItem`, keyed by `use_uuids`. Set `false` when the subscription tables came from Cashier's own migrations |
| `billing.tier_order` | `[]` | Tier ids, cheapest first. The first is the free floor. Required with billing on |
| `billing.tiers` | `[]` | Display copy per tier id; every string but `id`, and every string in a list, is passed through `__()` per request |
| `billing.products` | `[]` | What you sell, keyed `<tier>_<cycle>`: type, tier, cycle, prices, refs, `sellable` |
| `billing.pricing.currency` | `'USD'` | Base currency a screen falls back to |
| `billing.pricing.commission` | `absorb`, `0.15` | How store prices derive from web prices: `mode` is `absorb` or `gross_up` |
| `billing.reconcile.cadence` | `env('MAGIC_STARTER_BILLING_RECONCILE_CADENCE', 'daily')` | Frequency word or cron expression for `billing:reconcile` |
| `billing.promotion_codes` | `env('MAGIC_STARTER_BILLING_PROMOTION_CODES', false)` | Show Stripe's promotion code field on every web checkout, trial or not. Codes are created in the Stripe dashboard, see [Promotion Codes](https://anilcancakir.com/magic-starter-laravel/docs/v0.0/basics/billing.md#promotion-codes) |
| `billing.revenuecat.path` | `env('REVENUECAT_WEBHOOK_PATH', 'webhooks/revenuecat')` | Whole served path of the RevenueCat webhook |
| `billing.revenuecat.webhook_secret` | `env('REVENUECAT_WEBHOOK_SECRET')` | HMAC signing secret of the webhook; without it the route is withheld |
| `billing.revenuecat.secret_api_key` | `env('REVENUECAT_SECRET_API_KEY')` | RevenueCat v1 secret key for the authoritative subscriber read; setting it turns the store rail on |
| `billing.revenuecat.base_url` | `env('REVENUECAT_BASE_URL')` | RevenueCat API base URL |
| `billing.revenuecat.operation_budget_seconds` | `10` | Time budget for the whole retried read |
| `billing.revenuecat.accept_sandbox` | `false` | Whether sandbox purchases may grant a tier. Never in production |
| `billing.revenuecat.api_v2_key` | `env('REVENUECAT_API_V2_KEY')` | RevenueCat v2 read key, used by `billing:doctor --remote` only |
| `billing.revenuecat.project_id` | `env('REVENUECAT_PROJECT_ID')` | RevenueCat project id, used by `billing:doctor --remote` only |
| `billing.stripe_test_mode.emails` | `env('MAGIC_STARTER_BILLING_STRIPE_TEST_EMAILS')`, comma list | Emails allowed to check out or swap while a Stripe key that is not provably live runs outside `local` and `testing`. Verified and lower-cased; empty refuses everybody |
| `newsletter.consent_version` | `env('MAGIC_STARTER_NEWSLETTER_CONSENT_VERSION', '1')` | Version of your newsletter consent wording, stored in `consent_version` on every consent from now on (32 characters at most). Raise it when the wording changes, see [Consent Record](https://anilcancakir.com/magic-starter-laravel/docs/v0.0/basics/profile.md#newsletter-consent) |
| `mail.brand.enabled` | `env('MAGIC_STARTER_MAIL_BRAND_ENABLED', false)` | Brand every markdown mail with the package layout and theme, see [Mail Branding](https://anilcancakir.com/magic-starter-laravel/docs/v0.0/basics/notifications.md#mail-branding) |
| `mail.brand.name` | `env('APP_NAME', 'Laravel')` | Name beside the logo, the logo's alt text and the default footer |
| `mail.brand.logo_url` | `null` | Absolute `http` or `https` URL of the header logo (a PNG); `null` shows the name only |
| `mail.brand.logo_width` | `48` | Logo width in pixels, 1 to 600 |
| `mail.brand.footer` | `null` | Footer line, Markdown, `:year` is the current year; `null` prints `© <year> <name>. All rights reserved.` |
| `mail.brand.font_stack` | Laravel's system font stack | CSS `font-family` value: letters, digits, spaces, commas, quotes and hyphens |
| `mail.brand.button_radius` | `4` | Button corner radius in pixels, 0 to 64 |
| `mail.brand.card_radius` | `4` | Card corner radius in pixels, 0 to 64 |
| `mail.brand.colors.light.*` | Laravel's default theme | Eight six-digit hex colours: `primary`, `on_primary`, `heading`, `text`, `muted`, `background`, `card`, `border` |
| `mail.brand.colors.dark.*` | all `null` | The same eight keys for dark mode: all eight or none |
| `schedule.audit_prune` | `env('MAGIC_STARTER_SCHEDULE_AUDIT_PRUNE', '0 0 * * *')` | Cron expression for `magic-starter:audit:prune` (daily) |
| `schedule.mail_prune_sends` | `env('MAGIC_STARTER_SCHEDULE_MAIL_PRUNE_SENDS', '0 0 * * *')` | Cron expression for `magic-starter:mail:prune-sends` (daily) |
| `schedule.billing_prune` | `env('MAGIC_STARTER_SCHEDULE_BILLING_PRUNE', '0 0 * * *')` | Cron expression for `magic-starter:billing:prune` (daily) |
| `schedule.support_article_images_prune` | `env('MAGIC_STARTER_SCHEDULE_SUPPORT_ARTICLE_IMAGES_PRUNE', '0 0 * * *')` | Cron expression for `magic-starter:support-articles:prune-images` (daily) |
| `schedule.ai_runs_prune` | `env('MAGIC_STARTER_SCHEDULE_AI_RUNS_PRUNE', '0 * * * *')` | Cron expression for `magic-starter:ai-runs:prune` (hourly) |
| `schedule.billing_expire_grants` | `env('MAGIC_STARTER_SCHEDULE_BILLING_EXPIRE_GRANTS', '0 * * * *')` | Cron expression for `magic-starter:billing:expire-grants` (hourly) |

## Authentication Identity

The package supports email and phone as separate, independent identity mechanisms. Both can be active simultaneously -- a user may authenticate with either their email or phone number depending on what they provided at registration.

```php
'auth' => [
    'email' => true,   // allow email-based login/register
    'phone' => false,  // allow phone-based login/register
],
```

**Mode behavior:**

| `auth.email` | `auth.phone` | Behavior |
|:-------------|:-------------|:---------|
| `true` | `false` | Email is required for registration and login |
| `false` | `true` | Phone is required for registration and login |
| `true` | `true` | Either email or phone is accepted (at least one required) |

When both are enabled, the validation rules use `required_without` constraints so that at least one identifier must be provided.

Check identity status programmatically:

```php
use FlutterSdk\MagicStarter\Features;

Features::emailIdentity();   // bool — whether email identity is enabled
Features::phoneIdentity();   // bool — whether phone identity is enabled
```

Override via environment variables:

```env
MAGIC_STARTER_AUTH_EMAIL=true
MAGIC_STARTER_AUTH_PHONE=false
```

> [!NOTE]
> The `auth.phone` setting is independent of the `phone-otp` feature flag. `auth.phone` controls whether phone is accepted as a login credential; the `phone-otp` feature adds the OTP-based verification flow on top.

## Route Prefix

All routes registered by the package are prefixed with the `route_prefix` value. This avoids collisions with your application's existing routes:

```php
'route_prefix' => 'api/v1',
```

```env
MAGIC_STARTER_ROUTE_PREFIX=api/v1
```

With this default, authentication endpoints are available at `/api/v1/login`, `/api/v1/register`, etc.

### Route Middleware

The package loads its routes from its own service provider rather than from your `routes/api.php`, so **they join no middleware group**. Laravel's `api` group, and anything you appended beside it, does not run on them.

That is invisible until something in your group is load-bearing, and then it is invisible in a different way: nothing errors. A locale resolver reading the caller's stored language ran on every route the host wrote and on none of this package's, and a Turkish account read English refusals from exactly the screens this package owns.

```php
'route_middleware' => [
    \App\Http\Middleware\SetApiLocale::class,
],
```

This covers the routes in `api.php` only. The vendor webhook routes load separately and inherit nothing from here on purpose: a webhook is called by the vendor rather than by one of your users, so there is nobody for a locale resolver or a tenant scope to resolve, and an auth middleware would reject the call outright.

Empty by default rather than `['api']`, so nothing changes for an existing install. Defaulting into your api group would be worse than doing nothing: every route here already declares the throttle it wants by name, and a group carrying `throttle:api` as well would silently halve a rate limit a prior release granted. Name what you want.

### Required Token Ability

Sanctum issues a token with `*` unless told otherwise, and nothing checks what a token is for. An application that mints a narrower token for another surface (a partner API, an operator panel) finds that token accepted by every signed-in route of this package, `/teams` and `/user` included.

```php
// config/magic-starter.php, or MAGIC_STARTER_REQUIRED_ABILITY in .env
'required_ability' => 'app',
```

With an ability named, every route behind `auth:sanctum` refuses a token that does not carry it, with `403` and `{"code": "missing_ability"}`. A `*` token satisfies any ability and a session-authenticated first-party request is let through. A token row with a NULL `abilities` column is read as unrestricted: Sanctum never writes one itself, and its own `can()` throws on it, so it can only be a row your application inserted or migrated by hand. The tokens this package issues are `*`, so they pass. A value that is not a string (`true` from an env file, an array) stops the request with an exception instead of switching the check off.

The check sits on the signed-in groups and not in `route_middleware`: login, register, password reset, the handoff exchange and the other routes a caller reaches without a token are untouched. The connect and confirm intents of the social flow (`auth/social/{provider}/token` and `auth/social/exchange`) act for a bearer on a public route; they apply the same rule and answer `401` to a bearer without the ability, so a narrow token cannot link a sign-in method or mint a step-up confirmation. Null by default, which checks nothing, so an existing install changes nothing. The sign-in handoff mint stays stricter on its own: it needs a token with every ability.

### Translations

Every user-facing sentence the API answers with resolves through `__('magic-starter::...')`, so a caller is answered in the locale the request resolved to. English and Turkish ship with the package. Publish them to override a wording or add a language:

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

The mail strings sit under the same namespace: `magic-starter::mail.invitation.*` and `magic-starter::mail.verify.*`. Override one key per locale in `lang/vendor/magic-starter/<locale>/mail.php`. The password reset mail and the template chrome of every mail (`Hello!`, `Regards,`, the button subcopy) are Laravel's own English strings, translated in the package's `resources/lang/tr.json`, which is registered with `loadJsonTranslationsFrom`. That file is not part of `magic-starter-lang`, since Laravel reads no JSON file from `lang/vendor/`: override a framework string in your application's own `lang/tr.json`, which loads after the package's and wins per key.

Note that a published file WINS over the package's own, and Laravel reads it before the shipped catalogue. A published copy left behind after an upgrade keeps serving the old wording, and a locale test can end up measuring the copy rather than the catalogue.

Selecting the locale is your application's job. This package resolves nothing on its own: put your locale middleware in `route_middleware` above, or these routes answer in `config('app.locale')` whatever the caller asked for.

## Storage Disks

Configure separate filesystem disks and path prefixes for user profile photos and team photos:

```php
'profile_photo_disk' => 'public',
'team_photo_disk'    => 'public',
'profile_photo_path' => 'profile-photos',
'team_photo_path'    => 'team-photos',
```

The `team_photo_disk` defaults to the same value as `profile_photo_disk` if not explicitly set. A user or team with no uploaded photo answers `profile_photo_url: null`, and the client draws its own initials.

Override disks via environment variables for production (e.g., to use S3):

```env
MAGIC_STARTER_PROFILE_PHOTO_DISK=s3
MAGIC_STARTER_TEAM_PHOTO_DISK=s3
MAGIC_STARTER_PROFILE_PHOTO_PATH=profile-photos
MAGIC_STARTER_TEAM_PHOTO_PATH=team-photos
```

> [!TIP]
> The `profile_photo_path` field supports max 2048 characters in the database to accommodate long filesystem paths. Keep your path prefixes short and let the storage driver handle the rest.

## UUID Configuration

The `use_uuids` key determines the primary key strategy for all package migrations:

```php
'use_uuids' => true,
```

| Value | Primary Keys | Foreign Keys | Morph Columns |
|:------|:-------------|:-------------|:--------------|
| `true` | `uuid()` columns | `foreignUuid()` references | UUID-based polymorphic columns |
| `false` | `id()` auto-incrementing | `foreignId()` references | Integer-based polymorphic columns |

> [!NOTE]
> `notifications.id` is a UUID in both modes, because Laravel's `database` channel writes the notification's own UUID there; only its `notifiable` morph columns follow `use_uuids`. An install that migrated before this was true has an auto-incrementing id the channel cannot write to: copy `vendor/fluttersdk/magic-starter-laravel/database/migrations/rekey_notifications_table_by_uuid.php` into `database/migrations/` under a timestamp later than your notifications migration, then run `php artisan migrate`. Re-running `magic-starter:install` is not the way to get it, because the installer also rewrites the users migration and the feature list. The same goes for `convert_notifications_data_to_json.php` on PostgreSQL, which turns a text `data` column into JSON so Filament's database notifications can query it; copy it under a timestamp later than the rekey.

This value is set automatically during installation based on your existing database schema. All package models include the `ConditionallyUsesUuids` trait, which reads this config at runtime to determine key behavior.

In migrations, always use the `MigrationHelper` methods instead of raw Laravel column methods:

```php
use FlutterSdk\MagicStarter\Support\MigrationHelper;

// Primary key — uses uuid() or id() based on config
MigrationHelper::primaryKey($table);

// Foreign key — uses foreignUuid() or foreignId() based on config
MigrationHelper::foreignKey($table, 'user_id')->constrained()->cascadeOnDelete();

// Morph columns — handles UUID/integer polymorphism
MigrationHelper::morphColumns($table, 'notifiable');
```

> [!NOTE]
> Changing `use_uuids` after running migrations requires a full migration reset. Plan your primary key strategy before deploying to production.

## Model Resolution

The package resolves model classes dynamically through `MagicStarter::userModel()`, `MagicStarter::teamModel()`, etc. The resolution order is:

1. **Config value** -- checks `config('magic-starter.models.user')` (settable via environment variable)
2. **`class_exists()` fallback** -- tries `App\Models\User`, `App\Models\Team`, etc.
3. **Package default** -- falls back to the package's built-in model classes

Override model classes via environment variables:

```env
MAGIC_STARTER_USER_MODEL=App\Models\User
MAGIC_STARTER_TEAM_MODEL=App\Models\Team
MAGIC_STARTER_MEMBERSHIP_MODEL=App\Models\TeamUser
MAGIC_STARTER_TEAM_INVITATION_MODEL=App\Models\TeamInvitation
```

Or set them directly in the config file:

```php
'models' => [
    'user'            => \App\Models\User::class,
    'team'            => \App\Models\Team::class,
    'membership'      => \App\Models\TeamUser::class,
    'team_invitation' => \App\Models\TeamInvitation::class,
],
```

You can also override model resolution programmatically in your `AppServiceProvider`:

```php
use FlutterSdk\MagicStarter\MagicStarter;

MagicStarter::useUserModel(\App\Models\User::class);
MagicStarter::useTeamModel(\App\Models\Team::class);
```

> [!NOTE]
> A stale Composer classmap can cause `class_exists()` to return incorrect results. Run `composer dump-autoload` if model auto-resolution is not picking up your custom models.

`MagicStarter::serializeUserUsing()` belongs to the same family: it registers extra fields for `UserResource` to publish, which is how an application exposes a column it added to `users`. See [Publishing Your Own Columns](https://magic.fluttersdk.com/packages/starter-laravel/basics/profile#publishing-your-own-columns).

## Two-Factor Authentication Settings

When the `two-factor-authentication` feature is enabled, the following settings control its behavior:

```php
'two_factor' => [
    'company_name'        => env('APP_NAME', 'Laravel'),
    'recovery_codes_count' => 8,
    'geoip_db_path'       => null,
    'challenge_token_ttl'  => 5,
],
```

| Key | Description |
|:----|:------------|
| `company_name` | Displayed in the user's authenticator app as the issuer. Defaults to your `APP_NAME`. |
| `recovery_codes_count` | Number of one-time recovery codes generated when a user enables 2FA. Each code can be used once to bypass the TOTP challenge. |
| `geoip_db_path` | Absolute path to a MaxMind GeoIP2 `.mmdb` database file. When set, 2FA challenge attempts include location data. Set to `null` to disable. |
| `challenge_token_ttl` | Number of minutes a 2FA challenge token remains valid. Users must complete the challenge within this window. |

> [!TIP]
> To use GeoIP location resolution, download a MaxMind GeoLite2-City database and set the `geoip_db_path` to its absolute path on disk. The database is not included with the package.

## Billing

With the `billing` feature on, `config('magic-starter.billing')` holds one catalogue that every rail reads: tiers, their ranking, the products that sell them, and the pricing rule behind store prices. Boot validates it and refuses a catalogue that could sell the wrong thing.

```php
'billing' => [
    'billable' => 'user',
    'tier_order' => ['free', 'pro'],
    'tiers' => [
        'free' => ['name' => 'Free'],
        'pro' => ['name' => 'Pro'],
    ],
    'products' => [
        'pro_monthly' => [
            'type' => 'subscription',
            'tier' => 'pro',
            'cycle' => 'monthly',
            'prices' => ['web' => ['USD' => 2900]],
            'refs' => [
                'stripe_price' => env('CASHIER_PRICE_PRO_MONTHLY'),
                'app_store' => 'com.example.app.pro.monthly',
                'play' => 'pro:monthly',
            ],
        ],
    ],
],
```

The Stripe price id of a product is read from `CASHIER_PRICE_<KEY>`, the product key uppercased: `pro_monthly` reads `CASHIER_PRICE_PRO_MONTHLY`. The RevenueCat keys are `webhook_secret` (the HMAC signing secret), `secret_api_key` (reads subscribers), and `api_v2_key` with `project_id` (read by `billing:doctor --remote` only; neither is needed to sell).

> [!WARNING]
> `plans`, `prices` and `store_products` were removed. A config that still carries one, even empty, stops boot with a message naming where its content moved. See the [changelog](../../CHANGELOG.md).

The full reference, including the refusals and the webhook, is in [Billing](https://anilcancakir.com/magic-starter-laravel/docs/v0.0/basics/billing.md).

## Scheduled Task Times

The package puts six maintenance tasks on the scheduler: the daily `magic-starter:audit:prune`, `mail:prune-sends`, `billing:prune` and `support-articles:prune-images`, and the hourly `magic-starter:ai-runs:prune` and `billing:expire-grants`. They all start at 00:00 or at minute 0, which collides with a shared box that runs its database dumps at midnight or its own spike on the hour. `config('magic-starter.schedule')` takes one cron expression per task, so a host moves each of them:

```php
'schedule' => [
    'audit_prune' => '20 5 * * *',
    'ai_runs_prune' => '25 * * * *',
],
```

These are times, not cadences: each task keeps the cadence its retention needs, so move a daily one within the day and an hourly one within the hour. Any cron expression is accepted; one that is not valid raises from `schedule:run` instead of being replaced. A key that is missing, empty or not a string keeps the default shown in the table above, so a config published before this block existed changes nothing. `magic-starter:support:sweep` (every minute) and `billing:reconcile` (`billing.reconcile.cadence`) are not part of this block.

## Environment Variables

All environment variables recognized by the package:

| Variable | Config Key | Default | Description |
|:---------|:-----------|:--------|:------------|
| `MAGIC_STARTER_FRONTEND_URL` | `frontend_url` | `null` | Frontend application URL for email links |
| `MAGIC_STARTER_USER_MODEL` | `models.user` | `null` | Custom User model class |
| `MAGIC_STARTER_TEAM_MODEL` | `models.team` | `Team::class` | Custom Team model class |
| `MAGIC_STARTER_MEMBERSHIP_MODEL` | `models.membership` | `TeamUser::class` | Custom membership pivot model class |
| `MAGIC_STARTER_TEAM_INVITATION_MODEL` | `models.team_invitation` | `TeamInvitation::class` | Custom invitation model class |
| `MAGIC_STARTER_DEFAULT_LOCALE` | `defaults.locale` | `'en'` | Default locale for new users |
| `MAGIC_STARTER_DEFAULT_TIMEZONE` | `defaults.timezone` | `'UTC'` | Default timezone for new users |
| `MAGIC_STARTER_PROFILE_PHOTO_DISK` | `profile_photo_disk` | `'public'` | Filesystem disk for profile photos |
| `MAGIC_STARTER_TEAM_PHOTO_DISK` | `team_photo_disk` | `'public'` | Filesystem disk for team photos |
| `MAGIC_STARTER_PROFILE_PHOTO_PATH` | `profile_photo_path` | `'profile-photos'` | Directory for profile photos |
| `MAGIC_STARTER_TEAM_PHOTO_PATH` | `team_photo_path` | `'team-photos'` | Directory for team photos |
| `MAGIC_STARTER_ROUTE_PREFIX` | `route_prefix` | `'api/v1'` | Route prefix for all package routes |
| `MAGIC_STARTER_INVITATION_EXPIRY_DAYS` | `invitation_expiry_days` | `7` | Team invitation expiry in days |
| `MAGIC_STARTER_INVITATION_CONFIRM_EMAIL_MISMATCH` | `invitation_confirm_email_mismatch` | `false` | Let a Sign in with Apple user confirm joining with a different email |
| `MAGIC_STARTER_TOKEN_EXPIRATION` | `token_expiration_minutes` | `null` | Sanctum token TTL in minutes |
| `MAGIC_STARTER_AUTH_EMAIL` | `auth.email` | `true` | Enable email-based authentication |
| `MAGIC_STARTER_AUTH_PHONE` | `auth.phone` | `false` | Enable phone-based authentication |
| `APP_NAME` | `two_factor.company_name` | `'Laravel'` | Company name in authenticator apps |
| `CASHIER_PRICE_<KEY>` | `billing.products.<key>.refs.stripe_price` | `null` | Stripe price id of a product; `<KEY>` is the product key uppercased (`CASHIER_PRICE_PRO_MONTHLY`) |
| `MAGIC_STARTER_BILLING_RECONCILE_CADENCE` | `billing.reconcile.cadence` | `'daily'` | How often `billing:reconcile` runs; `hourly` suits a store-heavy app |
| `MAGIC_STARTER_BILLING_PROMOTION_CODES` | `billing.promotion_codes` | `false` | Show Stripe's promotion code field on every web checkout |
| `REVENUECAT_WEBHOOK_PATH` | `billing.revenuecat.path` | `'webhooks/revenuecat'` | Served path of the RevenueCat webhook |
| `REVENUECAT_WEBHOOK_SECRET` | `billing.revenuecat.webhook_secret` | `null` | HMAC signing secret, shown once in the RevenueCat dashboard |
| `REVENUECAT_SECRET_API_KEY` | `billing.revenuecat.secret_api_key` | `null` | RevenueCat v1 secret key |
| `REVENUECAT_BASE_URL` | `billing.revenuecat.base_url` | RevenueCat's API | RevenueCat API base URL |
| `REVENUECAT_OPERATION_BUDGET_SECONDS` | `billing.revenuecat.operation_budget_seconds` | `10` | Time budget for the whole retried read |
| `REVENUECAT_ACCEPT_SANDBOX` | `billing.revenuecat.accept_sandbox` | `false` | Act on sandbox purchases. Never in production |
| `REVENUECAT_API_V2_KEY` | `billing.revenuecat.api_v2_key` | `null` | v2 read key for `billing:doctor --remote` |
| `REVENUECAT_PROJECT_ID` | `billing.revenuecat.project_id` | `null` | RevenueCat project id for `billing:doctor --remote` |
| `MAGIC_STARTER_BILLING_STRIPE_TEST_EMAILS` | `billing.stripe_test_mode.emails` | empty | Comma-separated emails allowed to buy on a Stripe key that is not provably live, outside `local` and `testing` |
| `MAGIC_STARTER_NEWSLETTER_CONSENT_VERSION` | `newsletter.consent_version` | `'1'` | Version of the newsletter consent wording recorded with each consent |
| `MAGIC_STARTER_MAIL_BRAND_ENABLED` | `mail.brand.enabled` | `false` | Brand every markdown mail with the package layout and theme |
| `MAGIC_STARTER_SCHEDULE_AUDIT_PRUNE` | `schedule.audit_prune` | `'0 0 * * *'` | Cron expression for `magic-starter:audit:prune` |
| `MAGIC_STARTER_SCHEDULE_MAIL_PRUNE_SENDS` | `schedule.mail_prune_sends` | `'0 0 * * *'` | Cron expression for `magic-starter:mail:prune-sends` |
| `MAGIC_STARTER_SCHEDULE_BILLING_PRUNE` | `schedule.billing_prune` | `'0 0 * * *'` | Cron expression for `magic-starter:billing:prune` |
| `MAGIC_STARTER_SCHEDULE_SUPPORT_ARTICLE_IMAGES_PRUNE` | `schedule.support_article_images_prune` | `'0 0 * * *'` | Cron expression for `magic-starter:support-articles:prune-images` |
| `MAGIC_STARTER_SCHEDULE_AI_RUNS_PRUNE` | `schedule.ai_runs_prune` | `'0 * * * *'` | Cron expression for `magic-starter:ai-runs:prune` |
| `MAGIC_STARTER_SCHEDULE_BILLING_EXPIRE_GRANTS` | `schedule.billing_expire_grants` | `'0 * * * *'` | Cron expression for `magic-starter:billing:expire-grants` |
