|
| 1 | +.. index:: |
| 2 | + single: Bundle; Dependencies |
| 3 | + |
| 4 | +How to Use Bundle Dependencies to Load other Bundles |
| 5 | +==================================================== |
| 6 | + |
| 7 | +.. versionadded:: 2.8 |
| 8 | + Support for bundle dependencies was introduced in Symfony 2.8. |
| 9 | + |
| 10 | +When working on your own bundle(s), you'll sometimes have the need to reuse |
| 11 | +other bundles, either by just requiring, overriding or inheriting from them. |
| 12 | + |
| 13 | +While Composer takes care about making sure these dependencies are loaded, |
| 14 | +you'll also need to enable these bundles in the kernel. |
| 15 | + |
| 16 | +If your bundle is meant to be reused, bundle dependencies will complicate |
| 17 | +your installation documentation. This makes installation and upgrading your |
| 18 | +bundle more tedious for your users. |
| 19 | + |
| 20 | +You can avoid this by specifying your dependencies. This will make sure that |
| 21 | +they are loaded in the kernel. It'll also make sure they are loaded *before* |
| 22 | +your own bundle, to make sure you can extend them. |
| 23 | + |
| 24 | +Additional use case for this is for distribution bundles, where one |
| 25 | +bundle is in fact bundling several others. |
| 26 | + |
| 27 | +Specifying Dependencies |
| 28 | +----------------------- |
| 29 | + |
| 30 | +Dependencies are specified using FQN_ (`Fully Qualified Name`) for the bundle class in |
| 31 | +same format as PHP uses for :phpfunction:`get_class`, and for class_ constant introduced in PHP 5.5. |
| 32 | + |
| 33 | +This implies you can only specify bundles that does not take arguments in it's constructor. |
| 34 | +This is in-line with Symfony best practice, avoids same bundle being loaded several times, |
| 35 | +and allows this information to be easily cached in future versions of Symfony. |
| 36 | + |
| 37 | +Specifying dependencies is accomplished by implementing the |
| 38 | +:class:`Symfony\\Component\\HttpKernel\\Bundle\\BundleDependenciesInterface`:: |
| 39 | + |
| 40 | + // src/CacheBundle/CacheBundle.php |
| 41 | + namespace CacheBundle; |
| 42 | + |
| 43 | + use Symfony\Component\HttpKernel\Bundle\Bundle; |
| 44 | + use Symfony\Component\HttpKernel\Bundle\BundleDependenciesInterface; |
| 45 | + |
| 46 | + class CacheBundle extends Bundle implements BundleDependenciesInterface |
| 47 | + { |
| 48 | + public function getBundleDependencies($environment, $debug) |
| 49 | + { |
| 50 | + return array('FOS\HttpCacheBundle\FOSHttpCacheBundle' => self::DEP_REQUIRED); |
| 51 | + } |
| 52 | + } |
| 53 | + |
| 54 | +.. tip:: |
| 55 | + |
| 56 | + If your bundle requires PHP 5.5 or higher, you can also take advantage of |
| 57 | + the ``class`` constant:: |
| 58 | + |
| 59 | + use FOS\HttpCacheBundle\FOSHttpCacheBundle; |
| 60 | + |
| 61 | + // ... |
| 62 | + public function getBundleDependencies($environment, $debug) |
| 63 | + { |
| 64 | + return array(FOSHttpCacheBundle::class => self::DEP_REQUIRED); |
| 65 | + } |
| 66 | + |
| 67 | +.. tip:: |
| 68 | + |
| 69 | + If your dependency is only to be loaded in ``dev`` or when debugging, use the provided arguments:: |
| 70 | + |
| 71 | + use Egulias\SecurityDebugCommandBundle\EguliasSecurityDebugCommandBundle; |
| 72 | + |
| 73 | + // ... |
| 74 | + public function getBundleDependencies($environment, $debug) |
| 75 | + { |
| 76 | + if ($environment !== 'dev') { |
| 77 | + return array(); |
| 78 | + } |
| 79 | + |
| 80 | + return array('Egulias\SecurityDebugCommandBundle\EguliasSecurityDebugCommandBundle' => self::DEP_REQUIRED); |
| 81 | + } |
| 82 | + |
| 83 | + |
| 84 | +Specifying Optional Dependencies |
| 85 | +-------------------------------- |
| 86 | + |
| 87 | +Specifying a optional dependency follows the same format but with a different constant:: |
| 88 | + |
| 89 | + // ... |
| 90 | + public function getBundleDependencies($environment, $debug) |
| 91 | + { |
| 92 | + return array('Oneup\FlysystemBundle\OneupFlysystemBundle' => self::DEP_OPTIONAL); |
| 93 | + } |
| 94 | + |
| 95 | + |
| 96 | +.. _FQN: https://en.wikipedia.org/wiki/Fully_qualified_name |
| 97 | +.. _class: http://php.net/manual/en/language.oop5.basic.php#language.oop5.basic.class.class |
0 commit comments