Предварительная настройка

Для начала работы достаточно базового шаблона Yii2. Создание проекта и настройку виртуального хоста я описывать не буду и перейду сразу к настройке REST.

После скачивания проекта настроим компоненту user в файле web.php. Добавим туда следующие строки:

'enableSession' => false,
'loginUrl' => null,

Первая строка отключает сохранение состояния пользователя на сервере: одно из требований архитектуры REST.

Вторая строка отключает перенаправление на страницу входа после неудачной аутентификации.

В User.php добавим следующий код:

public static function getAll()
{
   $result = [];

   foreach (self::$users as $user) {
       $result[] = [
           'id' => $user['id'],
           'username' => $user['username'],
       ];
   }

   return $result;
}

Создание контроллера

Мы не используем базу данных в нашем примере и создание контроллера займет чуть больше времени, чем в случае использования AR-моделей.

В папке controllers создадим файл UserController.php со следующим содержимым:

<?php
namespace app\controllers;

use yii\rest\Controller;
use app\models\User;

class UserController extends Controller
{
    public function actionIndex()
    {
        return User::getAll();
    }

    /**
     * @inheritdoc
     */
    protected function verbs()
    {
        return [
            'index' => ['GET', 'HEAD'],
        ];
    }
}

Как видно из примера, мы наследуем свой класс от yii\rest\Controller. Данный класс реализует поддержку сериализации и представления массивов в форматах XML и JSON перед отправкой ответа. Дополнительно можно задать параметры аутентификации и ограничить количесто запросов к API.

Метод verbs позволяет задать типы запросов, которые принимает каждое из действий контроллера.

Чтобы контроллер заработал, нужно отредактировать настройки компоненты urlManager в файле web.php:

'rules' => [
    ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
],

Протестируем работу API, используя curl:

$ curl -i -H "Accept:application/json" "http://yii2-rest.dev/users"
$ curl -i -H "Accept:application/xml" "http://yii2-rest.dev/users"

Вместо yii2-rest.dev нужно указать имя вашего хоста.

Аутентификация

При реализации любого из методов аутентификации в продакшене не забывайте об использовании https для предотвращения атаки типа “человек посередине”

Yii2 поддерживает несколько типов аутентификации. Реализуем HTTP Basic Auth.

В UserContoller.php добавим следующие строки:

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => HttpBasicAuth::className(),
    ];

    return $behaviors;
}

Не забываем перед объявлением класса прописать:

use yii\filters\auth\HttpBasicAuth;

Чтобы все заработало, модель пользователя должна реализовывать метод findIdentityByAccessToken. Если вы используете базовый шаблон Yii2, то он уже реализован и ничего менять не нужно.

Проверям работу механизма аутентификации:

$ curl -i -H "Accept:application/json" "http://yii2-rest.dev/users"

Выполнение кода выше должно вернуть ошибку с кодом 401.

Пробуем авторизоваться, используя HTTP Basic Auth:

$ curl -i -H "Accept:application/json" "http://yii2-task_manager.dev/users" -H "Authorization: Basic MTAwLXRva2VuOg=="

Должен вернуться полный список пользователей в json-ответе.

Заключение

Я описал лишь один из вариантов реализации REST в Yii2. Без рассмотрения остались множество других тем, таких как версионирование, ограничение числа запросов и обработка ошибок. Многое из этого описано в документации.

Ниже перечислен ряд моментов, которые для меня оказались не очевидны.

Advanced-шаблон и алиас @app

В проекте я использую advanced-шаблон. Он позволяет разделять проект на три части:

• Для пользователя (frontend)
• Для администраторов и контент-менеджеров (backend)
• Для работы с cli-интерфейсом приложения (console)

Для каждой из частей проекта так же предусмотрены алиасы @frontend, @backend и @console соответственно.

Однако у моих ассетов во frontend-части в свойстве sourcePath был прописан алиас @app вместо @frontend.

В этом не было ничего страшного до тех пор, пока не стало нужно выполнить минификацию ресурсов с помощью предоставляемого фреймворком инструментария.

Как выяснилось, алиас @app для консоли в случае с advanced-шаблоном указывает на алиас @console и ассеты пытались распаковаться туда, что и сбивало с толку инструмент. Тот случай, когда неплохо бы лишний раз читать доки. :)

Вывод: в случае использования advanced-шаблона, нужно проверить, что ассеты, расположенные во frontend/assets используют в sourcePath алиас @frontend вместо @app. Аналогично и для backend-части приложения.

Ошибка file_put_contents

Функция file_put_contents падает с ошибкой в случае несуществующего пути до папки.

Вывод: следует проверять, что все пути к папкам в конфиге сжатия ассетов верные.

Невозможность доступа к baseUrl ассета после минификации

На заре создания проекта я хранил всю frontend-статику в папке assets. Путь до папки с финальными ассетами я получал комбинацией:

$asset = frontend\assets\AppAsset::register($this);
echo $asset->baseUrl;

Оказалось, это плохая практика. После сжатия свойство baseUrl у ассетов зануляется и картинки, шрифты и прочие вещи, которые до этого прекрасно отображались, перестают работать в production-окружении (в dev-окружении все в порядке).

Пришлось вынести папки со шрифтами и картинками в публичную часть сайта, а относительные пути в css переделать на абсолютные.

Вывод: в assets лучше хранить только то, что будем сжимать. Остальное выносить в публичную часть. К тому же так лишний раз не копируются большие объемы данных.

Не все расширения фреймворка совместимы с инструментом сжатия ассетов

Об этом прямо указывается в документации в желтой сноске в конце параграфа An Example, но я помучался с этой ошибкой.

Выглядит это так: ассеты прекрасно сжимаются, но на странице подключаются дважды (минифицированная версия и еще раз несовместимые ассеты из отдельной папки).

В итоге эти расширения пришлось исключить из минификации, а подключаются они на странице отдельно как и раньше, что, конечно же, увеличивает число запросов к серверу.

Вывод: иметь в виду эту особенность при работе с расширениями использующими динамическое задание параметров ассетов в методе init().