Skip to content

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

Merged
merged 2 commits into from
Dec 23, 2013
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 43 additions & 44 deletions cookbook/bundles/extension.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Class

Copy link
Contributor Author

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)

Copy link
Member

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK

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

An Extension class will automatically be registered by Symfony2 when following these simple conventions:
Copy link
Member

Choose a reason for hiding this comment

The 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

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this is correct, I'll investigate it tomorrow

Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That means it should not be put in this list

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Member

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Manually Registering an Extension Class

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No it is not

method in your bundle::
Copy link
Member

Choose a reason for hiding this comment

The 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)::

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Member

Choose a reason for hiding this comment

The 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
------------------------------

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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