|
| 1 | +--- |
| 2 | +slug: 2023/enhanced-resources-for-laravel |
| 3 | +title: Enhanced Resources for Laravel |
| 4 | +authors: [connort, jasonj] |
| 5 | +tags: [php, resources, fractal, responses, laravel] |
| 6 | +--- |
| 7 | + |
| 8 | +Developing an API was a common task for engineers working with Laravel in the early days of the framework. Prior to version 5.5 Laravel did not offer an elegant way to format/prepare API responses. Historically, it worked by calling `toArray()` on your model instance. |
| 9 | + |
| 10 | +This pattern of calling `toArray()` risked the possibility of exposing attributes that should not be exposed over an API. As a result, it was common to use the `$hidden` property to exclude the specified attributes during serialization which was helpful in building an API response as both a mechanism to avoid exposing sensitive data and more generally controlling which data would be included. The example shown below was a common pattern prior to Laravel 5.5. |
| 11 | + |
| 12 | +```php |
| 13 | +<?php |
| 14 | + |
| 15 | +class User extends Eloquent { |
| 16 | + protected $hidden = ['password', 'remember_token']; |
| 17 | +} |
| 18 | + |
| 19 | +// Usage |
| 20 | +$user = User::find(1); |
| 21 | +$user->toArray(); |
| 22 | +// Returns: ['name' => 'John', 'email' => ' [email protected]'] |
| 23 | +``` |
| 24 | + |
| 25 | +This approach was flexible, but any change to your database schema resulted in those changes appearing in your API. We needed something more concrete and landed on [Fractal](https://fractal.thephpleague.com) which served us well until Laravel added [official support](https://laravel.com/docs/5.5/releases) for API Resources, and thus we worked on an enhancement for that feature. |
| 26 | + |
| 27 | +{/* truncate */} |
| 28 | + |
| 29 | +A stock installation of Laravel leveraging API resources may have a class similar to the one shown below. |
| 30 | + |
| 31 | +```php |
| 32 | +<?php |
| 33 | + |
| 34 | +class UserResource extends JsonResource |
| 35 | +{ |
| 36 | + public function toArray(Request $request): array |
| 37 | + { |
| 38 | + return [ |
| 39 | + 'id' => $this->id, |
| 40 | + 'name' => $this->name, |
| 41 | + 'email' => $this->email, |
| 42 | + 'created_at' => $this->created_at, |
| 43 | + 'updated_at' => $this->updated_at, |
| 44 | + ]; |
| 45 | + } |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +A common complaint we had was that an entity (in this case a User) may have a different responses depending on the permissions of the user making the request. An admin may see more information about a user than a support user, or staff member. Laravel offered conditional attributes we could leverage, but those exploded in complexity pretty quickly when balancing many roles and many conditional attributes. |
| 50 | + |
| 51 | +So we built [Enhanced Resources](https://github.com/sourcetoad/enhanced-resources) to make this is a bit easier. |
| 52 | + |
| 53 | +```php |
| 54 | +<?php |
| 55 | + |
| 56 | +use Sourcetoad\EnhancedResources\Formatting\Attributes\Format; |
| 57 | +use Sourcetoad\EnhancedResources\Formatting\Attributes\IsDefault; |
| 58 | +use Sourcetoad\EnhancedResources\Resource; |
| 59 | + |
| 60 | +class QuestionResource extends Resource |
| 61 | +{ |
| 62 | + #[IsDefault, Format] |
| 63 | + public function base(): array |
| 64 | + { |
| 65 | + return [ |
| 66 | + 'type' => $this->type, |
| 67 | + 'text' => $this->text, |
| 68 | + 'answers' => $this->answers, |
| 69 | + ]; |
| 70 | + } |
| 71 | + |
| 72 | + #[Format] |
| 73 | + public function teacher(): array |
| 74 | + { |
| 75 | + $data = $this->base(); |
| 76 | + $data['correct_answer'] = $this->correct_answer; |
| 77 | + |
| 78 | + return $data; |
| 79 | + } |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +In this example we had a format that was the default (or `base`) for usage of the Question model. This example reflected a question schema which may have a question type, the question itself and any possible answers. We know students shouldn't have the answers, but the teacher should. We can easily assume the properties of the base resource and add on multiple conditional properties. |
| 84 | + |
| 85 | +Over time, we found this package to excel when formatting data differently depending on the permissions/roles of the requesting user. In addition to the structured approach that the Resource file had we also supported a variety of mutations directly on the resource. |
| 86 | + |
| 87 | +* `modify` - Change a key/value. |
| 88 | +* `except` - Exclude specific keys. |
| 89 | +* `only` - Include specific keys only. |
| 90 | + |
| 91 | +This meant we could quickly apply a change if needed without adapting the resource file. We could also apply an attribute directly to the model to bind it to the corresponding Resource that represented it. |
| 92 | + |
| 93 | +```php |
| 94 | +use Illuminate\Database\Eloquent\Model; |
| 95 | +use Sourcetoad\EnhancedResources\Resourceable\AsResource; |
| 96 | +use Sourcetoad\EnhancedResources\Resourceable\ConvertsToResource; |
| 97 | + |
| 98 | +/** |
| 99 | + * @method ExampleResource toResource() |
| 100 | + */ |
| 101 | +#[AsResource(ExampleResource::class)] |
| 102 | +class Example extends Model |
| 103 | +{ |
| 104 | + use ConvertsToResource; |
| 105 | +} |
| 106 | + |
| 107 | +(new Example)->toResource(); |
| 108 | +``` |
| 109 | + |
| 110 | +Enhanced Resources has been around since 2019 and is still in use to this day. |
| 111 | + |
| 112 | +* [GitHub Repo](https://github.com/sourcetoad/enhanced-resources) |
| 113 | +* [Packagist](https://packagist.org/packages/sourcetoad/enhanced-resources) |
0 commit comments