Merge branch '2.1'

Author: weaverryan

book/from_flat_php_to_symfony2.rst

@@ -420,34 +420,36 @@ Why should you have to reinvent solutions to all these routine problems?
 Add a Touch of Symfony2
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Symfony2 to the rescue. Before actually using Symfony2, you need to make
-sure PHP knows how to find the Symfony2 classes. This is accomplished via
-an autoloader that Symfony provides. An autoloader is a tool that makes it
-possible to start using PHP classes without explicitly including the file
-containing the class.
+Symfony2 to the rescue. Before actually using Symfony2, you need to download
+it. This can be done by using Composer, which takes care of downloading the
+correct version and all its dependencies and provides an autoloader. An 
+autoloader is a tool that makes it possible to start using PHP classes 
+without explicitly including the file containing the class.
 
-First, `download Symfony`_ and place it into a ``vendor/symfony/symfony/`` directory.
-Next, create an ``app/bootstrap.php`` file. Use it to ``require`` the two
-files in the application and to configure the autoloader:
+In your root directory, create a ``composer.json`` file with the following
+content:
 
-.. code-block:: html+php
+.. code-block:: json
 
-    <?php
-    // bootstrap.php
-    require_once 'model.php';
-    require_once 'controllers.php';
-    require_once 'vendor/symfony/symfony/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
+    {
+        "require": {
+            "symfony/symfony": "2.1.*"
+        },
+        "autoload": {
+            "files": ["model.php","controller.php"]
+        }
+    }
+    
+Next, `download Composer`_ and then run the following command, which will download Symfony
+into a vendor/ directory:
 
-    $loader = new Symfony\Component\ClassLoader\UniversalClassLoader();
-    $loader->registerNamespaces(array(
-        'Symfony' => __DIR__.'/../vendor/symfony/symfony/src',
-    ));
+.. code-block:: bash
 
-    $loader->register();
+    $ php composer.phar install
 
-This tells the autoloader where the ``Symfony`` classes are. With this, you
-can start using Symfony classes without using the ``require`` statement for
-the files that contain them.
+Beside downloading your dependencies, Composer generates a ``vendor/autoload.php`` file,
+which takes care of autoloading for all the files in the Symfony Framework as well as 
+the files mentioned in the autoload section of your ``composer.json``.
 
 Core to Symfony's philosophy is the idea that an application's main job is
 to interpret each request and return a response. To this end, Symfony2 provides
@@ -460,7 +462,7 @@ the HTTP response being returned. Use them to improve the blog:
 
     <?php
     // index.php
-    require_once 'app/bootstrap.php';
+    require_once 'vendor/bootstrap.php';
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
@@ -752,7 +754,7 @@ Learn more from the Cookbook
 * :doc:`/cookbook/controller/service`
 
 .. _`Doctrine`: http://www.doctrine-project.org
-.. _`download Symfony`: http://symfony.com/download
+.. _`download Composer`: http://getcomposer.org/download/
 .. _`Routing`: https://github.com/symfony/Routing
 .. _`Templating`: https://github.com/symfony/Templating
 .. _`KnpBundles.com`: http://knpbundles.com/

book/http_fundamentals.rst

@@ -357,9 +357,9 @@ Almost all modern web apps do this - including apps like WordPress.
 Stay Organized
 ~~~~~~~~~~~~~~
 
-But inside your front controller, how do you know which page should
-be rendered and how can you render each in a sane way? One way or another, you'll need to
-check the incoming URI and execute different parts of your code depending
+Inside your front controller, you have to figure out which code should be
+executed and what the content to return should be. To figure this out, you'll 
+need to check the incoming URI and execute different parts of your code depending
 on that value. This can get ugly quickly::
 
     // index.php
@@ -504,7 +504,7 @@ regardless of how your project is developed. To name a few:
   the ``Request`` and ``Response`` classes, as well as other classes for handling
   sessions and file uploads;
 
-* :doc:`Routing</components/routing>` - Powerful and fast routing system that
+* :doc:`Routing</components/routing/introduction>` - Powerful and fast routing system that
   allows you to map a specific URI (e.g. ``/contact``) to some information
   about how that request should be handled (e.g. execute the ``contactAction()``
   method);

book/internals.rst

@@ -23,7 +23,7 @@ on top of the previous one.
 
     Autoloading is not managed by the framework directly; it's done by using
     Composer's autoloader (``vendor/autoload.php``), which is included in
-    the ``src/autoload.php`` file.
+    the ``app/autoload.php`` file.
 
 ``HttpFoundation`` Component
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

book/page_creation.rst

@@ -512,13 +512,13 @@ You'll learn more about each of these directories in later chapters.
 
 .. sidebar:: Autoloading
 
-    When Symfony is loading, a special file - ``app/autoload.php`` - is included.
-    This file is responsible for configuring the autoloader, which will autoload
-    your application files from the ``src/`` directory and third-party libraries
-    from the ``vendor/`` directory.
+    When Symfony is loading, a special file - ``vendor/autoload.php`` - is 
+    included. This file is created by Composer and will autoload all 
+    application files living in the `src/` folder as well as all 
+    third-party libraries mentioned in the ``composer.json`` file.
 
     Because of the autoloader, you never need to worry about using ``include``
-    or ``require`` statements. Instead, Symfony2 uses the namespace of a class
+    or ``require`` statements. Instead, Composer uses the namespace of a class
     to determine its location and automatically includes the file on your
     behalf the instant you need a class.
 
@@ -533,11 +533,6 @@ You'll learn more about each of these directories in later chapters.
         Path:
             src/Acme/HelloBundle/Controller/HelloController.php
 
-    Typically, the only time you'll need to worry about the ``app/autoload.php``
-    file is when you're including a new third-party library in the ``vendor/``
-    directory. For more information on autoloading, see
-    :doc:`How to autoload Classes</components/class_loader>`.
-
 The Source (``src``) Directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -609,7 +604,6 @@ are used by your application (including the core Symfony bundles).
 
    A bundle can live *anywhere* as long as it can be autoloaded (via the
    autoloader configured at ``app/autoload.php``).
-
 Creating a Bundle
 ~~~~~~~~~~~~~~~~~
 

components/using_components.rst

@@ -6,7 +6,7 @@ How to Install and Use the Symfony2 Components
 ==============================================
 
 If you're starting a new project (or already have a project) that will use
-one or more components, the easiest way to integrate everything is with Composer.
+one or more components, the easiest way to integrate everything is with `Composer`_.
 Composer is smart enough to download the component(s) that you need and take
 care of autoloading so that you can begin using the libraries immediately.
 
@@ -33,13 +33,15 @@ may also need to adjust the version (e.g. ``2.1.1`` or ``2.2.*``).
 
 You can research the component names and versions at `packagist.org`_.
 
-**3.** Download the vendor libraries and generate the ``vendor/autoload.php`` file:
+**3.** `Install composer`_ if you don't already have it present on your system: 
+
+**4.** Download the vendor libraries and generate the ``vendor/autoload.php`` file:
 
 .. code-block:: bash
 
     $ php composer.phar install
 
-**4.** Write your code:
+**5.** Write your code:
 
 Once Composer has downloaded the component(s), all you need to do is include
 the ``vendor/autoload.php`` file that was generated by Composer. This file
@@ -48,6 +50,7 @@ immediately::
 
         // File: src/script.php
 
+        // update this to the path to the "vendor/" directory, relative to this file
         require_once '../vendor/autoload.php';
 
         use Symfony\Component\Finder\Finder;
@@ -93,4 +96,6 @@ documentation to find out more about how to use it.
 
 And have fun!
 
+.. _Composer: http://getcomposer.org
+.. _Install composer: http://getcomposer.org/download/
 .. _packagist.org: https://packagist.org/

contributing/code/security.rst

@@ -1,21 +1,75 @@
+Security Issues
+===============
+
+This document explains how Symfony security issues are handled by the Symfony
+core team (Symfony being the code hosted on the main ``symfony/symfony`` `Git
+repository`_).
+
 Reporting a Security Issue
-==========================
+--------------------------
+
+If you think that you have found a security issue in Symfony, don't use the
+mailing-list or the bug tracker and don't publish it publicly. Instead, all
+security issues must be sent to **security [at] symfony.com**. Emails sent to
+this address are forwarded to the Symfony core-team private mailing-list.
 
-Found a security issue in Symfony2? Don't use the mailing-list or the bug
-tracker. All security issues must be sent to **security [at]
-symfony-project.com** instead. Emails sent to this address are forwarded to
-the Symfony core-team private mailing-list.
+Resolving Process
+-----------------
 
 For each report, we first try to confirm the vulnerability. When it is
 confirmed, the core-team works on a solution following these steps:
 
 1. Send an acknowledgement to the reporter;
 2. Work on a patch;
-3. Write a post describing the vulnerability, the possible exploits, and how
-   to patch/upgrade affected applications;
-4. Apply the patch to all maintained versions of Symfony;
-5. Publish the post on the official Symfony blog.
+3. Write a security announcement for the official Symfony `blog`_ about the
+   vulnerability. This post should contain the following information:
+
+   * a title that always include the "Security release" string;
+   * a description of the vulnerability;
+   * the affected versions;
+   * the possible exploits;
+   * how to patch/upgrade/workaround affected applications;
+   * credits.
+4. Send the patch and the announcement to the reporter for review;
+5. Apply the patch to all maintained versions of Symfony;
+6. Package new versions for all affected versions;
+7. Publish the post on the official Symfony `blog`_ (it must also be added to
+   the "`Security Advisories`_" category);
+8. Update the security advisory list (see below).
+
+.. note::
+
+    Releases that include security issues should not be done on Saturday or
+    Sunday, except if the vulnerability has been publicly posted.
 
 .. note::
 
     While we are working on a patch, please do not reveal the issue publicly.
+
+Security Advisories
+-------------------
+
+This section indexes security vulnerabilities that were fixed in Symfony
+releases, starting from Symfony 1.0.0:
+
+* November 29, 2012: `Security release: Symfony 2.0.19 and 2.1.4 <http://symfony.com/blog/security-release-symfony-2-0-19-and-2-1-4>`_
+* November 25, 2012: `Security release: symfony 1.4.20 released  <http://symfony.com/blog/security-release-symfony-1-4-20-released>`_
+* August 28, 2012: `Security Release: Symfony 2.0.17 released <http://symfony.com/blog/security-release-symfony-2-0-17-released>`_
+* May 30, 2012: `Security Release: symfony 1.4.18 released <http://symfony.com/blog/security-release-symfony-1-4-18-released>`_
+* February 24, 2012: `Security Release: Symfony 2.0.11 released <http://symfony.com/blog/security-release-symfony-2-0-11-released>`_
+* November 16, 2011: `Security Release: Symfony 2.0.6 <http://symfony.com/blog/security-release-symfony-2-0-6>`_
+* March 21, 2011: `symfony 1.3.10 and 1.4.10: security releases <http://symfony.com/blog/symfony-1-3-10-and-1-4-10-security-releases>`_
+* June 29, 2010: `Security Release: symfony 1.3.6 and 1.4.6 <http://symfony.com/blog/security-release-symfony-1-3-6-and-1-4-6>`_
+* May 31, 2010: `symfony 1.3.5 and 1.4.5 <http://symfony.com/blog/symfony-1-3-5-and-1-4-5>`_
+* February 25, 2010: `Security Release: 1.2.12, 1.3.3 and 1.4.3 <http://symfony.com/blog/security-release-1-2-12-1-3-3-and-1-4-3>`_
+* February 13, 2010: `symfony 1.3.2 and 1.4.2 <http://symfony.com/blog/symfony-1-3-2-and-1-4-2>`_
+* April 27, 2009: `symfony 1.2.6: Security fix <http://symfony.com/blog/symfony-1-2-6-security-fix>`_
+* October 03, 2008: `symfony 1.1.4 released: Security fix <http://symfony.com/blog/symfony-1-1-4-released-security-fix>`_
+* May 14, 2008: `symfony 1.0.16 is out  <http://symfony.com/blog/symfony-1-0-16-is-out>`_
+* April 01, 2008: `symfony 1.0.13 is out  <http://symfony.com/blog/symfony-1-0-13-is-out>`_
+* March 21, 2008: `symfony 1.0.12 is (finally) out ! <http://symfony.com/blog/symfony-1-0-12-is-finally-out>`_
+* June 25, 2007: `symfony 1.0.5 released (security fix) <http://symfony.com/blog/symfony-1-0-5-released-security-fix>`_
+
+.. _Git repository:      https://github.com/symfony/symfony
+.. _blog:                https://symfony.com/blog/
+.. _Security Advisories: http://symfony.com/blog/category/security-advisories

contributing/code/standards.rst

@@ -108,6 +108,8 @@ Naming Conventions
 
 * Use namespaces for all classes;
 
+* Abstract classes are often prefixed with `Abstract`;
+
 * Suffix interfaces with `Interface`;
 
 * Use alphanumeric characters and underscores for file names;

contributing/community/releases.rst

@@ -2,7 +2,7 @@ The Release Process
 ===================
 
 This document explains the Symfony release process (Symfony being the code
-hosted on the main symfony/symfony `Git repository`_).
+hosted on the main ``symfony/symfony`` `Git repository`_).
 
 Symfony manages its releases through a *time-based model*; a new Symfony
 release comes out every *six months*: one in *May* and one in *November*.

cookbook/symfony1.rst

@@ -114,7 +114,7 @@ That array told symfony1 exactly which file contained each class. In the
 production environment, this caused you to need to clear the cache when classes
 were added or moved.
 
-In Symfony2, a new class - ``UniversalClassLoader`` - handles this process.
+In Symfony2, a tool named `Composer`_ handles this process.
 The idea behind the autoloader is simple: the name of your class (including
 the namespace) must match up with the path to the file containing that class.
 Take the ``FrameworkExtraBundle`` from the Symfony2 Standard Edition as an
@@ -136,18 +136,7 @@ As you can see, the location of the file follows the namespace of the class.
 Specifically, the namespace, ``Sensio\Bundle\FrameworkExtraBundle``, spells out
 the directory that the file should live in
 (``vendor/sensio/framework-extra-bundle/Sensio/Bundle/FrameworkExtraBundle/``).
-This is because, in the ``app/autoload.php`` file, you'll configure Symfony to
-look for the ``Sensio`` namespace in the ``vendor/sensio`` directory:
-
-.. code-block:: php
-
-    // app/autoload.php
-
-    // ...
-    $loader->registerNamespaces(array(
-        ...,
-        'Sensio'           => __DIR__.'/../vendor/sensio/framework-extra-bundle',
-    ));
+Composer can then look for the file at this specific place and load it very fast.
 
 If the file did *not* live at this exact location, you'd receive a
 ``Class "Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle" does not exist.``
@@ -160,24 +149,24 @@ contains a different class). In order for a class to be autoloaded, you
 As mentioned before, for the autoloader to work, it needs to know that the
 ``Sensio`` namespace lives in the ``vendor/bundles`` directory and that, for
 example, the ``Doctrine`` namespace lives in the ``vendor/doctrine/orm/lib/``
-directory. This mapping is entirely controlled by you via the
-``app/autoload.php`` file.
+directory. This mapping is entirely controlled by Composer. Each 
+third-party library you load through composer has their settings defined
+and Composer takes care of everything for you.
+
+For this to work, all third-party libraries used by your project must be 
+defined in the ``composer.json`` file. 
 
 If you look at the ``HelloController`` from the Symfony2 Standard Edition you
 can see that it lives in the ``Acme\DemoBundle\Controller`` namespace. Yet, the
-``Acme`` namespace is not defined in the ``app/autoload.php``. By default you
-do not need to explicitly configure the location of bundles that live in the
-``src/`` directory. The ``UniversalClassLoader`` is configured to fallback to
-the ``src/`` directory using its ``registerNamespaceFallbacks`` method:
+``AcmeDemoBundle`` is not defined in your ``composer.json`` file. Nonetheless are
+the files autoloaded. This is because you can tell composer to autoload files 
+from specific directories without defining a dependency:
 
-.. code-block:: php
-
-    // app/autoload.php
+.. code-block:: yaml
 
-    // ...
-    $loader->registerNamespaceFallbacks(array(
-        __DIR__.'/../src',
-    ));
+    "autoload": {
+        "psr-0": { "": "src/" }
+    }
 
 Using the Console
 -----------------
@@ -312,3 +301,4 @@ primarily to configure objects that you can use. For more information, see
 the chapter titled ":doc:`/book/service_container`".
 
 .. _`Symfony2 Standard`: https://github.com/symfony/symfony-standard
+.. _`Composer`: http://getcomposer.org