Demystifying Bundles

Demystifying

Bundles

View Slide

Lead Software Developer

eos.uptrade GmbH

[email protected]

@jschaedl
Jan Schädlich

View Slide

@jschaedl
Why a talk about Bundles?

View Slide

@jschaedl
What do we cover?

View Slide

@jschaedl
A little history

View Slide

@jschaedl
A little history
1 2 4 4.4 6.1

View Slide

@jschaedl
A little history
Symfony 1 already provided
a plugin system.
1 2 4 4.4 6.1

View Slide

@jschaedl
A little history
a plugin system.
Symfony 2 came with the bundle system and
a recommendation to even organise your
application code using the AppBundle.
1 2 4 4.4 6.1

View Slide

@jschaedl
A little history
a plugin system.
Organising application code by using
bundles is not recommended anymore.
1 2 4 4.4 6.1

View Slide

@jschaedl
A little history
a plugin system.
The bundle folder structure was updated to
follow the Symfony standard application.
(The old structure is still supported)
1 2 4 4.4 6.1

View Slide

@jschaedl
A little history
a plugin system.
The bundle folder structure was updated to
follow the Symfony standard application.
(The old structure is still supported)
Easier bundle extension and
configuration was introduced.
1 2 4 4.4 6.1

View Slide

@jschaedl
What is a Bundle
… on a higher level
‣ It is an extension point to Symfony

‣ It works like a “plugin” in other programming environments

‣ It can add new features to an existing Symfony application

‣ It can be shared by multiple Symfony applications

View Slide

@jschaedl
What is a Bundle
… on a lower level
‣ It can add/remove/manipulate services in Symfony's DI
container based on bundle speci
fi
c con
fi
guration

‣ It can de
fi
ne routing con
fi
guration

‣ It can provide templates

‣ It can provide translations

‣ …

View Slide

@jschaedl
What is a Bundle
… on a lower level
‣ It can add/remove/manipulate services in Symfony's DI
container based on bundle speci
fi
c con
fi
guration

‣ It can de
fi
ne routing con
fi
guration

‣ It can provide templates

‣ It can provide translations

‣ …
/

├── config/

├── docs/

│ └─ index.md

├── public/

├── src/

│ ├── Controller/

│ ├── DependencyInjection/

│ └── AcmeBlogBundle.php

├── templates/

├── tests/

├── translations/

├── LICENSE

└── README.md

View Slide

@jschaedl
Building blocks
‣ All classes we need to create a bundle are provided by
Symfony's HttpKernel component

‣ The Symfony Framework itself uses bundles to couple and
provide functionality based on its components

View Slide

// /src/SymfonyWorldBundle.php

use Symfony\Component\HttpKernel\Bundle\Bundle;

class SymfonyWorldBundle extends Bundle

{

}

View Slide

// /config/bundles.php

use Symfony\Bundle\FrameworkBundle\FrameworkBundle;

use Symfony\Bundle\SymfonyWorldBundle\SymfonyWorldBundle;

return [

FrameworkBundle::class => ['all' => true],

SymfonyWorldBundle::class => ['all' => true],

];

View Slide

// /config/bundles.php

{

"kernel.bundles": {

"FrameworkBundle": "Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle",

"SymfonyWorldBundle": "Symfony\\Bundle\\SymfonyWorldBundle\\SymfonyWorldBundle"

}

}

View Slide

// /src/SymfonyWorldService.php

class SymfonyWorldService implements SymfonyWorldServiceInterface

{

public function __construct(

private readonly Edition $edition,

private readonly int $year

) {

}

public function show(): string

{

return sprintf('Symfony World %s Edition %d', $this->edition->value, $this->year);

}

}

View Slide



{




) {

}


{


}

}
interface SymfonyWorldServiceInterface

{

public function show(): string;

}

View Slide



{




) {

}


{


}

}

{


}
enum Edition: string

{

case SUMMER = 'Summer';

case WINTER = 'Winter';

}

View Slide



{




) {

}


{


}

}

{


}
enum Edition: string

{

case SUMMER = 'Summer';

case WINTER = 'Winter';

}
$service = new SymfonyWorldService(Edition::SUMMER, 2022);

echo $service->show();

// Symfony World Summer Edition 2022

View Slide

// /config/services.php

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

return static function (ContainerConfigurator $container) {

$services = $container->services();

$services

->set(‘symfony_world.service’, SymfonyWorldService::class)

->private()

->args([abstract_arg('edition'), abstract_arg('year')]);

};

View Slide

// /src/DependencyInjection/Configuration.php

class Configuration implements ConfigurationInterface

{

public function getConfigTreeBuilder(): TreeBuilder

{

$treeBuilder = new TreeBuilder('symfony_world'); // bundle extension alias => symfony_world

$rootNode = $treeBuilder->getRootNode();

$rootNode->children()

->enumNode('edition')

->values(array_map(fn (Edition $edition) => $edition->value, Edition::cases()))

->end()

->scalarNode('year')->end()

->end()

;

return $treeBuilder;

}

}

View Slide

// /src/DependencyInjection/Configuration.php

symfony_world:

edition: Summer

year: 2022

View Slide

// /src/DependencyInjection/SymfonyWorldExtension.php

class SymfonyWorldExtension extends Extension

{

public function load(array $configs, ContainerBuilder $container)

{

$config = $this->processConfiguration(

$this->getConfiguration($configs, $container),

$configs

);

$loader = new PhpFileLoader($container, new FileLocator(\dirname(__DIR__, 2).'/config'));

$loader->load('services.php');

$container->getDefinition('symfony_world.service')

->setArgument('$edition', Edition::from($config['edition']))

->setArgument('$year', $config['year']);

}

View Slide

> ./bin/console debug:container symfony_world.service

View Slide

> ./bin/console debug:container symfony_world.service
Information for Service "symfony_world.service"

==========================================

---------------- -------------------------------------------------------

Option Value

---------------- -------------------------------------------------------

Service ID symfony_world.service

Class Symfony\Bundle\SymfonyWorldBundle\SymfonyWorldService

Tags -

Public no

Synthetic no

Lazy no

Shared yes

Abstract no

Autowired no

Autoconfigured no

---------------- -------------------------------------------------------

View Slide

@jschaedl
The Kernel boot process
https://symfony.com/doc/current/introduction/http_fundamentals.html

View Slide

@jschaedl
$request = Request::createFromGlobals();

$kernel = new Kernel('prod', false);

$response = $kernel->handle($request);

$response->send();

View Slide

@jschaedl

View Slide

// vendor/symfony/http-kernel/Kernel.php

public function handle(Request $request, ...): Response

{

// ...

$this->boot();

// ...

return $this->getHttpKernel()->handle($request, $type, $catch);

}

View Slide

@jschaedl
└─ Kernel::boot()

├─ Kernel::preBoot()

│ ├─ Kernel::initializeBundles()

│ │ └─ Kernel::registerBundles()

│ └─ Kernel::initializeContainer()

│ ├─ Kernel::buildContainer()

│ │ ├─ Kernel::prepareContainer()

│ │ │ ├─ SymfonyWorldBundle::getContainerExtension()

│ │ │ ├─ SymfonyWorldBundle::build()

│ │ │ ├─ Kernel::build()

│ │ │ └─ SymfonyWorldBundleExtension::getAlias()

│ │ └─ Kernel::registerContainerConfiguration()

│ │ └─ MicroKernelTrait::configureContainer()

│ └─ ContainerBuilder::compile()

│ └─ Compiler::compile()

│ └─ MergeExtensionConfigurationPass::process()

│ └─ SymfonyWorldBundleExtension::load()

└─ SymfonyWorldBundle::boot()

View Slide

@jschaedl





View Slide

@jschaedl






View Slide


protected function initializeBundles()

{

$this->bundles = [];

foreach ($this->registerBundles() as $bundle) {

$name = $bundle->getName();

if (isset($this->bundles[$name])) {

throw new \LogicException(

sprintf('Trying to register ... same name "%s".', $name)

);

}

$this->bundles[$name] = $bundle;

}

}

View Slide

// src/Kernel.php

use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;

use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel

{

use MicroKernelTrait;

}

View Slide

// vendor/symfony/framwork-bundle/Kernel/MicroKernelTrait.php

public function registerBundles(): iterable

{

$contents = require $this->getBundlesPath();

foreach ($contents as $class => $envs) {

if ($envs[$this->environment] ?? $envs['all'] ?? false) {

yield new $class();

}

// src/Kernel.php

View Slide


public function registerBundles(): iterable

{

$contents = require $this->getBundlesPath();

foreach ($contents as $class => $envs) {

if ($envs[$this->environment] ?? $envs['all'] ?? false) {

yield new $class();

}

// src/Kernel.php

private function getBundlesPath(): string

{

return $this->getConfigDir().'/bundles.php';

}

View Slide


use Symfony\Bundle\FrameworkBundle\FrameworkBundle;

use Symfony\Bundle\SymfonyWorldBundle\SymfonyWorldBundle;

return [

FrameworkBundle::class => ['all' => true],

SymfonyWorldBundle::class => ['all' => true],

];

private function getBundlesPath(): string

{

return $this->getConfigDir().'/bundles.php';

}

View Slide

@jschaedl






View Slide

@jschaedl








View Slide

@jschaedl










View Slide

@jschaedl














View Slide


/**

* Prepares the ContainerBuilder before it is compiled.

*/

protected function prepareContainer(ContainerBuilder $container)

{

$extensions = [];

foreach ($this->bundles as $bundle) {

if ($extension = $bundle->getContainerExtension()) {

$container->registerExtension($extension);

}

// ...

}

View Slide

// vendor/symfony/http-kernel/Bundle/Bundle.php

public function getContainerExtension(): ?ExtensionInterface

{

if (null === $this->extension) {

$extension = $this->createContainerExtension();

if (null !== $extension) {

// ...

$this->extension = $extension;

} else {

$this->extension = false;

}

}

return $this->extension ?: null;

}

View Slide



{




// ...


} else {


}

}


}

protected function createContainerExtension(): ?ExtensionInterface

{

return class_exists($class = $this->getContainerExtensionClass())

? new $class()

: null

;

}

View Slide



{




// ...


} else {


}

}


}

protected function createContainerExtension(): ?ExtensionInterface

{

return class_exists($class = $this->getContainerExtensionClass())

? new $class()

: null

;

}

protected function getContainerExtensionClass(): string

{

$basename = preg_replace('/Bundle$/', '', $this->getName());

return $this->getNamespace().'\\DependencyInjection\\'.$basename.'Extension';

}

View Slide

@jschaedl














View Slide



{

// ...

// register bundle extensions

foreach ($this->bundles as $bundle) {

$bundle->build($container);

}

// ...

}

View Slide


/**

* Builds the bundle.

*

* It is only ever called once when the cache is empty.

*

* This method can be overridden to register compiler passes,

* other extensions, ...

*/

public function build(ContainerBuilder $container): void

{

parent::build($container);

$container->registerExtension(new SymfonyWorldExtension());

}

View Slide

@jschaedl














View Slide



{


// call build() on every bundle

$this->build($container);

// ...

}

View Slide



{


// call Bundle::build() on every bundle

// call Kernel::build()

foreach ($container->getExtensions() as $extension) {

$extensions[] = $extension->getAlias();

}

// ensure these extensions are implicitly loaded

$container

->getCompilerPassConfig()

->setMergePass(new MergeExtensionConfigurationPass($extensions))

;

}

View Slide

@jschaedl














View Slide

// vendor/symfony/http-kernel/KernelInterface.php

interface KernelInterface extends HttpKernelInterface

{

/**

* Loads the container configuration.

*/

public function registerContainerConfiguration(LoaderInterface $loader);

// ...

}

View Slide

@jschaedl















View Slide

// vendor/symfony/framework-bundle/Kernel/MicroKernelTrait.php

private function configureContainer(

ContainerConfigurator $container,

LoaderInterface $loader,

ContainerBuilder $builder

): void {

$configDir = $this->getConfigDir();

$container->import($configDir.'/{packages}/*.{php,yaml}');

$container->import($configDir.'/{packages}/'.$this->environment.'/*.{php,yaml}');

if (is_file($configDir.'/services.yaml')) {

$container->import($configDir.'/services.yaml');

$container->import($configDir.'/{services}_'.$this->environment.'.yaml');

} else {

$container->import($configDir.'/{services}.php');

}

}

View Slide

@jschaedl















View Slide

@jschaedl
















View Slide

// vendor/symfony/dependency-injection/Compiler/Compiler.php

/**

* Run the Compiler and process all Passes.

*/

public function compile(ContainerBuilder $container)

{

// ...

foreach ($this->passConfig->getPasses() as $pass) {

$pass->process($container);

}

// ...

}

View Slide

// vendor/symfony/dependency-injection/Compiler/Compiler.php

/**

* Run the Compiler and process all Passes.

*/

public function compile(ContainerBuilder $container)

{

// ...

foreach ($this->passConfig->getPasses() as $pass) {

$pass->process($container);

}

// ...

}

{


// call Bundle::build() on every bundle

// call Kernel::build()

foreach ($container->getExtensions() as $extension) {

$extensions[] = $extension->getAlias();

}

// ensure these extensions are implicitly loaded

$container

->getCompilerPassConfig()

->setMergePass(new MergeExtensionConfigurationPass($extensions))

;

}

View Slide

@jschaedl

















View Slide

// vendor/symfony/http-kernel/DependencyInjection/MergeExtensionConfigurationPass.php

public function process(ContainerBuilder $container)

{

foreach ($this->extensions as $extension) {

if (!\count($container->getExtensionConfig($extension))) {

$container->loadFromExtension($extension, []);

}

}

parent::process($container);

}

View Slide

// vendor/symfony/http-kernel/DependencyInjection/MergeExtensionConfigurationPass.php


{

foreach ($this->extensions as $extension) {

if (!\count($container->getExtensionConfig($extension))) {

$container->loadFromExtension($extension, []);

}

}

parent::process($container);

}
// vendor/symfony/dependency-injection/ContainerBuilder.php

public function loadFromExtension(

string $extension,

array $values = null

): static {

if ($this->isCompiled()) {

throw new BadMethodCallException(

'Cannot load from an extension on a compiled container.’

);

}

$namespace = $this->getExtension($extension)->getAlias();

$this->extensionConfigs[$namespace][] = $values ?? [];

return $this;

}

View Slide

// vendor/symfony/dependency-injection/Compiler/MergeExtensionConfigurationPass.php


{

// ...

foreach ($container->getExtensions() as $name => $extension) {

if (!$config = $container->getExtensionConfig($name)) {

continue;

}

$resolvingBag = $container->getParameterBag();

// ... resolve config values using container parameters

$config = $resolvingBag->resolveValue($config);

$tmpContainer = new MergeExtensionConfigurationContainerBuilder(

View Slide

if (!$config = $container->getExtensionConfig($name)) {

continue;

}

$resolvingBag = $container->getParameterBag();

// ... resolve config values using container parameters

$config = $resolvingBag->resolveValue($config);

$tmpContainer = new MergeExtensionConfigurationContainerBuilder(

$extension,

$resolvingBag

);

// ...

$extension->load($config, $tmpContainer);

// ... merge $tmpContainer into actual $container

View Slide

@jschaedl


















View Slide



{


{

dump($configs);

// ...

}

}

View Slide



{


{

dump($configs);

// ...

}

}

array:1 [

0 => array:2 [

"edition" => "Summer"

"year" => 2022

]

]

View Slide



{


{



$configs

);

dump($config);

// ...

}

}

View Slide



{


{



$configs

);

dump($config);

// ...

}

}

array:2 [


"year" => 2022

]

View Slide



{


{


new Configuration(),

$configs

);

dump($config);

// ...

}

}

View Slide

// ../src/DependencyInjection/SymfonyWorldExtension.php


{


{



$configs

);



$container

->getDefinition('symfony_world.service')


->setArgument('$year', $config['year'])

View Slide

// ../src/DependencyInjection/SymfonyWorldExtension.php


{


{



$configs

);



$container




// /config/services.php


return static function (ContainerConfigurator $container) {

$services = $container->services();

$services

->set('symfony_world.service', SymfonyWorldService::class)

->private()

->args([abstract_arg('edition'), abstract_arg('year')]);

};

View Slide


{


{



$configs

);



$container




;

}

}

View Slide

@jschaedl

















!" SymfonyWorldBundle::boot()

View Slide


/**

* Boots the Bundle.

*

* The $this->container property is already populated.

*

* Unlike Bundle::build(), Bundle::boot() is called for every Kernel boot.

*/

public function boot(): void

{

// ...

}

View Slide

@jschaedl


















View Slide

@jschaedl
Extension points
‣ ExtensionInterface::load(array $con
fi
gs, ContainerBuilder $container)

‣ Bundle::build(ContainerBuilder $container)

‣ Bundle::boot()

View Slide

@jschaedl
Conventions

View Slide

// vendor/symfony/dependency-injection—kernel/Extension/Extension.php

public function getAlias(): string

{

$className = static::class;

if (!str_ends_with($className, 'Extension')) {

throw new BadMethodCallException('...');

}

$classBaseName = substr(strrchr($className, '\\'), 1, -9);

return Container::underscore($classBaseName);

}

// SymfonyWorldBundle: alias => symfony_world

View Slide



{




}



}

// /config/packages/symfony_world.yaml

symfony_world:

edition: Summer

year: 2022

View Slide



{




}



}

// /config/packages/symfony_world.yaml

symfony_world:

edition: Summer

year: 2022
// /config/packages/sf_world.yaml

sf_world:

edition: Summer

year: 2022

View Slide



{

// ...


{

return 'sf_world';

}

}

// SymfonyWorldBundle: alias => sf_world

View Slide



{




// ...

// check naming convention


$expectedAlias = Container::underscore($basename);

if ($expectedAlias != $extension->getAlias()) {

throw new \LogicException(sprintf('...', $expectedAlias, $extension->getAlias()));

}


} else {

View Slide



{




// ...

// check naming convention


$expectedAlias = Container::underscore($basename);

if ($expectedAlias != $extension->getAlias()) {

throw new \LogicException(sprintf('...', $expectedAlias, $extension->getAlias()));

}


} else {

Users will expect the alias of the default extension of a bundle

to be the underscored version of the bundle name. You can override

Bundle::getContainerExtension() if you want to use another alias.

View Slide


to be the underscored version of the bundle name. You can override

Bundle::getContainerExtension() if you want to use another alias.

final class SymfonyWorldBundle extends Bundle

{

/**

* Override this method in case your Extension does not follow

* the naming convention.

*/


{

return $this->extension ?? new SymfonyWorldExtension();

}

}

View Slide


class SymfonyWorldExtension extends ConfigurableExtension

{

protected function loadInternal(array $mergedConfig, ContainerBuilder $container)

{

$loader = new PhpFileLoader($container, new FileLocator(\dirname(__DIR__).'/config'));


$container

->getDefinition('sf_world.service')

->setArgument('$edition', Edition::from($mergedConfig['edition']))

->setArgument('$year', $mergedConfig['year'])

;

}

}

View Slide


class SymfonyWorldExtension extends ConfigurableExtension

{

protected function loadInternal(array $mergedConfig, ContainerBuilder $container)

{

$loader = new PhpFileLoader($container, new FileLocator(\dirname(__DIR__).'/config'));


$container

->getDefinition('sf_world.service')

->setArgument('$edition', Edition::from($mergedConfig['edition']))

->setArgument('$year', $mergedConfig['year'])

;

}

}

array:2 [


"year" => 2022

]

View Slide

@jschaedl
‣ A Bundle class

‣ A Con
fi
guration class to de
fi
ne bundle con
fi
g

‣ An Extension class which extends from the base Extension class
and implements the ExtensionInterface::load() method to
process bundle con
fi
g and load service de
fi
nitions

‣ Follow the conventions
Bundles prior Symfony 6.1 needed …

View Slide

@jschaedl
‣ Bundle must extend the new abstract class AbstractBundle
Easier bundle con
fi
guration since Symfony 6.1

View Slide


use Symfony\Component\DependencyInjection\ContainerBuilder;


use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class SymfonyWorldBundle extends AbstractBundle

{

public function loadExtension(

array $config,



): void {

$container->import('../config/services.php');

$container->services()

->get('sf_world.service')

->arg('$edition', Edition::from($config['edition']))

View Slide



{

public function loadExtension(

array $config,



): void {

$container->import('../config/services.php');

$container->services()

->get('sf_world.service')

->arg('$edition', Edition::from($config['edition']))

->arg('$year', $config['year'])

;

}

// ...

}

View Slide


use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;



{

// ...

public function configure(DefinitionConfigurator $definition): void

{

$definition->import('../config/definition.php');

}

// ...

}

View Slide

// /config/definition.php


return static function (DefinitionConfigurator $definition) {

$definition->rootNode()

->children()

->enumNode('edition')

->values(array_map(fn (Edition $edition) => $edition->value, Edition::cases()))

->end()

->scalarNode('year')

->end()

->end()

;

};

View Slide





{

// ...


{

$definition->import('../config/definition/*.php');

}

// ...

}

View Slide





{

// ...


{

$definition->rootNode()

->children()

->scalarNode('foo')->defaultValue('bar')->end()

->end()

;

}

// ...

View Slide





{

// ...

protected string $extensionAlias = 'sf_world';

// ...

}

View Slide

@jschaedl
https://symfony.com/blog/new-in-symfony-6-1-simpler-bundle-extension-and-con
fi
guration
https://github.com/symfony/symfony/pull/43701

View Slide

@jschaedl
When to use bundles?

View Slide

@jschaedl
Tipps
‣ Use the new bundle folder structure

‣ Follow the conventions

‣ Use the container con
fi
gurator to de
fi
ne your bundle services

‣ Checkout what famous bundles do and follow along

View Slide

Thank you!
https://speakerdeck.com/jschaedl

View Slide

View Slide

Demystifying Bundles

Demystifying Bundles

Jan Schädlich

More Decks by Jan Schädlich

Other Decks in Programming

Featured

Transcript