Разработка дополнений

Содержание:

Введение

Пакеты — основной способ добавить функциональность в Ларавел. Диапазон пакетов может быть совершенно различным: от превосходной работы с датами и врененм как Carbon, или целый фреймворк тестирования, такой как Behat.

Есть различные типы компонентов. Некоторые пакеты являются независимыми одиночками и могут работать с любым фреймворком PHP. Указанные выше пакеты Carbon и Behat являются примером одиночных пакетов. Любой из таких пакетов может быть использован с Ларавел путём указания их в вашем файле composer.json.

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

Заметка о фасадах

При написании приложения Ларавел, нет большой разницы что использовать: контракты или фасады. Оба подхода являются одинаково пригодными для тестирования. Однако, при написании пакетов, ваш пакет не будет иметь доступ ко всем стандартным помощникам проведения тестов Ларавел. Если вы хотите писать тесты пакета так, словно они существуют внутри обычного приложения Laravel, вы можете использовать пакет Orchestral Testbench.

Обнаружение пакетов

В приложениях Ларавел, в файле конфигурации config/app.php, опция providers определяет список сервис провайдеров, которые фреймворк должне загружать. Когда кто-то устанавливает ваш пакет, вы обычно хотите, чтобы ваш сервис-провайдер был включён в этот лист. Вместо того, чтобы требовать от пользователя вручную добавлять ваш сервис провайдер в список, вы можете определить провайдер в секции extra вашего файла пакета composer.json. В дополнение к сервис провайдерам, вы можете также перечислить любые фасады, которые вы хотели бы зарегистрировать: 

"extra": {
    "laravel": {
        "providers": [
            "Barryvdh\\Debugbar\\ServiceProvider"
        ],
        "aliases": {
            "Debugbar": "Barryvdh\\Debugbar\\Facade"
        }
    }
},

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

Отказ от обнаружения пакетов.

Если вы являетесь пользователем пакета и хотите отключить обнаружение пакета, вы можете указать имя пакета в секции extra директиве dont-discover файла composer.json: 

"extra": {
    "laravel": {
        "dont-discover": [
            "barryvdh/laravel-debugbar"
        ]
    }
},

Вы можете отключить обнаружение всех пакетов используя символ * внутри директивы dont-discover: 

"extra": {
    "laravel": {
        "dont-discover": [
            "*"
        ]
    }
},

Сервис провайдеры

Сервис провайдеры — это соединение между вашим пакетом и Ларавел. Они отвечают за связывание вещей в сервис контейнр и информируют Laravel где загружать ресурсы пакета: представления, конфигурацию, файлы локанлизации и другое.

Сервис контейнер расширяют класс Illuminate\Support\ServiceProvider и содержат два метода: register и boot. Базовый класс ServiceProvider располагается в illuminate/support пакета Composer, который вы должны добавить в ваши зависимости пакета. Для изучения целй и структуры сервис провайдеров, проверьте документацию.

Ресурсы

Конфигурация

Обычно, вам необходимо публиковать файл конфигурации вашего пакета в собственной директории приложения config. Это позволит пользователям вашего пакета легко переписать предустановленные вами опции конфигурации. Чтобы опубликовать ваш файл конфигурации, вызовите метод publishes и метода сервис провайдера boot: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/path/to/config/courier.php' => config_path('courier.php'),
    ]);
}

Теперь, когда пользователи вашего пакета выполняют команду Ларавел vendor:publish, ваш файл будет скопирован в указанную папку. После публикации вашей конфигурации, получить значения можно будет как и для других файлов конфигурации: 

$value = config('courier.option');
Вам не следует определять Замыкания в файле конфигурации. Их нельзя корректно сериализовать при выполнении пользователем комады Artisan config:cache.

Базовая конфигурация пакета

Вы также можете соединить файл конфигурации пакета с копией приложения. Это позволит пользователям определять только те опции, которые необоходимо переопределить в опубликованной копии конфигурации. Чтобы соединить конфигурацию, используйте метод mergeConfigFrom внутри вашего метода сервис провайдера register: 

/**
 * Register bindings in the container.
 *
 * @return void
 */
public function register()
{
    $this->mergeConfigFrom(
        __DIR__.'/path/to/config/courier.php', 'courier'
    );
}
Этот метод соединяет только первый уровень массива конфигурации. Если ваши пользователи определяют многомерный массив конфигурации, отсутствующие параметры не будут соединены.

Миграции

Если пакет содержит миграции базы данных, вы можете использовать метод loadMigrationsFrom, чтобы проинформировать Ларавел как загружать их. Этот метод принимает путь к миграциям вашего пакета в качестве единственного аргумента: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadMigrationsFrom(__DIR__.'/path/to/migrations');
}

После регистрации миграций вашего пакета, они автоматически будут выполнены при запуске команды php artisan migrate. Нет необходимости экспортировать их в основную папку приложения database/migrations.

Маршруты

Если ваш пакет содержить маршруты, вы можете загрузить их используя метод loadRoutesFrom. Этот метод автоматически определит, если маршруты приложения закешированы и не будет загружать ваш файл маршрутов, если маршруты уже закешированы: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadRoutesFrom(__DIR__.'/routes.php');
}

Локализация

Если ваш пакет содержит файлы перевода на другие языки, вы можете использовать метод loadTranslationsFrom для информирования Ларавел о том, как их загружать. Например, если ваш пакет назван как courier, вы должны добавить следующее в ваш метод сервис провайдера boot: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');
}

Чтобы ссылаться на фразы перевода можно использовать аналогичный синтаксис package::file.line. Таким образом вы можете загрузить строку welcome пакета courier из файла messages следующим образом: 

echo trans('courier::messages.welcome');

Публикация переводов

Если вы хотите опубликовать переводы в папку приложения resources/lang/vendor, вы можете использовать метод сервис провайдера publishes. Этот метод принимает массив путей пакета и желаемую папку для публикации. Например, для публикации файлов перевода для пакета courier вы можете сделать следующее: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');

    $this->publishes([
        __DIR__.'/path/to/translations' => resource_path('lang/vendor/courier'),
    ]);
}

Теперь, когда пользователи вашего пакета выполняют команду Artisan vendor:publish, переводы вашего пакета будут опубликованны в указанную директорию.

Представления

Для регистрации ваших представлений пакета вам необходимо рассказать Ларавел, где расположены представления. Вы можете сделать это используя метод loadViewsFrom. Этот метод принимает два аргумента: путь к шаблонам представлений и имя вашего пакета. Например, если название вашего пакета courier, то вам необходимо добавить следующее в метод boot вашего сервис провайдера: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');
}

Представления пакета ссылаются используя package::view конструкцию синтаксиса. Поэтому, после регистрации пути вашего представления в сервис провайдере, вы можете загрузить представление admin из пакета courier следующим образом: 

Route::get('admin', function () {
    return view('courier::admin');
});

Переопределение представлений пакета.

При использовании метода loadViewsFrom Ларавел на практике регистрирует две локации для ваших представлений: папка приложения resources/views/vendor и указанная директория. Поэтому, используя пример courier, Laravel в первую очередь проверяет, что пользовательская версия представления находится в папке resources/views/vendor/courier. После чего, если представление не было настроено пользователем, Ларавел будет искать директорию пакета, которая указана в вызове loadViewsFrom. Такой подход делает настройку представлений для пользователей пакета простой и понятной.

Публикация представлений

Если вы хотите сделать представления доступными для публикации в папку приложения resources/views/vendor, вы можете использовать метод сервис провайдера publishes. Метод publishes принимает массив путей представлений пакета и соответсвующее предполагаемое место публикации: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');

    $this->publishes([
        __DIR__.'/path/to/views' => resource_path('views/vendor/courier'),
    ]);
}

Теперь, когда пользователи вашего пакета выполняют команду Artisan vendor:publish, представления пакета будут скопированы в указанные папки.

Команды

Для регистрации команды Artisan пакета для Ларавел, вы можете исопльзовать метод commands. Этот метод принимает массив команд имён класса. После регистрации команд вы можете выполнить их используя командную строку Артизан: 

/**
 * Bootstrap the application services.
 *
 * @return void
 */
public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            FooCommand::class,
            BarCommand::class,
        ]);
    }
}

Публичные активы

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

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/path/to/assets' => public_path('vendor/courier'),
    ], 'public');
}

Теперь, когда пользователи вашего пакета выполняют команду vendor:publish, ваши активы будут скопированы в указанную локацию. В силу того, что обычно необходимо перезаписывать файлы каждый раз при обновлении пакета, вы можете использовать опцию --force: 

php artisan vendor:publish --tag=public --force

Публикация групп файлов

Вы можете опубликовать группу файлов пакета отдельно. Например, вы можете захотеть позволить пользователям проводить публикацию файлов конфигурации без необходимости публикации остальных активов. Вы можете это сделать используя тэги во время вызова метод publishes сервис провайдера пакета. Например, давайте используем тэги для определения двух групп методе boot сервис провайдера пакета: 

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/../config/package.php' => config_path('package.php')
    ], 'config');

    $this->publishes([
        __DIR__.'/../database/migrations/' => database_path('migrations')
    ], 'migrations');
}

Теперь ваши пользователи могут публиковать эти группы отдельно путём обращения к имени тэга при выполнении команды vendor:publish: 

php artisan vendor:publish --tag=config