-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
Improvements to registering an extension (#2) #3236
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please add a line break after the first word that crosses the 72th character There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. when ~ following |
||
|
||
* 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure if this is correct, I'll investigate it tomorrow There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's not mandatory but good practive if your bundle provides its own config tree. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That means it should not be put in this list There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is outside of the scope of this PR (see improvements points 1,2 and 3). Please submit a new PR for this. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I see no reason not to do such small change in this PR? |
||
|
||
Manually registering an Extension class | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Manually Registering an Extension Class There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It Looks Pretty, CamelCase, But No We Don't Write English Like This There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes we write english like that and call it Title Case... http://symfony.com/doc/current/contributing/documentation/standards.html#language-standards There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Actually we do (see http://symfony.com/doc/current/contributing/documentation/standards.html#language-standards). Sorry, was too late. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. OK |
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To manually register an extension class override the | ||
:method:`Bundle::build() <Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build>` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. :method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build` There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is outside of the scope of this PR (see improvements points 1,2 and 3). Please submit a new PR for this. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No it is not |
||
method in your bundle:: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. method in your bundle (e.g. when the extension does not follow the conventions):: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I belief you can follow the conventions and still manual register your extension. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, that's why I added "e.g." as an example why you would want to do that. Btw, I see no reason why you want to register it when it already would get registered by Symfony? |
||
|
||
// ... | ||
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() <Symfony\\Component\\HttpKernel\\Bundle\\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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Class
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
class here is not used as php keyword but as regular english. The rest of the docs are wrong. Extension is a class name (and thus refering to actual code)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Class should be uppercased, following our capitialization rules
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK