Opt-in typed model attributes with real PHP properties (#[Column])

[clementbirkle]

Eloquent attributes are invisible to the language. A model's columns and their types live in @property docblocks, written by hand or generated by tools like laravel-ide-helper. Docblocks drift from the schema, need a generation step, and are the only type information IDEs, PHPStan and AI coding agents get about a model. Agents in particular read the class file and little else, so what is missing from the class is missing for them.

I would like to propose an opt-in way to declare attributes as real typed properties, without changing how Eloquent works:

class Invoice extends Model
{
    use HasDeclaredAttributes;

    #[Column] public int $id;
    #[Column] public string $reference;
    #[Column] public CarbonInterface $issuedAt;  // 'immutable_datetime' cast still applies
    #[Column] public InvoiceStatus $status;      // enum cast still applies
}

How it works. Eloquent already calls initialize{Trait}() on every instantiation. The trait unset()s the properties marked with #[Column]. PHP then routes access to those properties back to __get/__set, so casts, accessors, mutators and dirty tracking behave exactly as before. It uses plain unset(), no PHP 8.4 features (I only tested on 8.5). The whole trait is small:

trait HasDeclaredAttributes
{
    private static array $declaredAttributeNames = [];

    public function initializeHasDeclaredAttributes(): void
    {
        foreach (self::declaredAttributeNames() as $name) {
            unset($this->{$name});
        }
    }

    private static function declaredAttributeNames(): array
    {
        return self::$declaredAttributeNames[static::class] ??= array_values(array_map(
            fn (ReflectionProperty $p): string => $p->getName(),
            array_filter(
                (new ReflectionClass(static::class))->getProperties(ReflectionProperty::IS_PUBLIC),
                fn (ReflectionProperty $p): bool => ! $p->isStatic()
                    && $p->getAttributes(Column::class) !== [],
            ),
        ));
    }
}

What I checked (Pest, against Laravel 13):

• reads and writes go through casts, accessors and mutators; isDirty() and getChanges() are correct
• fill(), isset(), toArray(), create/find/save against a real database
• clone, replicate(), serialize/unserialize
• reading a column that was not selected still throws MissingAttributeException
• PHPStan sees the declared types, and reports a wrong write such as $invoice->id = 'abc'

Cost. Measured on 20,000 hydrated models (PHP 8.5, median of 7 runs, newFromBuilder only, no SQL): about +0.3 µs per model (+6%) with 6 declared columns, +0.4 µs with 25. Attribute reads and writes take the same path as today, and memory per model is unchanged.

Limits. There is no runtime TypeError when writing a wrong type; static analysis catches it, the framework does not. The declared type also has to match what the cast returns, which is up to the developer.

Compatibility. Models that do not use the trait are untouched, so this could ship in a minor release.

Tooling. Today this information is rebuilt outside the class: laravel-ide-helper writes @property docblocks (or a _ide_helper_models.php stub file), and editor tooling inspects the schema at runtime. With declared properties the class itself is the source of truth, so these tools could read it directly. They would remain needed for models that have not opted in, and for relations, scopes and facades.

This also fits the direction of the recent attributes (#[Fillable], #[Hidden], #[Table]). Related requests (#32459, laravel/ideas#2240) asked for native properties on Model itself, which is a much bigger change. This is a narrower and additive take on the same need.

I would be glad to send a PR against 13.x if there is interest. Open questions I would value input on: whether this belongs in the framework or in a package, whether #[Column] is the right name, and whether an artisan command to generate the declarations from the schema would be welcome.

[shaedrich]

This looks like what Doctrine ORM does and is fundamentally what Eloquent does, so I doubt, it will be adopted in this form.

However, I also always felt, that this wasn't ideal.

This also fits the direction of the recent attributes (#[Fillable], #[Hidden], #[Table]). Related requests (#32459, laravel/ideas#2240) asked for native properties on Model itself, which is a much bigger change. This is a narrower and additive take on the same need.

Following this example, the attributes are declared on the class, not the property, so if it would be implemented, it would probably look more like this:

#[Column(name: 'name', fillable: true, …)]
class User extends Model
{

}

So, this could be utilized, but it won't result in auto-completion and such.

[clementbirkle]

Thanks for the feedback. You're right that Doctrine's mapping looks similar. The difference is that this keeps Eloquent's $attributes model as is, and only adds a typed declaration on top.

I put the marker on the property because that is the only way to get a native type. A class-level attribute can't declare a property, so editors, PHPStan and AI agents would still see nothing. A property-level marker also keeps the opt-in explicit: Model already has public properties that are not columns ($timestamps, $incrementing), and models often redeclare them, so "every public property" can't be assumed to be an attribute.

Grouping the metadata is a fair idea. #[Fillable] and #[Hidden] could also target a property, so #[Column, Hidden] public string $password; would work. I kept #[Column] as a bare marker to keep the first step small, but I'm open to that as a follow-up if it fits the direction of the other attributes.

[shaedrich]

I understand your logic. But I don't see this happen as Eloquent is intentionally designed to work not like Doctrine. All model real properties are "config" values and that probably won't change as well as all model columns being purely "virtual", meaning having getters defined for shortcuts to $attributes. I really don't see Taylor wanting to change what Eloquent is at its core. That's all I'm saying.

PHPStan and AI agents would still see nothing

Yes and no. They won't natively see anything but attributes aren't private. They can be accessed. Even without parsing a PHPDoc block text. That might be the best we can get.

[clementbirkle]

Thanks, that's a fair concern. One clarification: the attributes stay virtual with this. The declared properties are unset on instantiation, so $attributes, casts and accessors behave exactly as today. It only gives them a declaration that the class carries itself, rather than a generated PHPDoc block that can drift from the schema. Happy to leave it there and see what the maintainers think.