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. Publish configuration and run migrations

php artisan vendor:publish --tag=magic-starter-config
php artisan migrate

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.

---

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.

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.

---

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