Новичкам иногда сложно сходу добавить новый функционал в виртуальную машину на базе Homestead.

Для примера дан простой набор шагов по добавлению php-расширения APCu в Homestead. Оно используется, например, в Symfony.

Настраиваем Homestead

Находим в папке с Homestead файл after.sh и добавляем нужные строки:

#Install APCu
sudo apt-get -y \
    -o Dpkg::Options::="--force-confdef" \
    -o Dpkg::Options::="--force-confold" \
    install php-apcu

Пересобираем виртуальную машину

В терминале в папке с Homestead выполянем:

$ vagrant destroy
$ vagrant up --provision

Проверяем результат

Там же выполняем:

$ vagrant ssh

Внутри виртуальной машины выполняем:

$ php -m | grep apcu

Мы должны увидеть в выводе apcu.

Аналогичным образом можно установить остальные недостающие расширения.

Все интереснее, когда код приходится отлаживать не на локальной машине, а внутри docker-контейнера. Особенно, если нужно отладить cli-скрипт внутри контейнера.

Для успешной отладки следует:

1. Настроить docker-контейнер с Xdebug внутри;
2. Настроить Xdebug внутри контейнера;
3. Настроить NetBeans.

При обычной отладке с использованием браузера и при отладке cli-скрипта настройки будут слегка отличаться. Итак, поехали.

Настройка контейнера

Установку Xdebug внутрь контейнера мы обсуждать не будем. Эти настройки можно найти, например, тут.

Интереснее настройки самого Xdebug.

В случае с обычной отладкой:

xdebug.remote_enable=1
xdebug.remote_connect_back=1
xdebug.idekey=netbeans-xdebug

Расшифровка:

• xdebug.remote_enable — разрешает удаленную отладку.
• xdebug.remote_connect_back — автоматическое установление соединения с хостом, который иницирует удаленную отладку. Если не указывать эту опцию, то нужно использовать xdebug.remote_host, где следует указать ip вашего хоста из виртуального docker-адаптера.
• xdebug.idekey — ключ для соединения. Значение netbeans-xdebug задано в NetBeans по умолчанию. Можно не задавать эту опцию и использовать xdebug.remote_autostart=1, но тогда Xdebug будет стартовать в каждом скрипте, даже если это не нужно, что скажется на производительности.

Настройка NetBeans

Для успешной отладки NetBeans должен знать как сопоставить между собой пути внутри docker-контейнера и пути в хостовой машине.

Идем в Свойства проекта, далее Выполнить настройку → Дополнительно. Внизу в разделе Отображение пути добавляем наше сопоставление.

Теперь, если запустить отладку проекта, то отладчик должен автоматически остановить выполнение на первой строке скрипта точки входа в приложение (если активирована соответствующая настройка в IDE).

Если ничего не произошло и вас отключена опция NetBeans Остановить в первой строчке, то удостоверьтесь, что поставили breakpoint где-то по пути выполнения скрипта. Если ни одного breakpoint не установлено, то следует установить его, остановить отладку и запустить снова.

Отладка cli-скрипта

Для отладки cli-скрипта все немного иначе. Главное отличие в том, что опция xdebug.remote_connect_back=1 нам не нужна, ведь соединения от хостовой машины не будет. Вместо этого NetBeans будет ожидать обращений от приложения.

Для начала настроим NetBeans.

Идем по уже известному пути Свойства проекта → Выполнить настройку. Здесь добавляем новую конфигурацию, нажав Создать…. Далее жмем Дополнительно и указываем опцию Не открывать браузер.

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

Теперь можно нажать Отладка проекта или просто Ctrl+F5. Браузер не должен открыться.

Идем в меню Окно → IDE и сервис → Терминал. В появившемся терминале выполняем вход в docker-контейнер, выполнив что-то вроде:

$ docker exec -ti %container_id% bash

%container_id% в данном случае id контейнера с вашим приложением.

Теперь самое интересное. Выполняем:

$ export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=%remote_host_ip% remote_connect_back=0 idekey=netbeans-xdebug"

Обратите внимание на указанный remote_host. Именно по этому адресу Xdebug будет ломиться в отладчик. Проставьте свое значение на место %remote_host_ip%.

Теперь можно запустить какой-нибудь cli-скрипт. Например, миграции yii:

$ ./yii migrate

Если отладчик NetBeans запущен, то он должен отловить это событие и прервать выполнение на первой строке скрипта точки входа.

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

Для начала работы достаточно базового шаблона 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. Без рассмотрения остались множество других тем, таких как версионирование, ограничение числа запросов и обработка ошибок. Многое из этого описано в документации.

PHP_CodeSniffer - это инструмент для проверки кода на соответствие принятым соглашениям и (в некоторых случаях) автоматического его исправления после проверки.

Установка и запуск

В самом простом случае можно выполнить такой код в папке с исходниками проекта:

$ curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar
$ php phpcs.phar -h

$ curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar
$ php phpcbf.phar -h

Так же поддерживается установка через composer. Далее будет рассматриваться именно этот вариант.

Пропишем в composer.json следующий код:

{
    "require-dev": {
        "squizlabs/php_codesniffer": "3.*"
    }
}

После обновления composer пробуем выполнить

$ ./vendor/bin/phpcs -h
$ ./vendor/bin/phpcbf -h

Первый скрипт проверяет код на соответствие стандартам и выдает отчет. Второй - исправляет, то что можно исправить автоматически.

Чтобы посмотреть перечень доступных стандартов, можно выполнить

$ ./vendor/bin/phpcs -i

Для вывода списка проверок интересующего стандарта (в данном случае PSR-2) выполняем:

$ ./vendor/bin/phpcs --standard=PSR2 -e

Проверка кода

К примеру, при кодировании мы хотим следовать стандарту PSR-2.

Выполняем в консоли:

$ ./vendor/bin/phpcs --standard=PSR2 -p ./

Данная команда проверит все файлы проекта на соответствие PSR-2. Все файлы нам не нужны, поэтому некоторые мы можем смело исключить:

$ ./vendor/bin/phpcs --standard=PSR2 -p --ignore=*/vendor/*,*/tests/*,*.css,*.js ./

В примере выше я исключил папки с тестами проекта, а так же третьесторонние модули и файлы js-скриптов и стилей css (PHP_CodeSniffer знает некоторые проверки для css и js-файлов тоже).

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

Быстро исправить некоторые простые вещи поможет выполнение следующего кода:

$ ./vendor/bin/phpcbf --standard=PSR2 -p --ignore=*/vendor/*,*/tests/*,*.css,*.js ./

Затем можно снова вызвать phpcs и доправить остальные замечания вручную.

Что дальше?

В идеале PHP_CodeSniffer должен запускаться с определенной периодичностью. Желательно перед сдачей кода в master-ветку проекта. Оставим этот вопрос за пределами данной заметки.

Если в вашей компании есть свой ни на что не похожий code-style, то здесь вам поможет написание собственного набора правил в формате xml.

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

После написания собственного набора правил, подключить его можно просто:

$ ./vendor/bin/phpcs --standard=path_to_my_ruleset/ruleset.xml

Желаю успеха в борьбе с беспорядком в коде!

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

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().