Skip to content

Commit d185dde

Browse files
committed
Appropriate naming for custom cast classes and README.md updated
1 parent 9384775 commit d185dde

File tree

6 files changed

+55
-32
lines changed

6 files changed

+55
-32
lines changed

README.md

Lines changed: 43 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,11 @@
55
[![Stable](https://poser.pugx.org/movor/laravel-custom-casts/v/stable)](https://packagist.org/packages/movor/laravel-custom-casts)
66
[![License](https://poser.pugx.org/movor/laravel-custom-casts/license)](https://packagist.org/packages/movor/laravel-custom-casts)
77

8-
By default, from version 5 Laravel supports attribute casting. If we define cast property on our model, Laravel will help us convert defined attributes to common data types. Currently supported cast types (Laravel 5.6) are: integer, real, float, double, string, boolean, object, array,
9-
collection,date, datetime and timestamp.
8+
By default, from version 5 Laravel supports attribute casting. If we define cast property on our model, Laravel will
9+
help us convert defined attributes to common data types. Currently supported cast types (Laravel 5.6) are: `integer`,
10+
`real`, `float`, `double`, `string`, `boolean`, `object`, `array`, `collection`, `date`, `datetime` and `timestamp`.
1011

11-
If those default cast types are not enough and you want to make your own, this Laravel package is here to help you accomplish that.
12+
If those default cast types are not enough and you want to make your own, this Laravel package is here to help.
1213

1314
---
1415

@@ -26,43 +27,59 @@ composer require movor/laravel-custom-casts
2627

2728
## Example: Casting User Image
2829

29-
Let's use default Laravel user model found in `app/User.php`.
30+
When saving an image, there is two things that needs to be done:
31+
1. Save image name (sometimes with path) into corresponding database field
32+
2. Save image physically on the disk
3033

31-
Beside basic, predefined fields: `name`, `email` and `password`, we also want to allow user to upload his avatar. Assume that we already have users table with `image` field (you should create seeder for this).
34+
As a guidance for this example we'll use default Laravel user model found in `app/User.php`.
35+
36+
Beside basic, predefined fields: `name`, `email` and `password`, we also want to allow user to upload his avatar. Assume
37+
that we already have `users` table with `image` field (you should create seeder for this).
3238

3339
To utilize custom casts, we'll need to add trait to user model, and via `$casts` property link it to the cast class.
3440

3541
```php
3642
// File: app/User.php
3743

44+
namespace App;
45+
3846
use App\CustomCasts\ImageCast;
47+
use Illuminate\Foundation\Auth\User as Authenticatable;
48+
use Illuminate\Notifications\Notifiable;
49+
use Movor\LaravelCustomCasts\HasCustomCasts;
3950

40-
// ...
51+
class User extends Authenticatable
52+
{
53+
use Notifiable, HasCustomCasts;
4154

42-
protected $fillable = [
43-
'name', 'email', 'password',
44-
// We need to add "image" as well:
45-
'image'
46-
];
55+
protected $fillable = [
56+
'name', 'email', 'password', 'image'
57+
];
4758

48-
protected $casts = [
49-
'image' => ImageCast::class
50-
];
59+
protected $hidden = [
60+
'password', 'remember_token'
61+
];
62+
63+
protected $casts = [
64+
'image' => ImageCast::class
65+
];
66+
}
5167

5268
// ...
5369
```
5470

55-
Next step is to create class that'll handle casting. It must implement "setAttribute" method which will take care of saving the image (from UploadedFile object) and generating image name with path - to be preserved in db.
71+
Next step is to create class that'll handle casting. It must implement `setAttribute` method which will take care of
72+
saving the image (from UploadedFile object) and generating image name with path - to be preserved in database.
5673

5774
```php
5875
// File: app/CustomCasts/ImageCast.php
5976

6077
namespace App\CustomCasts;
6178

62-
use Movor\LaravelCustomCasts\CustomCastableBase;
79+
use Movor\LaravelCustomCasts\CustomCastBase;
6380
use Illuminate\Http\UploadedFile;
6481

65-
class ImageCast extends CustomCastableBase
82+
class ImageCast extends CustomCastBase
6683
{
6784
public function setAttribute($file)
6885
{
@@ -85,7 +102,10 @@ class ImageCast extends CustomCastableBase
85102

86103
Let's jump to user creation example. This will trigger our custom cast logic.
87104

88-
Assume that we have user controller which will handle user creation.
105+
Assume that we have user controller which will handle user creation. You should create this on your
106+
own.
107+
108+
> Code below is just a simple example and should be used as guidance only.
89109
90110
```php
91111
// File: app/Http/Controllers/UserController.php
@@ -110,14 +130,17 @@ protected function create(Request $request)
110130
Ok, now we have our user created and image stored.
111131

112132
But we should also handle deleting image when user is deleted. This can be accomplished by utilizing underlying eloquent
113-
events handling. Each time eloquent event is fired, it'll look up for public method with the same name in our custom cast class.
133+
events handling. Each time eloquent event is fired, logic will look up for public method with the same name in our custom
134+
cast class.
114135

115136
Possible method names are:
116-
`retrieved`, `creating`, `created`, `updating`, `updated`, `saving`, `saved`, `deleting`, `deleted`, `restoring`, `restored`.
137+
`retrieved`, `creating`, `created`, `updating`, `updated`, `saving`, `saved`, `deleting`, `deleted`, `restoring`,
138+
`restored`.
117139

118140
```php
119141
// File: app/CustomCasts/ImageCast.php
120142

143+
// Add at the top
121144
use Storage;
122145

123146
// ...

src/package/CustomCastableBase.php renamed to src/package/CustomCastBase.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
use Illuminate\Database\Eloquent\Model;
66

7-
abstract class CustomCastableBase
7+
abstract class CustomCastBase
88
{
99
/**
1010
* Model

src/package/CustomCastableTrait.php renamed to src/package/HasCustomCasts.php

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
namespace Movor\LaravelCustomCasts;
44

5-
trait CustomCastableTrait
5+
trait HasCustomCasts
66
{
77
/**
88
* Each field which is going to be custom casted
@@ -15,7 +15,7 @@ trait CustomCastableTrait
1515
/**
1616
* Boot trait
1717
*/
18-
public static function bootCustomCastableTrait()
18+
public static function bootHasCustomCasts()
1919
{
2020
// Enable custom cast classes to listen to model events
2121
\Event::listen('eloquent.*: ' . get_called_class(), function ($event, $data) {
@@ -56,7 +56,7 @@ public function setAttribute($attribute, $value)
5656
}
5757

5858
if (array_key_exists($attribute, $this->filterCustomCasts())) {
59-
/** @var $customCastObject CustomCastableBase */
59+
/** @var $customCastObject CustomCastBase */
6060
$customCastObject = $this->getCustomCastObject($attribute);
6161

6262
$this->attributes[$attribute] = $customCastObject->setAttribute($value);
@@ -92,7 +92,7 @@ protected function castAttribute($attribute, $value)
9292
*
9393
* @param $attribute
9494
*
95-
* @return CustomCastableBase
95+
* @return CustomCastBase
9696
*/
9797
protected function getCustomCastObject($attribute)
9898
{
@@ -117,7 +117,7 @@ protected function filterCustomCasts()
117117
{
118118
$customCasts = [];
119119
foreach ($this->casts as $attribute => $castClass) {
120-
if (is_subclass_of($castClass, CustomCastableBase::class)) {
120+
if (is_subclass_of($castClass, CustomCastBase::class)) {
121121
$customCasts[$attribute] = $castClass;
122122
}
123123
}

tests/Support/CustomCasts/Base64ImageCast.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
namespace Movor\LaravelCustomCasts\Test\Support\CustomCasts;
44

5-
use Movor\LaravelCustomCasts\CustomCastableBase;
5+
use Movor\LaravelCustomCasts\CustomCastBase;
66

7-
class Base64ImageCast extends CustomCastableBase
7+
class Base64ImageCast extends CustomCastBase
88
{
99
/**
1010
* This array will be filled with all events called on related model

tests/Support/CustomCasts/PrefixNameCast.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
namespace Movor\LaravelCustomCasts\Test\Support\CustomCasts;
44

5-
use Movor\LaravelCustomCasts\CustomCastableBase;
5+
use Movor\LaravelCustomCasts\CustomCastBase;
66

7-
class PrefixNameCast extends CustomCastableBase
7+
class PrefixNameCast extends CustomCastBase
88
{
99
public function setAttribute($value)
1010
{

tests/Support/Models/Image.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
namespace Movor\LaravelCustomCasts\Test\Support\Models;
44

55
use Illuminate\Database\Eloquent\Model;
6-
use Movor\LaravelCustomCasts\CustomCastableTrait;
6+
use Movor\LaravelCustomCasts\HasCustomCasts;
77
use Movor\LaravelCustomCasts\Test\Support\CustomCasts\Base64ImageCast;
88

99
class Image extends Model
1010
{
11-
use CustomCastableTrait;
11+
use HasCustomCasts;
1212

1313
protected $guarded = [];
1414
protected $table = 'images';

0 commit comments

Comments
 (0)