joecianflone / modelproperties
Make the DX of Eloquent Models better
Requires
- php: ^8.2
- crell/attributeutils: ^1.2.0
- illuminate/config: ^11.0|^12.0
- illuminate/contracts: ^11.0|^12.0
Requires (Dev)
- larastan/larastan: ^3.1
- laravel/pint: ^1.13
- nunomaduro/collision: ^8.0
- orchestra/testbench: ^10.0
- pestphp/pest: ^3.7
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0.1
- phpstan/phpstan-phpunit: ^2.0.4
- ramsey/conventional-commits: ^1.5
This package is auto-updated.
Last update: 2025-03-10 10:34:53 UTC
README
As a developer, you may have experienced the cognitive load of dealing with arrays to define various model behaviors in Laravel, such as fillable, guarded, casting, default values, and hidden properties. I found myself wondering if there was a more streamlined way to handle this. What if we could use PHP attributes on the class itself to define these properties? This idea led me to explore this approach, which I share in this video
Support Me
Buy me a coffee or something, but more importantly would be if you used this and like it, if you'd talk about this and also tell me if you have any issues with it.
Installation
composer require joecianflone/modelproperties
Usage
Here's a standard User
model where you've got some fillable fields and a few casts and whatnot:
class User extends Model { protected $fillable = ['name', 'email', 'password', 'role', 'is_active']; protected $hidden = ['password', 'remember_token']; protected $casts = [ 'id' => 'string', 'role' => UserRole::class 'is_active' => 'boolean', 'email_activated_at' => 'datetime', 'remember_token' => 'datetime', 'created_at' => 'datetime', 'updated_at' => 'datetime', ]; protected $attributes = [ 'role' => UserRole::STANDARD 'is_active' => true, ]; }
Again, my gripe here is that it takes a bit of work to understand all the fields this model has. It's pretty easy to miss that the id
is a string if you were looking quickly...and oh crap, I forgot to turn off auto-incrementing did you catch that? How about the fact that the password should be cast and I forgot that one too
So using the model properties it would now look like this:
#[ModelProperties( id: ['string', 'is:primary' 'auto-increment' => false], name: ['string', 'is:fillable'], email: ['string', 'is:fillable'], password: ['hashed', 'is:hidden|fillable'], role: [UserRole::class => UserRole::STANDARD], is_active: ['boolean' => true], remember_token: ['string', 'is:hidden'], email_verified_at: ['datetime'], created_at: ['datetime'], updated_at: ['datetime'], )] class User extends Model { use HasModelProperties; }
That's it. Add the HasModelProperties
trait and you're good to start using the ModelProperties
attribute and have a better DX.
Config Settings
Model properties has a few configurations you can change and they're publishable.
$ php artisan vendor:publish --provider="JoeCianflone\ModelProperties\ModelPropertiesServiceProvider"
Mass Assignment
Turn this off at your own risk! By default, this will set $guarded = ['*']
you should leave it this way.
[ 'mass_assignment_protection' => true, // default ]
Default Mass Assignment Mode
Now if you don't want to set all your properties to either guareded or fillable on all your models you can change this to be either 'guarded' or 'fillable' and then you don't have to worry about being explicit.
NOTE: with mass_assignment_protection
turned on, you really never have to expliclty set something to guarded
they'll really be discarded because $guarded = ['*']
. If you DO turn off mass_assignment_protection
you're going to NEED to set this to guarded or else we'll throw an exception with this set to either 'none' or 'fillable'.
Honestly, think twice before doing that. Your best bet here is to leave mass_assignment_protection set to true and, if anything, set this to fillable. That's basically Laravel's default behavior and setting all the props over to the fillable array.
[ // values could be 'none' | 'fillable' | 'guarded' 'default_property_assignment' => 'none', // default ]
Explicitly Cast Strings
[ 'explicity_cast_strings' => false // default ]
In the above examples, see how how told the model that some properties were strings? You don't actually need to cast strings as strings in laravel, but some people like doing that, so if you'd like to be explicit, set this to true.
How it works
Under the hood, we're not doing too many fancy things. At the end of the day, the attribute will get transformed into a PHP object and we "just use" all the standard Laravel model variables to populate fillable, guarded and whatever else. The only magic here, if there is any, is Laravels own built-in ability to automatically execute a method in a trait.
So what is this doing? Mostly parsing the attributes and dumping them in the right places. It adds no extra cruft to the model and if you were to dd()
a model that uses ModelProperties
and a model that does not, you'd see no difference in the object created.
Testing
This plugin uses Pest for our Unit and Architecture tests, if you'd like to run them yourself you can use...
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.