README

Magic Starter Laravel

Pre-built Auth, Profile, Teams & Notifications API for Laravel.
12 opt-in features — every action overridable.

Website · Docs · Packagist · Issues · Discussions

Alpha — magic-starter-laravel is under active development. APIs may change between minor versions until 1.0.0.

Why Magic Starter Laravel?

Stop rebuilding authentication, profile management, and team features from scratch in every Laravel project. The same controllers, the same validation, the same service bindings — over and over.

Magic Starter Laravel gives you a production-ready JSON API for auth, profile, teams, and notifications out of the box. Everything is config-driven with 12 opt-in feature toggles. Every action is overridable via contract bindings — swap any business logic from your host app without touching the package.

Config-driven API starter kit. Enable only what you need. Override any action. Ship faster.

Features

	Feature	Description
🔑	Authentication	Login, register, forgot/reset password, social login
🛡️	Two-Factor Auth	Enable/disable 2FA with QR code, OTP confirm, recovery codes
👤	Profile Management	Photo upload, email/password change, account deletion
👥	Teams	Create, switch, invite members, manage roles, team photos
🔔	Notifications	Listing, unread count, mark read/unread, preference matrix
📱	OTP Login	Phone-based authentication with send/verify flow
👻	Guest Auth	Guest-only login without a registered account
✉️	Email Verification	Signed verification URL, resend notification
📰	Newsletter	Subscribe/unsubscribe toggle per user
🌐	Timezones	Timezone listing API for extended profile
📷	Profile Photos	Upload and delete for users and teams
🖥️	Sessions	Active session listing and revocation

Quick Start

1. Install the package

composer require fluttersdk/magic-starter-laravel

2. Run the install command

php artisan magic-starter:install

The magic-starter:install command guides you through setup interactively:

Selects which of the 12 features to enable (all enabled by default)
Detects your database primary key type (UUID or auto-incrementing integer)
Publishes configuration and migrations in correct order
Removes Laravel's default users migration to avoid conflicts
Publishes model stubs, factory, and language files

The installer prompts to run php artisan migrate at the end (default: no). If you skip that prompt, run the migrations yourself before using the API, otherwise the published migrations stay unapplied:

php artisan migrate

Important

Frontend URL: The backend signs email links (verification, password reset, and other email links) using APP_URL as the base. If your email links should open a frontend whose host or scheme differs from APP_URL, set MAGIC_STARTER_FRONTEND_URL in your .env to the frontend base URL (the magic-starter.frontend_url config reads it), or pass --frontend-url=https://app.example.com when installing via php artisan magic-starter:install. Without it, email links point at the backend host (e.g. https://api.example.com/email/verify/...) instead of opening the intended frontend app.

For CI/CD or non-interactive environments, use command options:

# Install all features with UUID primary keys and custom route prefix
php artisan magic-starter:install --all --uuid --route-prefix=api/v2

# Install specific features, auto-detect primary key type
php artisan magic-starter:install --features=teams --features=profile-photos --features=notifications

# Install with integer primary keys instead of UUID
php artisan magic-starter:install --all --no-uuid

# Use custom frontend URL for email links
php artisan magic-starter:install --all --frontend-url=https://app.example.com

# Overwrite existing files (migrations, config, stubs)
php artisan magic-starter:install --all --force

Available options:

--all: Enable all 12 features without prompting
--features=<name>: Enable specific feature(s); repeat for multiple (e.g. --features=teams --features=sessions)
--uuid: Force UUID primary keys
--no-uuid: Force auto-incrementing integer primary keys
--route-prefix=<prefix>: Set route prefix (default: api/v1)
--frontend-url=<url>: Frontend URL for email links (e.g. verification and password resets)
--force: Overwrite existing published files

3. Prepare your User model

Add the required traits to your User model:

use FlutterSdk\MagicStarter\Traits\HasTeams;
use FlutterSdk\MagicStarter\Traits\HasGuestSupport;
use FlutterSdk\MagicStarter\Traits\HasProfilePhoto;
use FlutterSdk\MagicStarter\Traits\HasNotifications;
use FlutterSdk\MagicStarter\Support\ConditionallyUsesUuids;

class User extends Authenticatable
{
    use ConditionallyUsesUuids;
    use HasTeams;
    use HasGuestSupport;
    use HasProfilePhoto;
    use HasNotifications;
}

That's it — auth, profile, teams, and notifications API endpoints are ready to use.

Advanced: Manual Installation

If you prefer to publish and migrate without the install command, you can run the steps manually. Note that manual vendor:publish does NOT generate ordered migration timestamps, so migrations may run in unpredictable order and cause foreign key conflicts. The magic-starter:install command is the recommended path because it ensures correct migration order.

If you must use manual steps:

php artisan vendor:publish --provider="FlutterSdk\MagicStarter\MagicStarterServiceProvider" --tag=magic-starter-config
php artisan migrate

You will also need to:

Remove Laravel's default database/migrations/0001_01_01_000000_create_users_table.php if it conflicts
Manually publish migrations from the package at src/../database/migrations/ to database/migrations/ with ordered Y_m_d_NNNNNN_ prefixes
Apply the traits listed in Step 3 above to your User model

Feature Toggles

All 12 features are opt-in. Enable them by uncommenting in config/magic-starter.php:

Toggle Key	Description
`teams`	Team creation, switching, member invitations, role management
`profile-photos`	Profile photo upload and display for users and teams
`sessions`	Active session listing and revocation
`social-login`	Social authentication via Socialite providers
`newsletter-subscription`	Newsletter subscribe/unsubscribe toggle
`extended-profile`	Extended profile fields: phone, timezone, language, locale
`notifications`	Notification listing, unread count, read/unread, preferences
`two-factor-authentication`	Two-factor auth with QR code, OTP confirmation, recovery codes
`email-verification`	Signed email verification URL and resend notification
`guest-auth`	Guest-only authentication without a registered account
`phone-otp`	Phone-based OTP send/verify login flow
`timezones`	Timezone listing API endpoint

Architecture

Request → Route (feature-gated, rate-limited)
  → Controller (thin — injects contract)
    → Contract interface
      → Action (business logic, validator, model resolution)
        → Model (ConditionallyUsesUuids, dynamic resolution)

Key patterns:

Pattern	Implementation
Contract-Action	Controllers inject interfaces from `Contracts/`, bound in ServiceProvider
Feature Toggles	`Features::enabled()` gates routes, logic, and resource fields
Dynamic Model Resolution	`MagicStarter::userModel()`, `::teamModel()` — never hardcode classes
Service Provider	Contract bindings, route registration, rate limiters, password reset URL
Rate Limiters	Per-endpoint throttle groups: auth, register, social, 2FA, OTP, etc.

Documentation

Document	Description
Installation	Adding the package, publishing config, running migrations
Configuration	Config file reference and feature toggles
Authentication	Login, register, forgot/reset password, social login, OTP
Teams	Team CRUD, switching, invitations, member roles
Profile	Profile updates, photo upload, password change, account deletion
Two-Factor Auth	2FA enable/disable, QR code, confirm, recovery codes
Notifications	Listing, unread count, mark read, preferences
Service Provider	Contract bindings, route registration, rate limiters
Action Contracts	Overriding business logic via singleton binding
Models	Dynamic resolution, UUID support, traits

Contributing

Contributions are welcome! Please see the issues page for open tasks or to report bugs.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Write tests following the TDD flow — red, green, refactor
Ensure all checks pass: composer test, composer lint, composer analyse
Submit a pull request

License

Magic Starter Laravel is open-sourced software licensed under the MIT License.

Built with care by FlutterSDK
_{If Magic Starter Laravel helps your project, consider giving it a star on GitHub.}

fluttersdk / magic-starter-laravel

Maintainers

Package info

Statistics

Security