Typed Objects for Eloquent with Expressive

Expressive, by Wendell Adriel, converts Eloquent models into typed PHP objects and can convert those objects back into Eloquent models when your application needs to persist data. The goal is to give services, actions, and tests a typed object boundary while Eloquent continues to handle querying, relationships, casts, visibility rules, mass assignment, and database writes.

Instead of passing full Eloquent models throughout your codebase, you work with lightweight objects that have public, typed properties. This keeps your domain logic separate from the database layer without forcing you to abandon Eloquent.

#Opting Models In

Models opt in by adding the IsExpressive trait. Attributes like #[Fillable] and #[Hidden] describe how the model maps to its typed counterpart:

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\HasOne;
use Illuminate\Foundation\Auth\User as Authenticatable;
use WendellAdriel\Expressive\Concerns\IsExpressive;

#[Fillable(['name', 'email', 'role', 'password'])]
#[Hidden(['password', 'remember_token'])]
class User extends Authenticatable
{
    use IsExpressive;

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }

    public function address(): HasOne
    {
        return $this->hasOne(Address::class);
    }

    protected function displayName(): Attribute
    {
        return Attribute::make(
            get: fn (): string => "{$this->name} ({$this->role->value})",
        );
    }
}

#Generating Expressive Classes

The package includes an Artisan command to scaffold a typed class from an existing model:

php artisan make:expressive User --model="App\Models\User"

By default, generated classes live in App\Expressive. Each class extends the base Expressive class with typed public properties that mirror the model's columns, relationships, and accessors:

use App\Enums\UserRole;
use App\Expressive\Address;
use App\Expressive\Post;
use Carbon\CarbonInterface;
use Illuminate\Support\Collection;
use WendellAdriel\Expressive\Attributes\Relationship;
use WendellAdriel\Expressive\Attributes\Virtual;
use WendellAdriel\Expressive\Expressive;

final class User extends Expressive
{
    public ?int $id = null;

    public string $name;

    public string $email;

    public UserRole $role;

    public ?CarbonInterface $createdAt = null;

    #[Relationship]
    public ?Address $address = null;

    /** @var Collection<int, Post>|null */
    #[Relationship]
    public ?Collection $posts = null;

    #[Virtual]
    public ?string $displayName = null;
}

The #[Relationship] attribute marks properties that map to Eloquent relations, and #[Virtual] marks accessor-backed values like displayName that are not real columns.

#Converting Models to Typed Objects

Call expressive() on a model, collection, or query builder to get back typed objects. You can selectively include accessors and relationships:

// A single model with a virtual attribute
$user = User::findOrFail(1)->expressive(attributes: ['display_name']);

// A collection with an eager-loaded relationship
$users = User::query()->get()->expressive(relationships: ['posts']);

// Straight from the query builder
$users = User::query()
    ->where('active', true)
    ->expressive(relationships: ['posts']);

Loaded relationships are converted recursively. A HasOne relation becomes the related model's Expressive object, and a HasMany relation becomes a Collection of Expressive objects.

#Persisting Typed Objects

Expressive can also go the other direction. The model() method builds an unsaved Eloquent instance from the typed object, while save() persists it:

// Build an in-memory model without writing to the database
$model = (new App\Expressive\User([
    'name' => 'Wendell',
    'email' => 'wendell@example.com',
]))->model();

// Persist the model and its supported relationships
$saved = (new App\Expressive\User([
    'name' => 'Wendell',
    'email' => 'wendell@example.com',
]))->save();

The save() method persists the root model along with supported direct relationships, including BelongsTo, HasOne, HasMany, MorphOne, and MorphMany. Both methods respect Eloquent's mass-assignment rules and ignore non-fillable attributes, so persistence flows through Eloquent's standard mechanisms.

#Installation

You can install the package via Composer:

composer require wendelladriel/laravel-expressive

You can then publish the config file:

php artisan vendor:publish --tag="expressive"

The package requires PHP 8.3 or higher and supports Laravel 12 and 13. For more information, you can read the documentation or view the source code on GitHub.