Skip to content

Updated the bundle install and uninstall articles for Symfony 4 #8617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Updated the bundle install and uninstall articles for Symfony 4 #8617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f2b8eb5
Updated the bundle install and uninstall articles for Symfony 4
javiereguiluz Nov 10, 2017
793210c
Fixed a RST syntax issue
javiereguiluz Nov 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 64 additions & 88 deletions bundles/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -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 </setup/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 </configuration/environments>`. 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 </configuration/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 </setup/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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

php 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

$ php bin/console ...


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::

Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

php bin/console


# 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
114 changes: 38 additions & 76 deletions bundles/remove.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <package-name>

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 </setup/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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whoa, we shouldn't edit third party bundles to remove their integration? I know you don't mean that, but that title seems to indicate it (and I'm also not very sure what you do mean with this section).

As soon as bundle A depends on B, composer will not allow you to remove B so I don't think there is a problem here?

What we can say is that you have to remove the integration in your application. But that's rather obvious...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't change that from the original article. See https://symfony.com/doc/current/bundles/remove.html#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::

Expand Down