From 69e76ab6d66276eed0fbb5e3858b99c574a66967 Mon Sep 17 00:00:00 2001 From: flip111 Date: Thu, 28 Nov 2013 23:10:29 +0100 Subject: [PATCH 1/2] Improvements to registering an extension (#2) | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | all | Fixed tickets | #9644 (symfony) and #3231 (symfony-docs) 1. The original text is good but the topic of that paragraph is not "extension conventions" but "registering an extension" (i.e. if you follow these conventions then register goes like so ..) 2. Cleaned up different terminology "Conventions" v "Standards" -> just conventions now 3. Move this part to a more logical place. First create then register, then modify for additional needs. --- cookbook/bundles/extension.rst | 87 +++++++++++++++++----------------- 1 file changed, 43 insertions(+), 44 deletions(-) diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index da17b973bed..efedfba20d2 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -177,6 +177,49 @@ You can begin specifying configuration under this namespace immediately: array. You can still provide some sensible defaults for your bundle if you want. +Registering the Extension class +------------------------------- + +An Extension class will automatically be registered by Symfony2 when following these simple conventions: + +* The extension must be stored in the ``DependencyInjection`` sub-namespace; + +* The extension must be named after the bundle name and suffixed with + ``Extension`` (``AcmeHelloExtension`` for ``AcmeHelloBundle``); + +* The extension should provide an XSD schema. + +Manually registering an Extension class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To manually register an extension class override the +:method:`Bundle::build() ` +method in your bundle:: + + // ... + use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass; + + class AcmeHelloBundle extends Bundle + { + public function build(ContainerBuilder $container) + { + parent::build($container); + + // register extensions that do not follow the conventions manually + $container->registerExtension(new UnconventionalExtensionClass()); + } + } + +In this case, the extension class must also implement a ``getAlias()`` method +and return a unique alias named after the bundle (e.g. ``acme_hello``). This +is required because the class name doesn't follow the conventions by ending +in ``Extension``. + +Additionally, the ``load()`` method of your extension will *only* be called +if the user specifies the ``acme_hello`` alias in at least one configuration +file. Once again, this is because the Extension class doesn't follow the +conventions set out above, so nothing happens automatically. + Parsing the ``$configs`` Array ------------------------------ @@ -511,9 +554,6 @@ For more details, see :doc:`/cookbook/bundles/prepend_extension`. Default Configuration Dump ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 2.1 - The ``config:dump-reference`` command was added in Symfony 2.1 - The ``config:dump-reference`` command allows a bundle's default configuration to be output to the console in YAML. @@ -561,46 +601,5 @@ command. .. index:: pair: Convention; Configuration -Extension Conventions ---------------------- - -When creating an extension, follow these simple conventions: - -* The extension must be stored in the ``DependencyInjection`` sub-namespace; - -* The extension must be named after the bundle name and suffixed with - ``Extension`` (``AcmeHelloExtension`` for ``AcmeHelloBundle``); - -* The extension should provide an XSD schema. - -If you follow these simple conventions, your extensions will be registered -automatically by Symfony2. If not, override the -:method:`Bundle::build() ` -method in your bundle:: - - // ... - use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass; - - class AcmeHelloBundle extends Bundle - { - public function build(ContainerBuilder $container) - { - parent::build($container); - - // register extensions that do not follow the conventions manually - $container->registerExtension(new UnconventionalExtensionClass()); - } - } - -In this case, the extension class must also implement a ``getAlias()`` method -and return a unique alias named after the bundle (e.g. ``acme_hello``). This -is required because the class name doesn't follow the standards by ending -in ``Extension``. - -Additionally, the ``load()`` method of your extension will *only* be called -if the user specifies the ``acme_hello`` alias in at least one configuration -file. Once again, this is because the Extension class doesn't follow the -standards set out above, so nothing happens automatically. - .. _`FrameworkBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php .. _`TwigBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php From 60ab4d00b76dd609695ba5ea001254aa7cca933d Mon Sep 17 00:00:00 2001 From: flip111 Date: Fri, 29 Nov 2013 00:40:54 +0100 Subject: [PATCH 2/2] Changed due to comments in repo collab --- cookbook/bundles/extension.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index efedfba20d2..cd0f08467d0 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -177,10 +177,11 @@ You can begin specifying configuration under this namespace immediately: array. You can still provide some sensible defaults for your bundle if you want. -Registering the Extension class +Registering the Extension Class ------------------------------- -An Extension class will automatically be registered by Symfony2 when following these simple conventions: +An Extension class will automatically be registered by Symfony2 when +following these simple conventions: * The extension must be stored in the ``DependencyInjection`` sub-namespace; @@ -189,10 +190,11 @@ An Extension class will automatically be registered by Symfony2 when following t * The extension should provide an XSD schema. -Manually registering an Extension class +Manually Registering an Extension Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To manually register an extension class override the +When not following the conventions you will have to manually register your +extension. To manually register an extension class override the :method:`Bundle::build() ` method in your bundle:: @@ -554,6 +556,9 @@ For more details, see :doc:`/cookbook/bundles/prepend_extension`. Default Configuration Dump ~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 2.1 + The ``config:dump-reference`` command was added in Symfony 2.1 + The ``config:dump-reference`` command allows a bundle's default configuration to be output to the console in YAML.