From 1a7c4b9c7d243b1908566f4b0394bb2113cd435c Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 3 Oct 2014 10:32:16 -0400 Subject: [PATCH 1/4] Updating library/bundle installation docs to use the new composer require (no version) functionality --- .../dependency_injection/lazy_services.rst | 14 ++- cookbook/bundles/best_practices.rst | 5 +- cookbook/bundles/installation.rst | 98 +++++++------------ cookbook/workflow/_vendor_deps.rst.inc | 23 +---- 4 files changed, 45 insertions(+), 95 deletions(-) diff --git a/components/dependency_injection/lazy_services.rst b/components/dependency_injection/lazy_services.rst index 57226d9e463..497e45720ce 100644 --- a/components/dependency_injection/lazy_services.rst +++ b/components/dependency_injection/lazy_services.rst @@ -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 .. 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 - 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 ------------- diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index d9c5fa88801..169746fe2b3 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -212,7 +212,7 @@ following standardized instructions in your ``README.md`` file. following command to download the latest stable version of this bundle: ```bash - $ composer require "~1" + $ composer require ``` This command requires you to have Composer installed globally, as explained @@ -247,9 +247,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. diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index a9150291642..8f3978bb06b 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -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/ +.. _`composer require`: https://getcomposer.org/doc/03-cli.md#require diff --git a/cookbook/workflow/_vendor_deps.rst.inc b/cookbook/workflow/_vendor_deps.rst.inc index 23ab3c3e073..93d009550b4 100644 --- a/cookbook/workflow/_vendor_deps.rst.inc +++ b/cookbook/workflow/_vendor_deps.rst.inc @@ -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`_: From a174a2b91257cd877bc10be080e6bf2c59f5ab78 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 3 Oct 2014 10:54:23 -0400 Subject: [PATCH 2/4] Fixing bad link --- cookbook/bundles/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index 8f3978bb06b..c546ffad58c 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -114,5 +114,5 @@ what to do next. Have fun! .. _their documentation: http://getcomposer.org/doc/00-intro.md .. _Packagist.org: https://packagist.org .. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle -.. _KnpBundles: http://knpbundles.com/ +.. _KnpBundles.com: http://knpbundles.com/ .. _`composer require`: https://getcomposer.org/doc/03-cli.md#require From ab2a688efc4653c12326a84deefdc26954dcd3c9 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 18 Oct 2014 15:39:05 -0400 Subject: [PATCH 3/4] [#4290] Re-adding version back --- components/dependency_injection/lazy_services.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/dependency_injection/lazy_services.rst b/components/dependency_injection/lazy_services.rst index 497e45720ce..5c8447fb579 100644 --- a/components/dependency_injection/lazy_services.rst +++ b/components/dependency_injection/lazy_services.rst @@ -39,7 +39,7 @@ the `ProxyManager bridge`_: .. code-block:: bash - $ php composer.phar require ocramius/proxy-manager + $ php composer.phar require ocramius/proxy-manager:~0.5 Afterwards compile your container and check to make sure that you get a proxy for your lazy services. From d7ccbf3e2c0360252605c202906c853a9d182713 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 18 Oct 2014 15:41:03 -0400 Subject: [PATCH 4/4] Re-adding one more version --- components/dependency_injection/lazy_services.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/dependency_injection/lazy_services.rst b/components/dependency_injection/lazy_services.rst index 5c8447fb579..2d3eafc1785 100644 --- a/components/dependency_injection/lazy_services.rst +++ b/components/dependency_injection/lazy_services.rst @@ -30,7 +30,7 @@ the `ProxyManager bridge`_: .. code-block:: bash - $ php composer.phar require symfony/proxy-manager-bridge + $ php composer.phar require symfony/proxy-manager-bridge:~2.3 .. note::