|
1 | 1 | .. index:: |
2 | 2 | single: Bundle; Inheritance |
3 | | - single: Bundle; Overriding |
4 | 3 |
|
5 | 4 | How to use Bundle Inheritance to Override parts of a Bundle |
6 | 5 | =========================================================== |
7 | 6 |
|
8 | | -This article has not been written yet, but will soon. If you're interested |
9 | | -in writing this entry, see :doc:`/contributing/documentation/overview`. |
| 7 | +When working with third-party bundles, you'll probably come across a situation |
| 8 | +where you want to override a file in that third-party bundle with a file |
| 9 | +in one of your own bundles. Symfony gives you a very convenient way to override |
| 10 | +things like controllers, templates, translations, and other files in a bundle's |
| 11 | +``Resources/`` directory. |
10 | 12 |
|
11 | | -This topic is meant to show how you can make one bundle "extend" another |
12 | | -and use this to override different aspects of that bundle. |
| 13 | +For example, suppose that you're installing the `FOSUserBundle`_, but you |
| 14 | +want to override its base ``layout.html.twig`` template, as well as one of |
| 15 | +its controllers. Suppose also that you have your own ``AcmeUserBundle`` |
| 16 | +where you want the overridden files to live. Start by registering the ``FOSUserBundle`` |
| 17 | +as the "parent" of your bundle:: |
| 18 | + |
| 19 | + // src/Acme/UserBundle/AcmeUserBundle.php |
| 20 | + namespace Acme\UserBundle; |
| 21 | + |
| 22 | + use Symfony\Component\HttpKernel\Bundle\Bundle; |
| 23 | + |
| 24 | + class AcmeUserBundle extends Bundle |
| 25 | + { |
| 26 | + public function getParent() |
| 27 | + { |
| 28 | + return 'FOSUserBundle'; |
| 29 | + } |
| 30 | + } |
| 31 | + |
| 32 | +By making this simple change, you can now override several parts of the ``FOSUserBundle`` |
| 33 | +simply by creating a file with the same name. |
| 34 | + |
| 35 | +Overriding Controllers |
| 36 | +~~~~~~~~~~~~~~~~~~~~~~ |
| 37 | + |
| 38 | +Suppose you want to add some functionality to the ``registerAction`` of a |
| 39 | +``RegistrationController`` that lives inside ``FOSUserBundle``. To do so, |
| 40 | +just create your own ``RegistrationController.php`` file, override the bundle's |
| 41 | +original method, and change its functionality:: |
| 42 | + |
| 43 | + // src/Acme/UserBundle/Controller/RegistrationController.php |
| 44 | + namespace Acme\UserBundle\Controller; |
| 45 | + |
| 46 | + use FOS\UserBundle\Controller\RegistrationController as BaseController; |
| 47 | + |
| 48 | + class RegistrationController extends BaseController |
| 49 | + { |
| 50 | + public function registerAction() |
| 51 | + { |
| 52 | + $response = parent:registerAction(); |
| 53 | + |
| 54 | + // do custom stuff |
| 55 | + |
| 56 | + return $response; |
| 57 | + } |
| 58 | + } |
| 59 | + |
| 60 | +.. tip:: |
| 61 | + |
| 62 | + Depending on how severely you need to change the behavior, you might |
| 63 | + call ``parent::registerAction()`` or completely replace its logic with |
| 64 | + your own. |
| 65 | + |
| 66 | +.. note:: |
| 67 | + |
| 68 | + Overriding controllers in this way only works if the bundle refers to |
| 69 | + the controller using the standard ``FOSUserBundle:Registration:register`` |
| 70 | + syntax in routes and templates. This is the best practice. |
| 71 | + |
| 72 | +Overriding Resources: Templates, Routing, Translations, Validation, etc |
| 73 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 74 | + |
| 75 | +Most resources can also be overridden, simply by creating a file in the same |
| 76 | +location as your parent bundle. |
| 77 | + |
| 78 | +For example, it's very common to need to override the ``FOSUserBundle``'s |
| 79 | +``layout.html.twig`` template so that it uses your application's base layout. |
| 80 | +Since the file lives at ``Resources/views/layout.html.twig`` in the ``FOSUserBundle``, |
| 81 | +you can create your own file in the same location of ``AcmeUserBundle``. |
| 82 | +Symfony will ignore the file that lives inside the ``FOSUserBundle`` entirely, |
| 83 | +and use your file instead. |
| 84 | + |
| 85 | +The same goes for routing files, validation configuration and other resources. |
| 86 | + |
| 87 | +.. note:: |
| 88 | + |
| 89 | + The overriding of resources only works when you refer to resources with |
| 90 | + the ``@FosUserBundle/Resources/config/routing/security.xml`` method. |
| 91 | + If you refer to resources without using the @BundleName shortcut, they |
| 92 | + can't be overridden in this way. |
| 93 | + |
| 94 | +.. _`FOSUserBundle`: https://github.com/friendsofsymfony/fosuserbundle |
0 commit comments