README

Magic Starter Laravel

Pre-built Auth, Profile, Teams & Notifications API for Laravel.
14 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 14 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
💳	Billing	Entitlement columns on the subject you bill, a user or a team, plus one guarded write path so more than one payment rail can claim a tier without racing

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 14 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 14 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 14 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
`onesignal`	OneSignal push channel for the notification features
`billing`	Entitlement columns on the declared billable subject (`billing.billable`, a user or a team) and the arbitration contract that writes them

Billing

The billing feature declares what you bill through magic-starter.billing.billable, a closed token that accepts user or team. Everything downstream resolves from it: the entitlement provenance columns, the Cashier customer columns, and the subscriptions foreign key all land on the table that token names, and the primary keys follow magic-starter.use_uuids like every other table the package ships.

laravel/cashier is a hard requirement and the package registers it from register(): Cashier::ignoreRoutes() (the package serves its own webhook route under a key of its own) plus Cashier::useSubscriptionModel() and Cashier::useSubscriptionItemModel(), pointed at the package's UUID-optional subclasses.

Warning

Do not run php artisan vendor:publish --tag=cashier-migrations. Cashier's five migrations hardcode Schema::table('users'), $table->id() and foreignId('user_id'). On an application billing a team they put the Stripe customer columns on the wrong table; on any application using UUID primary keys they create a bigint subscriptions that the subscription_items child cannot reference. The package ships three replacements (add_cashier_customer_columns_to_billable_table, create_subscriptions_table, create_subscription_items_table) that resolve the table from billing.billable and the key type from use_uuids, with Cashier's two later meter columns folded into the items create. magic-starter:install publishes them in dependency order. Cashier's publish group still appears in vendor:publish output because addPublishGroup() is additive and Laravel exposes no way to remove one, so this is a rule the package can document and cannot enforce.

Important

Upgrading from a release before billing.billable existed: set the key explicitly before re-running the installer. mergeConfigFrom is a shallow merge, so a config/magic-starter.php published before that key existed carries no billable at all, and the user default answers for it. If you bill a team, that default silently retargets the entitlement provenance and the three Cashier migrations at users instead of teams. Nothing refuses it: the boot guard rejects only a token it does not recognise, and user is a valid one. Set 'billable' => 'team' in your published config first, then re-run php artisan magic-starter:install.

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