Expressive Development

Expressive Development

Use this skill when a Laravel application needs Typed Objects for Eloquent using Expressive.

Primary Goal

• apply Expressive through its public Laravel integration points only
• keep Eloquent responsible for querying, relationship semantics, model events, mass assignment, and database writes
• prefer the smallest class, config, command, or mapping change that gives the application typed public properties

Workflow

1. Inspect the Laravel app context

• confirm the app is a Laravel project and identify its Laravel/PHP versions before recommending installation
• inspect the target Eloquent model, casts, accessors, relationships, $fillable/$guarded, $hidden, and $visible
• check whether the application already uses DTOs, resources, actions, or domain objects so Expressive fits the existing boundary instead of replacing unrelated patterns
• decide whether the Expressive class should mirror the model shape, expose a smaller application boundary, or be generated and then edited

2. Install and configure only what is needed

• install with composer require wendelladriel/laravel-expressive; Laravel auto-discovers the service provider
• publish with php artisan vendor:publish --tag="expressive" only when the app needs config/expressive.php or stubs/expressive.stub
• publish only config with php artisan vendor:publish --tag="expressive-config" when changing namespace, suffix, strict mode, diagnostics, serialization casing, or generator defaults
• publish only the generator stub with php artisan vendor:publish --tag="expressive-stubs" when generated class formatting must be customized
• set expressive.namespace and expressive.suffix before relying on implicit lookup or running make:expressive
• set expressive.strict to true when Expressive objects should convert back to Eloquent models but never write database state through save()
• set expressive.diagnostics.throw_on_unfillable to true during adoption when ignored unfillable properties should fail fast
• set expressive.serialization.case to snake only when serialized keys should be snake case globally

3. Define mappings deliberately

• add WendellAdriel\Expressive\Concerns\IsExpressive only to Eloquent models that should expose $model->expressive()
• create Expressive classes under the configured namespace, or run php artisan make:expressive User --model="App\Models\User"
• run php artisan expressive:generate --path="app/Models" when scaffolding Expressive classes for multiple discovered Eloquent models
• Expressive classes must extend WendellAdriel\Expressive\Expressive and expose mapped data as public typed properties
• use #[Model(User::class)] on an Expressive class when the model cannot be inferred from namespace and suffix
• use #[Expressive(UserData::class)] on a model when it should resolve a specific Expressive class
• use #[Map('remember_token')] when a property maps to a non-default Eloquent key; unmapped non-relationship properties default to snake-case keys
• use #[Relationship] only for relationship properties, and #[Virtual] only for accessor/appended values
• keep relationship and virtual properties nullable because unloaded relationships and unrequested virtual accessors map to null
• type single relationships as ?RelatedExpressive; type many relationships as ?Illuminate\Support\Collection with @var Collection<int, RelatedExpressive>|null
• do not put mapping attributes on private or protected properties; Expressive only maps public non-static properties

4. Convert from Eloquent at explicit boundaries

• use $model->expressive(relationships: [...], attributes: [...]) for a single opted-in model
• use $eloquentCollection->expressive(relationships: [...], attributes: [...]) to convert an Eloquent collection without mutating the original collection
• use $builder->expressive(relationships: [...], attributes: [...]) when it is acceptable to execute get() immediately and return an in-memory Illuminate\Support\Collection
• use $builder->expressiveChunk($count, $callback, relationships: [...], attributes: [...]) for large result sets that can be processed with Laravel chunk(); the count must be at least 1
• pass relationship names to relationships instead of relying on lazy loading; Expressive uses loadMissing() and leaves unloaded relationships as null
• pass accessor keys to attributes for virtual properties; Expressive calls Eloquent append() and leaves unrequested virtual values as null
• use API resources or transformers when the response contract differs from the Expressive object shape

5. Generate and sync classes safely

• use php artisan make:expressive User --model="App\Models\User" to generate a starting class from model columns, casts, relationships, and detected accessors
• use php artisan expressive:generate to scan app/Models, or pass one or more --path options for explicit model directories
• use --exclude with expressive:generate to skip selected model basenames or fully qualified class names
• use --namespace, --suffix, --attributes, --without-attributes, --relationships, --without-relationships, --include-hidden, --exclude-hidden, --hint-morph-map, --dry-run, and --force only for the current generation need
• remember hidden attributes are generated by default, but serialization still respects the mapped model's hidden and visible rules
• use php artisan expressive:sync User --model="App\Models\User" to detect drift; --model is required
• use php artisan expressive:sync --all in CI to scan the configured Expressive namespace and fail when generated classes drift from their mapped models
• combine expressive:sync --all --write only when generated classes are safe to rewrite in bulk
• add --write only for generated classes that are safe to rewrite; if the class has custom methods or intentional shape changes, update it manually
• treat sync output as review input because missing, stale, or type differences may be intentional application design

6. Serialize or persist intentionally

• use $expressive->toArray(), $expressive->toJson(), or json_encode($expressive) for direct serialization of initialized public properties
• expect nested Expressive objects and collections to serialize recursively
• expect uninitialized typed properties to be skipped; nullable properties with default null are initialized and may appear unless hidden or invisible
• use $expressive->model() to create an unsaved Eloquent model filled only with mapped, fillable, non-virtual, non-relationship properties
• use $expressive->save() to save the root model and supported direct relationships when expressive.strict is false: BelongsTo, HasOne, MorphOne, HasMany, and MorphMany
• keep BelongsToMany, morph-to-many, through relationships, pivot semantics, and deletion in explicit Eloquent application code

Rules, References, and Templates

Read before executing:

• official documentation: https://laravel-expressive.wendelladriel.com
• installed package config after publishing: config/expressive.php
• installed package stub after publishing: stubs/expressive.stub
• target application models under app/Models/
• target application Expressive classes under the configured expressive.namespace
• Artisan help in the consuming app: php artisan help make:expressive, php artisan help expressive:generate, and php artisan help expressive:sync

Examples

• For a read boundary, add IsExpressive to App\Models\User, run php artisan make:expressive User --model="App\Models\User", keep #[Relationship] public ?Collection $posts = null;, then return User::query()->where('active', true)->expressive(relationships: ['posts']) from an application service.
• For a custom boundary, create App\Data\PublicUser extends Expressive, add #[Model(App\Models\User::class)], include only public properties the service needs, and call $user->expressive(attributes: ['display_name']) when a nullable #[Virtual] property should be populated.
• For write input, hydrate an Expressive object from validated data, call $object->model() when application code should decide how to save or strict mode is enabled, or call $object->save() only when root fillable attributes and supported direct relationships should be persisted immediately.
• For CI drift checks, run php artisan expressive:sync --all and review differences before choosing either manual class edits or safe --write rewrites.

Anti-patterns

• do not use Expressive as a replacement for Eloquent querying, resources, validation, authorization, model events, or relationship APIs
• do not make relationship or virtual properties non-nullable
• do not rely on lazy loading during conversion; request relationships explicitly
• do not expect virtual accessors to populate unless passed through attributes
• do not expect model() to save records or persist relationships
• do not call save() when expressive.strict is enabled; convert with model() and persist through Eloquent explicitly
• do not expect save() to handle many-to-many, morph-to-many, through relationships, pivot sync, detach, attach, or deletion
• do not use make:expressive --force or expressive:sync --write over custom classes without reviewing intentional user edits
• do not assume expressive:sync --all can decide whether customized class drift is intentional; treat its output as review input
• do not document private package classes as application-facing APIs