Merge branch '2.3'

Conflicts:
	Tests/Form/DataTransformer/ModelToIdPropertyTransformerTest.php

Form/DataTransformer/ModelToIdPropertyTransformer.php

@@ -94,9 +94,10 @@ public function transform($entityOrCollection)
         }
 
         if ($this->multiple) {
-            if (substr(get_class($entityOrCollection), -1 * strlen($this->className)) == $this->className) {
+            $isArray = is_array($entityOrCollection);
+            if (!$isArray && substr(get_class($entityOrCollection), -1 * strlen($this->className)) == $this->className) {
                 throw new \InvalidArgumentException('A multiple selection must be passed a collection not a single value. Make sure that form option "multiple=false" is set for many-to-one relation and "multiple=true" is set for many-to-many or one-to-many relations.');
-            } elseif ($entityOrCollection instanceof \ArrayAccess) {
+            } elseif ($isArray || ($entityOrCollection instanceof \ArrayAccess)) {
                 $collection = $entityOrCollection;
             } else {
                 throw new \InvalidArgumentException('A multiple selection must be passed a collection not a single value. Make sure that form option "multiple=false" is set for many-to-one relation and "multiple=true" is set for many-to-many or one-to-many relations.');

Resources/doc/getting_started/creating_an_admin.rst

@@ -0,0 +1,206 @@
+Creating an Admin
+=================
+
+You've been able to get the admin interface working in :doc:`the previous
+chapter <installation>`. In this tutorial, you'll learn how to tell SonataAdmin
+how an admin can manage your models.
+
+Step 0: Create a Model
+----------------------
+
+For the rest of the tutorial, you'll need some sort of model. In this tutorial,
+two very simple ``Post`` and ``Tag`` entities will be used. Generate them by
+using these commands:
+
+.. code-block:: bash
+
+    $ php app/console doctrine:generate:entity --entity="AppBundle:Category" --fields="name:string(255)" --no-interaction
+    $ php app/console doctrine:generate:entity --entity="AppBundle:BlogPost" --fields="title:string(255) body:textdraft:boolean" --no-interaction
+
+After this, you'll need to tweak the entities a bit:
+
+.. code-block:: php
+
+    // src/AppBundle/Entity/BlogPost.php
+    
+    // ...
+    class BlogPost
+    {
+        // ...
+
+        /**
+         * @ORM\ManyToOne(targetEntity="Category", inversedBy="blogPosts")
+         */
+        private $category;
+
+        public function setCategory(Category $category)
+        {
+            $this->category = $category;
+        }
+
+        public function getCategory()
+        {
+            return $this->category;
+        }
+
+        // ...
+    }
+
+.. code-block:: php
+
+    // src/AppBundle/Entity/Category.php
+
+    // ...
+    use Doctrine\Common\Collections\ArrayCollection;
+    // ...
+
+    class Category
+    {
+        // ...
+
+        /**
+        * @ORM\OneToMany(targetEntity="BlogPost", mappedBy="category")
+        */
+        private $blogPosts;
+
+        public function __construct()
+        {
+            $this->blogPosts = new ArrayCollection();
+        }
+
+        public function getBlogPosts()
+        {
+            return $this->blogPosts;
+        }
+
+        // ...
+    }
+
+After this, create the schema for these entities:
+
+.. code-block:: bash
+
+    $ php app/console doctrine:schema:create
+
+.. note::
+
+    This article assumes you have basic knowledge of the Doctrine2 ORM and
+    you've set up a database correctly.
+
+Step 1: Create an Admin Class
+-----------------------------
+
+SonataAdminBundle helps you manage your data using a graphical interface that
+will let you create, update or search your model instances. The bundle relies
+on Admin classes to know which models will be managed and how these actions
+will look like.
+
+An Admin class decides which fields to show on a listing, which fields are used
+to find entries and how the create form will look like. Each model will have
+its own Admin class.
+
+Knowing this, let's create an Admin class for the ``Category`` entity. The
+easiest way to do this is by extending ``Sonata\AdminBundle\Admin\Admin``.
+
+.. code-block:: php
+
+    // src/AppBundle/Admin/CategoryAdmin.php
+    namespace AppBundle\Admin;
+
+    use Sonata\AdminBundle\Admin\Admin;
+    use Sonata\AdminBundle\Datagrid\ListMapper;
+    use Sonata\AdminBundle\Datagrid\DatagridMapper;
+    use Sonata\AdminBundle\Form\FormMapper;
+
+    class CategoryAdmin extends Admin
+    {
+        protected function configureFormFields(FormMapper $formMapper)
+        {
+            $formMapper->add('name', 'text');
+        }
+
+        protected function configureDatagridFilters(DatagridMapper $datagridMapper)
+        {
+            $datagridMapper->add('name');
+        }
+
+        protected function configureListFields(ListMapper $listMapper)
+        {
+            $listMapper->addIdentifier('name');
+        }
+    }
+
+So, what does this code do?
+
+* **Line 11-14**: These lines configure which fields are displayed on the edit
+  and create actions. The ``FormMapper`` behaves similar to the ``FormBuilder``
+  of the Symfony Form component;
+* **Line 16-19**: This method configures the filters, used to filter and sort
+  the list of models;
+* **Line 21-24**: Here you specify which fields are shown when all models are
+  listed (the ``addIdentifier()`` method means that this field will link to the
+  show/edit page of this particular model).
+
+This is the most basic example of the Admin class. You can configure a lot more
+with the Admin class. This will be covered by other, more advanced, articles.
+
+Step 3: Register the Admin class
+--------------------------------
+
+You've now created an Admin class, but there is currently no way for the
+SonataAdminBundle to know that this Admin class exists. To tell the
+SonataAdminBundle of the existence of this Admin class, you have to create a
+service and tag it with the ``sonata.admin`` tag:
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    
+    # ...
+    services:
+        admin.category:
+            class: AppBundle\Admin\CategoryAdmin
+            arguments: [~, AppBundle\Entity\Category, ~]
+            tags:
+                - { name: sonata.admin, manager_type: orm, label: Category }
+
+The constructor of the base Admin class has many arguments. SonataAdminBundle
+provides a compiler pass which takes care of configuring it correctly for you.
+You can often tweak things using tag attributes. The code shown here is the
+shortest code needed to get it working.
+
+Step 4: Register SonataAdmin custom Routes
+------------------------------------------
+
+SonataAdminBundle generates routes for the Admin classes on the fly. To load these
+routes, you have to make sure the routing loader of the SonataAdminBundle is executed:
+
+.. code-block:: yaml
+
+    # app/config/routing.yml
+
+    # ...
+    _sonata_admin:
+        resource: .
+        type: sonata_admin
+        prefix: /admin
+
+View the Category Admin Interface
+---------------------------------
+
+Now you've created the admin class for your category, you probably want to know
+how this looks like in the admin interface. Well, let's find out by going to
+http://localhost:8000/admin
+
+.. image:: ../images/getting_started_category_dashboard.png
+
+Feel free to play around and add some categories, like "Symfony" and "Sonata
+Project". In the next chapters, you'll create an admin for the ``BlogPost``
+entity and learn more about this class.
+
+.. tip::
+
+    If you're not seeing the nice labels, but instead something like
+    "link_add", you should make sure that you've `enabled the translator`_.
+
+.. _`enabled the translator`: http://symfony.com/doc/current/book/translation.html#configuration

Resources/doc/getting_started/installation.rst

@@ -0,0 +1,173 @@
+Installation
+============
+
+SonataAdminBundle is just a bundle and as such, you can install it at any
+moment during a project's lifecycle.
+
+1. Download the Bundle
+----------------------
+
+Open a command console, enter your project directory and execute the
+following command to download the latest stable version of this bundle:
+
+.. code-block:: bash
+
+    $ composer require sonata-project/admin-bundle "2.3.*"
+
+This command requires you to have Composer installed globally, as explained in
+the `installation chapter`_ of the Composer documentation.
+
+1.1. Download a Storage Bundle
+------------------------------
+
+You've now downloaded the SonataAdminBundle. While this bundle contains all
+functionality, it needs storage bundles to be able to communicate with a
+database. Before using the SonataAdminBundle, you have to download one of these
+storage bundles. The official storage bundles are:
+
+* `SonataDoctrineORMAdminBundle`_ (integrates the Doctrine ORM);
+* `SonataDoctrineMongoDBAdminBundle`_ (integrates the Doctrine MongoDB ODM);
+* `SonataPropelAdminBundle`_ (integrates Propel);
+* `SonataDoctrinePhpcrAdminBundle`_ (integrates the Doctrine PHPCR ODM).
+
+You can download them in the same way as the SonataAdminBundle. For instance,
+to download the SonataDoctrineORMAdminBundle, execute the following command:
+
+.. code-block:: bash
+
+    $ composer require sonata-project/doctrine-orm-admin-bundle "2.3.*"
+
+.. tip::
+
+    Don't know which to choose? Most new users prefer SonataDoctrineORMAdmin,
+    to interact with traditional relational databases (MySQL, PostgreSQL, etc).
+
+Step 2: Enable the Bundle
+-------------------------
+
+Then, enable the bundle and the bundles is relies on by adding the following
+line in the `app/AppKernel.php` file of your project:
+
+.. code-block:: php
+
+    // app/AppKernel.php
+
+    // ...
+    class AppKernel extends Kernel
+    {
+        public function registerBundles()
+        {
+            $bundles = array(
+                // ...
+
+                // The admin requires some twig functions defined in the security
+                // bundle, like is_granted. Register this bundle if it wasn't the case
+                // already.
+                new Symfony\Bundle\SecurityBundle\SecurityBundle(),
+
+                // These are the other bundles the SonataAdminBundle relies on
+                new Sonata\CoreBundle\SonataCoreBundle(),
+                new Sonata\BlockBundle\SonataBlockBundle(),
+                new Knp\Bundle\MenuBundle\KnpMenuBundle(),
+
+                // And finally, the storage and SonataAdminBundle
+                new Sonata\DoctrineORMAdminBundle\SonataDoctrineORMAdminBundle(),
+                new Sonata\AdminBundle\SonataAdminBundle(),
+            );
+
+            // ...
+        }
+
+        // ...
+    }
+
+.. note::
+
+    If a bundle is already registered somewhere in your ``AppKernel.php``, you
+    should not register it again.
+
+.. note::
+
+    Since version 2.3, the bundle comes with jQuery and other front-end
+    libraries. To update the versions (which isn't required), you can use
+    `Bower`_. To make sure you get the dependencies that match the version of
+    SonataAdminBundle you are using, you can make bower use the local bower
+    dependency file, like this:
+
+    .. code-block:: bash
+
+        $ bower install ./vendor/sonata-project/admin-bundle/bower.json
+
+Step 3: Configure the Installed Bundles
+---------------------------------------
+
+Now all needed bundles are downloaded and registered, you have to add some
+configuration. The admin interface is using SonataBlockBundle to put everything
+in blocks. You just have to tell the block bundle about the existence of the
+admin block:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    sonata_block:
+        default_contexts: [cms]
+        blocks:
+            # enable the SonataAdminBundle block
+            sonata.admin.block.admin_list:
+                contexts: [admin]
+            # ...
+
+.. note::
+
+    Don't worry too much if, at this point, you don't yet understand fully
+    what a block is. The SonataBlockBundle is a useful tool, but it's not vital
+    that you understand it in order to use the admin bundle.
+
+Step 4: Import Routing Configuration
+------------------------------------
+
+The bundles are now registered and configured correctly. Before you can use it,
+the Symfony router needs to know the routes provided by the SonataAdminBundle.
+You can do this by importing them in the routing configuration:
+
+.. code-block:: yaml
+
+    # app/config/routing.yml
+    admin_area:
+        resource: "@SonataAdminBundle/Resources/config/routing/sonata_admin.xml"
+        prefix: /admin
+
+Step 5: Preparing your Environment
+----------------------------------
+
+As with all bundles you install, it's a good practice to clear the cache and
+install the assets:
+
+.. code-block:: bash
+
+    $ php app/console cache:clear
+    $ php app/console assets:install
+
+The Admin Interface
+-------------------
+
+You've finished the installation process, congratulations. If you fire up the
+server, you can now visit the admin page on http://localhost:8000/admin
+
+.. note::
+
+    This tutorial assumes you are using the build-in server using the
+    ``php app/console server:start`` (or ``server:run``) command.
+
+.. image:: ../images/getting_started_empty_dashboard.png
+
+As you can see, the admin panel is very empty. This is because no bundle has
+provided admin functionality for the admin bundle yet. Fortunately, you'll
+learn how to do this in the :doc:`next chapter <creating_an_admin>`.
+
+.. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
+.. _SonataDoctrineORMAdminBundle: http://sonata-project.org/bundles/doctrine-orm-admin/master/doc/index.html
+.. _SonataDoctrineMongoDBAdminBundle: http://sonata-project.org/bundles/mongo-admin/master/doc/index.html
+.. _SonataPropelAdminBundle: http://sonata-project.org/bundles/propel-admin/master/doc/index.html
+.. _SonataDoctrinePhpcrAdminBundle: http://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/index.html
+.. _Bower: http://bower.io/