[Cookbook] Bootstrapped article about removing bundles

Author: wouterj

book/installation.rst

@@ -185,13 +185,17 @@ Beginning Development
 Now that you have a fully-functional Symfony2 application, you can begin
 development! Your distribution may contain some sample code - check the
 ``README.md`` file included with the distribution (open it as a text file)
-to learn about what sample code was included with your distribution and how
-you can remove it later.
+to learn about what sample code was included with your distribution.
 
 If you're new to Symfony, check out ":doc:`page_creation`", where you'll
 learn how to create pages, change configuration, and do everything else you'll
 need in your new application.
 
+.. note::
+
+    If you want to remove the sample code from your distribution, take a look
+    at this cookbook article: ":doc:`/cookbook/bundles/remove`"
+
 Using Source Control
 --------------------
 

cookbook/bundles/index.rst

@@ -7,4 +7,5 @@ Bundles
     best_practices
     inheritance
     override
+    remove
     extension

cookbook/bundles/remove.rst

@@ -0,0 +1,103 @@
+.. index::
+    single: Bundle; Removing AcmeDemoBundle
+
+How to remove the AcmeDemoBundle
+================================
+
+The Symfony2 Standard Edition comes with a complete demo, that lives inside a
+bundle called ``AcmeDemoBundle``. It is a great boilerplate to refer to while
+starting with your project, but later on the project, it will become usefull
+to remove this bundle.
+
+.. tip::
+
+    This article uses the AcmeDemoBundle as an example, you can use this
+    article on every bundle you want to remove.
+
+1. Unregister the bundle in the ``AppKernel``
+---------------------------------------------
+
+To disconnect the bundle from the framework, you should remove the bundle from
+the ``Appkernel::registerBundles()`` method. The bundle is normally found in
+the ``$bundles`` array but the ``AcmeDemoBundle`` is only registered in a
+development environment and you can find him in the if statement thereafter::
+
+    // app/AppKernel.php
+
+    // ...
+    class AppKernel extends Kernel
+    {
+        public function registerBundles()
+        {
+            $bundles = array(...);
+
+            if (in_array($this->getEnvironment(), array('dev', 'test'))) {
+                // comment or remove this line:
+                // $bundles[] = new Acme\DemoBundle\AcmeDemoBundle();
+                // ...
+            }
+        }
+    }
+
+2. Remove bundle configuration
+------------------------------
+
+Now Symfony doesn't know about the bundle, you need to remove any
+configuration and routing configuration inside the ``app/config`` directory
+that refers to the bundle.
+
+2.1 Remove bundle routing
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The routing for the AcmeDemoBundle can be found in
+``app/config/routing_dev.yml``. The routes are ``_welcome``, ``_demo_secured``
+and ``_demo``.
+
+2.2 Remove bundle configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some bundles contains configuration in one of the ``app/config/config*.yml``
+files. Be sure to remove the related configuration from these files. You can
+quickly spot bundle configuration by looking at a ``acme_demo`` (or whatever
+the name of the bundle is, e.g. ``fos_user`` with the FOSUserBundle) string in
+the configuration files.
+
+The AcmeDemoBundle doesn't have configuration. However, the bundle has set up
+the ``app/config/security.yml`` file. You can use it as a boilerplate for your
+own security, but you **can** also remove everything: It doesn't make sense to
+Symfony if you remove it or not.
+
+3. Remove integration in other bundles
+--------------------------------------
+
+Some bundles rely on other bundles, if you remove one of the two, the other
+will properbly not work. Be sure that no other bundles, third party or self
+made, relies on the bundle you are about to remove.
+
+.. tip::
+
+    If a bundle relies on another bundle, it means in most of the cases that
+    it uses some services from the other bundle. Searching for a ``acme_demo``
+    string will help you spot them.
+
+.. tip::
+
+    If a third party bundle relies on another bundle, you can find the bundle
+    in the ``composer.json`` file included in the bundle directory.
+
+4. Remove the bundle from the filesystem
+----------------------------------------
+
+Now you have removed every reference to the bundle in the Symfony2
+application, the last thing you should do is removing the bundle from the file
+system. The bundle is located in the ``src/Acme/DemoBundle`` directory. You
+should remove this directory and you can remove the ``Acme`` directory as
+well, you likely won't get other bundles in that vendor.
+
+.. tip::
+
+    If you don't know the location of a bundle, you can use the
+    :method:`Symfony\\Bundle\\FrameworkBundle\\Bundle\\Bundle::getPath` method
+    to get the path of the bundle::
+
+        echo $this->container->get('kernel')->getBundle('AcmeDemoBundle')->getPath();

cookbook/map.rst.inc

@@ -10,6 +10,7 @@
   * :doc:`/cookbook/bundles/best_practices`
   * :doc:`/cookbook/bundles/inheritance`
   * :doc:`/cookbook/bundles/override`
+  * :doc:`/cookbook/bundles/remove`
   * :doc:`/cookbook/bundles/extension`
 
 * :doc:`/cookbook/cache/index`

cookbook/workflow/new_project_git.rst

@@ -116,7 +116,8 @@ to learn more about how to configure and develop inside your application.
 .. tip::
 
     The Symfony2 Standard Edition comes with some example functionality. To
-    remove the sample code, follow the instructions on the `Standard Edition Readme`_.
+    remove the sample code, follow the instructions in the
+    ":doc:`/components/bundles/remove`" article.
 
 .. _cookbook-managing-vendor-libraries:
 
@@ -149,7 +150,6 @@ manage this is `Gitolite`_.
 
 .. _`git`: http://git-scm.com/
 .. _`Symfony2 Standard Edition`: http://symfony.com/download
-.. _`Standard Edition Readme`: https://github.com/symfony/symfony-standard/blob/master/README.md
 .. _`git submodules`: http://git-scm.com/book/en/Git-Tools-Submodules
 .. _`GitHub`: https://github.com/
 .. _`barebones repository`: http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository

cookbook/workflow/new_project_svn.rst

@@ -122,7 +122,8 @@ to learn more about how to configure and develop inside your application.
 .. tip::
 
     The Symfony2 Standard Edition comes with some example functionality. To
-    remove the sample code, follow the instructions on the `Standard Edition Readme`_.
+    remove the sample code, follow the instructions in the
+    ":doc:`/components/bundles/remove`" article.
 
 .. include:: _vendor_deps.rst.inc
 
@@ -146,7 +147,6 @@ central repository to work. You then have several solutions:
 .. _`svn`: http://subversion.apache.org/
 .. _`Subversion`: http://subversion.apache.org/
 .. _`Symfony2 Standard Edition`: http://symfony.com/download
-.. _`Standard Edition Readme`: https://github.com/symfony/symfony-standard/blob/master/README.md
 .. _`Version Control with Subversion`: http://svnbook.red-bean.com/
 .. _`GitHub`: https://github.com/
 .. _`Google code`: http://code.google.com/hosting/