Download the PHP package thepublicgood/is-presentable without Composer

IsPresentable for Laravel

IsPresentable is a simple package to help you format you Laravel model's data so that it's presentable in your views. For example, if you needed to print the creation date of a model in a Blade view, and you wrote:

You'd get HTML output that looks a little this this:

That's fine, but it's not great. What if you wanted to format it? Well, you could do this:

Laravel automatically hands the created_at timestamp to Carbon so this actually works nicely. But what if you need to use the same format in a whole lot of places. Now it gets frustrating. You could create a model accessor, which would work just fine, but then it feels like it's litering up your model with presentation data. And do you add the same accessor to all your models? This is where IsPresentable comes in.

Installation

As always, install into your Laravel app using Composer:

Usage

Version 2 brings a whole new approach to adding presentables to your models. The old version 1 way of using presentable methods still works fine and is backward compatible.

Using presentable classes

First add the IsPresentable trait to your model class:

Now create a new presentable class for the attribute you'd like to present. Make sure to extend the Presentable abstract class. The model you are presenting will be injected as a $model class property so you can reference it with $this->model. Here's a simple CreatedAtPresentable class:

Now you can assign this presentable class to the attribute name in your model's $presentables array:

So now, in your Blade view file, you can do this:

No more calls to format in your views.

It can be really useful to create presentables as classes like this as they are reusable. A created_at column is fairly standard on Laravel models, so you can use the same class to format that data on any model. No need to write another presentable for each model. Just add it to the $presentables array wherever you need it.

Using presentable methods

If you don't want/need to create presentable classes, or you're adding just one presenter to a model that will not be used elsewhere, you can create simple "accessor" methods directly on the model class by prefixing them with the word presentable. As an example, a User might need a username that is calculated on the fly. We can write a "presentable" method on the model class like this:

To make this a little neater, you could create traits for your presentable methods and include the IsPresentable trait inside your OWN traits:

Then in your User model class, use just the UserPresenter trait:

This allows for a bit of reusability as these traits can also be used by multiple models.

Using with JavaScript

The IsPresentable trait will extend the toArray() method and add the rendered data to the result. This is useful if you need to access your presenters in a JavaScript front-end. A presentable child array containing all the formatted data will be added to the resulting array. For example, $user->toArray() would result in something like:

If you're using a front-end framework like Vue, and the array gets cast as a JSON object, then you could get to the same formatted created_at property like this:

Advanced uses

Hiding presenters

If for whatever reason you don't want to include presented data when the model is cast to an array, you can implement the IsHidden interface in your presentable class to hide that data:

You'll still have access to the presentable in your Laravel app through the presentable() method, but it will no longer show up when the model is cast to an array.

Accessing the attribute name

The presenter class has access to the attribute name that you set as the key in your $presentables array. For example, you could have the following presentables set up on your User model class:

Instead of creating two separate presentable classes for each attribute, we can access the name of the attribute we're presenting via $this->attribute in the presentable class:

This can be very useful if we need to display ALL dates and times in a consistent way.

Passing data into presenters

Using presentable classes, it's possible to pass arbitrary data in, which can be used to alter how the presentable reacts. You can do this by making a small change to the $presentables attribute on the model class. Instead of passing a string class path, you can pass a simple array with the first element being the class path and the second being the data you want to pass in:

In your presenter class, the second element can be accessed with $this->option:

Options don't have to be strings, you could pass an array of options:

This gives you quite a lot of power over how the models attributes could be presented.

You can also move this entire configuration into a getPresentables method if you don't wish to use the $presentables array:

Default presentables

Sometimes it can be useful to specify a default set of presentable classes that will be automatically used for all model classes that use the IsPresentable trait. You can add defaults into the presentable.php configuration file. First, publish the configutation file using Artisan:

Now you can add your default presentable classes to the default array. You are free to use all the same functionality as if you were adding them directly to model classes:

You don't need to add anything to your $presentables array. Simply include the IsPresentable trait, and a created_at presentable attribute will be included by default.

Testing

Tests can be run using PHPUnit:

Credits

• Warrick Bayman

Changelog

All API changes are documented in the CHANGELOG file.

License

IsPresentable is licensed in The MIT License. Please see LICENSE for more details.