Installation
How to install Magic Starter Laravel, the feature-gated JSON API backend for the Magic Starter Flutter app, into a Laravel application.
On this page
Quick Reference#
composer require anilcancakir/magic-starter-laravel
php artisan magic-starter:install
php artisan migrate
| Step | What you do | Details |
|---|---|---|
| Require | composer require anilcancakir/magic-starter-laravel; the service provider registers itself. |
Installing the Package |
| Install | php artisan magic-starter:install publishes the config, the migrations for the features you pick, and the stubs. |
Running the Install Command |
| Frontend URL | Set MAGIC_STARTER_FRONTEND_URL when the frontend host or scheme differs from APP_URL. |
Frontend URL for Non-Localhost Deployments |
| User model | Add HasApiTokens, and HasUuids when use_uuids is true, plus the package traits. |
User Model Setup |
| Customise | Bind your own class to a contract in AppServiceProvider. |
Binding Action Contracts |
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 (illuminate/*) |
^12.32 | ^13.0 |
ext-gd, ext-exif |
* |
| 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:
composer require anilcancakir/magic-starter-laravel
Service Provider Auto-Discovery#
The package registers AnilcanCakir\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-starterkey. - Action contract binding: binds all action interfaces to default implementations (see Binding Action Contracts).
- Sanctum setup: uses a custom
PersonalAccessTokenmodel 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:
php artisan magic-starter:install
Interactive Mode#
When run without flags, the command uses Laravel Prompts to walk you through setup:
- Features: a
multiselectprompt with every feature pre-selected. - Route prefix: a
textinput (defaults toapi/v1). - Frontend URL: a
textinput (defaults tohttp://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 fromAPP_URL(see Frontend URL below). - Run migrations: a
confirmprompt to runphp artisan migrateimmediately.
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:
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: two-factor-authentication, teams, profile-photos, sessions, social-login, newsletter-subscription, extended-profile, notifications, guest-auth, phone-otp, email-verification, timezones, billing, audit, support, releases, campaigns, ai-runs, ai-prompts. A name outside that list is dropped silently.
When --all is passed, every feature is enabled regardless of --features. With neither flag and no terminal to prompt on, every feature is enabled as well.
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:
-
During install with the flag:
bash php artisan magic-starter:install --all --frontend-url=https://app.example.com -
During interactive install: When prompted for "Frontend URL", enter your frontend app URL (e.g.
https://app.example.com). -
Via environment variable: Set
MAGIC_STARTER_FRONTEND_URLin 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:
php artisan magic-starter:install --all --frontend-url=http://localhost:3000
Publishable Assets#
The install command publishes the config, the migrations, the translations, a factory and the User model stub. Action 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 the teams feature is selected) |
magic-starter-models |
| Policy stubs | app/Policies/ (only when the teams feature is selected) |
magic-starter-policies |
| User model stub | app/Models/User.php |
magic-starter-user-model |
| Translations | lang/vendor/magic-starter/ |
magic-starter-lang |
| User factory | database/factories/UserFactory.php |
magic-starter-factories |
Published Manually#
To customize default implementations, publish the action stubs with vendor:publish. Any other tag above can be published the same way when you skipped the install command.
| Asset | Destination | Publish Tag |
|---|---|---|
| Action stubs | app/Actions/MagicStarter/ |
magic-starter-stubs |
php artisan vendor:publish --tag=magic-starter-stubs
User Model Setup#
Add the relevant traits to your User model. HasApiTokens (from Sanctum) is required for token authentication:
use AnilcanCakir\MagicStarter\Traits\HasTeams;
use AnilcanCakir\MagicStarter\Traits\HasProfilePhoto;
use AnilcanCakir\MagicStarter\Traits\HasSocialAccounts;
use AnilcanCakir\MagicStarter\Traits\NormalizesEmail;
use AnilcanCakir\MagicStarter\Traits\HasNotifications;
use AnilcanCakir\MagicStarter\Traits\TwoFactorAuthenticatable;
use AnilcanCakir\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 |
AnilcanCakir\MagicStarter\Traits |
Team membership, current team, personal team |
HasProfilePhoto |
AnilcanCakir\MagicStarter\Traits |
Profile photo URL, null when none is stored |
HasSocialAccounts |
AnilcanCakir\MagicStarter\Traits |
The socialAccounts() relation and hasPassword(), for social login and account deletion |
NormalizesEmail |
AnilcanCakir\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 |
AnilcanCakir\MagicStarter\Traits |
notifications feature is enabled |
TwoFactorAuthenticatable |
AnilcanCakir\MagicStarter\Traits |
two-factor-authentication feature is enabled |
HasGuestSupport |
AnilcanCakir\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:
php artisan vendor:publish --tag=magic-starter-stubs
use AnilcanCakir\MagicStarter\Contracts\CreatesUsers;
use AnilcanCakir\MagicStarter\Contracts\CreatesTeams;
use AnilcanCakir\MagicStarter\Contracts\UpdatesTeams;
use AnilcanCakir\MagicStarter\Contracts\DeletesTeams;
use AnilcanCakir\MagicStarter\Contracts\UpdatesUserProfiles;
use AnilcanCakir\MagicStarter\Contracts\UpdatesUserPasswords;
use AnilcanCakir\MagicStarter\Contracts\DeletesUsers;
use AnilcanCakir\MagicStarter\Contracts\AddsTeamMembers;
use AnilcanCakir\MagicStarter\Contracts\InvitesTeamMembers;
use AnilcanCakir\MagicStarter\Contracts\RemovesTeamMembers;
use AnilcanCakir\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);
}
Gotchas#
| Mistake | Fix |
|---|---|
Creating users with use_uuids on and no HasUuids on the User model |
Add HasUuids, or install with --no-uuid. Without it user creation fails with a NOT NULL error on id. |
Leaving frontend_url unset when the frontend host differs from APP_URL |
Set MAGIC_STARTER_FRONTEND_URL, or the email links point at the backend host. |
| Publishing the action stubs and deploying | A published stub throws RuntimeException until you implement it. |
Passing a misspelt name to --features |
The name is dropped without a warning. Check the summary the command prints. |
Re-running magic-starter:install to refresh published files |
Existing files are kept. Pass --force to overwrite them. |
Related Documentation#
- Configuration: feature flags, identity strategy, model overrides and UUID settings.
- Authentication: login, registration, password reset and the other sign-in flows.
- Teams: team management, invitations and member roles.
- Action Contracts: every contract you can bind your own class to.