Пакеты

Статистика: Символов — 7 707/6 533 без пробелов (5 352/4 560 без кода):, слов — 793
Разметка: Wiki
{{TOC}}

== Основы ==
**Пакеты** (англ. //bundle//) лежат в основе улучшений, сделанных в Laravel 3. Они позволяют легко структурировать код в удобные для распространения модульные "пакеты". //Пакет// может иметь свои собственные ((docs/v3/views шаблоны)), ((47 настройки)), ((docs/v3/routing маршруты)), ((docs/v3/database/migrations миграции)), ((docs/v3/artisan/tasks задания "Artisan")) и т.д. //Пакетом// может быть всё - начиная от ORM и заканчивая продвинутой системой управления правами. Модульность такого рода - важное понятие, которое стоит почти за всеми решениями в Laravel. На самом деле, во многих случаях вы можете думать о папке **application** как о специальном //пакете//, с которым Laravel работает по умолчанию.

== Создание пакетов ==
Первый шаг при создании //пакета// - сделать для него папку в **bundles**.Например, давайте создадим //пакет// **admin**, который будет содержать в себе административный центр управления нашим приложением. Файл **application/start.php** даёт возможность настроить окружение, в котором будет работать наше вёб-приложение; точно так же мы создадим файл **start.php** в папке нашего нового //пакета// - он будет загружаться каждый раз при запуске //пакета//.

%%
  <?php
  // Файл: bundles/admin/start.php

  Autoloader::namespaces(array(
    'Admin' => Bundle::path('admin').'models',
  ));
%%

Здесь мы говорим ((docs/v3/loading автозагрузчику)), что классы в пространстве имён %%Admin%% должны загружаться из папки **models** нашего пакета. Вы можете делать всё, что угодо в своём %%(t)start.php%%, но обычно он предназначен для регистрации классов в автозагрузчике. Но на самом деле **вам даже не обязательно создавать этот файл**.

Теперь посмотрим, как зарегистрировать пакет в нашем приложении.

== Регистрация пакетов ==
Теперь когда у нас есть //пакет// **admin** нам нужно его зарегистрировать внутри Laravel. Откройте файл **application/bundles.php** - это как раз то место, куда вносятся все //пакеты//.

%%
  <?php
  // Файл: application/bundles.php

  return array('admin');
%%

По умолчанию Laravel предположит, что //пакет// **admin** находится внутри папки **bundles**, но при желании мы можем указать иное размещение:
%%
  <?php
  // Файл: application/bundles.php

  return array(
    'admin' => array('location' => 'userscape/admin'),
  );
%%

После этого Laravel будет искать //пакет// в %%(t)bundles/userscape/admin%%.

== Загрузка классов ==
Обычно **start.php** любого пакета содержит только определения для ((docs/v3/loading автозагрузчика классов)). Если это так, то мы можем не создавать этот файл, а внести их прямо в запись пакета в %%application/bundles.php%%.

**Задание правил автозагрузки в настройках пакета:**
%%
  <?php
  // Файл: application/bundles.php

  return array(
    'admin' => array(
      'autoloads' => array(
        'map' => array(
          'Admin' => '(:bundle)/admin.php',
        ),
        'namespaces' => array(
          'Admin' => '(:bundle)/lib',
        ),
        'directories' => array(
          '(:bundle)/models',
        ),
      ),
    ),
  );
%%

Заметьте, что каждый элемент массива соответствует методу ((docs/v3/loading автозагрузчика)). На самом деле значения этих настроек автоматически передаются в соответствующий метод.

Как вы видите, здесь используется **(:bundle)** - она заменяется на путь к //пакету//, чтобы вам не нужно было писать его вручную.

== Запуск пакетов ==
Наш //пакет// ((#создание создан)) и ((#регистрация зарегистрирован)), но мы ещё не можем его использовать. Для начала нам нужно его //запустить//; это делается следующим вызовом:
%%
  Bundle::start('admin');
%%

Laravel загрузит файл **start.php** в папке //пакета//, а так же **routes.php**, где обычно регистрируются ((docs/v3/routing маршруты)) и ((docs/v3/controllers контроллеры)). Любой из файлов загружается только, если он существует.

.(alert)
Пакет запускается только один раз, все последующие вызовы %%Bundle::start%% будут проигнорированы.

Если вы очень часто используете какой-то //пакет// в своём приложении, то было бы полезно запускать его в начале каждого запроса. Это можно сделать, настроив %%(t)application/bundles.php%%.

**Включение автозапуска для пакета:**
%%
  <?php
  // Файл: application/bundles.php

  return array(
    'admin' => array('auto' => true),
  );
%%

Вам не всегда понадобиться запускать пакет вручную - вы можете использовать его при необходимости, а Laravel загрузит его сам. Это произойдён при обращении к его ((docs/v3/views шаблону)), ((47 настройке)), языковой строке, ((docs/v3/routing маршруту)) или ((docs/v3/routing#фильтр+ы))у.

((#event))
Каждый раз при запуске //пакета// возникает ((docs/v3/events событие)), которое вы можете отслеживать.

**Отслеживание события при запуске пакета:**
%%
  Event::listen('laravel.started: admin', function () {
    // Пакет "admin" был запущен...
  });
%%

**Отключение пакета - он никогда не будет запущен:**
%%
  Bundle::disable('admin');
%%

== Маршрутизация ==
См. соответствующие разделы в документации по ((docs/v3/routing#пакеты маршрутам)) и ((docs/v3/controllers#пакеты контроллерам)).

== Обращение к ресурсам ==
Как уже упоминалось выше, //пакеты// могут содержать ((docs/v3/views шаблоны)), ((47 настройки)), языковые файлы и многое другое. Laravel использует **двойное двоеточие (%%(t)::%%)** для указания пакета в имени этих элементов.

**Загрузка шаблона в пакете:**
%%
  return View::make('admin::view');
  // возможное размещение: bundles/admin/views/view.php
%%

**Чтение настройки пакета:**
%%
  return Config::get('admin::file.option');
  // возможное размещение: bundles/admin/config/file.php
%%

**Чтение языковой строки пакета:**
%%
  return Lang::line('admin::file.line');
  // возможное размещение: bundles/admin/languages/en/file.php
%%

Иногда вам может понадобиться узнать системную информацию о пакете - существует ли он, где находится или что-то из его опций в %%(t)application/bundles.php%%. Посмотрим, как это делается.

**Определение существования пакета:**
%%
  Bundle::exists('admin');
%%

**Получение пути к пакету:**
%%
  $location = Bundle::path('admin');
%%

**Чтение массива опций пакета:**
%%
  $config = Bundle::get('admin');
%%

**Получение списка установленных пакетов:**
%%
  $names = Bundle::names();
%%

== Публикация вёб-содержимого ==
Если ваш //пакет// содержит ((docs/v3/views шаблоны)), то он наверняка содержит и нужные ему файлы JavaScript, картинки и прочее - они обычно расположены в его подпапке **public**. Однако для доступа из Интернета они должны быть внутри папки **public** вашего приложения - для этого просто скопируйте их туда (например, %%(t)bundles/admin/public/styles.css%% в %%(t)public/bundles/admin/styles.css%%).

Если у вас есть доступ к командной строке, вы можете использовать "((docs/v3/artisan/tasks Artisan))":
%%(sh)
  php artisan bundle:publish
%%

Эта команда создаст подпапку в **public** для каждого //пакета// и скопирует туда все файлы из его папки **public**. Например, если у вас есть пакет **admin**, //Artisan// разместит его ресурсы в %%(t)public/bundles/admin%%.

Больше информации о том, как удобно адресоваться к ресурсам вашего //пакета// содержится в разделе про ((docs/v3/views/assets#пакеты ресурсы)).

== Установка пакетов ==
Конечно, вы можете устанавливать //пакеты// вручную, но интерфейс командной строки "((docs/v3/artisan/tasks Artisan))" даёт возможность автоматически устанавливать и обновлять их. Для распространения пакетов используются обычные ((ВП:ZIP))-архивы.

**Установка пакета с помощью Artisan:**
%%(sh)
  php artisan bundle:install eloquent
%%

Отлично! Теперь вы можете ((#регистрация зарегистрировать)) ваш новый пакет и ((#публикация опубликовать)) его вёб-содержимое.

**Официальное хранилище пакетов:** %%(t)http://bundles.Laravel.com%%.

== Обновление пакетов ==
.(alert)
При обновлении с помощью "((docs/v3/artisan/tasks Artisan))" старая папка пакета будет полностью удалена, включая файлы настроек и ваши другие возможные изменения.

%%(sh)
  php artisan bundle:upgrade admin
%%

**Внимание:** после обновления вам может потребоваться ((#публикация переопубликовать)) вёб-содержимое данного //пакета//.

Так как обновление полностью удаляет старую версию пакета на данный момент рекомендуется использовать ((#event события загрузки)) для изменения настроек пакета вместо использования его папки **config**. Например:
%%
  // Файл: application/start.php

  Event::listen('laravel.started: admin', function () {
    Config::set('admin::file.option', 'the_value');
  });
%%