diff --git a/bundles/installation.rst b/bundles/installation.rst index c37752b8388..e23171e8d51 100644 --- a/bundles/installation.rst +++ b/bundles/installation.rst @@ -1,32 +1,39 @@ .. index:: single: Bundle; Installation -How to Install 3rd Party Bundles -================================ +.. _how-to-install-3rd-party-bundles: + +How to Install Third Party Bundles +================================== Most bundles provide their own installation instructions. However, the basic steps for installing a bundle are the same: -* `A) Add Composer Dependencies`_ +* `A) Install the Bundle`_ * `B) Enable the Bundle`_ * `C) Configure the Bundle`_ -A) Add Composer Dependencies ----------------------------- +.. _a-add-composer-dependencies: + +A) Install the Bundle +--------------------- -Dependencies are managed with Composer, so if Composer is new to you, learn -some basics in `their documentation`_. This involves two steps: +In Symfony applications, dependencies like bundles are managed with `Composer`_, +the package manager used in modern PHP applications. Make sure to have Composer +installed and working on your computer. Then, follow these steps: -1) Find out the Name of the Bundle on Packagist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _find-out-the-name-of-the-bundle-on-packagist: + +1) Find out the Name of the Bundle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The README for a bundle (e.g. `FOSUserBundle`_) usually tells you its name -(e.g. ``friendsofsymfony/user-bundle``). If it doesn't, you can search for -the bundle on the `Packagist.org`_ site. +The README file for a bundle usually tells you its name (e.g. ``friendsofsymfony +/user-bundle`` for `FOSUserBundle`_). If it doesn't, you can search for the +bundle on `Packagist.org`_, the official repository of Composer packages. .. tip:: - Looking for bundles? Try searching for `symfony-bundle topic on GitHub`_. + Looking for Symfony bundles? Try searching for `symfony-bundle topic on GitHub`_. 2) Install the Bundle via Composer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -48,89 +55,56 @@ version, include it as the second argument of the `composer require`_ command: B) Enable the Bundle -------------------- -At this point, the bundle is installed in your Symfony project (e.g. -``vendor/friendsofsymfony/``) and the autoloader recognizes its classes. -The only thing you need to do now is register the bundle in ``AppKernel``:: - - // app/AppKernel.php - - // ... - class AppKernel extends Kernel - { - // ... - - public function registerBundles() - { - $bundles = array( - // ... - new FOS\UserBundle\FOSUserBundle(), - ); - - // ... - } - } +If your application uses :doc:`Symfony Flex `, bundles are enabled +automatically, so you can skip this step entirely. -In a few rare cases, you may want a bundle to be *only* enabled in the development -:doc:`environment `. For example, -the DoctrineFixturesBundle helps to load dummy data - something you probably -only want to do while developing. To only load this bundle in the ``dev`` -and ``test`` environments, register the bundle in this way:: +At this point, the bundle is installed in your Symfony project (e.g. +``vendor/friendsofsymfony/``) and the autoloader recognizes its classes. The +only thing you need to do now is register the bundle for some or all +:doc:`Symfony environments ` using the +``config/bundles.php`` file:: - // app/AppKernel.php - - // ... - class AppKernel extends Kernel - { + // config/bundles.php + return [ // ... - public function registerBundles() - { - $bundles = array( - // ... - ); + // enable the bundle for any Symfony environment: + FOS\UserBundle\FOSUserBundle::class => ['all' => true], - if (in_array($this->getEnvironment(), array('dev', 'test'))) { - $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle(); - } + // enable the bundle only for 'dev' and 'test' environment (not 'prod'): + FOS\UserBundle\FOSUserBundle::class => ['dev' => true, 'test' => true], - // ... - } - } + // enable the bundle only for 'prod' environment (not 'dev', 'test', etc.): + FOS\UserBundle\FOSUserBundle::class => ['prod' => true], + ]; C) Configure the Bundle ----------------------- -It's pretty common for a bundle to need some additional setup or configuration -in ``app/config/config.yml``. The bundle's documentation will tell you about -the configuration, but you can also get a reference of the bundle's configuration -via the ``config:dump-reference`` command: +If your application uses :doc:`Symfony Flex ` and the bundle +defines a `Symfony Flex recipe`_, the initial bundle configuration is created +automatically in the ``config/packages/`` directory, so you just need to review +its default values. -.. code-block:: terminal - - $ bin/console config:dump-reference AsseticBundle - -Instead of the full bundle name, you can also pass the short name used as the root -of the bundle's configuration: +Otherwise, you need the create those configuration files manually following the +bundle's documentation. In case you need it, you can also get a reference of the +bundle's configuration via the ``config:dump-reference`` command: .. code-block:: terminal - $ bin/console config:dump-reference assetic + $ bin/console config:dump-reference WebProfilerBundle + + # you can also pass the bundle alias used in its config files: + # bin/console config:dump-reference web_profiler The output will look like this: .. code-block:: yaml - assetic: - debug: '%kernel.debug%' - use_controller: - enabled: '%kernel.debug%' - profiler: false - read_from: '%kernel.project_dir%/web' - write_to: '%assetic.read_from%' - java: /usr/bin/java - node: /usr/local/bin/node - node_paths: [] - # ... + web_profiler: + toolbar: false + intercept_redirects: false + excluded_ajax_paths: '^/(app(_[\w]+)?\.php/)?_wdt' .. tip:: @@ -140,21 +114,23 @@ The output will look like this: .. code-block:: terminal - $ bin/console config:dump-reference AsseticBundle use_controller + $ bin/console config:dump-reference TwigBundle date - # Default configuration for "AsseticBundle" at path "use_controller" - use_controller: - enabled: '%kernel.debug%' - profiler: false + # Default configuration for "TwigBundle" at path "date" + date: + format: 'F j, Y H:i' + interval_format: '%d days' + timezone: null Other Setup ----------- -At this point, check the ``README`` file of your brand new bundle to see -what to do next. Have fun! +At this point, check the ``README`` file of the bundle to see if it requires +further steps to complete its integration with your Symfony application. -.. _their documentation: https://getcomposer.org/doc/00-intro.md -.. _Packagist.org: https://packagist.org -.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle -.. _`composer require`: https://getcomposer.org/doc/03-cli.md#require +.. _`Composer`: https://getcomposer.org/ +.. _`Packagist.org`: https://packagist.org +.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle +.. _`composer require`: https://getcomposer.org/doc/03-cli.md#require .. _`symfony-bundle topic on GitHub`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories +.. _`Symfony Flex recipe`: https://github.com/symfony/recipes diff --git a/bundles/remove.rst b/bundles/remove.rst index 525b3c7787a..1b50c60e98a 100644 --- a/bundles/remove.rst +++ b/bundles/remove.rst @@ -4,91 +4,53 @@ How to Remove a Bundle ====================== -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 will likely be found in -the ``$bundles`` array declaration or added to it in a later statement if the -bundle is only registered in the development environment:: - - // app/AppKernel.php - - // ... - class AppKernel extends Kernel - { - public function registerBundles() - { - $bundles = array( - new Acme\DemoBundle\AcmeDemoBundle(), - ); - - if (in_array($this->getEnvironment(), array('dev', 'test'))) { - // comment or remove this line: - // $bundles[] = new Acme\DemoBundle\AcmeDemoBundle(); - // ... - } - } - } - -2. Remove Bundle Configuration ------------------------------- - -Now that 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 -~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Some* bundles require you to import routing configuration. Check for references -to the bundle in the routing configuration (inside ``config/routes/``). If you -find any references, remove them completely. - -2.2 Remove Bundle Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some bundles contain 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 for an ``acme_demo`` (or whatever -the name of the bundle is, e.g. ``fos_user`` for the FOSUserBundle) string in -the configuration files. - -3. Remove the Bundle from the Filesystem ----------------------------------------- - -Now you have removed every reference to the bundle in your application, you -should remove the bundle from the filesystem. The bundle will be located in -`src/` for example the ``src/Acme/DemoBundle`` directory. You should remove this -directory, and any parent directories that are now empty (e.g. ``src/Acme/``). +.. _unregister-the-bundle-in-the-appkernel: +.. _remove-bundle-configuration: +.. _remove-bundle-routing: +.. _remove-the-bundle-from-the-filesystem: -.. tip:: +1. Uninstall the Bundle +----------------------- - If you don't know the location of a bundle, you can use the - :method:`Symfony\\Component\\HttpKernel\\Bundle\\BundleInterface::getPath` method - to get the path of the bundle:: +Execute this command to remove the Composer package associated with the bundle: - dump($this->container->get('kernel')->getBundle('AcmeDemoBundle')->getPath()); - die(); +.. code-block:: terminal -3.1 Remove Bundle Assets -~~~~~~~~~~~~~~~~~~~~~~~~ + $ composer remove -Remove the assets of the bundle in the public/ directory (e.g. -``public/bundles/acmedemo`` for the AcmeDemoBundle). + # the package name is the same used when you installed it. Example: + # composer remove friendsofsymfony/user-bundle -4. Remove Integration in other Bundles --------------------------------------- +If your application uses :doc:`Symfony Flex `, this command will +also unregister the bundle from the application and remove its configuration +files, environment variables defined by the bundle, etc. Otherwise, you need to +remove all that manually: -Some bundles rely on other bundles, if you remove one of the two, the other -will probably not work. Be sure that no other bundles, third party or self-made, -rely on the bundle you are about to remove. +* Unregister the bundle in the application removing it from the + ``config/bundles.php`` file; +* Remove any configuration file related to the bundle from the ``config/packages/`` + directories (the files will be called like the bundle; e.g. ``fos_user.yaml`` + for FOSUserBundle); +* Remove any routes file related to the bundle from the ``config/routes/`` + directories (the file names will also match the bundle name; e.g. + ``config/routes/fos_js_routing.yaml`` for FOSJsRoutingBundle). -.. tip:: +2. Remove Bundle Assets +----------------------- + +If the bundle included web assets, remove them from the ``public/bundles/`` +directory (e.g. ``public/bundles/nelmioapidoc/`` for the NelmioApiDocBundle). + +3. Remove Integration in other Bundles +-------------------------------------- + +Some bundles rely on other bundles; if you remove one of the two, the other will +probably not work. In most cases, when one bundle relies on another, it means +that it uses some services from it. - If one bundle relies on another, in most cases it means that it uses - some services from the bundle. Searching for the bundle alias string may - help you spot them (e.g. ``acme_demo`` for bundles depending on AcmeDemoBundle). +Look for the bundle alias or PHP namespace (e.g. ``sonata.admin`` or +``Sonata\AdminBundle\`` for bundles depending on SonataAdminBundle) to find the +dependent bundles. .. tip::