Merge branch 'master' into security

Conflicts:
	book/security/authorization.rst
	cookbook/map.rst.inc

Author: weaverryan

book/doctrine/orm.rst

@@ -47,7 +47,7 @@ any PHP class:
 
 .. code-block:: php
 
-    // Acme/HelloBundle/Entity/User.php
+    // src/Acme/HelloBundle/Entity/User.php
     namespace Acme\HelloBundle\Entity;
 
     class User
@@ -85,7 +85,7 @@ write mapping information with annotations, XML, or YAML:
 
     .. code-block:: php-annotations
 
-        // Acme/HelloBundle/Entity/User.php
+        // src/Acme/HelloBundle/Entity/User.php
         namespace Acme\HelloBundle\Entity;
 
         /**
@@ -108,7 +108,7 @@ write mapping information with annotations, XML, or YAML:
 
     .. code-block:: yaml
 
-        # Acme/HelloBundle/Resources/config/doctrine/Acme.HelloBundle.Entity.User.orm.yml
+        # src/Acme/HelloBundle/Resources/config/doctrine/Acme.HelloBundle.Entity.User.orm.yml
         Acme\HelloBundle\Entity\User:
             type: entity
             table: user
@@ -124,7 +124,7 @@ write mapping information with annotations, XML, or YAML:
 
     .. code-block:: xml
 
-        <!-- Acme/HelloBundle/Resources/config/doctrine/Acme.HelloBundle.Entity.User.orm.xml -->
+        <!-- src/Acme/HelloBundle/Resources/config/doctrine/Acme.HelloBundle.Entity.User.orm.xml -->
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
@@ -167,7 +167,7 @@ Eventually, use your entity and manage its persistent state with Doctrine:
 
 .. code-block:: php
 
-    // Acme/HelloBundle/Controller/UserController.php
+    // src/Acme/HelloBundle/Controller/UserController.php
     namespace Acme\HelloBundle\Controller;
 
     use Acme\HelloBundle\Entity\User;
@@ -215,6 +215,7 @@ losing your existing data. So first let's just add a new property to our
 
 .. code-block:: php
 
+    // src/Acme/HelloBundle/Entity/User.php
     namespace Acme\HelloBundle\Entity;
 
     /** @orm:Entity */
@@ -234,6 +235,166 @@ you just need to run the following command:
 Now your database will be updated and the new column added to the database
 table.
 
+.. index::
+   single: Doctrine ORM; Queries;
+
+Queries
+~~~~~~~
+
+As you have already seen, working with single objects is straightforward and
+easy with the entity manager. But how can you query for a set of objects?
+As every with any Doctrine operation, this is done via the entity manager.
+Change the delete action used in the previous example to use a query instead
+of loading the object and then deleting it afterwards:
+
+.. code-block:: php
+
+    public function deleteAction($id)
+    {
+        $query = $this->get('doctrine')->getEntityManager()
+                   ->createQuery('DELETE FROM Acme\HelloBundle\Entity\User u 
+                            WHERE u.id = :id');
+        $query->setParameters(array(
+                    'id' => $id
+        ));
+
+        $query->execute();
+
+        // ...
+    }
+    
+Of course you can use SELECT and UPDATE queries too. Doctrine brings its own 
+Query Language called DQL (Doctrine Query Language). The DQL has some 
+similarities with SQL but is a query language with its own syntax.
+
+.. tip::
+
+    You can read more about the Doctrine Query Language on the official
+    `Doctrine Query Language documentation`_ website. The advantage of DQL
+    is that it is database-agnostic - the same queries can be written in
+    DQL and work with any supported database engine.
+
+.. note::
+
+    There is a drawback when using a DQL DELETE or UPDATE statement. Specifically,
+    since this operation is made directly to the database, Doctrine isn't
+    aware of the option internally. For example, if you query for an object
+    and then make an update to that object directly in the database via an
+    UPDATE statement, the object itself won't reflect that update. So, be
+    careful when using these statements - your objects can become out-of-sync
+    with your database inside a single request.
+
+.. index::
+   single: Doctrine ORM; Repository;
+
+Repositories
+~~~~~~~~~~~~
+
+It is bad practice to make queries in the Symfony controllers. Such queries 
+should be done in the model layer of your bundle so that they can be tested
+and reused through your application. Fortunately, Doctrine allows you to
+use special classes called Repositories to encapsulate queries.
+
+Doctrine provides a default implementation for your repository classes, so you 
+can use their common methods to query your entities data. One of them is the 
+``findAll`` function.
+
+.. code-block:: php
+
+    $em = $this->get('doctrine')->getEntityManager();
+    $users = $em->getRepository('AcmeHelloBundle:User')->findAll();
+
+If you want to create your own function to query or manipulate your data, you 
+need to create a custom repository class for an entity. To do so, you need to 
+add the name of the repository class to your mapping definition.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Acme/HelloBundle/Entity/User.php
+        namespace Acme\HelloBundle\Entity;
+
+        /**
+         * @orm:Entity(repositoryClass="Acme\HelloBundle\Repository\UserRepository")
+         */
+        class User
+        {
+            //...
+        }
+
+    .. code-block:: yaml
+
+        # src/Acme/HelloBundle/Resources/config/doctrine/Acme.HelloBundle.Entity.User.orm.yml
+        Acme\HelloBundle\Entity\User:
+            type: entity
+            table: user
+            repositoryClass: Acme\HelloBundle\Repository\UserRepository
+            #...
+
+    .. code-block:: xml
+
+        <!-- src/Acme/HelloBundle/Resources/config/doctrine/Acme.HelloBundle.Entity.User.orm.xml -->
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+            <entity name="Acme\HelloBundle\Entity\User" table="user"
+                    repository-class="Acme\HelloBundle\Repository\UserRepository">
+                <id name="id" type="integer" column="id">
+                    <generator strategy="AUTO"/>
+                </id>
+                <field name="name" column="name" type="string" length="255" />
+            </entity>
+
+        </doctrine-mapping>
+
+The repository class is created for you if you run the following command
+to generate your entities.
+
+    $ php app/console doctrine:generate:entities
+
+If you have already generated your entity class before adding the ``repositoryClass``
+mapping, you have to create the class on your own. Fortunately, it's pretty
+easy. Simply create the class in the ``Repository`` directory of your bundle
+and be sure it extends ``Doctrine\ORM\EntityRepository``. Once you've created
+the class, you can add any method to query your entities.
+
+The following code shows a sample repository class.
+
+.. code-block:: php
+
+    // src/Acme/HelloBundle/Repository/UserRepository.php
+    namespace Acme\HelloBundle\Repository;
+
+    use Doctrine\ORM\EntityRepository;
+
+    class UserRepository extends EntityRepository
+    {
+        public function findAllOrderedByName()
+        {
+            return $this->getEntityManager()
+                        ->createQuery('SELECT u FROM Acme\HelloBundle\Entity\User u 
+                                        ORDER BY u.name ASC')
+                        ->getResult();
+        }
+    }
+
+.. tip::
+
+    The entity manager can be accessed via ``$this->getEntityManager()`` in the 
+    repositories functions.
+
+The usage of this new method is the same as with the default finder functions.
+
+.. code-block:: php
+
+    $em = $this->get('doctrine')->getEntityManager();
+    $users = $em->getRepository('AcmeHelloBundle:User')
+                ->findAllOrderedByName();
+
+
 .. index::
    single: Configuration; Doctrine ORM
    single: Doctrine; ORM Configuration
@@ -242,7 +403,7 @@ Configuration
 -------------
 
 In the overview we already described the only necessary configuration option
-to get the Doctrine ORM running with Symfony 2. All the other configuration
+to get the Doctrine ORM running with Symfony2. All the other configuration
 options are used with reasonable default values.
 
 This following configuration example shows all the configuration defaults that
@@ -356,7 +517,7 @@ The following configuration shows a bunch of mapping examples:
 Multiple Entity Managers
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use multiple ``EntityManager``s in a Symfony2 application. This is
+You can use multiple entity managers in a Symfony2 application. This is
 necessary if you are using different databases or even vendors with entirely
 different sets of entities.
 
@@ -617,3 +778,4 @@ get the choices. If not set all entities will be used.
 
 .. _documentation: http://www.doctrine-project.org/docs/orm/2.0/en
 .. _Doctrine:      http://www.doctrine-project.org
+.. _Doctrine Query Language documentation: http://www.doctrine-project.org/docs/orm/2.0/en/reference/dql-doctrine-query-language.html

book/forms.rst

@@ -368,8 +368,8 @@ the common form fields and data types you'll encounter:
 .. include:: /reference/forms/types/map.rst.inc
 
 Of course, you can also create your own custom field types. This topic is
-covered in the ":doc:`/cookbook/forms/create_custom_fields`" article of the
-cookbook.
+covered in the ":doc:`/cookbook/forms/create_custom_field_type`" article
+of the cookbook.
 
 .. index::
    single: Forms; Field type options
@@ -1149,7 +1149,6 @@ Learn more from the Cookbook
 
 * :doc:`Handling File Uploads </cookbook/forms/file_uploads>`
 * :doc:`Creating Custom Field Types </cookbook/forms/custom_field_types>`
-* :doc:`Dynamically adding Fields to a Form </cookbook/forms/dynamically_adding_fields>`
 * :doc:`/cookbook/form/twig_form_customization`
 
 .. _`Symfony2 Form Component`: https://github.com/symfony/Form

book/index.rst

@@ -17,7 +17,6 @@ Book
     security
     http_cache
     translation
-    console
     bundles
     service_container
     internals/index

book/internals/overview.rst

@@ -43,10 +43,6 @@ variables:
   :class:`Symfony\\Component\\HttpFoundation\\SessionStorage\\SessionStorageInterface`
   interface abstract session management ``session_*()`` functions.
 
-.. seealso::
-
-    Read more about the :doc:`HttpFoundation <http_foundation>` component.
-
 ``HttpKernel`` Component
 ------------------------
 

book/routing.rst

@@ -710,7 +710,7 @@ routing system can be:
 
         article_show:
           pattern:  /articles/{culture}/{year}/{title}.{_format}
-          defaults  { _controller: AcmeDemoBundle:Article:show, _format: html }
+          defaults: { _controller: AcmeDemoBundle:Article:show, _format: html }
           requirements:
               culture:  en|fr
               _format:  html|rss

cookbook/cache/varnish.rst

@@ -88,3 +88,5 @@ that will invalidate the cache for a given resource:
 
     You must protect the ``PURGE`` HTTP method somehow to avoid random people
     purging your cached data.
+
+.. _`Edge Architecture`: http://www.w3.org/TR/edge-arch

cookbook/configuration/pdo_session_storage.rst

@@ -0,0 +1,87 @@
+.. index::
+   single: Session; Database Storage
+
+How to use PdoSessionStorage to store Sessions in the Database
+==============================================================
+
+The default session storage of Symfony2 writes the session information to
+file(s). Most medium to large websites use a database to store the session
+values instead of files, because databases are easier to use and scale in
+a multi-webserver environment.
+
+Symfony2 has a built-in solution for database session storage called
+:class:`Symfony\\\Component\\HttpFoundation\\SessionStorage\\PdoSessionStorage`.
+To use it, you just need to change some parameters in ``config.yml`` (or the
+configuration format of your choice).
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        session:
+            # ...
+            storage_id:     session.storage.pdo
+            
+        parameters:
+            pdo.db_options:
+                db_table: session
+                db_id_col: session_id
+                db_data_col: session_value
+                db_time_col: session_time
+		
+        services:
+            session.storage.pdo:
+                class:     Symfony\Component\HttpFoundation\SessionStorage\PdoSessionStorage
+                arguments: [@pdo, %pdo.db_options%]
+					
+            pdo:
+                class: PDO
+                arguments:
+                    dsn:      "mysql:dbname=mydatabase"
+                    user:     myuser
+                    password: mypassword				
+
+
+* ``db_table``: The name of the session table in your database
+* ``db_id_col``: The name of the id column in your session table (VARCHAR(255) or larger)
+* ``db_data_col``: The name of the value column in your session table (TEXT or CLOB)
+* ``db_time_col``: The name of the time column in your session table (INTEGER)
+
+Sharing your Database Connection Information
+--------------------------------------------
+
+With the given configuration, the database connection settings are defined
+for the session storage connection only. This is OK when you use a separate
+database for the session data.
+
+But if you'd like to store the session data in the same database as the rest
+of your project's data, you can use the connection settings from the parameter.ini
+by referencing the database-related parameters defined there:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        pdo:
+            class: PDO
+            arguments:
+                dsn:      "mysql:dbname=%database_name%"
+                user:     %database_user%
+                password: %database_password%
+
+Example MySQL Statement
+-----------------------
+
+The SQL-Statement for creating the needed Database-Table could look like
+the following (MySQL):
+
+.. code-block:: sql
+
+    CREATE TABLE `session` (
+        `session_id` varchar(255) NOT NULL,
+        `session_value` text NOT NULL,
+        `session_time` int(11) NOT NULL,
+        PRIMARY KEY (`session_id`),
+        UNIQUE KEY `session_id_idx` (`session_id`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;