Download the PHP package kyzegs/laravel-eloquent-embeddables without Composer

Laravel Eloquent Embeddables

Doctrine-like embeddables for Eloquent, built on Laravel's native custom cast system.

Group several plain database columns into a rich PHP value object — no JSON column, no extra table, and no trait required on the parent model.

…while the database keeps ordinary columns:

Mental model

Laravel custom casts, but powerful enough to behave like Doctrine embeddables.

An embeddable owns structure, casting, validation and clean object access. The parent model owns persistence. The embeddable has no table, no identity, and is never saved on its own — it is persisted only through its parent.

Requirements

• PHP 8.2+ (Laravel 13 requires PHP 8.3+)
• Laravel 12 or 13

Installation

Defining an embeddable

Extend EmbeddableModel. It reuses Eloquent's attribute machinery (fillable/guarded, casts, accessors, mutators, hidden, visible, appends, toArray()/toJson(), default attributes) but refuses every persistence and relationship method.

Using it in a parent model

Add the cast to the parent's casts() method. No trait is required.

Zero-config form

The prefix defaults to the cast key + _ (address_), and the columns are discovered by matching that prefix against the parent table's real columns (one cached schema query per table). No columns match, or no connection is available? The map falls back to the embeddable's fillable attributes and cast keys, prefixed.

The full resolution order, most explicit first:

1. An explicit columns map.
2. Explicit attributes, prefixed.
3. Schema discovery: parent table columns matching the prefix.
4. Fallback: the embeddable's fillable attributes + cast keys, prefixed.

If none of these produce a map, an InvalidArgumentException explains exactly what was tried. Combining columns with prefix/attributes throws as well — the forms are mutually exclusive.

Prefix form

Maps:

Explicit column-map form

Working with embeddables

Read like an object:

Assign an array:

Assign an instance:

Mutate in place — changes are synced back to the parent columns on save:

Compare as value objects — equals() is true for the same concrete class with identical attributes, regardless of order:

Nullable embeddables

With nullable: true:

When reading, if all mapped columns are null, the cast returns null instead of an empty embeddable.

Serialization

Use the optional HasEmbeddables trait on the parent to expose a clean nested object in toArray() / toJson(). It appends each embeddable and hides its backing columns:

Without the trait, casts/reads/writes still work — the model just serializes the flat columns instead of a nested object.

Querying

Embeddables are plain columns, so query the parent model normally:

IDE support (laravel-ide-helper)

barryvdh/laravel-ide-helper works out of the box: ide-helper:models resolves the cast through EmbeddableCast::get() and annotates every embeddable as the generic EmbeddableModel|null.

For the concrete class and correct nullability, register the shipped model hook in config/ide-helper.php:

ide-helper:models then generates:

The |null is only added when the cast is nullable. (The write side also accepts an attribute array or null; the generated single-type @property favors the concrete class.)

The hook also types the embeddable classes themselves. An embeddable has no table to introspect, so the hook finds a parent model embedding it (scanning ide-helper's model_locations), maps each attribute to its backing parent column, and derives the type from the embeddable's own cast or the column's schema type:

Make sure both the parent models and the embeddable classes live in directories covered by model_locations in config/ide-helper.php. When several parents embed the same class, their column maps are merged; the first parent to supply an attribute wins.

What is not supported

An embeddable is not a full Eloquent model. Every persistence method (save, saveOrFail, update, delete, forceDelete, push, refresh, fresh, touch, increment, decrement and their quiet variants) and every relationship method (hasOne, hasMany, hasOneThrough, hasManyThrough, through, belongsTo, belongsToMany, morphOne, morphMany, morphTo, morphToMany, morphedByMany) throws an EmbeddableException:

Embeddables are persisted through their parent Eloquent model. Call save() on the parent model instead.

Embeddables do not participate in relationships. Define the relationship on the parent Eloquent model instead.

How it works

EmbeddableCast::using() returns an encoded Castable definition, so Laravel's native cast resolver builds the configured cast. The attribute => column map is resolved lazily on first use, following the resolution order above. On the cast:

1. get() reads the mapped parent columns and hydrates an embeddable (its own casts apply).
2. set() flattens an array / instance / null back into the mapped columns.
3. Because Eloquent re-invokes set() for cached cast objects during save(), direct mutations are synced to the parent automatically.
4. serialize() renders the embeddable as a nested array for toArray()/toJson().

Testing

License

MIT.