Разработка API на Yii2 с использованием REST

Вы когда-нибудь пытались написать API на чистом PHP и через час хотели выкинуть ноутбук в окно? Я — да. Слишком много рутины: парсинг запросов, проверка заголовков, обработка ошибок. Но есть фреймворк Yii2, который берёт на себя всю эту боль. В этой статье я покажу, как за 15 минут собрать REST API, которое будет работать как часы. Без магии, только код и здравый смысл.

Почему Yii2 и REST — это любовь

REST — это не протокол, а стиль архитектуры. Представьте, что ваше приложение — это ресторан. Клиент (фронтенд или мобильное приложение) делает заказ (HTTP-запрос), а кухня (сервер) выдаёт блюдо (JSON-ответ). Yii2 из коробки понимает REST: он умеет различать GET, POST, PUT, DELETE и автоматически сериализовать данные. Вам остаётся только описать модели и контроллеры.

Вот что вы получаете:

• Автоматическая маршрутизация — не нужно писать роуты для каждой сущности.
• Поддержка форматов — JSON, XML, и даже свой кастомный.
• Встроенная аутентификация — OAuth2, HTTP Basic и другие.
• Пагинация и фильтрация — из коробки.

Согласитесь, звучит как сказка. Но давайте перейдём к делу.

Настройка окружения: минимум телодвижений

Первым делом установите Yii2 через Composer. Если у вас его нет — бегом ставить. Это стандарт де-факто.

composer create-project --prefer-dist yiisoft/yii2-app-basic api-project

После установки откройте файл config/web.php. Там нужно включить компонент urlManager с правилами для REST. Вот минимальная настройка:

'components' => [
    'urlManager' => [
        'enablePrettyUrl' => true,
        'showScriptName' => false,
        'rules' => [
            ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
        ],
    ],
],

Что здесь происходит? Мы говорим Yii2: «Слушай, все запросы к /users перенаправляй в контроллер UserController». И фреймворк сам разберётся, какой метод вызывать — actionIndex для GET, actionCreate для POST и так далее.

Создаём модель и контроллер: база

Допустим, у нас есть таблица user с полями id, name, email. Сначала сгенерируем модель через Gii (это встроенный генератор кода). Но если вы любите ручной труд — вот пример:

namespace app\models;

use yii\db\ActiveRecord;

class User extends ActiveRecord
{
    public static function tableName()
    {
        return 'user';
    }

    public function rules()
    {
        return [
            [['name', 'email'], 'required'],
            [['email'], 'email'],
            [['name'], 'string', 'max' => 255],
        ];
    }
}

Теперь контроллер. Yii2 предлагает базовый класс yii\rest\ActiveController, который уже содержит все CRUD-методы. Просто наследуйтесь:

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}

Всё. Теперь по адресу /users вы получите список пользователей в JSON. Попробуйте отправить GET-запрос через Postman или curl. Удивительно, но работает.

Кастомизация: добавляем свою логику

Стандартные методы — это круто, но жизнь сложнее. Например, нужно добавить фильтрацию или скрыть пароль в ответе. Давайте разберёмся.

Фильтрация данных. Допустим, клиент хочет получать только активных пользователей. Добавьте в контроллер метод actions():

public function actions()
{
    $actions = parent::actions();
    unset($actions['index']); // удаляем стандартный actionIndex
    return $actions;
}

public function actionIndex()
{
    $activeUsers = User::find()->where(['status' => 1])->all();
    return $activeUsers;
}

Скрытие полей. В модели переопределите метод fields():

public function fields()
{
    return [
        'id',
        'name',
        'email',
        // 'password_hash' не включаем
    ];
}

Так вы гарантируете, что пароль не утечёт в ответ. Безопасность превыше всего.

Аутентификация: закрываем доступ

API без защиты — как дом без двери. Yii2 поддерживает несколько способов аутентификации. Самый простой — HTTP Basic Auth. Добавьте в контроллер поведение:

use yii\filters\auth\HttpBasicAuth;

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

Теперь при запросе нужно передавать логин и пароль в заголовке. Yii2 автоматически проверит их через метод findIdentityByAccessToken() в модели User. Если данные неверные — вернётся ошибка 401.

Для более сложных сценариев (например, токены) используйте QueryParamAuth или OAuth2. Но это уже тема отдельной статьи.

Обработка ошибок: чтобы не было сюрпризов

Когда что-то идёт не так, API должен возвращать понятный JSON, а не HTML-страницу с ошибкой. Yii2 по умолчанию делает это, но можно настроить. В конфиге config/web.php добавьте:

'components' => [
    'errorHandler' => [
        'errorAction' => 'site/error',
    ],
],

А в контроллере SiteController создайте actionError:

public function actionError()
{
    $exception = Yii::$app->errorHandler->exception;
    if ($exception !== null) {
        return [
            'name' => ($exception instanceof \yii\web\HttpException) ? $exception->statusCode : '500',
            'message' => $exception->getMessage(),
            'code' => $exception->getCode(),
        ];
    }
    return [];
}

Теперь любая ошибка будет возвращать структурированный JSON. Клиент сможет её обработать без головной боли.

Сравнение способов аутентификации

Итоги: что вы получили

Мы прошли путь от установки до готового API с аутентификацией и обработкой ошибок. Yii2 делает REST-разработку быстрой и приятной. Главное — не бойтесь экспериментировать. Начните с малого: создайте одну модель, один контроллер и протестируйте через curl.

Вот что вы теперь умеете:

• Настраивать роутинг для REST.
• Создавать модели и контроллеры за пару минут.
• Добавлять свою логику без поломки стандартного поведения.
• Защищать API базовой аутентификацией.
• Возвращать понятные ошибки.

Теперь идите и пишите код. И помните: если что-то пошло не так — читайте документацию Yii2. Она, кстати, отличная.