├── LICENSE.md
├── README.md
├── composer.json
└── src
    ├── Bootstrap.php
    ├── Decorator.php
    ├── Presenter.php
    ├── exceptions
        └── PresenterException.php
    ├── rest
        └── Serializer.php
    └── traits
        └── PresentableTrait.php


/LICENSE.md:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2015 Ivan Kudinov
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 6 | 
 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 8 | 
 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
10 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | Yii2 View Presenters
  2 | =============
  3 | 
  4 | So you have those scenarios where a bit of logic needs to be performed before some data (likely from your entity) 
  5 | is displayed from the view.
  6 | 
  7 | * Should that logic be hard-coded into the view? **No.**
  8 | * Should we instead store the logic in the model? **No again!**
  9 | 
 10 | Instead, leverage view presenters. That's what they're for! This package provides one such implementation.
 11 | 
 12 | ## Installation
 13 | 
 14 | Run the [Composer](http://getcomposer.org/download/) command to install the latest stable version:
 15 | 
 16 | ```bash
 17 | composer require frostealth/yii2-presenter @stable
 18 | ```
 19 | 
 20 | ## Usage
 21 | 
 22 | The first step is to store your presenters somewhere - anywhere. 
 23 | These will be simple objects that do nothing more than format data, as required.
 24 | 
 25 | Here's an example of a presenter.
 26 | 
 27 | ```php
 28 | namespace app\presenters;
 29 | 
 30 | use app\models\User;
 31 | use frostealth\yii2\presenter\Presenter;
 32 | 
 33 | /**
 34 |  * Class ConcreteEntityPresenter
 35 |  *
 36 |  * @property User   $entity
 37 |  *
 38 |  * @property-read string $firstName
 39 |  * @property-read string $lastName
 40 |  * @property-read string $fullName
 41 |  * @property-read string $birthDate
 42 |  */
 43 | class UserPresenter extends Presenter
 44 | {
 45 |     /**
 46 |      * @return string
 47 |      */
 48 |     public function getFullName()
 49 |     {
 50 |         return implode(' ', [$this->firstName, $this->lastName]);
 51 |     }
 52 |     
 53 |     /**
 54 |      * @return string
 55 |      */
 56 |     public function getBirthDate()
 57 |     {
 58 |         return date('y.M.d', $this->entity->birthDate);
 59 |     }
 60 |     
 61 |     /**
 62 |      * @inheritdoc
 63 |      * @see \yii\base\Arrayable::fields()
 64 |      * @link http://www.yiiframework.com/doc-2.0/guide-rest-resources.html#fields
 65 |      */
 66 |     public function fields()
 67 |     {
 68 |         $fields = parent::fields();
 69 |         $fields[] = 'fullName';
 70 |         
 71 |         return $fields;
 72 |     }
 73 | }
 74 | ```
 75 | 
 76 | Next, on your entity, pull in the `frostealth\yii2\presenter\traits\PresentableTrait` trait, 
 77 | which will automatically instantiate your presenter class.
 78 | 
 79 | Here's an example of an presentable model.
 80 | 
 81 | ```php
 82 | namespace app\models;
 83 | 
 84 | use app\presenters\UserPresenter;
 85 | use frostealth\presenter\interfaces\PresentableInterface;
 86 | use frostealth\yii2\presenter\traits\PresentableTrait;
 87 | 
 88 | /**
 89 |  * Class User
 90 |  *
 91 |  * @property string $firstName
 92 |  * @property string $lastName
 93 |  * @property string $birthDate
 94 |  * @property string $passwordHash
 95 |  * @property string $passwordResetToken
 96 |  *
 97 |  * @method UserPresenter presenter()
 98 |  */
 99 | class User extends ActiveRecord implements PresentableInterface
100 | {
101 |     use PresentableTrait;
102 |     
103 |     /**
104 |      * @inheritdoc
105 |      * @see \yii\base\Arrayable::fields()
106 |      * @link http://www.yiiframework.com/doc-2.0/guide-rest-resources.html#fields
107 |      */
108 |     public function fields()
109 |     {
110 |         $fields = parent::fields();
111 |         unset($fields['passwordHash'], $fields['passwordResetToken']);
112 |         
113 |         return $fields;
114 |     }
115 |     
116 |     /**
117 |      * @return string|array
118 |      */
119 |     protected function getPresenterClass()
120 |     {
121 |         return 'app\presenters\UserPresenter';
122 |     }
123 | }
124 | ```
125 | 
126 | Now, within your view, you can do:
127 | 
128 | ```php
129 | <dl>
130 |     <dt>Name</dt>
131 |     <dd><?= $model->presenter()->fullName ?></dd>
132 |     
133 |     <dt>Birth Date</dt>
134 |     <dd><?= $model->presenter()->birthDate ?></dd>
135 | </dl>
136 | ```
137 | 
138 | ### Yii2 REST
139 | 
140 | Here's an example of an controller.
141 | 
142 | ```php
143 | namespace app\controllers;
144 | 
145 | use yii\rest\ActiveController;
146 | 
147 | class UserController extends ActiveController
148 | {
149 |     /** @inheritdoc */
150 |     public $serializer = 'frostealth\yii2\presenter\rest\Serializer';
151 |     
152 |     /** @inheritdoc */
153 |     public $className = 'app\models\User';
154 | }
155 | ```
156 | 
157 | ## License
158 | 
159 | The MIT License (MIT).
160 | See [LICENSE.md](https://github.com/frostealth/yii2-presenter/blob/master/LICENSE.md) for more information.
161 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "frostealth/yii2-presenter",
 3 |     "description": "Yii2 View Presenter",
 4 |     "keywords": ["yii2", "presenter"],
 5 |     "type": "yii2-extension",
 6 |     "license": "MIT",
 7 |     "authors": [
 8 |         {
 9 |             "name": "Ivan Kudinov",
10 |             "email": "i.kudinov@frostealth.ru",
11 |             "homepage": "http://frostealth.ru"
12 |         }
13 |     ],
14 |     "require": {
15 |         "php": ">=5.4",
16 |         "yiisoft/yii2": "~2.0",
17 |         "frostealth/php-presenter": "~0.1"
18 |     },
19 |     "autoload": {
20 |         "psr-4": {
21 |             "frostealth\\yii2\\presenter\\": "src/"
22 |         }
23 |     },
24 |     "extra": {
25 |         "bootstrap": "frostealth\\yii2\\presenter\\Bootstrap"
26 |     }
27 | }
28 | 


--------------------------------------------------------------------------------
/src/Bootstrap.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace frostealth\yii2\presenter;
 4 | 
 5 | use yii\base\BootstrapInterface;
 6 | 
 7 | /**
 8 |  * Class Bootstrap
 9 |  *
10 |  * @package frostealth\yii2\presenter
11 |  */
12 | class Bootstrap implements BootstrapInterface
13 | {
14 |     /**
15 |      * @inheritDoc
16 |      */
17 |     public function bootstrap($app)
18 |     {
19 |         \Yii::$container->setSingleton(
20 |             'frostealth\presenter\interfaces\DecoratorInterface',
21 |             'frostealth\yii2\presenter\Decorator'
22 |         );
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/src/Decorator.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace frostealth\yii2\presenter;
 4 | 
 5 | use frostealth\presenter\Decorator as BaseDecorator;
 6 | 
 7 | /**
 8 |  * Class Decorator
 9 |  *
10 |  * @package frostealth\yii2\presenter
11 |  */
12 | class Decorator extends BaseDecorator
13 | {
14 | 
15 | }
16 | 


--------------------------------------------------------------------------------
/src/Presenter.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace frostealth\yii2\presenter;
 4 | 
 5 | use frostealth\presenter\Presenter as BasePresenter;
 6 | use yii\base\Arrayable;
 7 | use yii\base\ArrayableTrait;
 8 | 
 9 | /**
10 |  * Class Presenter
11 |  *
12 |  * @package frostealth\yii2\presenter
13 |  */
14 | abstract class Presenter extends BasePresenter implements Arrayable
15 | {
16 |     use ArrayableTrait;
17 | 
18 |     /**
19 |      * @inheritDoc
20 |      */
21 |     public function fields()
22 |     {
23 |         if ($this->entity instanceof Arrayable) {
24 |             return $this->entity->fields();
25 |         }
26 | 
27 |         $fields = is_array($this->entity) ? $this->entity : \Yii::getObjectVars($this->entity);
28 |         $fields = array_keys($fields);
29 |         $fields = array_combine($fields, $fields);
30 | 
31 |         return $fields;
32 |     }
33 | 
34 |     /**
35 |      * @inheritDoc
36 |      */
37 |     public function extraFields()
38 |     {
39 |         if ($this->entity instanceof Arrayable) {
40 |             return $this->entity->extraFields();
41 |         }
42 | 
43 |         return [];
44 |     }
45 | }
46 | 


--------------------------------------------------------------------------------
/src/exceptions/PresenterException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace frostealth\yii2\presenter\exceptions;
 4 | 
 5 | use yii\base\Exception;
 6 | 
 7 | /**
 8 |  * Class PresenterException
 9 |  *
10 |  * @package frostealth\yii2\presenter\exceptions
11 |  */
12 | class PresenterException extends Exception
13 | {
14 |     /**
15 |      * @inheritDoc
16 |      */
17 |     public function getName()
18 |     {
19 |         return 'Presenter Exception';
20 |     }
21 | }
22 | 


--------------------------------------------------------------------------------
/src/rest/Serializer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace frostealth\yii2\presenter\rest;
 4 | 
 5 | use yii\rest\Serializer as BaseSerializer;
 6 | 
 7 | /**
 8 |  * Class Serializer
 9 |  *
10 |  * @package frostealth\yii2\presenter\rest
11 |  */
12 | class Serializer extends BaseSerializer
13 | {
14 |     /** @var string|array the configuration for creating the decorator. */
15 |     public $decorator = 'frostealth\presenter\interfaces\DecoratorInterface';
16 | 
17 |     /**
18 |      * @inheritDoc
19 |      */
20 |     protected function serializeModel($model)
21 |     {
22 |         $model = $this->decorate($model);
23 | 
24 |         return parent::serializeModel($model);
25 |     }
26 | 
27 |     /**
28 |      * @inheritDoc
29 |      */
30 |     protected function serializeModels(array $models)
31 |     {
32 |         $models = $this->decorate($models);
33 | 
34 |         return parent::serializeModels($models);
35 |     }
36 | 
37 |     /**
38 |      * @param mixed $value
39 |      *
40 |      * @return mixed
41 |      * @throws \yii\base\InvalidConfigException
42 |      */
43 |     protected function decorate($value)
44 |     {
45 |         return \Yii::createObject($this->decorator)->decorate($value);
46 |     }
47 | }
48 | 


--------------------------------------------------------------------------------
/src/traits/PresentableTrait.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace frostealth\yii2\presenter\traits;
 4 | 
 5 | use frostealth\presenter\interfaces\PresenterInterface;
 6 | use frostealth\yii2\presenter\exceptions\PresenterException;
 7 | 
 8 | /**
 9 |  * Trait PresentableTrait
10 |  *
11 |  * @package frostealth\yii2\presenter\traits
12 |  */
13 | trait PresentableTrait
14 | {
15 |     /** @var PresenterInterface */
16 |     protected $presenterInstance;
17 | 
18 |     /**
19 |      * @return PresenterInterface
20 |      * @throws PresenterException
21 |      * @throws \yii\base\InvalidConfigException
22 |      */
23 |     public function presenter()
24 |     {
25 |         if (empty($this->presenterInstance)) {
26 |             $this->presenterInstance = $this->buildPresenter();
27 |         }
28 | 
29 |         return $this->presenterInstance;
30 |     }
31 | 
32 |     /**
33 |      * @return PresenterInterface
34 |      * @throws PresenterException
35 |      * @throws \yii\base\InvalidConfigException
36 |      */
37 |     protected function buildPresenter()
38 |     {
39 |         $presenter = $this->getPresenterClass();
40 |         $presenter = is_string($presenter) ? ['class' => $presenter] : (array)$presenter;
41 |         $presenter = \Yii::createObject($presenter, [$this]);
42 | 
43 |         if (!$presenter instanceof PresenterInterface) {
44 |             throw new PresenterException(strtr(
45 |                 '"{{class}}" must implement "frostealth\presenter\interfaces\PresenterInterface".',
46 |                 ['{{class}}' => get_class($presenter)]
47 |             ));
48 |         }
49 | 
50 |         return $presenter;
51 |     }
52 | 
53 |     /**
54 |      * @return string|array
55 |      */
56 |     abstract protected function getPresenterClass();
57 | }
58 | 


--------------------------------------------------------------------------------