Laravel: разработка пакетов07.04.2022 09:46

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

После загрузки сервис-провайдера, загружаемые в его методе boot компоненты (у нас это миграции, команды и роуты) становятся доступны в наших тестах.

Так как наш пакет предоставляет класс миграции, для его тестирования потребуется база данных. В качестве СУБД мы будем использовать SQLite. SQLite — это встраиваемая кроссплатформенная СУБД, реализованная в виде библиотеки на языке С, и которая присутствует в любом дистрибутиве интерпретатора PHP. Данный вариант драйвера идеально подходит для тестирования Laravel-пакетов, использующих базу данных.

При работе с Laravel-проектом, для того, чтобы иметь доступ к SQLite нам бы потребовалось внести соответствующие настройки в файл config/database.php. Пакет Orchestra\Testbench предоставляет метод getEnvironmentSetUp () для настройки конфигурации.

Переопределяем данный метод в нашем классе FeatureTestCase, и настраиваем в нем доступ к SQLite.

set('database.default', 'sqlite');
    $app['config']->set('database.connections.sqlite', [
        'driver' => 'sqlite',
        'database' => ':memory:',
        'prefix' => '',
    ]);
}

В данном методе вы можете устанавливать любые значения параметров конфигурации Laravel-приложения (файлы config/app.php, config/auth.php и т. д.), конфигурации разрабатываемого пакета, а также конфигураций Laravel-пакетов, указанных в качестве зависимостей разрабатываемого пакета.

После настройки базы данных нам необходимо выполнить миграции, предоставляемые нашим пакетом. Так как миграции уже загружены в приложение сервис-провайдером, нам необходимо лишь выполнить Artisan-команду 'migrate'. Создадим метод setUpDatabase () с вызовом Artisan-команды для запуска миграций:

artisan('migrate')->run();
}

Вызовем этот метод в нашем методе setUp () после вызова его родительской реализации.

setUpDatabase();
}

Теперь каждый наш функциональный тест будет иметь доступ к базе данных с готовой структурой таблиц. Если таблицы необходимо наполнить тестовыми данными, сделать это можно как в самих тестовых методах, так и в методе setUpDatabase () сразу после запуска миграций.

Для запуска миграций в пакете Testbench предусмотрен альтернативный вариант. Он подходит в том случае, если миграции пакета в сервис-провайдере не загружаются, а подготавливаются к публикации. То есть если в методе boot () сервис-провайдера к миграциям применяется не метод loadMigrationsFrom (), а метод publishes (). Такие миграции по Artisan-команде не выполнятся, их необходимо сначала загрузить в приложение, а затем выполнить. Для этого в пакете Testbench предусмотрен метод с уже знакомым именем loadMigrationsFrom (). Этот метод не только загружает миграции в приложение, но и тут же выполняет их. Таким образом, вместо вызова Artisan-команды в методе setUpDatabase () мы могли бы использовать следующий код:

loadMigrationsFrom(__DIR__ . '/../database/migrations/0000_00_00_000000_create_items_table.php');

Если разрабатываемый вами пакет имеет в своих зависимостях Laravel-пакеты с собственными публикуемыми миграциями, запустить их можно также методом loadMigrationsFrom (), указав путь к файлу миграции через директорию vendor.

После того как в базе данных созданы необходимые таблицы их можно наполнить тестовыми данными. Сделать это можно как в методе setUpDatabase () сразу после запуска миграций, так и непосредственно в самих тестовых методах. Воспользуемся вторым вариантом.

Сначала напишем тест для нашего контроллера. Создаем файл tests/ItemsTest.php:

 'Name 1']);
        Item::forceCreate(['name' => 'Name 2']);

        $response = $this->get('items');

        $response->assertStatus(200);

        $response->assertExactJson([
            'items' => [
                ['name' => 'Name 1'],
                ['name' => 'Name 2'],
            ]
        ]);
    }
}

Класс теста мы наследуем от созданного абстрактного класса FeatureTestCase. В данном тесте мы наполняем базу данных тестовыми данными; вызываем роут 'items', предоставляемый пакетом и проверяем код http-ответа и содержимое тела ответа.

Теперь напишем тест для консольной команды, предоставляемой нашим пакетом. Создаем файл tests/CommandTest.php:

set('example.param', 200);
    }

    /**
     * @test
     */
    public function it_executes_example_command()
    {
        $output = $this->artisan('example-command');

        $output->assertExitCode(0);

        $output->expectsOutput("Command executed with config param value 200");
    }
}

Так как наша консольная команда использует файл конфигурации config/example.php, нам необходимо установить тестовое значение его параметров. В классе CommandTest мы переопределяем метод getEnvironmentSetUp () и после вызова его родительской реализации устанавливаем тестовое значение параметра example.param. В самом тестовом методе мы вызываем консольную команду и проверяем код завершения команды, а также выведенный в консоль текст.

Таким образом, мы покрыли тестами функционал нашего пакета.

В завершение работы над кодом пакета добавим в файл composer.json следующую директиву для упрощения процесса установки пакета:

"extra": {
  "laravel": {
    "providers": [
      "Yuraplohov\\LaravelExample\\Providers\\EloquentFilterServiceProvider"
    ]
  }
}

Данная директива позволяет использовать механизм автоматического обнаружения пакетов Laravel. Без этого кода при установке пакета потребуется вручную добавлять наш сервис-провайдер в массив providers в файле config/app.php проекта, а с наличием этого кода сервис-провайдер будет загружен автоматически и все объявленные в нем компоненты станут доступны в приложении.

Разработку пакета будем считать завершенной. После завершения разработки пакета настоятельно рекомендуется создать файл README.md. В этом файле должны быть описаны шаги установки пакета, а также варианты использования функционала, предоставляемого пакетом. При составлении README.md может быть полезен данный ресурс.

Файлом README.md не стоит пренебрегать ни только в публичных пакетах, но и в приватных. Один раз задокументировав функционал пакета, вы облегчите жизнь себе и своим коллегам.

Выпуск релиза пакета

Перед тем, как загрузить пакет в git-репозиторий, в корне пакета создаем файл .gitignore. В него добавляем следующее содержимое:

vendor
composer.lock
.phpunit.result.cache

Данные директории и файлы не будут добавлены в git-репозиторий.

Обратите внимание, что файл composer.lock добавляется в .gitignore только при разработке пакета. При разработке проекта файл composer.lock в .gitignore не добавляется и должен быть помещен в git-репозиторий. В процессе развертывания проекта при выполнении команды composer install все зависимости проекта будут скачаны согласно версиям, указанным в composer.lock. В пакете же composer.lock не нужен. При установке пакета в проект, все зависимости пакета будут скачаны согласно версиям, указанным в composer.json. Даже если composer.lock добавлен в репозиторий пакета, его содержимое никак не повлияет на установку зависимостей пакета.

После того, как вы загрузили свой пакет в git-репозиторий и убедились, что в основной ветке (обычно это ветка master либо main) находится версия кода, готовая к установке в проект, вам необходимо создать тэг. Тэг в данном случае — это версия релиза пакета, которая традиционно указывается согласно правилам семантического версионирования.

Объяснение правил семантического версионирования выходит за рамки данного туториала. Ознакомиться с этими правилами можно здесь. В рамках же текущего материала стоит отметить, что соблюдение правил семантического версионирования при разработке пакетов строго обязательно. Необходимо следовать им не только в публичных пакетах, но и в приватных. Это избавит вас и вашу команду от многих проблем.

Чтобы создать тэг и залить его в git-репозиторий, необходимо выполнить следующие команды:

git tag 1.0.0
git push --tags

Теперь в вашем пакете создан релиз с версией 1.0.0, и ему соответствует состояние основной ветки, зафиксированное перед созданием тега.

Для просмотра существующих тегов (версий) пакета необходимо выполнить команду:

git tag

Если вы создаете публичный пакет, его необходимо добавить в реестр packagist.org. Сделать это несложно. Для этого необходимо создать аккаунт и указать путь к git-репозиторию через соответствующую форму.

Установка пакета

Для того, чтобы установить в проект публичный, зарегистрированный на packagist.org пакет, достаточно выполнить команду composer require:

composer require yuraplohov/laravel-example

Для того, чтобы установить приватный пакет сначала необходимо указать его репозиторий в файле composer.json проекта.

"repositories": [
    {
        "type": "vcs",
        "url": "git@github.com:yuraplohov/laravel-example.git"
    }
]

Далее выполняем привычную команду:

composer require yuraplohov/laravel-example

При этом Сomposer попросит вас ввести логин и пароль вашего аккаунта в git-репозитории. После авторизации пакет будет установлен.

Если в процессе разработки пакета появилась необходимость протестировать его в реальном проекте, то вам не обязательно создавать новый релиз, чтобы затем установить его. Пакет можно установить по названию ветки и идентификатору конкретного коммита в этой ветке. Для этого при установке пакета вместо тэга версии указывается название ветки с префиксом »dev-», а через символ решетки (#) можно указать идентификатор коммита. Например, так можно установить версию пакета, соответствующую текущему состоянию ветки master.

composer require yuraplohov/laravel-example:dev-master

А так можно установить версию пакета, соответствующую конкретному коммиту в ветке master:

composer require yuraplohov/laravel-example:dev-master#ecb50b62a5ca4edd4f74ba94792660631277a779

Подробнее о способах установки пакетов можно прочитать здесь.

Код демонстрационного пакета, разработанного в рамках данного туториала, можно найти здесь.

© Habrahabr.ru