https://github.com/culturegr/presenter
Eloquent Model Presenters for your Laravel app
https://github.com/culturegr/presenter
decorators laravel php presenters
Last synced: 6 months ago
JSON representation
Eloquent Model Presenters for your Laravel app
- Host: GitHub
- URL: https://github.com/culturegr/presenter
- Owner: culturegr
- License: other
- Created: 2019-11-12T07:32:11.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-04-10T07:21:08.000Z (about 1 year ago)
- Last Synced: 2025-09-24T04:14:20.398Z (9 months ago)
- Topics: decorators, laravel, php, presenters
- Language: PHP
- Homepage:
- Size: 45.9 KB
- Stars: 14
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 🏺 Presenter
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Total Downloads][ico-downloads]][link-downloads]
This package provides an easy way to create Presenters that can be used to [decorate](https://en.wikipedia.org/wiki/Decorator_pattern) an Eloquent Model. It is heavily inspired by [Hemp Presenter](https://github.com/davidhemphill/presenter) and [Laravel API Resources](https://laravel.com/docs/6.x/eloquent-resources), however it comes with some key differences:
- It provides an easy way to handle *paginated* models
- It does not focus solely in JSON API responses but it serves as a *general purpose* decorator that can be used anywhere in the project
## TL;DR
A **Decorator** is an object that wraps another object in order to add functionality to the wrapped object. It also delegates calls to methods not available on the decorator to the class being decorated. Decorators can be useful when you need to modify the functionality of a class without relying on inheritance. You can use it to add optional features to your objects like logging, access-control, and things of that sort. A **Presenter** is a type of decorator used to present an object to the view of an application, such as a Blade view, or an API response.
## Installation
Via [Composer](https://getcomposer.org):
``` bash
$ composer require culturegr/presenter
```
In Laravel 5.5+, the package's service provider should be [auto-discovered](https://laravel.com/docs/5.7/packages#package-discovery), so you won't need to register it. If for some reason you need to register it manually you can do so by adding it to the providers array in `config/app.php`:
```php
'providers' => [
// ...
CultureGr\Presenter\PresenterServiceProvider::class,
],
```
## Usage
### Creating Presenter Classes
A Presenter class can be generated by running the `make:presenter` Artisan command:
```bash
php artisan make:presenter UserPresenter
```
This will generate an empty `Presenter` class inside of `app/Presenters`
### Customizing Presenter Classes
Presenters are simple classes designed to encapsulate complex or repetitive view logic. For example, here is a simple `UserPresenter` class:
```php
firstname.' '.$this->lastname;
}
}
```
Note that the original model's properties (`firstname`, `lastname`) can be directly accessed using the `$this` variable. This is because the `Presenter` class automatically proxies property and method access down to the underlying model.
This class has a custom method `fullname` that can be called wherever an instance of this Presenter is used.
```php
$presentedUser->firstname; //=> 'John'
$presentedUser->lastname; //=> 'Doe'
$presentedUser->fullname() //=> 'John Doe'
```
The Presenter class requires you to implement an abstract `toArray` method which returns the array of attributes that should be used when the presenter is converted to an array or JSON. This ensures consistent behavior across all presenter classes.
```php
firstname.' '.$this->lastname;
}
public function toArray()
{
return [
'id' => $this->id,
'fullname' => $this->fullname()
// ...
];
}
}
```
### Presenting Single Models
Once the presenter is defined, it may be used to create a presented model using the `make` factory method:
```php
$user = User::first();
$presentedUser = UserPresenter::make($user);
```
The presented model may be used anywhere in the project and can be passed to views, returned from controllers, or returned from API routes. Presenters implement `Arrayable`, `Jsonable`, `JsonSerializable`, and `ArrayAccess` interfaces, which means they can be:
- Automatically converted to arrays when needed (no need to call `toArray()` explicitly)
- Automatically converted to JSON when returned from routes (no need to call `toJson()` explicitly)
- Accessed like arrays using square bracket notation (e.g., `$presenter['key']`)
```php
UserPresenter::make(User::find($id))
]);
}
}
```
### Presenting Collections
To present a collection of models, the static `collection` method on the Presenter class can be used:
```php
$users = User::all();
$presentedUsers = UserPresenter::collection($users);
```
The collection of presented models may be used anywhere in the project. Thanks to the automatic conversion features, the collection can be directly returned from a route or controller without explicitly calling `toArray()`:
```php
present(UserPresenter::class);
```
This allows for a more fluent syntax when presenting models:
```php
$presentedUser = User::first()->present(UserPresenter::class);
```
For collections, you can use the `presentCollection` method directly on the collection:
```php
$users = User::all();
$presentedUsers = $users->presentCollection(UserPresenter::class);
```
This is equivalent to using the static `collection` method on the Presenter class, but provides a more fluent API.
You can also use the `presentCollection` method directly on a paginator instance:
```php
$users = User::paginate();
$presentedUsers = $users->presentCollection(UserPresenter::class);
```
When used on a paginator, the `presentCollection` method automatically detects that it's being called on a paginator and returns a structured result with the presented models wrapped in a `data` key, along with `links` and `meta` keys containing pagination information.
### Automatic Array and JSON Conversion
Presenters now implement the necessary interfaces to be automatically converted to arrays or JSON when needed:
- `Arrayable`: Allows automatic conversion to arrays
- `Jsonable`: Allows automatic conversion to JSON strings
- `JsonSerializable`: Ensures proper JSON serialization
- `ArrayAccess`: Allows accessing presenters like arrays using square bracket notation
This means you no longer need to explicitly call `toArray()` or `toJson()` in most contexts:
```php
// Before
$array = $presenter->toArray();
$json = $presenter->toJson();
// Now - automatic conversion happens when needed
$array = $presenter; // Automatic conversion to array
$json = json_encode($presenter); // Automatic conversion to JSON
return $presenter; // Automatic conversion when returned from routes
```
### Array Access Support
Presenters can now be accessed like arrays:
```php
$presenter = UserPresenter::make($user);
$id = $presenter['id']; // Same as $presenter->id
```
### Abstract toArray Method
The `toArray()` method is now abstract, which means all presenter classes must implement it. This ensures consistent behavior across all presenters.
### Note for Existing Users
If you're currently calling `toArray()` explicitly when using Presenters (e.g., `UserPresenter::make($user)->toArray()`), please note that these calls will continue to work as before. However, they are no longer necessary in most contexts due to the new automatic conversion feature. You can safely remove these explicit calls if desired, which will make your code cleaner and more concise.
## Testing
``` bash
$ composer test
```
## License
Please see the [license file](LICENSE.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/culturegr/presenter.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/culturegr/presenter.svg?style=flat-square
[ico-travis]: https://img.shields.io/travis/culturegr/presenter/master.svg?style=flat-square
[link-packagist]: https://packagist.org/packages/culturegr/presenter
[link-downloads]: https://packagist.org/packages/culturegr/presenter
[link-travis]: https://travis-ci.org/culturegr/presenter
## Credits
* Huge shout out to [David Hemphill](https://github.com/davidhemphill)
* Awesome Laravel/PHP community