Merge branch '2.1'

Author: weaverryan

book/controller.rst

@@ -705,6 +705,11 @@ headers and content that's sent back to the client::
     header names are normalized so that using ``Content-Type`` is equivalent
     to ``content-type`` or even ``content_type``.
 
+.. tip::
+
+    There is also a special :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
+    class that helps return JSON responses. See :ref:`component-http-foundation-json-response`.
+
 .. index::
    single: Controller; Request object
 

book/internals.rst

@@ -21,11 +21,9 @@ on top of the previous one.
 
 .. tip::
 
-    Autoloading is not managed by the framework directly; it's done
-    independently with the help of the
-    :class:`Symfony\\Component\\ClassLoader\\UniversalClassLoader` class
-    and the ``src/autoload.php`` file. Read the :doc:`dedicated chapter
-    </components/class_loader>` for more information.
+    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.
 
 ``HttpFoundation`` Component
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

book/performance.rst

@@ -42,19 +42,32 @@ your php.ini configuration.
 .. index::
    single: Performance; Autoloader
 
-Use an Autoloader that caches (e.g. ``ApcUniversalClassLoader``)
-----------------------------------------------------------------
+Use Composer's Class Map Functionality
+--------------------------------------
 
-By default, the Symfony2 standard edition uses the ``UniversalClassLoader``
-in the `autoloader.php`_ file. This autoloader is easy to use, as it will
+By default, the Symfony2 standard edition uses Composer's autoloader
+in the `autoload.php`_ file. This autoloader is easy to use, as it will
 automatically find any new classes that you've placed in the registered
 directories.
 
 Unfortunately, this comes at a cost, as the loader iterates over all configured
 namespaces to find a particular file, making ``file_exists`` calls until it
 finally finds the file it's looking for.
 
-The simplest solution is to cache the location of each class after it's located
+The simplest solution is to tell Composer to build a "class map" (i.e. a
+big array of the locations of all the classes). This can be done from the
+command line, and might become part of your deploy process::
+
+.. code-block:: bash
+
+    php composer.phar dump-autoload --optimize
+
+Internally, this builds the big class map array in ``vendor/composer/autoload_namespaces.php``.
+
+Caching the Autoloader with APC
+-------------------------------
+
+Another solution is to to cache the location of each class after it's located
 the first time. Symfony comes with a class - :class:`Symfony\\Component\\ClassLoader\\ApcClassLoader` -
 that does exactly this. To use it, just adapt your front controller file.
 If you're using the Standard Distribution, this code should already be available
@@ -125,5 +138,5 @@ is no longer a reason to use a bootstrap file.
 
 .. _`byte code caches`: http://en.wikipedia.org/wiki/List_of_PHP_accelerators
 .. _`APC`: http://php.net/manual/en/book.apc.php
-.. _`autoloader.php`: https://github.com/symfony/symfony-standard/blob/master/app/autoload.php
+.. _`autoload.php`: https://github.com/symfony/symfony-standard/blob/master/app/autoload.php
 .. _`bootstrap file`: https://github.com/sensio/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php

components/class_loader.rst

@@ -28,7 +28,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/ClassLoader);
-* Install it via Composer (``symfony/class-loader`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/class-loader`` on `Packagist`_).
 
 Usage
 -----

components/config/introduction.rst

@@ -18,7 +18,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Config);
-* Install it via Composer (``symfony/config`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/config`` on `Packagist`_).
 
 Sections
 --------

components/console/introduction.rst

@@ -18,7 +18,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Console);
-* Install it via Composer (``symfony/console`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/console`` on `Packagist`_).
 
 Creating a basic Command
 ------------------------

components/css_selector.rst

@@ -13,7 +13,7 @@ Installation
 You can install the component in several different ways:
 
 * Use the official Git repository (https://github.com/symfony/CssSelector);
-* Install it via Composer (``symfony/css-selector`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/css-selector`` on `Packagist`_).
 
 Usage
 -----

components/dependency_injection/introduction.rst

@@ -17,7 +17,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/DependencyInjection);
-* Install it via Composer (``symfony/dependency-injection`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/dependency-injection`` on `Packagist`_).
 
 Basic Usage
 -----------

components/dom_crawler.rst

@@ -13,7 +13,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/DomCrawler);
-* Install it via Composer (``symfony/dom-crawler`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/dom-crawler`` on `Packagist`_).
 
 Usage
 -----

components/event_dispatcher/introduction.rst

@@ -50,7 +50,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/EventDispatcher);
-* Install it via Composer (``symfony/event-dispatcher`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/event-dispatcher`` on `Packagist`_).
 
 Usage
 -----

components/finder.rst

@@ -14,7 +14,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Finder);
-* Install it via Composer (``symfony/finder`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/finder`` on `Packagist`_).
 
 Usage
 -----

components/http_foundation/introduction.rst

@@ -22,7 +22,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/HttpFoundation);
-* Install it via Composer (``symfony/http-foundation`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/http-foundation`` on `Packagist`_).
 
 Request
 -------
@@ -409,6 +409,49 @@ abstracts the hard work behind a simple API::
 
     $response->headers->set('Content-Disposition', $d);
 
+.. _component-http-foundation-json-response:
+
+Creating a JSON Response
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any type of response can be created via the
+:class:`Symfony\\Component\\HttpFoundation\\Response` class by setting the
+right content and headers. A JSON response might look like this::
+
+    use Symfony\Component\HttpFoundation\Response;
+    
+    $response = new Response();
+    $response->setContent(json_encode(array(
+        'data' => 123
+    )));
+    $response->headers->set('Content-Type', 'application/json');
+
+.. versionadded:: 2.1
+    The :class:`Symfony\\Component\\HttpFoundation\\JsonResponse` class was added in Symfony 2.1.
+
+There is also a helpful :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`
+class, which can make this even easier::
+
+    use Symfony\Component\HttpFoundation\JsonResponse;
+
+    $response = new JsonResponse();
+    $response->setContent(array(
+        'data' => 123
+    ));
+
+This encodes your array of data to JSON and sets the ``Content-Type`` header
+to ``application/json``. If you're using JSONP, you can set the callback
+function that the data should be passed to::
+
+    $response->setCallback('handleResponse');
+
+In this case, the ``Content-Type`` header will be ``text/javascript`` and
+the response content will look like this:
+
+.. code-block:: javascript
+
+    handleResponse({'data': 123});
+
 Session
 -------
 

components/index.rst

@@ -4,6 +4,7 @@ The Components
 .. toctree::
     :hidden:
 
+    using_components
     class_loader
     config/index
     console/index

components/locale.rst

@@ -28,7 +28,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Locale);
-* Install it via Composer (``symfony/locale`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/locale`` on `Packagist`_).
 
 Usage
 -----

components/map.rst.inc

@@ -1,3 +1,5 @@
+* :doc:`/components/using_components`
+
 * **Class Loader**
 
   * :doc:`/components/class_loader`

components/process.rst

@@ -13,7 +13,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Process);
-* Install it via Composer (``symfony/process`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/process`` on `Packagist`_).
 
 Usage
 -----

components/routing/introduction.rst

@@ -14,7 +14,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Routing);
-* Install it via Composer (``symfony/routing`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/routing`` on `Packagist`_).
 
 Usage
 -----

components/serializer.rst

@@ -28,7 +28,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Serializer);
-* Install it via Composer (``symfony/serializer`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/serializer`` on `Packagist`_).
 
 Usage
 -----

components/templating.rst

@@ -19,7 +19,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Templating);
-* Install it via Composer (``symfony/templating`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/templating`` on `Packagist`_).
 
 Usage
 -----

components/using_components.rst

@@ -0,0 +1,96 @@
+.. index::
+   single: Components; Installation
+   single: Components; Usage
+
+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.
+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.
+
+This article will take you through using the :doc:`/components/finder`, though
+this applies to using any component.
+
+Using the Finder Component
+--------------------------
+
+**1.** If you're creating a new project, create a new empty directory for it.
+
+**2.** Create a new file called ``composer.json`` and paste the following into it:
+
+.. code-block:: json
+
+    {
+        "require": {
+            "symfony/finder": "2.1.*"
+        }
+    }
+
+If you already have a ``composer.json`` file, just add this line to it. You
+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:
+
+.. code-block:: bash
+
+    $ php composer.phar install
+
+**4.** 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
+takes care of autoloading all of the libraries so that you can use them
+immediately::
+
+        // File: src/script.php
+
+        require_once '../vendor/autoload.php';
+
+        use Symfony\Component\Finder\Finder;
+
+        $finder = new Finder();
+        $finder->in('../data/');
+
+        // ...
+
+.. tip::
+
+    If you want to use all of the Symfony2 Components, then instead of adding
+    them one by one:
+
+        .. code-block:: json
+
+            {
+                "require": {
+                    "symfony/finder": "2.1.*",
+                    "symfony/dom-crawler": "2.1.*",
+                    "symfony/css-selector": "2.1.*"
+                }
+            }
+
+    you can use:
+
+        .. code-block:: json
+
+            {
+                "require": {
+                    "symfony/symfony": "2.1.*"
+                }
+            }
+
+    This will include the Bundle and Bridge libraries, which you may not
+    actually need.
+
+Now What?
+---------
+
+Now that the component is installed and autoloaded, read the specific component's
+documentation to find out more about how to use it.
+
+And have fun!
+
+.. _packagist.org: https://packagist.org/

components/yaml.rst

@@ -27,7 +27,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Yaml);
-* Install it via Composer (``symfony/yaml`` on `Packagist`_).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/yaml`` on `Packagist`_).
 
 Why?
 ----

cookbook/debugging.rst

@@ -46,7 +46,6 @@ below::
     // ...
 
     // require_once __DIR__.'/../app/bootstrap.php.cache';
-    require_once __DIR__.'/../vendor/symfony/symfony/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
     require_once __DIR__.'/../app/autoload.php';
     require_once __DIR__.'/../app/AppKernel.php';