Система пакетов

Дата обновления перевода 2025-07-05

Система пакетов

Warning

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

Пакет похож на плагин в других ПО, только лучше. Базовые функции фреймворка Symfony релизуются с помощью пакетов FrameworkBundle, SecurityBundle, DebugBundle, и др.). Они также используются для добавления новых функций в ваше приложение через сторонние пакеты.

Пакеты, используемые в вашем приложении, должны быть подключены для каждого окружения в файле config/bundles.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// config/bundles.php
return [
    // 'all' означает, что пакет включен для любого окружения Symfony
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    // ...

    // этот пакет включен только в 'dev'
    Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true],
    // ...


    // этот пакет включен только в 'dev' и 'test', поэтому вы не можете использовать его в 'prod'
    Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
    // ...
];

Tip

В приложении Symfony по умолчанию, которое использует Symfony Flex, пакеты подключаются и отключаются для вас автоматически при их установке или удалении, поэтому вам не нужно искать или редактировать файл bundles.php.

Cоздание пакета

Этот раздел создаёт и включает новый пакет, чтобы продемонстрировать, как это легко сделать. Новый пакет называется AcmeTestBundle, где часть Acme - просто шаблонное имя, которое нужно заменить неким именем "поставщика", который представляет вас или вашу организацию (например, ABCTestBundle для компании по имени ABC).

Начните с создания нового класса под названием AcmeBlogBundle:

1
2
3
4
5
6
7
8
// src/AcmeBlogBundle.php
namespace Acme\BlogBundle;

use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class AcmeBlogBundle extends AbstractBundle
{
}

Warning

Если ваш пакет должен быть совместим с предыдущими версиями Symfony, то вам необходимо расширять из Bundle вместо этого.

Tip

Имя AcmeTestBundle следует стандартным договоренностям присваивания имен пакетам . Вы также можете решить укоротить имя пакета до TestBundle, назвав этот класс TestBundle (и назвав файл TestBundle.php).

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

1
2
3
4
5
// config/bundles.php
return [
    // ...
    Acme\BlogBundle\AcmeBlogBundle::class => ['all' => true],
];

И хотя он пока ничего не делает, AcmeTestBundle готов к использованию.

Структура каталога пакета

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

assets/
Содержит JavaScript, CSS, изображения и другие ресурсы, связанные с пакетом, которые не находятся в public/ (например, контроллеры stimulus)
config/
Содержит конфигурацию, включительно с конфигурацией маршрутизации (например, routing.yaml).
public/
Содержит веб-ресурсы (изображения, таблицы стилей и т.д.) и копируется или символьно ссылается на каталог проекта public/ через консольную команду assets:install.
src/
Содержит все PHP-классы, связанные с логикой пакета (например, Controller/RandomController.php).
templates/
Содержит шаблоны, организованные по имени контроллера (например, random/index.html.twig).
tests/
Содержит все тесты пакета.
translations/
Содержит переводы, организованные по домену и локали (например, AcmeTestBundle.en.xlf).

Warning

В Symfony 5 была изменена рекомендуемая структура пакетов, читайте Документацию по пакетам Symfony 4.4 для получения информации о старой структуре.

При использовании нового класса AbstractBundle, пакет по умолчанию переходит на новую структуру. Переопределите метод Bundle::getPath() для перехода на старую структуру:

1
2
3
4
5
6
7
class AcmeBlogBundle extends AbstractBundle
{
    public function getPath(): string
    {
        return __DIR__;
    }
}

Tip

Рекомендуется использовать стандарт автозагрузки PSR-4: в качестве ключа использовать пространство имен, а в качестве значения - местоположение главного класса пакета (относительно composer.json). Так как основной класс находится в каталоге rc/ пакета:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "autoload": {
        "psr-4": {
            "Acme\\BlogBundle\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\BlogBundle\\Tests\\": "tests/"
        }
    }
}

Узнайте больше