mindtwo/laravel-decorator

Decorators for Eloquent Models in Laravel

3.0.3 2024-11-14 06:54 UTC

README

Build Status StyleCI Quality Score Latest Stable Version Total Downloads MIT Software License

Installation

You can install the package via composer:

composer require mindtwo/laravel-decorator

How to use?

Preparing the Eloquent Model

To use a decorator the underlaying eloquent model must implement the Decoratable interface. Farther you should use the HasDecorator trait, which implements the required methods.

use Illuminate\Database\Eloquent\Model;
use mindtwo\LaravelDecorator\Interfaces\Decoratable;
use mindtwo\LaravelDecorator\Traits\HasDecorator;

class MyModel extends Model implements Decoratable
{
    use HasDecorator;
}

You can optionally setup a default decorator on the eloquent model, which will be used when you call the decorate() method without any params.

use Illuminate\Database\Eloquent\Model;
use mindtwo\LaravelDecorator\Interfaces\Decoratable;
use mindtwo\LaravelDecorator\Traits\HasDecorator;

class MyModel extends Model implements Decoratable
{
    use HasDecorator;

    /**
     * Return the default decorator full qualified class name.
     *
     * @return string
     */
    public function defaultDecorator(): string
    {
        return MyDecorator::class;
    }
}

Writing a Decorator

To write a decorator simply extend the basic decorator class. You can access the undelaying eloquent model by the $this->model property. Whenever you try to access a property on the decorator, it will first look for a function with the camilzed property name. If it is defined, it will be called, otherwise it will be forwarded to the underlaying eloquent model.

use mindtwo\LaravelDecorator\Decorator;

class MyDecorator extends Decorator
{
    /**
     * Get formatted creation date.
     *
     * @return string
     */
    public function defaultDecorator(): string
    {
        return $this->model->created_at->format('Y-m-d');
    }
}

Using a Decorator

To use a decorator simply call the decorate() method on the model. You can use the full qualified class name of a decorator class as parameter to specify a decorator, otherwise the default decorator will be used.

$myObject = MyModel::make();

// Use a certain decorator
$myDecoratedObject = $myObject->decorate(MyDecorator::class);

// Use the default decorator (needs to be defined on the model)
$myDecoratedObject = $myObject->decorate();

It is also possible to call the 'decorate()' method on collections, cause the package autmatically registers it as a macro.

$myCollection = MyModel::get();

// Use a certain decorator
$myDecoratedCollection = $myCollection->decorate(MyDecorator::class);

// Use the default decorator (needs to be defined on the model)
$myDecoratedCollection = $myCollection->decorate();

Note that all items in the collection must implement the Decoratable interface, otherwise this will throw an exception.

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email info@mindtwo.de instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.