@@ -13,17 +13,17 @@ Understanding the Directory Structure
1313The directory structure of a Symfony:term: `application ` is rather flexible,
1414but the recommended structure is as follows:
1515
16- * ``app/ ``:
17- * ``src/ ``:
16+ * ``app/ ``: the application configuration and templates ;
17+ * ``src/ ``: the project's PHP code;
1818* ``vendor/ ``: the third-party dependencies;
19- * ``web/ ``:
19+ * ``web/ ``: the web root directory.
2020
2121The ``web/ `` Directory
2222~~~~~~~~~~~~~~~~~~~~~~
2323
2424The web root directory is the home of all public and static files like images,
2525stylesheets, and JavaScript files. It is also where each:term: `front controller `
26- lives::
26+ lives, such as the production controller shown here ::
2727
2828 // web/app.php
2929 require_once __DIR__.'/../app/bootstrap.php.cache';
@@ -33,7 +33,9 @@ lives::
3333
3434 $kernel = new AppKernel('prod', false);
3535 $kernel->loadClassCache();
36- $kernel->handle(Request::createFromGlobals())->send();
36+ $request = Request::createFromGlobals();
37+ $response = $kernel->handle($request);
38+ $response->send();
3739
3840The controller first bootstraps the application using a kernel class (``AppKernel ``
3941in this case). Then, it creates the ``Request `` object using the PHP's global
@@ -51,8 +53,7 @@ configuration and as such, it is stored in the ``app/`` directory.
5153This class must implement two methods:
5254
5355* ``registerBundles() `` must return an array of all bundles needed to run the
54- application;
55-
56+ application, as explained in the next section;
5657* ``registerContainerConfiguration() `` loads the application configuration
5758 (more on this later).
5859
@@ -73,12 +74,21 @@ A bundle is kind of like a plugin in other software. So why is it called a
7374Symfony, from the core framework features to the code you write for your
7475application.
7576
77+ All the code you write for your application is organized in bundles. In Symfony
78+ speak, a bundle is a structured set of files (PHP files, stylesheets, JavaScripts,
79+ images, ...) that implements a single feature (a blog, a forum, ...) and which
80+ can be easily shared with other developers.
81+
7682Bundles are first-class citizens in Symfony. This gives you the flexibility
7783to use pre-built features packaged in third-party bundles or to distribute your
7884own bundles. It makes it easy to pick and choose which features to enable in
7985your application and optimize them the way you want. And at the end of the day,
8086your application code is just as *important * as the core framework itself.
8187
88+ Symfony already includes an ``AppBundle `` that you may use to start developing
89+ your application. Then, if you need to split the application into reusable
90+ components, you can create your own bundles.
91+
8292Registering a Bundle
8393~~~~~~~~~~~~~~~~~~~~
8494
@@ -98,10 +108,10 @@ a single ``Bundle`` class that describes it::
98108 new Symfony\Bundle\DoctrineBundle\DoctrineBundle(),
99109 new Symfony\Bundle\AsseticBundle\AsseticBundle(),
100110 new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(),
111+ new AppBundle\AppBundle();
101112 );
102113
103114 if (in_array($this->getEnvironment(), array('dev', 'test'))) {
104- $bundles[] = new Acme\DemoBundle\AcmeDemoBundle();
105115 $bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle();
106116 $bundles[] = new Sensio\Bundle\DistributionBundle\SensioDistributionBundle();
107117 $bundles[] = new Sensio\Bundle\GeneratorBundle\SensioGeneratorBundle();
@@ -110,23 +120,23 @@ a single ``Bundle`` class that describes it::
110120 return $bundles;
111121 }
112122
113- In addition to the AcmeDemoBundle that was already talked about, notice
114- that the kernel also enables other bundles such as the FrameworkBundle,
115- DoctrineBundle, SwiftmailerBundle and AsseticBundle bundle. They are all part
116- of the core framework.
123+ In addition to the AppBundle that was already talked about, notice that the
124+ kernel also enables other bundles such as the FrameworkBundle, DoctrineBundle,
125+ SwiftmailerBundle and AsseticBundle bundle. They are all part of the core framework.
117126
118127Configuring a Bundle
119128~~~~~~~~~~~~~~~~~~~~
120129
121130Each bundle can be customized via configuration files written in YAML, XML, or
122- PHP. Have a look at the default Symfony configuration:
131+ PHP. Have a look atthis sample of the default Symfony configuration:
123132
124133..code-block ::yaml
125134
126135# app/config/config.yml
127136imports :
128137 -{ resource: parameters.yml }
129138 -{ resource: security.yml }
139+ -{ resource: services.yml }
130140
131141framework :
132142# esi: ~
@@ -138,7 +148,7 @@ PHP. Have a look at the default Symfony configuration:
138148form :true
139149csrf_protection :true
140150validation :{ enable_annotations: true }
141- templating :{ engines: ['twig'] } # assets_version: SomeVersionScheme
151+ templating :{ engines: ['twig'] }
142152default_locale :" %locale%"
143153trusted_proxies :~
144154session :~
@@ -148,34 +158,6 @@ PHP. Have a look at the default Symfony configuration:
148158debug :" %kernel.debug%"
149159strict_variables :" %kernel.debug%"
150160
151- # Assetic Configuration
152- assetic :
153- debug :" %kernel.debug%"
154- use_controller :false
155- bundles :[ ]
156- # java: /usr/bin/java
157- filters :
158- cssrewrite :~
159- # closure:
160- # jar: "%kernel.root_dir%/Resources/java/compiler.jar"
161- # yui_css:
162- # jar: "%kernel.root_dir%/Resources/java/yuicompressor-2.4.7.jar"
163-
164- # Doctrine Configuration
165- doctrine :
166- dbal :
167- driver :" %database_driver%"
168- host :" %database_host%"
169- port :" %database_port%"
170- dbname :" %database_name%"
171- user :" %database_user%"
172- password :" %database_password%"
173- charset :UTF8
174-
175- orm :
176- auto_generate_proxy_classes :" %kernel.debug%"
177- auto_mapping :true
178-
179161# Swift Mailer Configuration
180162swiftmailer :
181163transport :" %mailer_transport%"
@@ -184,9 +166,11 @@ PHP. Have a look at the default Symfony configuration:
184166password :" %mailer_password%"
185167spool :{ type: memory }
186168
187- framework ``, ``twig `` or ``doctrine `` defines the
188- configuration for a specific bundle. For example, ``framework `` configures the
189- FrameworkBundle while ``swiftmailer `` configures the SwiftmailerBundle.
169+ # ...
170+
171+ framework ``, ``twig `` or ``swiftmailer `` defines
172+ the configuration for a specific bundle. For example, ``framework `` configures
173+ the FrameworkBundle while ``swiftmailer `` configures the SwiftmailerBundle.
190174
191175Each:term: `environment ` can override the default configuration by providing a
192176specific configuration file. For example, the ``dev `` environment loads the
@@ -207,64 +191,42 @@ and then modifies it to add some debugging tools:
207191toolbar :true
208192intercept_redirects :false
209193
210- monolog :
211- handlers :
212- main :
213- type :stream
214- path :" %kernel.logs_dir%/%kernel.environment%.log"
215- level :debug
216- firephp :
217- type :firephp
218- level :info
219-
220- assetic :
221- use_controller :true
194+ # ...
222195
223196
224197~~~~~~~~~~~~~~~~~~
225198
226199In addition to being a nice way to organize and configure your code, a bundle
227200can extend another bundle. Bundle inheritance allows you to override any existing
228201bundle in order to customize its controllers, templates, or any of its files.
229- This is where the logical names (e.g. ``@AcmeDemoBundle/Controller/SecuredController.php ``)
230- come in handy: they abstract where the resource is actually stored.
231202
232203Logical File Names
233204..................
234205
235206When you want to reference a file from a bundle, use this notation:
236207``@BUNDLE_NAME/path/to/file ``; Symfony will resolve ``@BUNDLE_NAME ``
237208to the real path to the bundle. For instance, the logical path
238- ``@AcmeDemoBundle /Controller/DemoController .php `` would be converted to
239- ``src/Acme/DemoBundle/ Controller/DemoController .php ``, because Symfony knows
240- the location of theAcmeDemoBundle .
209+ ``@AppBundle /Controller/DefaultController .php `` would be converted to
210+ ``src/AppBundle/ Controller/DefaultController .php ``, because Symfony knows
211+ the location of theAppBundle .
241212
242213Logical Controller Names
243214........................
244215
245- For controllers, you need to referencemethod names using the format
216+ For controllers, you need to referenceaction using the format
246217``BUNDLE_NAME:CONTROLLER_NAME:ACTION_NAME ``. For instance,
247- ``AcmeDemoBundle:Welcome:index `` maps to the ``indexAction `` method from the
248- ``Acme\DemoBundle\Controller\WelcomeController `` class.
249-
250- Logical Template Names
251- ......................
252-
253- For templates, the logical name ``AcmeDemoBundle:Welcome:index.html.twig `` is
254- converted to the file path ``src/Acme/DemoBundle/Resources/views/Welcome/index.html.twig ``.
255- Templates become even more interesting when you realize they don't need to be
256- stored on the filesystem. You can easily store them in a database table for
257- instance.
218+ ``AppBundle:Default:index `` maps to the ``indexAction `` method from the
219+ ``AppBundle\Controller\DefaultController `` class.
258220
259221Extending Bundles
260222.................
261223
262- If you follow these conventions, then you can use:doc: `bundle inheritance</cookbook/bundles/inheritance> `
263- to" override" files, controllers or templates. For example, you can create
264- a bundle -AcmeNewBundle - and specify that it overridesAcmeDemoBundle .
265- When Symfony loads the ``AcmeDemoBundle:Welcome :index
266- first look for the ``WelcomeController `` class inAcmeNewBundle and, if
267- it doesn't exist, then look insideAcmeDemoBundle . This means that one bundle
224+ If you follow these conventions, then you can use:doc: `bundle inheritance </cookbook/bundles/inheritance >`
225+ to override files, controllers or templates. For example, you can create
226+ a bundle -NewBundle - and specify that it overridesAppBundle .
227+ When Symfony loads the ``AppBundle:Default :index
228+ first look for the ``DefaultController `` class inNewBundle and, if
229+ it doesn't exist, then look insideAppBundle . This means that one bundle
268230can override almost any part of another bundle!
269231
270232Do you understand now why Symfony is so flexible? Share your bundles between
@@ -276,22 +238,28 @@ Using Vendors
276238-------------
277239
278240Odds are that your application will depend on third-party libraries. Those
279- should be stored in the ``vendor/ `` directory. This directory already contains
280- the Symfony libraries, the SwiftMailer library, the Doctrine ORM, the Twig
281- templating system, and some other third party libraries and bundles.
241+ should be stored in the ``vendor/ `` directory and managed by Composer.
242+ This directory already contains the Symfony libraries, the SwiftMailer library,
243+ the Doctrine ORM, the Twig templating system, and some other third party
244+ libraries and bundles.
282245
283246Understanding the Cache and Logs
284247--------------------------------
285248
286- Symfonyis probably one ofthe fastest full-stack frameworks around. But how
287- can it be so fast if it parses andinterprets tens of YAML and XML files for
288- each request? The speed is partly due to its cache system.The application
249+ Symfonyapplications can contain tens ofconfiguration files defined in several
250+ formats (YAML, XML, PHP, etc.) Instead of parsing andcombining all those files
251+ for each request, Symfony uses itsown cache system.In fact, the application
289252configuration is only parsed for the very first request and then compiled down
290- to plain PHP code stored in the ``app/cache/ `` directory. In the development
291- environment, Symfony is smart enough to flush the cache when you change a
292- file. But in the production environment, to speed things up, it is your
293- responsibility to clear the cache when you update your code or change its
294- configuration.
253+ to plain PHP code stored in the ``app/cache/ `` directory.
254+
255+ In the development environment, Symfony is smart enough to update the cache when
256+ you change a file. But in the production environment, to speed things up, it is
257+ your responsibility to clear the cache when you update your code or change its
258+ configuration. Execute this command to clear the cache in the ``prod `` environment:
259+
260+ ..code-block ::bash
261+
262+ $ php app/console cache:clear --env=prod
295263
296264
297265files in the ``app/logs/ `` directory tell you everything about the requests