Jun 25, 2010 · Jul 20, 2010 · Jul 26, 2010 · Jul 23, 2010 · Jul 28, 2010 · Jul 29, 2010
diff --git a/guides/doctrine/configuration.rst b/guides/doctrine/configuration.rst
 DBAL Configuration
 ------------------

 <<<<<<< HEAD:guides/doctrine/configuration.rst
 .. code-block:: yaml

 =======
    [yml]
 >>>>>>> origin/PR3:guides/en/Doctrine/Configuration.markdown
    # config/config.yml
    doctrine.dbal:
        driver:   PDOMySql
 ORM Configuration
 -----------------

 <<<<<<< HEAD:guides/doctrine/configuration.rst
 .. code-block:: yaml
 =======
    doctrine.orm:
      default_entity_manager:   default
      cache_driver:             apc           # array, apc, memcache, xcache
      entity_managers:
        default:
          connection:           default
        customer:
          connection:           customer
 >>>>>>> origin/PR3:guides/en/Doctrine/Configuration.markdown

    doctrine.orm:
      default_entity_manager:   default
      :drop                        Processes the schema and either drop the database schema of EntityManager Storage Connection or generate the SQL output.
      :update                      Processes the schema and either update the database schema of EntityManager Storage Connection or generate the SQL output.

    ...
    ...
diff --git a/guides/pt_BR/Twig.rst b/guides/pt_BR/Twig.rst
 .. index::
   single: Twig
   single: View; Twig

 Twig & Symfony2
 ===============

 `Twig`_ is a flexible, fast, and secure template language for PHP. Symfony2
 has native support for Twig through ``TwigBundle``.

 .. index::
   single: Twig; Installation
   single: Twig; Configuration

 Installation & Configuration
 ----------------------------

 Enable the ``TwigBundle`` in your kernel::

    public function registerBundles()
    {
      $bundles = array(
        // ...
        new Symfony\Framework\TwigBundle\Bundle(),
      );

      // ...
    }

 Then, configure it:

 .. code-block:: yaml

    # config/config.yml
    twig.config: ~

    # config/config_dev.yml
    twig.config:
        auto_reload: true

 .. tip::
   The configuration options are the same as the ones you pass to the
   ``Twig_Environment`` `constructor`_.

 Usage
 -----

 To render a Twig template instead of a PHP one, add the ``:twig`` suffix at the
 end of the template name. The controller below renders the ``index.twig``
 template::

    public function indexAction($name)
    {
        return $this->render('HelloBundle:Hello:index:twig', array('name' => $name));
    }

 The ``:twig`` suffix is only needed when there is no context, like in a
 controller. But when you extend or include a template from a Twig template,
 Symfony2 automatically switches the default engine to Twig:

 .. code-block:: jinja

    {# index.twig #}

    {# no need to add :twig as this is the default #}
    {% extends 'HelloBundle::layout' %}

    {% block content %}
        Hello {{ name }}

        {# use the special render tag to render a template #}
        {% render 'HelloBundle:Hello:sidebar' %}
    {% endblock %}

 To embed a PHP template in a Twig one, add the ``:php`` suffix to the template
 name:

 .. code-block:: jinja

    {# index.twig #}

    {% render 'HelloBundle:Hello:sidebar:php' %}

 And the opposite is also true::

    {# index.php #}

    <?php $view->render('HelloBundle:Hello:sidebar:twig') ?>

 .. index::
   single: Twig; Helpers

 Helpers
 -------

 The default Symfony2 helpers are available within a Twig template via
 specialized tags:

 .. code-block:: jinja

    {# add a javascript #}
    {% javascript 'bundles/blog/js/blog.js' %}

    {# add a stylesheet #}
    {% stylesheet 'bundles/blog/css/blog.css' with ['media': 'screen'] %}

    {# output the javascripts and stylesheets in the layout #}
    {% javascripts %}
    {% stylesheets %}

    {# generate a URL for an asset #}
    {% asset 'css/blog.css' %}
    {% asset 'images/logo.png' %}

    {# generate a route #}
    {% route 'blog_post' with ['id': post.id] %}

    {# render a template #}
    {% include 'BlogBundle:Post:list' %}

    {# embed another controller response #}
    {% render 'BlogBundle:Post:list' with ['path': ['limit': 2], 'alt': 'BlogBundle:Post:error'] %}

 .. _twig_extensions::

 Enabling Custom Extensions
 --------------------------

 To enable a Twig extension, add it as a regular service in one of your
 configuration, and add a ``twig.extension`` annotation:

 .. code-block:: yaml

    services:
        twig.extension.your_extension_name:
            class:      Fully\Qualified\Extension\Class\Name
            annotation: { name: twig.extension }

 .. _Twig:        http://www.twig-project.org/
 .. _constructor: http://www.twig-project.org/book/03-Twig-for-Developers
diff --git a/guides/pt_BR/bundles/best_practices.rst b/guides/pt_BR/bundles/best_practices.rst
 .. index::
   single: Bundles; Best Practices

 Bundle Best Practices
 =====================

 A bundle is a directory that has a well-defined structure and can host
 anything from classes to controllers and web resources. Even if bundles are
 very flexible, you should follow some best practices if you want to distribute
 them.

 .. index::
   pair: Bundles; Naming Conventions

 Bundle Name
 -----------

 A bundle is also a PHP namespace, composed of several segments:

 * The **main namespace**: either ``Bundle``, for reusable bundles, or
  ``Application`` for application specific bundles;
 * The **vendor namespace** (optional for ``Application`` bundles): something
  unique to you or your company (like ``Sensio``);
 * *(optional)* The **category namespace(s)** to better organize a large set of
  bundles;
 * The **bundle name**.

 .. caution::
   The vendor namespace and the category namespaces are only possible as of
   Symfony2 PR3.

 The bundle name must follow the following rules:

 * Use only alphanumeric characters and underscores;
 * Use a CamelCased name;
 * Use a descriptive and short name (no more than 2 words);
 * Prefix the name with the concatenation of the vendor and category
  namespaces;
 * Suffix the name with ``Bundle``.

 Some good bundle names:

 =================================== ==========================
 Namespace                           Bundle Name
 =================================== ==========================
 ``Bundle\Sensio\BlogBundle``        ``SensioBlogBundle``
 ``Bundle\Sensio\Social\BlogBundle`` ``SensioSocialBlogBundle``
 ``Application\BlogBundle``          ``BlogBundle``
 =================================== ==========================

 Directory Structure
 -------------------

 The basic directory structure of a ``HelloBundle`` bundle must read as
 follows::

    XXX/...
        HelloBundle/
            HelloBundle.php
            Controller/
            Resources/
                meta/
                    LICENSE
                config/
                doc/
                    index.rst
                views/
                web/
            Tests/

 The ``XXX`` directory(ies) reflects the namespace structure of the bundle.

 The following files are mandatory:

 * ``HelloBundle.php``;
 * ``Resources/meta/LICENSE``: The full license for the code;
 * ``Resources/doc/index.rst``: The root file for the Bundle documentation.

 .. note::
   These conventions ensure that automated tools can rely on this default
   structure to work.

 The depth of sub-directories should be kept to the minimal for most used
 classes and files (2 levels at a maximum). More levels can be defined for
 non-strategic, less-used files.

 The bundle directory is read-only. If you need to write temporary files, store
 them under the ``cache/`` or ``log/`` directory of the host application. Tools can
 generate files in the bundle directory structure, but only if the generated
 files are going to be part of the repository.

 The following classes and files have specific emplacements:

 ========================= =====================
 Type                      Directory
 ========================= =====================
 Controllers               ``Controller/``
 Templates                 ``Resources/views/``
 Unit and Functional Tests ``Tests/``
 Web Resources             ``Resources/web/``
 Configuration             ``Resources/config/``
 Commands                  ``Command/``
 ========================= =====================

 Classes
 -------

 The bundle directory structure is used as the namespace hierarchy. For
 instance, a ``HelloController`` controller is stored in
 ``Bundle/HelloBundle/Controller/HelloController.php`` and the fully qualified
 class name is ``Bundle\HelloBundle\Controller\HelloController``.

 All classes and files must follow the Symfony2 coding `standards`_.

 Some classes should be seen as facades and should be as short as possible,
 like Commands, Helpers, Listeners, and Controllers.

 Classes that connects to the Event Dispatcher should have a name that ends
 with ``Listener``.

 Exceptions classes should be stored in an ``Exception`` sub-namespace.

 Vendors
 -------

 A bundle must not embed third-party PHP libraries. It should rely on the
 standard Symfony2 autoloading instead.

 A bundle should not embed third-party libraries written in JavaScript, CSS, or
 any other language.

 Tests
 -----

 A bundle should come with a test suite written with PHPUnit and stored under
 the ``Tests/`` directory. Tests should follow the following principles:

 * The test suite must be executable with a simple ``phpunit`` command run from
  a sample application;
 * The functional tests should only be used to test the response output and
  some profiling information if you have some;
 * The code coverage should at least covers 95% of the code base.

 .. note::
   A test suite must not contain ``AllTests.php`` scripts, but must rely on the
   existence of a ``phpunit.xml.dist`` file.

 Documentation
 -------------

 All classes and functions must come with full PHPDoc.

 Extensive documentation should also be provided in the :doc:`reStructuredText
 </contributing/documentation/format>` format, under the ``Resources/doc/``
 directory; the ``Resources/doc/index.rst`` file is the only mandatory file.

 Templates
 ---------

 If a bundle provides templates, they should be defined in plain PHP. A bundle
 must not provide a main layout, but extends a default ``base`` template (which
 must provide two slots: ``content`` and ``head``).

 .. note::
   The only other template engine supported is Twig, but only for specific
   cases.

 Configuration
 -------------

 Configuration must be done via the Symfony2 built-in `mechanism`_. A bundle
 should provide all its default configurations in XML.

 .. _standards: http://www.symfony-reloaded.org/contributing/Code/Standards
 .. _mechanism: http://www.symfony-reloaded.org/guides/Bundles/Configuration
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,8 +4,12 @@ Doctrine Configuration
		DBAL Configuration
		------------------

		<<<<<<< HEAD:guides/doctrine/configuration.rst
		.. code-block:: yaml

		=======
		[yml]
		>>>>>>> origin/PR3:guides/en/Doctrine/Configuration.markdown
		# config/config.yml
		doctrine.dbal:
		driver: PDOMySql
Expand DownExpand Up		@@ -64,7 +68,18 @@ but you must pass it an argument with the name of the connection you want to get
		ORM Configuration
		-----------------

		<<<<<<< HEAD:guides/doctrine/configuration.rst
		.. code-block:: yaml
		=======
		doctrine.orm:
		default_entity_manager: default
		cache_driver: apc # array, apc, memcache, xcache
		entity_managers:
		default:
		connection: default
		customer:
		connection: customer
		>>>>>>> origin/PR3:guides/en/Doctrine/Configuration.markdown

		doctrine.orm:
		default_entity_manager: default
Expand DownExpand Up		@@ -150,4 +165,4 @@ or options:
		:drop Processes the schema and either drop the database schema of EntityManager Storage Connection or generate the SQL output.
		:update Processes the schema and either update the database schema of EntityManager Storage Connection or generate the SQL output.

		...
		...
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,140 @@
		.. index::
		single: Twig
		single: View; Twig

		Twig & Symfony2
		===============

		`Twig`_ is a flexible, fast, and secure template language for PHP. Symfony2
		has native support for Twig through ``TwigBundle``.

		.. index::
		single: Twig; Installation
		single: Twig; Configuration

		Installation & Configuration
		----------------------------

		Enable the ``TwigBundle`` in your kernel::

		public function registerBundles()
		{
		$bundles = array(
		// ...
		new Symfony\Framework\TwigBundle\Bundle(),
		);

		// ...
		}

		Then, configure it:

		.. code-block:: yaml

		# config/config.yml
		twig.config: ~

		# config/config_dev.yml
		twig.config:
		auto_reload: true

		.. tip::
		The configuration options are the same as the ones you pass to the
		``Twig_Environment`` `constructor`_.

		Usage
		-----

		To render a Twig template instead of a PHP one, add the ``:twig`` suffix at the
		end of the template name. The controller below renders the ``index.twig``
		template::

		public function indexAction($name)
		{
		return $this->render('HelloBundle:Hello:index:twig', array('name' => $name));
		}

		The ``:twig`` suffix is only needed when there is no context, like in a
		controller. But when you extend or include a template from a Twig template,
		Symfony2 automatically switches the default engine to Twig:

		.. code-block:: jinja

		{# index.twig #}

		{# no need to add :twig as this is the default #}
		{% extends 'HelloBundle::layout' %}

		{% block content %}
		Hello {{ name }}

		{# use the special render tag to render a template #}
		{% render 'HelloBundle:Hello:sidebar' %}
		{% endblock %}

		To embed a PHP template in a Twig one, add the ``:php`` suffix to the template
		name:

		.. code-block:: jinja

		{# index.twig #}

		{% render 'HelloBundle:Hello:sidebar:php' %}

		And the opposite is also true::

		{# index.php #}

		<?php $view->render('HelloBundle:Hello:sidebar:twig') ?>

		.. index::
		single: Twig; Helpers

		Helpers
		-------

		The default Symfony2 helpers are available within a Twig template via
		specialized tags:

		.. code-block:: jinja

		{# add a javascript #}
		{% javascript 'bundles/blog/js/blog.js' %}

		{# add a stylesheet #}
		{% stylesheet 'bundles/blog/css/blog.css' with ['media': 'screen'] %}

		{# output the javascripts and stylesheets in the layout #}
		{% javascripts %}
		{% stylesheets %}

		{# generate a URL for an asset #}
		{% asset 'css/blog.css' %}
		{% asset 'images/logo.png' %}

		{# generate a route #}
		{% route 'blog_post' with ['id': post.id] %}

		{# render a template #}
		{% include 'BlogBundle:Post:list' %}

		{# embed another controller response #}
		{% render 'BlogBundle:Post:list' with ['path': ['limit': 2], 'alt': 'BlogBundle:Post:error'] %}

		.. _twig_extensions::

		Enabling Custom Extensions
		--------------------------

		To enable a Twig extension, add it as a regular service in one of your
		configuration, and add a ``twig.extension`` annotation:

		.. code-block:: yaml

		services:
		twig.extension.your_extension_name:
		class: Fully\Qualified\Extension\Class\Name
		annotation: { name: twig.extension }

		.. _Twig: http://www.twig-project.org/
		.. _constructor: http://www.twig-project.org/book/03-Twig-for-Developers
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,175 @@
		.. index::
		single: Bundles; Best Practices

		Bundle Best Practices
		=====================

		A bundle is a directory that has a well-defined structure and can host
		anything from classes to controllers and web resources. Even if bundles are
		very flexible, you should follow some best practices if you want to distribute
		them.

		.. index::
		pair: Bundles; Naming Conventions

		Bundle Name
		-----------

		A bundle is also a PHP namespace, composed of several segments:

		* The main namespace: either ``Bundle``, for reusable bundles, or
		``Application`` for application specific bundles;
		* The vendor namespace (optional for ``Application`` bundles): something
		unique to you or your company (like ``Sensio``);
		* (optional) The category namespace(s) to better organize a large set of
		bundles;
		* The bundle name.

		.. caution::
		The vendor namespace and the category namespaces are only possible as of
		Symfony2 PR3.

		The bundle name must follow the following rules:

		* Use only alphanumeric characters and underscores;
		* Use a CamelCased name;
		* Use a descriptive and short name (no more than 2 words);
		* Prefix the name with the concatenation of the vendor and category
		namespaces;
		* Suffix the name with ``Bundle``.

		Some good bundle names:

		=================================== ==========================
		Namespace Bundle Name
		=================================== ==========================
		``Bundle\Sensio\BlogBundle`` ``SensioBlogBundle``
		``Bundle\Sensio\Social\BlogBundle`` ``SensioSocialBlogBundle``
		``Application\BlogBundle`` ``BlogBundle``
		=================================== ==========================

		Directory Structure
		-------------------

		The basic directory structure of a ``HelloBundle`` bundle must read as
		follows::

		XXX/...
		HelloBundle/
		HelloBundle.php
		Controller/
		Resources/
		meta/
		LICENSE
		config/
		doc/
		index.rst
		views/
		web/
		Tests/

		The ``XXX`` directory(ies) reflects the namespace structure of the bundle.

		The following files are mandatory:

		* ``HelloBundle.php``;
		* ``Resources/meta/LICENSE``: The full license for the code;
		* ``Resources/doc/index.rst``: The root file for the Bundle documentation.

		.. note::
		These conventions ensure that automated tools can rely on this default
		structure to work.

		The depth of sub-directories should be kept to the minimal for most used
		classes and files (2 levels at a maximum). More levels can be defined for
		non-strategic, less-used files.

		The bundle directory is read-only. If you need to write temporary files, store
		them under the ``cache/`` or ``log/`` directory of the host application. Tools can
		generate files in the bundle directory structure, but only if the generated
		files are going to be part of the repository.

		The following classes and files have specific emplacements:

		========================= =====================
		Type Directory
		========================= =====================
		Controllers ``Controller/``
		Templates ``Resources/views/``
		Unit and Functional Tests ``Tests/``
		Web Resources ``Resources/web/``
		Configuration ``Resources/config/``
		Commands ``Command/``
		========================= =====================

		Classes
		-------

		The bundle directory structure is used as the namespace hierarchy. For
		instance, a ``HelloController`` controller is stored in
		``Bundle/HelloBundle/Controller/HelloController.php`` and the fully qualified
		class name is ``Bundle\HelloBundle\Controller\HelloController``.

		All classes and files must follow the Symfony2 coding `standards`_.

		Some classes should be seen as facades and should be as short as possible,
		like Commands, Helpers, Listeners, and Controllers.

		Classes that connects to the Event Dispatcher should have a name that ends
		with ``Listener``.

		Exceptions classes should be stored in an ``Exception`` sub-namespace.

		Vendors
		-------

		A bundle must not embed third-party PHP libraries. It should rely on the
		standard Symfony2 autoloading instead.

		A bundle should not embed third-party libraries written in JavaScript, CSS, or
		any other language.

		Tests
		-----

		A bundle should come with a test suite written with PHPUnit and stored under
		the ``Tests/`` directory. Tests should follow the following principles:

		* The test suite must be executable with a simple ``phpunit`` command run from
		a sample application;
		* The functional tests should only be used to test the response output and
		some profiling information if you have some;
		* The code coverage should at least covers 95% of the code base.

		.. note::
		A test suite must not contain ``AllTests.php`` scripts, but must rely on the
		existence of a ``phpunit.xml.dist`` file.

		Documentation
		-------------

		All classes and functions must come with full PHPDoc.

		Extensive documentation should also be provided in the :doc:`reStructuredText
		</contributing/documentation/format>` format, under the ``Resources/doc/``
		directory; the ``Resources/doc/index.rst`` file is the only mandatory file.

		Templates
		---------

		If a bundle provides templates, they should be defined in plain PHP. A bundle
		must not provide a main layout, but extends a default ``base`` template (which
		must provide two slots: ``content`` and ``head``).

		.. note::
		The only other template engine supported is Twig, but only for specific
		cases.

		Configuration
		-------------

		Configuration must be done via the Symfony2 built-in `mechanism`_. A bundle
		should provide all its default configurations in XML.

		.. _standards: http://www.symfony-reloaded.org/contributing/Code/Standards
		.. _mechanism: http://www.symfony-reloaded.org/guides/Bundles/Configuration