fluttersdk/magic-starter-laravel

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

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:

1. Remove Laravel's default database/migrations/0001_01_01_000000_create_users_table.php if it conflicts
2. Manually publish migrations from the package at src/../database/migrations/ to database/migrations/ with ordered Y_m_d_NNNNNN_ prefixes
3. 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:

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:

Documentation

Contributing

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

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

License

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