Skip to content

Models Architecture

View raw .md

This document describes the model layer of the magic-starter-laravel package: how models are resolved at runtime, how primary key types are toggled between UUID and integer, and the purpose and structure of each built-in model and user-model trait.

On this page

Introduction#

The package never hardcodes App\Models\* class names anywhere in its own code. All model references go through the MagicStarter static registry, which resolves the correct class at runtime based on configuration, consumer overrides, and auto-published stubs.

Primary key type (UUID vs. auto-incrementing integer) is a single config flag (magic-starter.use_uuids, default true). The ConditionallyUsesUuids trait and MigrationHelper class both read the same flag, ensuring that the schema and Eloquent behavior stay in sync without any model-level changes.


MagicStarter Registry#

FlutterSdk\MagicStarter\MagicStarter is a static service-locator for model class names. It exposes four public resolution methods:

Method Config key Fallback
userModel() magic-starter.models.user auth.providers.users.model
teamModel() magic-starter.models.team -
membershipModel() magic-starter.models.membership -
teamInvitationModel() magic-starter.models.team_invitation -

All four throw RuntimeException when the resolved value is null or an empty string.

Resolution Priority#

For each resolver the lookup order is:

  1. Runtime override registered via MagicStarter::use*Model(string $class).
  2. config('magic-starter.models.*') value.
  3. Fallback config (user only: auth.providers.users.model).

App\Models Fallback#

For teamModel(), membershipModel(), and teamInvitationModel(), after the config value is obtained it is passed through resolveConcreteModel(). This method checks an internal map:

php
protected static array $appModelOverrides = [
    Team::class           => 'App\\Models\\Team',
    TeamUser::class       => 'App\\Models\\TeamUser',
    TeamInvitation::class => 'App\\Models\\TeamInvitation',
];

When the configured class is one of the three built-in package models, class_exists() is called on the corresponding App\Models\* equivalent. If the consumer has published and extended the stub, that class is returned instead. The call is wrapped in try/catch (Throwable) to survive stale Composer classmaps that reference a deleted file.

Runtime Overrides#

Overrides are stored in the static $using array and take precedence over everything else. They are used in tests to inject fixture models:

php
MagicStarter::useUserModel(ConcreteUser::class);
MagicStarter::useTeamModel(ConcreteTeam::class);
MagicStarter::useMembershipModel(ConcreteTeamUser::class);
MagicStarter::useTeamInvitationModel(ConcreteTeamInvitation::class);

Call MagicStarter::reset() in tearDown() to clear all overrides and the ignoreRoutes flag.


ConditionallyUsesUuids Trait#

FlutterSdk\MagicStarter\Support\ConditionallyUsesUuids is applied to every package model. It conditionally activates UUID primary key behavior based on MigrationHelper::usesUuids().

Boot phase (bootConditionallyUsesUuids): when UUIDs are enabled, registers a creating observer that populates the primary key with an ordered UUID if it is empty. This replicates the core behavior of Laravel's HasUuids trait without statically use-ing it (which cannot be done conditionally).

Initialization phase (initializeConditionallyUsesUuids): runs on every model instantiation. Sets $incrementing = false and $keyType = 'string' when UUIDs are enabled.

uniqueIds() method: returns [$this->getKeyName()] when UUIDs are enabled, or an empty array otherwise. This is the hook used by HasUuids to discover which columns receive auto-generated UUIDs.

php
// Integer mode (use_uuids = false):
//   $incrementing = true, $keyType = 'int', no UUID generation

// UUID mode (use_uuids = true):
//   $incrementing = false, $keyType = 'string', ordered UUID on creating

MigrationHelper#

FlutterSdk\MagicStarter\Support\MigrationHelper centralizes the UUID/integer switch for all package migrations. The single source of truth is:

php
public static function usesUuids(): bool
{
    return (bool) config('magic-starter.use_uuids', true);
}

All three helper methods delegate to this flag.

primaryKey#

php
MigrationHelper::primaryKey(Blueprint $table): ColumnDefinition
  • UUID mode: $table->uuid('id')->primary()
  • Integer mode: $table->id()

Never use raw $table->id() or $table->uuid('id') directly in package migrations.

foreignKey#

php
MigrationHelper::foreignKey(Blueprint $table, string $column): ForeignIdColumnDefinition
  • UUID mode: $table->foreignUuid($column)
  • Integer mode: $table->foreignId($column)

Chain .constrained()->cascadeOnDelete() after the call to complete the foreign key definition:

php
MigrationHelper::foreignKey($table, 'user_id')->constrained()->cascadeOnDelete();

morphColumns#

php
MigrationHelper::morphColumns(Blueprint $table, string $name): void
  • UUID mode: $table->uuidMorphs($name) - generates {name}_type VARCHAR and {name}_id CHAR(36)
  • Integer mode: $table->morphs($name) - generates {name}_type VARCHAR and {name}_id BIGINT UNSIGNED

Used for polymorphic relations such as notifiable on notification_settings and tokenable on personal_access_tokens.


Package Models#

All package models live in FlutterSdk\MagicStarter\Models\. Every model uses ConditionallyUsesUuids and the Laravel 11+ casts() method syntax (not the $casts property).

Team#

FlutterSdk\MagicStarter\Models\Team

Represents a team (workspace). Teams can be personal (created automatically for each user) or shared.

Columns

Column Type Notes
id uuid / bigint PK via ConditionallyUsesUuids
user_id uuid / bigint FK → owner user
name string Team display name
personal_team boolean true for auto-created personal workspace
profile_photo_path string|null Stored path; URL resolved via accessor
created_at, updated_at timestamp

Accessor: profile_photo_url (appended): reads from the configured storage disk (magic-starter.profile_photo_disk, falling back to filesystems.default). Answers null when no photo is stored, so the client draws its own initials.

Relations

Method Type Notes
owner() BelongsTo<Model, $this> Resolves via MagicStarter::userModel()
users() BelongsToMany<Model, $this> team_user pivot, uses membershipModel(), exposes role pivot column
invitations() HasMany<TeamInvitation, $this> Resolves via MagicStarter::teamInvitationModel()

TeamUser (Pivot)#

FlutterSdk\MagicStarter\Models\TeamUser

Pivot model for the team_user join table. Extends Illuminate\Database\Eloquent\Relations\Pivot (not Model).

Columns

Column Type Notes
id uuid / bigint PK
team_id uuid / bigint FK → teams
user_id uuid / bigint FK → users
role string|null Member role string
created_at, updated_at timestamp

TeamInvitation#

FlutterSdk\MagicStarter\Models\TeamInvitation

Stores pending invitations to join a team, identified by a unique token sent to the invitee's email address.

Columns

Column Type Notes
id uuid / bigint PK
team_id uuid / bigint FK → teams (not fillable; set on creation)
email string Invitee email address
role string Role to assign on acceptance
token string Unique invitation token
expires_at datetime|null Nullable; no expiry when null
created_at timestamp No updated_at column

Methods

  • isExpired(): bool - returns true when expires_at is set and is in the past.
  • scopeValid(Builder $query) - filters to non-expired invitations (expires_at IS NULL OR expires_at > NOW()).

Relations

Method Type
team() BelongsTo<Team, $this> via MagicStarter::teamModel()

NotificationSetting#

FlutterSdk\MagicStarter\Models\NotificationSetting

Stores per-user overrides for notification delivery preferences. Each row represents a single (user, notification_type, channel) combination.

Columns

Column Type Notes
id uuid / bigint PK
notifiable_id uuid / bigint Polymorphic FK
notifiable_type string Polymorphic type
type string Notification slug
channel string Delivery channel (e.g. push, email)
is_enabled boolean Whether the channel is active
created_at, updated_at timestamp

Relations

Method Type
notifiable() MorphTo<Model, $this>

NewsletterSubscriber#

FlutterSdk\MagicStarter\Models\NewsletterSubscriber

A user's newsletter subscription and the consent it rests on. The row belongs to a user, not to an address: email is a copy kept in step with the user's. Use NewsletterSubscriber::forUser(), subscribeUser() and unsubscribe() rather than writing the columns, and read recipients through marketable() only.

Columns

Column Type Notes
id uuid / bigint PK
user_id uuid / bigint|null Owner, unique, foreign key to users with cascade on delete; null only on a row written by address alone, until the owner claims it
email string Copy of the owner's email (unique enforced at DB level)
is_active boolean Subscription status
source string|null Optional attribution source
consented_at timestamp|null When consent was last given
consent_version string(32)|null magic-starter.newsletter.consent_version at that moment; pre-e5a on rows that predate the record
consent_source string(32)|null Where consent was given, e.g. profile or registration
unsubscribed_at timestamp|null When consent was withdrawn
unsubscribe_token string(64)|null Unique one-click unsubscribe secret, minted on creation and never rotated; in $hidden
created_at, updated_at timestamp

Relations

Method Type
user() BelongsTo<Model, $this>

Methods

Method Behaviour
scopeMarketable() marketable(): active, consented_at set, unsubscribed_at null, user_id set. The only audience a sender may use
forUser($user) The user's row by user_id; failing that, claims an owner-less row with the user's address (case-insensitive). A row another user owns is never taken
subscribeUser($user, $source) Creates or reactivates the row, keeps its token, rewrites the consent fields, queues the confirmation mail when the row was not a marketing recipient, records newsletter.subscribed
unsubscribe($via, $auditContext = []) Sets is_active false and unsubscribed_at; does nothing when already withdrawn; records newsletter.unsubscribed

See Newsletter Subscription for the endpoints, the one-click link and the consent rules.

PersonalAccessToken#

FlutterSdk\MagicStarter\Models\PersonalAccessToken

Extends Laravel\Sanctum\PersonalAccessToken with device-tracking columns. This model is registered as the Sanctum token model in the service provider, replacing the default Sanctum implementation.

Additional columns (beyond standard Sanctum fields)

Column Type Notes
ip_address string|null Client IP at token creation
user_agent string|null Client user-agent string

All standard Sanctum columns (tokenable_type, tokenable_id, name, token, abilities, last_used_at, expires_at) are inherited.

Uses ConditionallyUsesUuids - the tokenable_id column type is kept in sync with the user PK type via MigrationHelper::morphColumns($table, 'tokenable').


User Traits#

These traits are mixed into the consumer's User model. They are all located in FlutterSdk\MagicStarter\Traits\.

HasTeams#

Adds team-membership relationships and helper methods.

Relations

Method Return type Notes
ownedTeams() HasMany<Model, $this> Teams where user_id = this.id
teams() BelongsToMany<Model, $this> Via team_user pivot; uses membershipModel(), exposes role
currentTeam() BelongsTo<Model, $this> Resolved from current_team_id column

Helper methods

Method Returns Notes
personalTeam() Model|null First owned team with personal_team = true
allTeams() Collection<int, Model> Merge of ownedTeams + teams, sorted by name
getCurrentTeamOrPersonal() Model|null currentTeam ?? personalTeam()
belongsToTeam(Model $team) bool Checks both owned and member teams
ownsTeam(Model $team) bool Compares user_id on the team with this user's PK
hasTeamRole(Model $team, string $role) bool Checks pivot role on member teams; does not cover owners

HasProfilePhoto#

Provides the profile_photo_url Eloquent accessor.

Accessor: getProfilePhotoUrlAttribute(): ?string

Resolution order:

  1. If profile_photo_path is non-empty: resolves the URL via the magic-starter.profile_photo_disk filesystem disk (falling back to filesystems.default).
  2. Otherwise: returns null. The client draws its own initials, in its own theme.

HasNotifications#

Manages per-user notification preferences and OneSignal routing.

Relation: notificationSettings(): MorphMany<NotificationSetting, $this>

Core method: prefers(string $type, string $channel): bool

Resolution order:

  1. If $type is not in the NotificationPreferenceRegistry, returns true (allow delivery by default).
  2. Looks for a DB override in notificationSettings for the (type, channel) pair; returns is_enabled if found.
  3. Falls back to the registry's default channels for the type.

notificationPreferenceMatrix(): array - returns the full preference state for all registered notification types. DB overrides use slug-based keys (not FQCNs) to ensure a stable API response shape regardless of how types were registered.

routeNotificationForOneSignal(): array: returns ['external_id' => [MagicStarter::onesignalExternalIdPrefix() . $this->getKey()]] for v5 SDK alias-based routing. The payload is passed to FlutterSdk\MagicStarter\Notifications\Channels\OneSignalChannel, which applies the aliases to the notification via setIncludeAliases(). A prefix is required because OneSignal rejects simple numeric values such as 0 or 1 as external IDs, and because the id has to match the one the Flutter client registered. Both sides read it from config (magic-starter.onesignal.external_id_prefix here, magic_starter.notifications.external_id_prefix there), defaulting to the same user_; a mismatch is silent, since OneSignal accepts a send to an alias no device carries.

Boot hook (bootHasNotifications()): keeps the OneSignal SMS subscription in step with phone. A saving hook clears sms_registered_at when an existing model's phone is dirty and the column is loaded, so the next SMS send reconciles again. An updated hook queues PruneSmsSubscriptions through DB::afterCommit when the old phone was non-empty and OneSignal is provisioned, so a rolled-back change sends nothing. initializeHasNotifications() merges the sms_registered_at datetime cast.

TwoFactorAuthenticatable#

Adds TOTP-based two-factor authentication to the user model.

Expected columns on the user table

Column Type
two_factor_secret text|null (encrypted)
two_factor_recovery_codes text|null (encrypted JSON array)
two_factor_confirmed_at timestamp|null

Methods

Method Returns Notes
hasEnabledTwoFactorAuthentication() bool true when two_factor_confirmed_at is not null
twoFactorSecret() string|null Decrypts two_factor_secret; returns null when not set
recoveryCodes() array<int, string> Decrypts and JSON-decodes two_factor_recovery_codes
twoFactorRecoveryCodesCount() int Count of remaining recovery codes
replaceRecoveryCode(string $code) void Swaps the given code for a new random(10)-random(10) string and saves
twoFactorQrCodeUrl() string TOTP provisioning URI via TwoFactorAuthenticationProvider
twoFactorQrCodeSvg() string 192×192 SVG QR code rendered by bacon/bacon-qr-code

The company name in the QR code provisioning URI is read from magic-starter.two_factor.company_name, falling back to app.name.

HasGuestSupport#

Provides identity helpers for models that support unauthenticated (guest) sessions.

Methods

Method Returns Notes
isGuest() bool Casts is_guest column to boolean
isRegistered() bool Not a guest, and has either (email + password) or (phone + password)

MustVerifyEmail#

Overrides Laravel's default MustVerifyEmail contract implementation with guest-awareness.

hasVerifiedEmail(): bool - guests are treated as verified (they have no email address, so the verified middleware must not block them). Internally calls method_exists($this, 'isGuest') before using isGuest() to avoid coupling to HasGuestSupport.

sendEmailVerificationNotification(): void - dispatches VerifyEmailNotification (the package's own notification class, not Laravel's default), at most once per model instance.

A registration reaches this method twice: Actions\CreateUser sends explicitly, and AuthController::register() then fires Registered, whose framework listener calls it again on the same object. Neither caller can go (the action has direct invokers, and CreatePersonalTeamListener hangs off Registered), so the "one verification mail per registration" invariant is enforced here, at the seam both paths funnel through. A deliberate resend through POST /email/verification-notification is unaffected, since it arrives in its own request with its own instance.

The guard is an instance property, never a static keyed by id: a static would survive between requests under Octane and mute a customer's later resend for the life of the worker. That also fixes its limit. A consumer who binds their own CreatesUsers and then fires event(new Registered($user->fresh())), or reloads the model in between, hands the listener a different object with the flag unset and gets both mails again. Pass the same instance through.


Relationship Typing Conventions#

All relationship return types use the generic syntax introduced in Laravel 11 / PHPStan-aware stubs:

php
// BelongsTo
public function owner(): BelongsTo  // typed as BelongsTo<Model, $this>

// HasMany
public function invitations(): HasMany  // typed as HasMany<TeamInvitation, $this>

// BelongsToMany (always include pivot setup)
public function users(): BelongsToMany  // BelongsToMany<Model, $this>
    // ...
    ->using(MagicStarter::membershipModel())
    ->withPivot('role')
    ->withTimestamps();

// MorphMany
public function notificationSettings(): MorphMany  // MorphMany<NotificationSetting, $this>

// MorphTo
public function notifiable(): MorphTo  // MorphTo<Model, $this>

The concrete type parameter for user-model relations is Model (not a specific class) because the actual class is resolved dynamically at runtime via MagicStarter::userModel().


PHPDoc Conventions#

Every model class carries PHPDoc block annotations above the class declaration:

php
/**
 * @property string      $id               Primary key (UUID or bigint as string)
 * @property string      $user_id          Foreign key
 * @property string      $name
 * @property bool        $personal_team
 * @property string|null $profile_photo_path
 * @property-read string|null $profile_photo_url Computed accessor
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 * @property-read Model            $owner        Relation accessor
 * @property-read Collection<...>  $users        Relation collection
 */

Key rules:

  • Use @property for every database column.
  • Use @property-read for Eloquent accessors and loaded relation results.
  • Type the id column as string even in integer mode - Eloquent casts it to string in PHP; document the PHP-visible type, not the SQL type.
  • Use Carbon|null for nullable timestamp columns, not string.
  • Collections are typed with their item type: Collection<int, TeamInvitation>.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.