How to Add Symfony Bundle to Your Project

PHPMaker User Submitted Tips (PHPMaker)
1

In the last post, I have explained how Symfony bundles extend your app just like plugins. This time, we'll look deeper at Symfony's recipe system, and how to handle it safely in your own application.

1. Installing a Bundle

When you install a Symfony bundle, you are adding a new feature to your application. For example, Symfony UX Icons lets you use SVG icons easily in Twig templates.

To install it:

composer require symfony/ux-icons

This downloads the bundle and makes it available to your project.

2. Recipes and Safe Installation

Some bundles work immediately after installation, but others need extra setup files such as configuration, routes, or assets. These are handled through Symfony recipes, which are small predefined files that tell Symfony how to integrate the bundle automatically.

Normally, Symfony Flex runs these recipes when you install a bundle. However, using Flex directly can cause unwanted file changes under config/packages/. Such changes may break PHPMaker code. To keep full control, PHPMaker does not run Flex directly. Instead, PHPMaker use a console command that applies recipes safely, e.g.

php bin/console app:recipes:install symfony/ux-icons

This performs what Flex normally would:

  • Registers the bundle in config/bundles.php
  • Adds configuration under config/packages/
  • Copies assets into the correct folder

You get the benefits of recipes while keeping your configuration structure intact.

3. What the Recipe Does

Each Symfony recipe tells the installer what needs to be added to your project.
For UX Icons, the recipe only does two things:

  • Registers UXIconsBundle for all environments
  • Copies the default icons from the recipe’s assets/ folder into your project's assets/ director

Unlike many other bundles, UX Icons' recipe does not include a configuration file. That means Symfony won't automatically create a config/packages/ux_icons.yaml file, but you can (and often should) create one yourself to customize default icon attributes and icon sets.

4. Configuration Example

Here's how you can add your own configuration file.

YAML Example

# config/packages/ux_icons.yaml
ux_icons:
    icon_dir: '%kernel.project_dir%/assets/icons'
    default_icon_attributes:
        fill: 'currentColor'
    icon_sets:
        bootstrap:
            alias: 'bi'

Alternatively, you can use PHP configuration file, which is what PHPMaker prefers.

PHP Example

<?php

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    $container->extension('ux_icons', [
        'icon_dir' => '%kernel.project_dir%/assets/icons',
        'default_icon_attributes' => [
            'fill' => 'currentColor',
        ],
        'icon_sets' => [
            'bootstrap' => [
                'alias' => 'bi',
            ],
        ],
    ]);
};

This registers the Bootstrap Icons set under the bootstrap: prefix (mapped to alias bi) and applies default icon attributes to all icons automatically.

5. Using the Bundle

PHPMaker does not use Twig tags by defaut, but you can enable it. In src/config.php, set:

    'USE_TWIG' => true,

You can now render icons in Twig tags, e.g.

{{ ux_icon('bootstrap:alarm', { width: 16, height: 16 }) }}
{{ ux_icon('bootstrap:gear', { width: 32, height: 32 }) }}

Note: If you use class in default_icon_attributes, then avoid passing { class: ... } in Twig, since it replaces, not merges, the default icon attributes.

6. Downloading and Importing Icons

Read:

7. Issues to Consider When Regenerating Your Project

Symfony recipes modify your current project by adding configuration files, assets, or templates.
However, these changes are not persistent in the sense that Symfony does not track or reapply them automatically. And you may also modify the added files yourself, which means the result may differ from the original recipe output.

If you regenerate your PHPMaker project, the recipe-created files may be overwritten or removed.

To avoid losing these adjustments, you can save your modifications so they are recreated automatically.

Next up

In the next topic, I'll explain how to preserve your recipe adjustments so they remain intact after regeneration.

1 Like