Может войдёшь?
Черновики Написать статью Профиль

Разработка пакетов

перевод документация 5.х

  1. 1. Введение
  2. 2. Сервис-провайдеры
  3. 3. Маршруты
  4. 4. Ресурсы
    1. 4.1. Представления
    2. 4.2. Переводы
    3. 4.3. Настройки
  5. 5. Общие ресурсы
  6. 6. Публикация файлов по группам
Этот перевод актуален для англоязычной документации на (ветка 5.1) и (ветка 5.0). Опечатка? Выдели и нажми Ctrl+Enter.

Введение

Пакеты (packages) — основной способ добавления нового функционала в Laravel. Пакеты могут быть всем, чем угодно — от классов для удобной работы с датами наподобие Carbon, до целых библиотек BDD-тестирования наподобие Behat.

Конечно, есть разные типы пакетов. Некоторые пакеты автономны, что позволяет им работать в составе любого фреймворка, не только Laravel. Примерами таких отдельных пакетов являются и Carbon, и Behat. Любой из них может быть использован в Laravel с помощью простого указания их в файле composer.json.

С другой стороны, некоторые пакеты разработаны специально для использования в Laravel. Они могут содержать маршруты, контроллеры, представления и настройки, специально рассчитанные для улучшения приложения на Laravel. Этот раздел документации в основном посвящён разработке именно пакетов для Laravel.

Все пакеты Laravel распространяются через Packagist и Composer, поэтому нужно изучить эти прекрасные средства распространения пакетов для PHP.

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

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

Сервис-провайдер наследует класс Illuminate\Support\ServiceProvider и содержит два метода: PHPregister() и PHPboot(). Базовый класс ServiceProvider находится в пакете Composer illuminate/support, который вы должны добавить в зависимости своего пакета.

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

Маршруты

Чтобы определить маршруты для своего пакета, просто затребуйте (PHPrequire) файл маршрутов в методе PHPboot() вашего сервис-провайдера. В этом файле вы можете использовать фасад Route для регистрации маршрутов, точно так же, как в обычном приложении Laravel:

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  if (! 
$this->app->routesAreCached()) {
    require 
__DIR__.'/../../routes.php';
  }
}
+ 5.0

добавлено в 5.0 ()

Чтобы загрузить файл маршрутов для вашего пакета, просто подключите его (include) в методе PHPboot() вашего сервис-провайдера.

PHP
public function boot()
{
  include 
__DIR__.'/../../routes.php';
}

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

Ресурсы

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

Для регистрации представлений вашего пакета в Laravel, вам надо указать Laravel, где они расположены. Вы можете сделать это методом PHPloadViewsFrom(). Этот метод принимает два аргумента: путь к шаблонам ваших представлений и название пакета. Например, если ваш пакет называется «courier», добавьте в метод PHPboot() своего сервис-провайдера следующее:

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  
$this->loadViewsFrom(__DIR__.'/path/to/views''courier');
}

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

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

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

Когда вы используете метод PHPloadViewsFrom(), на самом деле Laravel регистрирует два расположения для ваших представлений: одно в папке приложения resources/views/vendor, и второе в указанной вами папке. Поэтому в нашем примере с «courier» при запросе представления пакета Laravel сначала проверит, предоставил ли разработчик свою версию представления в PHPresources/views/vendor/courier. Затем, если представление не было изменено, Laravel будет искать в вызове PHPloadViewsFrom() указанную вами папку представлений пакета. Это упрощает редактирование или замену представлений вашего пакета для тех, кто им будет пользоваться.

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

Для публикации представлений вашего пакета в папку resources/views/vendor используйте метод PHPpublishes() в методе PHPboot() вашего сервис-провайдера. Метод PHPpublishes() принимает массив путей к представлениям пакета и соответствующие им места для публикации.

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  
$this->loadViewsFrom(__DIR__.'/path/to/views''courier');

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

Теперь, когда пользователи вашего пакета вызовут Artisan-команду Laravel shvendor:publish, папка ваших представлений будет скопирована в указанное место.

Переводы

Если ваш пакет содержит языковые файлы, вы можете использовать метод PHPloadTranslationsFrom(), чтобы указать Laravel, как их загружать. Например, если ваш пакет называется «courier», вы можете добавить в метод PHPboot() своего сервис-провайдера следующее:

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  
$this->loadTranslationsFrom(__DIR__.'/path/to/translations''courier');
}

На файлы переводов пакета ссылаются, используя синтаксис с двойным двоеточием. Поэтому вы можете загрузить строку welcome пакета courier из файла messages таким образом:

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

Помните, что в вашей папке с переводами должны быть подпапки для каждого языка, такие как en, es, ru и т.д.

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

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

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  
$this->loadTranslationsFrom(__DIR__.'/path/to/translations''courier');

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

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

Настройки

Скорее всего вы захотите опубликовать файл настроек вашего пакета в папку config самого приложения. Это позволит пользователям вашего пакета легко изменять настройки по умолчанию. Для публикации файла настроек просто используйте метод PHPpublishes() из метода PHPboot() вашего сервис-провайдера:

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  
$this->publishes([
    
__DIR__.'/path/to/config/courier.php' => config_path('courier.php'),
  ]);
}

Теперь, когда пользователи вашего пакета вызовут команду Laravel shvendor:publish, ваш файл будет скопирован в указанное место. Само собой, когда ваш файл настроек опубликован, к нему можно обращаться как к любому другому файлу настроек:

PHP
$value config('courier.option');

Настройки пакета по умолчанию

Вы также можете выбрать вариант соединения файла настроек вашего пакета с его копией в приложении. Это позволит вашим пользователям включать только те параметры, которые они хотят изменить в опубликованной копии конфигурации. Для объединения конфигураций используйте метод PHPmergeConfigFrom() в методе PHPregister() вашего сервис-провайдера:

PHP
/**
 * Регистрация привязок в контейнере.
 *
 * @return void
 */
public function register()
{
  
$this->mergeConfigFrom(
    
__DIR__.'/path/to/config/courier.php''courier'
  
);
}

Общие ресурсы

Ваши пакеты могут иметь ресурсы, такие как JavaScript, CSS и изображения. Для публикации этих ресурсов в папку приложения public используйте метод PHPpublishes() в методе PHPboot() вашего сервис-провайдера. В этом примере мы также добавим для ресурсов групповой тег «public», который можно использовать для публикации групп связанных ресурсов:

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @return void
 */
public function boot()
{
  
$this->publishes([
    
__DIR__.'/path/to/assets' => public_path('vendor/courier'),
  ], 
'public');
}

Теперь, когда пользователи вашего пакета вызовут команду Laravel shvendor:publish, ваши ресурсы будут скопированы в указанное место. Поскольку обычно каждый раз при обновлении пакета вам необходимо перезаписать ресурсы, используйте флаг sh--force:

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

Если вы хотите быть уверены, что ваши ресурсы всегда в актуальном состоянии, можете добавить эту команду в список post-update-cmd в вашем файле composer.json:

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

Вам может пригодиться возможность публиковать отдельные группы файлов. Например, если вы захотите дать вашим пользователям возможность публиковать файлы настроек вашего пакета и файлы ресурсов по отдельности. Вы можете сделать это, присвоив им теги при вызове метода PHPpublishes(). Например, давайте определим две группы для публикации в методе PHPboot() сервис-провайдера пакета:

PHP
/**
 * Выполнение после-регистрационной загрузки сервисов.
 *
 * @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');
}

Теперь вы можете публиковать эти файлы отдельно, указывая их тег при использовании Artisan-команды shvendor:publish:

shphp artisan vendor:publish --provider="Vendor\Providers\PackageServiceProvider" --tag="config"
+ 5.0

добавлено в 5.0 ()

Если вы хотите перезаписать существующие файлы, используйте флаг sh--force:

shphp artisan vendor:publish --force

Внимание: Вы можете использовать метод PHPpublishes() для публикации файлов любых типов в любое место.

Написать комментарий

Разметка: ? ?

Авторизуйся, чтобы прокомментировать.