|
6 | 6 | The Bundle System |
7 | 7 | ================= |
8 | 8 |
|
9 | | -A bundle is similar to a plugin in other software, but even better. The key |
10 | | -difference is that *everything* is a bundle in Symfony, including both the |
11 | | -core framework functionality and the code written for your application. |
12 | | -Bundles are first-class citizens in Symfony. This gives you the flexibility |
13 | | -to use pre-built features packaged in `third-party bundles`_ or to distribute |
14 | | -your own bundles. It makes it easy to pick and choose which features to enable |
15 | | -in your application and to optimize them the way you want. |
16 | | - |
17 | | -..note:: |
18 | | - |
19 | | - While you'll learn the basics here, an entire article is devoted to the |
20 | | - organization and best practices of:doc:`bundles</bundles/best_practices>`. |
21 | | - |
22 | | -A bundle is simply a structured set of files within a directory that implement |
23 | | -a single feature. You might create a BlogBundle, a ForumBundle or |
24 | | -a bundle for user management (many of these exist already as open source |
25 | | -bundles). Each directory contains everything related to that feature, including |
26 | | -PHP files, templates, stylesheets, JavaScript files, tests and anything else. |
27 | | -Every aspect of a feature exists in a bundle and every feature lives in a |
28 | | -bundle. |
29 | | - |
30 | | -Bundles used in your applications must be enabled by registering them in |
31 | | -the ``registerBundles()`` method of the ``AppKernel`` class:: |
32 | | - |
33 | | - // app/AppKernel.php |
34 | | - public function registerBundles() |
35 | | - { |
36 | | - $bundles = array( |
37 | | - new Symfony\Bundle\FrameworkBundle\FrameworkBundle(), |
38 | | - new Symfony\Bundle\SecurityBundle\SecurityBundle(), |
39 | | - new Symfony\Bundle\TwigBundle\TwigBundle(), |
40 | | - new Symfony\Bundle\MonologBundle\MonologBundle(), |
41 | | - new Symfony\Bundle\SwiftmailerBundle\SwiftmailerBundle(), |
42 | | - new Symfony\Bundle\DoctrineBundle\DoctrineBundle(), |
43 | | - new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(), |
44 | | - new AppBundle\AppBundle(), |
45 | | - ); |
46 | | - |
47 | | - if (in_array($this->getEnvironment(), array('dev', 'test'))) { |
48 | | - $bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle(); |
49 | | - $bundles[] = new Sensio\Bundle\DistributionBundle\SensioDistributionBundle(); |
50 | | - $bundles[] = new Sensio\Bundle\GeneratorBundle\SensioGeneratorBundle(); |
51 | | - } |
52 | | - |
53 | | - return $bundles; |
54 | | - } |
55 | | - |
56 | | -With the ``registerBundles()`` method, you have total control over which bundles |
57 | | -are used by your application (including the core Symfony bundles). |
| 9 | +..caution:: |
| 10 | + |
| 11 | + In Symfony versions prior to 4.0, it was recommended to organize your own |
| 12 | + application code using bundles. This is no longer recommended and bundles |
| 13 | + should only be used to share code and features between multiple applications. |
| 14 | + |
| 15 | +A bundle is similar to a plugin in other software, but even better. The core |
| 16 | +features of Symfony framework are implemented with bundles (FrameworkBundle, |
| 17 | +SecurityBundle, DebugBundle, etc.) They are also used to add new features in |
| 18 | +your application via `third-party bundles`_. |
| 19 | + |
| 20 | +Bundles used in your applications must be enabled per |
| 21 | +:doc:`environment</configuration/environments>` in the ``config/bundles.php`` |
| 22 | +file:: |
| 23 | + |
| 24 | + // config/bundles.php |
| 25 | + return [ |
| 26 | + // 'all' means that the bundle is enabled for any Symfony environment |
| 27 | + Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true], |
| 28 | + Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true], |
| 29 | + Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true], |
| 30 | + Symfony\Bundle\MonologBundle\MonologBundle::class => ['all' => true], |
| 31 | + Symfony\Bundle\SwiftmailerBundle\SwiftmailerBundle::class => ['all' => true], |
| 32 | + Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true], |
| 33 | + Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle::class => ['all' => true], |
| 34 | + // this bundle is enabled only in 'dev' and 'test', so you can't use it in 'prod' |
| 35 | + Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true], |
| 36 | + ]; |
58 | 37 |
|
59 | 38 | ..tip:: |
60 | 39 |
|
61 | | - A bundle can live *anywhere* as long as it can be autoloaded (via the |
62 | | - autoloader configured at ``app/autoload.php``). |
63 | | - |
64 | | -Creating a Bundle |
65 | | ------------------ |
66 | | - |
67 | | -The Symfony Standard Edition comes with a handy task that creates a fully-functional |
68 | | -bundle for you. Of course, creating a bundle by hand is pretty easy as well. |
69 | | - |
70 | | -To show you how simple the bundle system is, create a new bundle called |
71 | | -AcmeTestBundle and enable it. |
72 | | - |
73 | | -..tip:: |
74 | | - |
75 | | - The ``Acme`` portion is just a dummy name that should be replaced by |
76 | | - some "vendor" name that represents you or your organization (e.g. |
77 | | - ABCTestBundle for some company named ``ABC``). |
78 | | - |
79 | | -Start by creating a ``src/Acme/TestBundle/`` directory and adding a new file |
80 | | -called ``AcmeTestBundle.php``:: |
81 | | - |
82 | | - // src/Acme/TestBundle/AcmeTestBundle.php |
83 | | - namespace Acme\TestBundle; |
84 | | - |
85 | | - use Symfony\Component\HttpKernel\Bundle\Bundle; |
86 | | - |
87 | | - class AcmeTestBundle extends Bundle |
88 | | - { |
89 | | - } |
90 | | - |
91 | | -..tip:: |
92 | | - |
93 | | - The name AcmeTestBundle follows the standard |
94 | | -:ref:`Bundle naming conventions<bundles-naming-conventions>`. You could |
95 | | - also choose to shorten the name of the bundle to simply TestBundle by naming |
96 | | - this class TestBundle (and naming the file ``TestBundle.php``). |
97 | | - |
98 | | -This empty class is the only piece you need to create the new bundle. Though |
99 | | -commonly empty, this class is powerful and can be used to customize the behavior |
100 | | -of the bundle. |
101 | | - |
102 | | -Now that you've created the bundle, enable it via the ``AppKernel`` class:: |
103 | | - |
104 | | - // app/AppKernel.php |
105 | | - public function registerBundles() |
106 | | - { |
107 | | - $bundles = array( |
108 | | - // ... |
109 | | - |
110 | | - // register your bundle |
111 | | - new Acme\TestBundle\AcmeTestBundle(), |
112 | | - ); |
113 | | - // ... |
114 | | - |
115 | | - return $bundles; |
116 | | - } |
117 | | - |
118 | | -And while it doesn't do anything yet, AcmeTestBundle is now ready to be used. |
119 | | - |
120 | | -And as easy as this is, Symfony also provides a command-line interface for |
121 | | -generating a basic bundle skeleton: |
122 | | - |
123 | | -..code-block::terminal |
124 | | -
|
125 | | - $ php bin/console generate:bundle --namespace=Acme/TestBundle |
126 | | -
|
127 | | -The bundle skeleton generates a basic controller, template and routing |
128 | | -resource that can be customized. You'll learn more about Symfony's command-line |
129 | | -tools later. |
130 | | - |
131 | | -..tip:: |
132 | | - |
133 | | - Whenever creating a new bundle or using a third-party bundle, always make |
134 | | - sure the bundle has been enabled in ``registerBundles()``. When using |
135 | | - the ``generate:bundle`` command, this is done for you. |
136 | | - |
137 | | -Bundle Directory Structure |
138 | | --------------------------- |
139 | | - |
140 | | -The directory structure of a bundle is simple and flexible. By default, the |
141 | | -bundle system follows a set of conventions that help to keep code consistent |
142 | | -between all Symfony bundles. Take a look at AcmeDemoBundle, as it contains some |
143 | | -of the most common elements of a bundle: |
144 | | - |
145 | | -``Controller/`` |
146 | | - Contains the controllers of the bundle (e.g. ``RandomController.php``). |
147 | | - |
148 | | -``DependencyInjection/`` |
149 | | - Holds certain Dependency Injection Extension classes, which may import service |
150 | | - configuration, register compiler passes or more (this directory is not |
151 | | - necessary). |
152 | | - |
153 | | -``Resources/config/`` |
154 | | - Houses configuration, including routing configuration (e.g. ``routes.yaml``). |
155 | | - |
156 | | -``Resources/views/`` |
157 | | - Holds templates organized by controller name (e.g. ``Random/index.html.twig``). |
158 | | - |
159 | | -``Resources/public/`` |
160 | | - Contains web assets (images, stylesheets, etc) and is copied or symbolically |
161 | | - linked into the project ``public/`` directory via the ``assets:install`` console |
162 | | - command. |
163 | | - |
164 | | -``Tests/`` |
165 | | - Holds all tests for the bundle. |
166 | | - |
167 | | -A bundle can be as small or large as the feature it implements. It contains |
168 | | -only the files you need and nothing else. |
169 | | - |
170 | | -As you move through the guides, you'll learn how to persist objects to a |
171 | | -database, create and validate forms, create translations for your application, |
172 | | -write tests and much more. Each of these has their own place and role within |
173 | | -the bundle. |
| 40 | + In a default Symfony application that uses:doc:`Symfony Flex</setup/flex>`, |
| 41 | + bundles are enabled/disabled automatically for you when installing/removing |
| 42 | + them, so you don't need to look at or edit this ``bundles.php`` file. |
174 | 43 |
|
175 | 44 | Learn more |
176 | 45 | ---------- |
177 | 46 |
|
178 | | -..toctree:: |
179 | | -:maxdepth:1 |
180 | | -:glob: |
181 | | - |
182 | | -bundles/* |
| 47 | +*:doc:`/bundles/remove` |
| 48 | +*:doc:`/bundles/override` |
| 49 | +*:doc:`/bundles/best_practices` |
| 50 | +*:doc:`/bundles/configuration` |
| 51 | +*:doc:`/bundles/extension` |
| 52 | +*:doc:`/bundles/prepend_extension` |
183 | 53 |
|
184 | 54 | .. _`third-party bundles`:https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories |