Skip to content

Installation

View raw .md
On this page

Introduction#

Magic Starter Laravel is a modular backend package that provides authentication, team management, user profiles, session tracking, notifications, and more for Laravel applications. Inspired by Jetstream's architecture, it uses a contract-action pattern where every piece of business logic is bound through an interface, making every default replaceable without touching vendor code.

The package ships feature-gated routes, migrations, and resources — you enable only the modules your application needs via a single configuration file.

Requirements#

Dependency Version
PHP ^8.2
Laravel ^11.0 | ^12.0 | ^13.0
Laravel Sanctum ^4.0
Laravel Socialite ^5.0 (bundled)
socialiteproviders/apple ^6.1 (bundled)
socialiteproviders/microsoft ^4.9 (bundled)
firebase/php-jwt ^7.0 (bundled)
pragmarx/google2fa ^8.0 | ^9.0
bacon/bacon-qr-code ^3.0

Installing the Package#

Install the package via Composer:

bash
composer require fluttersdk/magic-starter-laravel

Service Provider Auto-Discovery#

The package registers FlutterSdk\MagicStarter\MagicStarterServiceProvider automatically through Laravel's package auto-discovery mechanism (via extra.laravel.providers in the package's composer.json). No manual provider registration is needed.

The service provider handles:

  • Configuration merging — merges the package config under the magic-starter key.
  • Action contract binding — binds all action interfaces to default implementations (see Binding Action Contracts).
  • Sanctum setup — uses a custom PersonalAccessToken model with device info columns and disables Sanctum's default migrations.
  • Password reset URL — customizes the reset link to point at your frontend URL from config.
  • Rate limiting — registers named rate limiters for all package endpoints (auth, 2FA, OTP, guest, settings, email verification).
  • Event listeners — auto-creates a personal team on user registration (when teams enabled) and gates notification channels (when notifications enabled).
  • Route loading — loads the package's API routes unless explicitly ignored via MagicStarter::ignoreRoutes().

Running the Install Command#

The package ships an Artisan command that publishes configuration and feature-relevant migrations:

bash
php artisan magic-starter:install

Interactive Mode#

When run without flags, the command uses Laravel Prompts to walk you through setup:

  1. Features — a multiselect prompt with all 12 features pre-selected.
  2. Route prefix — a text input (defaults to api/v1).
  3. Frontend URL — a text input (defaults to http://localhost:3000), used for email verification, password reset, and other email links. Important: Set this to your frontend base URL when its host or scheme differs from APP_URL (see Frontend URL below).
  4. Run migrations — a confirm prompt to run php artisan migrate immediately.

UUID vs. integer primary keys are auto-detected from your existing users table schema. If no users table exists (fresh install), UUID is used by default.

Non-Interactive Mode#

Pass flags to skip all prompts. Useful in CI/CD pipelines:

bash
php artisan magic-starter:install \
    --all \
    --uuid \
    --route-prefix=api/v1 \
    --frontend-url=https://app.example.com

Available Options#

Option Description
--all Install all features without prompting
--features=* Features to install (comma-separated, repeatable)
--uuid Use UUID primary keys
--no-uuid Use auto-incrementing integer primary keys
--route-prefix= Route prefix for package routes
--frontend-url= Frontend application URL for email links
--force Overwrite existing published files

The --features option accepts: teams, profile-photos, sessions, social-login, newsletter-subscription, extended-profile, notifications, two-factor-authentication, guest-auth, phone-otp, email-verification, timezones.

When --all is passed, all 12 features are enabled regardless of --features.

Frontend URL for Non-Localhost Deployments#

The backend signs email links (verification, password reset, and other email links) using APP_URL as the base. When your email links should open a frontend whose host or scheme differs from APP_URL, configure frontend_url to rewrite the link base to your frontend URL. Without it, email links point at the backend host (e.g. https://api.example.com/email/verify/{id}/{hash}) instead of opening the intended frontend app or deep link.

Solution: Configure the frontend_url setting to point to your frontend's base URL. This rewrites the base for all package email links.

Setting the Frontend URL#

You can provide the frontend URL in three ways:

  1. During install with the flag:

    bash
    php artisan magic-starter:install --all --frontend-url=https://app.example.com
    
  2. During interactive install: When prompted for "Frontend URL", enter your frontend app URL (e.g. https://app.example.com).

  3. Via environment variable: Set MAGIC_STARTER_FRONTEND_URL in your .env:

    text
    MAGIC_STARTER_FRONTEND_URL=https://app.example.com
    

Localhost Development#

For localhost development (backend at http://localhost:8000, frontend at http://localhost:3000), the hosts differ so you should keep frontend_url set. The installer defaults the prompt to http://localhost:3000, which covers this common case:

bash
php artisan magic-starter:install --all --frontend-url=http://localhost:3000

Publishable Assets#

The install command automatically publishes config and migrations. Action stubs and model stubs are not published by default — the package ships with working implementations out of the box.

Published by the Install Command#

Asset Destination Publish Tag
Config config/magic-starter.php magic-starter-config
Migrations database/migrations/ magic-starter-migrations
Model stubs app/Models/ (only when teams feature selected) magic-starter-models

Published Manually#

To customize default implementations, publish additional assets with vendor:publish:

Asset Destination Publish Tag
Action stubs app/Actions/MagicStarter/ magic-starter-stubs
Model stubs app/Models/ magic-starter-models
Policy stubs app/Policies/ magic-starter-policies
Translations lang/vendor/magic-starter/ magic-starter-lang
bash
php artisan vendor:publish --tag=magic-starter-stubs
php artisan vendor:publish --tag=magic-starter-models
php artisan vendor:publish --tag=magic-starter-policies
php artisan vendor:publish --tag=magic-starter-lang

User Model Setup#

Add the relevant traits to your User model. HasApiTokens (from Sanctum) is required for token authentication:

php
use FlutterSdk\MagicStarter\Traits\HasTeams;
use FlutterSdk\MagicStarter\Traits\HasProfilePhoto;
use FlutterSdk\MagicStarter\Traits\HasSocialAccounts;
use FlutterSdk\MagicStarter\Traits\NormalizesEmail;
use FlutterSdk\MagicStarter\Traits\HasNotifications;
use FlutterSdk\MagicStarter\Traits\TwoFactorAuthenticatable;
use FlutterSdk\MagicStarter\Traits\HasGuestSupport;
use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
    use HasUuids;
    use HasTeams;
    use HasProfilePhoto;
    use HasSocialAccounts;
    use NormalizesEmail;
    use HasNotifications;          // when notifications feature is enabled
    use TwoFactorAuthenticatable;  // when two-factor-authentication feature is enabled
    use HasGuestSupport;           // when guest-auth feature is enabled

    protected $appends = [
        'profile_photo_url',
    ];
}

Required Traits#

Trait Source Purpose
HasApiTokens laravel/sanctum Token-based API authentication
HasUuids illuminate/database UUID primary keys (only when use_uuids is true)
HasTeams FlutterSdk\MagicStarter\Traits Team membership, current team, personal team
HasProfilePhoto FlutterSdk\MagicStarter\Traits Profile photo URL, null when none is stored
HasSocialAccounts FlutterSdk\MagicStarter\Traits The socialAccounts() relation and hasPassword(), for social login and account deletion
NormalizesEmail FlutterSdk\MagicStarter\Traits Lower-cases an email on assignment, so [email protected] and [email protected] cannot become two accounts

Optional Traits#

Trait Source When to Add
HasNotifications FlutterSdk\MagicStarter\Traits notifications feature is enabled
TwoFactorAuthenticatable FlutterSdk\MagicStarter\Traits two-factor-authentication feature is enabled
HasGuestSupport FlutterSdk\MagicStarter\Traits guest-auth feature is enabled

Binding Action Contracts#

The service provider binds all action contracts to default implementations — no manual binding is required for the package to work out of the box.

To customize behavior, publish the action stubs and override the bindings in your AppServiceProvider:

bash
php artisan vendor:publish --tag=magic-starter-stubs
php
use FlutterSdk\MagicStarter\Contracts\CreatesUsers;
use FlutterSdk\MagicStarter\Contracts\CreatesTeams;
use FlutterSdk\MagicStarter\Contracts\UpdatesTeams;
use FlutterSdk\MagicStarter\Contracts\DeletesTeams;
use FlutterSdk\MagicStarter\Contracts\UpdatesUserProfiles;
use FlutterSdk\MagicStarter\Contracts\UpdatesUserPasswords;
use FlutterSdk\MagicStarter\Contracts\DeletesUsers;
use FlutterSdk\MagicStarter\Contracts\AddsTeamMembers;
use FlutterSdk\MagicStarter\Contracts\InvitesTeamMembers;
use FlutterSdk\MagicStarter\Contracts\RemovesTeamMembers;
use FlutterSdk\MagicStarter\Contracts\UpdatesTeamMemberRoles;

public function register(): void
{
    $this->app->bind(CreatesUsers::class, \App\Actions\MagicStarter\CreateUser::class);
    $this->app->bind(CreatesTeams::class, \App\Actions\MagicStarter\CreateTeam::class);
    $this->app->bind(UpdatesTeams::class, \App\Actions\MagicStarter\UpdateTeam::class);
    $this->app->bind(DeletesTeams::class, \App\Actions\MagicStarter\DeleteTeam::class);
    $this->app->bind(UpdatesUserProfiles::class, \App\Actions\MagicStarter\UpdateUserProfile::class);
    $this->app->bind(UpdatesUserPasswords::class, \App\Actions\MagicStarter\UpdateUserPassword::class);
    $this->app->bind(DeletesUsers::class, \App\Actions\MagicStarter\DeleteUser::class);
    $this->app->bind(AddsTeamMembers::class, \App\Actions\MagicStarter\AddTeamMember::class);
    $this->app->bind(InvitesTeamMembers::class, \App\Actions\MagicStarter\InviteTeamMember::class);
    $this->app->bind(RemovesTeamMembers::class, \App\Actions\MagicStarter\RemoveTeamMember::class);
    $this->app->bind(UpdatesTeamMemberRoles::class, \App\Actions\MagicStarter\UpdateTeamMemberRole::class);
}

Next Steps#

Now that Magic Starter is installed:

  • Configuration — Customize feature flags, authentication identity strategy, model overrides, and UUID settings.
  • Features — Learn about the 12 available feature flags and what each one enables.
  • Authentication — Set up login, registration, password reset, and social OAuth flows.
  • Teams — Configure team management, invitations, and member roles.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.