Skip to content

Commit 41d1733

Browse files
weaverryanweaverryan
committed
Merge branch '2.8'
* 2.8: Remoing link to now-gone web section Fixes thanks to Wouter! removing reference that I removed removing duplicate reference Lots of updates thanks to @javiereguiluz! adding missing reference Proofread! Complete rewrite of the page creation chapter to be much shorter WIP Fixed some issues reported by Wouter Fixed minor issue with the title case Added a mention to the Symfony Demo application
2 parents a68ff44 + 9538919 commit 41d1733

9 files changed

+835
-875
lines changed

Diff for: ‎book/bundles.rst

+175
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. index::
2+
single: Bundles
3+
4+
.. _page-creation-bundles:
5+
6+
The Bundle System
7+
=================
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 cookbook entry is devoted
20+
to the organization and best practices of :doc:`bundles </cookbook/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 Symfony\Bundle\AsseticBundle\AsseticBundle(),
44+
new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(),
45+
new AppBundle\AppBundle(),
46+
);
47+
48+
if (in_array($this->getEnvironment(), array('dev', 'test'))) {
49+
$bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle();
50+
$bundles[] = new Sensio\Bundle\DistributionBundle\SensioDistributionBundle();
51+
$bundles[] = new Sensio\Bundle\GeneratorBundle\SensioGeneratorBundle();
52+
}
53+
54+
return $bundles;
55+
}
56+
57+
With the ``registerBundles()`` method, you have total control over which bundles
58+
are used by your application (including the core Symfony bundles).
59+
60+
.. tip::
61+
62+
A bundle can live *anywhere* as long as it can be autoloaded (via the
63+
autoloader configured at ``app/autoload.php``).
64+
65+
Creating a Bundle
66+
-----------------
67+
68+
The Symfony Standard Edition comes with a handy task that creates a fully-functional
69+
bundle for you. Of course, creating a bundle by hand is pretty easy as well.
70+
71+
To show you how simple the bundle system is, create a new bundle called
72+
AcmeTestBundle and enable it.
73+
74+
.. tip::
75+
76+
The ``Acme`` portion is just a dummy name that should be replaced by
77+
some "vendor" name that represents you or your organization (e.g.
78+
ABCTestBundle for some company named ``ABC``).
79+
80+
Start by creating a ``src/Acme/TestBundle/`` directory and adding a new file
81+
called ``AcmeTestBundle.php``::
82+
83+
// src/Acme/TestBundle/AcmeTestBundle.php
84+
namespace Acme\TestBundle;
85+
86+
use Symfony\Component\HttpKernel\Bundle\Bundle;
87+
88+
class AcmeTestBundle extends Bundle
89+
{
90+
}
91+
92+
.. tip::
93+
94+
The name AcmeTestBundle follows the standard
95+
:ref:`Bundle naming conventions <bundles-naming-conventions>`. You could
96+
also choose to shorten the name of the bundle to simply TestBundle by naming
97+
this class TestBundle (and naming the file ``TestBundle.php``).
98+
99+
This empty class is the only piece you need to create the new bundle. Though
100+
commonly empty, this class is powerful and can be used to customize the behavior
101+
of the bundle.
102+
103+
Now that you've created the bundle, enable it via the ``AppKernel`` class::
104+
105+
// app/AppKernel.php
106+
public function registerBundles()
107+
{
108+
$bundles = array(
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:: bash
124+
125+
$ php app/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. ``routing.yml``).
155+
156+
``Resources/views/``
157+
Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
158+
159+
``Resources/public/``
160+
Contains web assets (images, stylesheets, etc) and is copied or symbolically
161+
linked into the project ``web/`` 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 book, you'll learn how to persist objects to a database,
171+
create and validate forms, create translations for your application, write
172+
tests and much more. Each of these has their own place and role within the
173+
bundle.
174+
175+
_`third-party bundles`: http://knpbundles.com

0 commit comments

Comments
 (0)