Skip to content

Commit

Permalink
feature #4290 Updating library/bundle install docs to use "require" (…
Browse files Browse the repository at this point in the history 
…weaverryan)

This PR was merged into the 2.3 branch.

Discussion
----------

Updating library/bundle install docs to use "require"

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | -

As of composer/composer#3906, you can now simply install a library via:

```
php composer.phar require myname/my-lib
```

The latest version if chosen for you. I've replaced all mentions of modifying composer.json and running `composer update` with using the `require` command. I think the result is much simpler :).

Thanks!

Commits
-------

d7ccbf3 Re-adding one more version
ab2a688 [#4290] Re-adding version back
a174a2b Fixing bad link
1a7c4b9 Updating library/bundle installation docs to use the new composer require (no version) functionality
  • Loading branch information
@weaverryan
weaverryan committed Oct 18, 2014
2 parents 44f570b + d7ccbf3 commit 925a162
Show file tree
Hide file tree
Showing 4 changed files with 46 additions and 96 deletions.
14 changes: 6 additions & 8 deletions components/dependency_injection/lazy_services.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,21 +30,19 @@ the `ProxyManager bridge`_:

.. code-block:: bash
$ php composer.phar require symfony/proxy-manager-bridge:2.3.*
$ php composer.phar require symfony/proxy-manager-bridge:~2.3
.. note::

If you're using the full-stack framework, the proxy manager bridge is already
included but the actual proxy manager needs to be included. Therefore add
included but the actual proxy manager needs to be included. So, run:

.. code-block:: json
.. code-block:: bash
"require": {
"ocramius/proxy-manager": "0.4.*"
}
$ php composer.phar require ocramius/proxy-manager:~0.5
to your ``composer.json``. Afterwards compile your container and check
to make sure that you get a proxy for your lazy services.
Afterwards compile your container and check to make sure that you get
a proxy for your lazy services.

Configuration
-------------
Expand Down
5 changes: 1 addition & 4 deletions cookbook/bundles/best_practices.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ following standardized instructions in your ``README.md`` file.
following command to download the latest stable version of this bundle:
```bash
$ composer require <package-name> "~1"
$ composer require <package-name>
```
This command requires you to have Composer installed globally, as explained
Expand Down Expand Up @@ -254,9 +254,6 @@ following standardized instructions in your ``README.md`` file.
}
```
This template assumes that your bundle is in its ``1.x`` version. If not, change
the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)

Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
explain other required installation tasks, such as registering routes or
dumping assets.
Expand Down
100 changes: 36 additions & 64 deletions cookbook/bundles/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,74 +5,46 @@ How to Install 3rd Party Bundles
================================

Most bundles provide their own installation instructions. However, the
basic steps for installing a bundle are the same.
basic steps for installing a bundle are the same:

Add Composer Dependencies
-------------------------
* `A) Add Composer Dependencies`_
* `B) Enable the Bundle`_
* `C) Configure the Bundle`_

Starting from Symfony 2.1, dependencies are managed with Composer. It's
a good idea to learn some basics of Composer in `their documentation`_.
A) Add Composer Dependencies
----------------------------

Before you can use Composer to install a bundle, you should look for a
`Packagist`_ package of that bundle. For example, if you search for the popular
`FOSUserBundle`_ you will find a package called `friendsofsymfony/user-bundle`_.
Dependencies are managed with Composer, so if Composer is new to you, learn
some basics in `their documentation`_. This has 2 steps:

.. note::

Packagist is the main archive for Composer. If you are searching
for a bundle, the best thing you can do is check out
`KnpBundles`_, it is the unofficial archive of Symfony Bundles. If
a bundle contains a ``README`` file, it is displayed there and if it
has a Packagist package it shows a link to the package. It's a
really useful site to begin searching for bundles.

Now that you have the package name, you should determine the version
you want to use. Usually different versions of a bundle correspond to
a particular version of Symfony. This information should be in the ``README``
file. If it isn't, you can use the version you want. If you choose an incompatible
version, Composer will throw dependency errors when you try to install. If
this happens, you can try a different version.

In the case of the FOSUserBundle, the ``README`` file has a caution that version
1.2.0 must be used for Symfony 2.0 and 1.3+ for Symfony 2.1+. Packagist displays
example ``require`` statements for all existing versions of a package. The
current development version of FOSUserBundle is ``"friendsofsymfony/user-bundle": "2.0.*@dev"``.

Now you can add the bundle to your ``composer.json`` file and update the
dependencies. You can do this manually:

1. **Add it to the ``composer.json`` file:**

.. code-block:: json
1) Find out the Name of the Bundle on Packagist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{
...,
"require": {
...,
"friendsofsymfony/user-bundle": "2.0.*@dev"
}
}
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 library on the `Packagist.org`_ site.

2. **Update the dependency:**
.. note::

.. code-block:: bash
Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
archive of Symfony Bundles.

$ php composer.phar update friendsofsymfony/user-bundle
2) Install the Bundle via Composer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

or update all dependencies
Now that you know the package name, you can install it via Composer:

.. code-block:: bash
$ php composer.phar update
$ php composer.phar require friendsofsymfony/user-bundle
Or you can do this in one command:

.. code-block:: bash
This will choose the best version for your project, add it to ``composer.json``
and download the library into the ``vendor/`` directory. If you need a specific
version, add a ``:`` and the version right after the library name (see
`composer require`_).

$ php composer.phar require friendsofsymfony/user-bundle:2.0.*@dev
Enable the Bundle
-----------------
B) Enable the Bundle
--------------------

At this point, the bundle is installed in your Symfony project (in
``vendor/friendsofsymfony/``) and the autoloader recognizes its classes.
Expand All @@ -96,13 +68,13 @@ The only thing you need to do now is register the bundle in ``AppKernel``::
}
}

Configure the Bundle
--------------------
C) Configure the Bundle
-----------------------

Usually a bundle requires some configuration to be added to app's
``app/config/config.yml`` file. The bundle's documentation will likely
describe that configuration. But you can also get a reference of the
bundle's config via the ``config:dump-reference`` command.
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 config
via the ``config:dump-reference`` command.

For instance, in order to look the reference of the ``assetic`` config you
can use this:
Expand Down Expand Up @@ -137,10 +109,10 @@ Other Setup
-----------

At this point, check the ``README`` file of your brand new bundle to see
what to do next.
what to do next. Have fun!

.. _their documentation: http://getcomposer.org/doc/00-intro.md
.. _Packagist: https://packagist.org
.. _Packagist.org: https://packagist.org
.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle
.. _`friendsofsymfony/user-bundle`: https://packagist.org/packages/friendsofsymfony/user-bundle
.. _KnpBundles: http://knpbundles.com/
.. _KnpBundles.com: http://knpbundles.com/
.. _`composer require`: https://getcomposer.org/doc/03-cli.md#require
23 changes: 3 additions & 20 deletions cookbook/workflow/_vendor_deps.rst.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,29 +24,12 @@ To upgrade your libraries to new versions, run ``php composer.phar update``.

.. tip::

If you want to add a new package to your application, modify the ``composer.json``
file:

.. code-block:: json

{
"require": {
...
"doctrine/doctrine-fixtures-bundle": "@dev"
}
}

and then execute the ``update`` command for this specific package, i.e.:

.. code-block:: bash

$ php composer.phar update doctrine/doctrine-fixtures-bundle

You can also combine both steps into a single command:
If you want to add a new package to your application, run the composer
``require`` command:

.. code-block:: bash

$ php composer.phar require doctrine/doctrine-fixtures-bundle:@dev
$ php composer.phar require doctrine/doctrine-fixtures-bundle

To learn more about Composer, see `GetComposer.org`_:

Expand Down

0 comments on commit 925a162

Please sign in to comment.