Laravel Custom Casts
Make your own cast type for Laravel model attributes
Laravel custom casts works similarly to Eloquent attribute casting, but with custom-defined logic (in a separate class). This means we can use the same casting logic across multiple models — we might write image upload logic and use it everywhere. In addition to casting to custom types, this package allows custom casts to listen and react to underlying model events.
Let's review some Laravel common cast types and examples of their usage:
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
protected $casts = [
'is_admin' => 'boolean',
'login_count' => 'integer'
'height' => 'decimal:2'
];
}
In addition to boolean, integer, and decimal, out of the box Laravel supports real, float, double, string, object, array, collection, date, datetime, and timestamp casts.
Sometimes it is convenient to handle more complex types with custom logic, and for casts to be able to listen and react to model events. This is where this package come in handy.
Handling events directly from custom casts can be very useful if, for example, we're storing an image using a custom casts and we need to delete it when the model is deleted. Check out the old documentation for this example.
📦
vkovic packages
📦
Please check out my other packages — they are all free, well-written, and some of them are useful
- vkovic/laravel-commando ~ Collection of useful
artisancommands - Coming soon vkovic/laravel-event-log ~ Easily log and access logged events, optionally with additional data and the related model
Compatibility
The package is compatible with Laravel versions 5.5, 5.6, 5.7, 5.8 and 6
and Lumen versions 5.5, 5.6, 5.7, 5.8.
Minimum supported version of PHP is 7.1. PHP 8 is also supported.
Installation
Install the package via Composer:
composer require vkovic/laravel-custom-casts
Usage
Utilizing a custom cast class
To enable custom casts in a model, use the HasCustomCasts trait and define which attributes will be casted using $casts - per Laravel standards.
// File: app/User.php
namespace App;
use App\CustomCasts\NameCast;
use Illuminate\Database\Eloquent\Model;
use Vkovic\LaravelCustomCasts\HasCustomCasts;
class User extends Model
{
use HasCustomCasts;
protected $casts = [
'is_admin' => 'boolean', // <-- Laravel default cast type
'name' => NameCast::class // <-- Our custom cast class (see the section below)
];
}
Defining a custom cast class
This class will be responsible for our custom casting logic.
// File: app/CustomCasts/NameCast.php
namespace App\CustomCasts;
use Vkovic\LaravelCustomCasts\CustomCastBase;
class NameCast extends CustomCastBase
{
public function setAttribute($value)
{
return ucwords($value);
}
public function castAttribute($value)
{
return $this->getTitle() . ' ' . $value;
}
protected function getTitle()
{
return ['Mr.', 'Mrs.', 'Ms.', 'Miss'][rand(0, 3)];
}
}
The required setAttribute method receives the $value being set on the model field, and should return a raw value to store in the database.
The optional castAttribute method receives the raw $value from the database, and should return a mutated value. If this method is omitted, the raw database value will be returned.
For the sake of this example we'll implement one more method which will attach a random title to a user when their name is retrieved from database.
Testing a custom cast class
Let's create a user and see what happens.
$user = new App\User;
$user->name = 'john doe';
$user->save();
This will create our new user and store their name in the database, with the first letter of each word uppercased.
When we retrieve the user and try to access their name, title will be prepended to it — just like we defined in our custom NameCast class.
dd($user->name); // 'Mr. John Doe'
Handling model events
Let's say that we want to notify our administrator when a user's name changes.
// File: app/CustomCasts/NameCast.php
public function updated()
{
$attribute = $this->attribute;
if($this->model->isDirty($attribute)) {
// Notify admin about name change
}
}
In addition to the updated method, we can define other methods for standard model events: retrieved, creating, created, updating, saving, saved, deleting, deleted, restoring and restored.
Other functionality
As you can see from the above code, we can easily access the casted attribute name as well as an instance of the underlying model.
// File: app/CustomCasts/NameCast.php
// Get the name of the model attribute being casted
dd($this->attribute); // 'name'
// Access our `User` model
dd(get_class($this->model)); // 'App/User'
We can also retrieve all casted attributes and their corresponding classes directly from the model.
// File: app/User.php
dd($this->getCustomCasts()); // ['name' => 'App/CustomCasts/NameCast']
Using aliased casts
You may find it easier to use aliases for custom casts, e.g.:
protected $casts = [
'avatar' => 'image' // <-- You prefer this ...
// ---
'avatar' => ImageCast::class // <-- ... over this
];
To make the magic happen, first add the package's service provider to the providers array:
// File: config/app.php
'providers' => [
// ...
/*
* Package Service Providers...
*/
Vkovic\LaravelCustomCasts\CustomCastsServiceProvider::class
// ...
]
Once the provider is added, publish the config file which will be used to associate aliases with their corresponding custom cast classes:
php artisan vendor:publish --provider="Vkovic\LaravelCustomCasts\CustomCastsServiceProvider"
This command should create a config file located at config/custom_casts.php. Open it up and check out the comments for examples of config options.
Use it without Laravel
This package can also be used without full Laravel installation, with something like jenssegers/model or if your project is using illuminate/database library.
More examples
You can find more examples in the old documentation.
Contributing
If you plan to modify this Laravel package you should run the tests that come with it. The easiest way to accomplish this is with Docker, docker-compose, and phpunit.
First, we need to initialize Docker container (see docker-composer.yaml for details).
docker-compose up --exit-code-from app
After that, we can run tests and watch the output:
docker-compose run --rm app phpunit
15 Oct 29, 2022
58 Oct 1, 2022
2 Jun 15, 2022
68 Aug 11, 2022
88 Dec 31, 2022
996 Dec 28, 2022
66 Sep 19, 2022
337 Dec 28, 2022
2 Aug 23, 2022
142 Sep 14, 2022
13 Oct 7, 2022
4 Sep 15, 2022
83 Dec 17, 2022
27 Nov 20, 2022
33 Nov 6, 2022
7 Nov 15, 2022
2 Oct 2, 2022