Permalink
Browse files

feature #4290 Updating library/bundle install docs to use "require" (…

…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 committed Oct 18, 2014
2 parents 44f570b + d7ccbf3 commit 925a162879990d28d6093df1af7dfd22fcb27890
@@ -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
-------------
@@ -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
@@ -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.
@@ -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.
@@ -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:
@@ -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
@@ -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`_:

0 comments on commit 925a162

Please sign in to comment.