From c7a3b09135a0ded713575c83fcdd6fa31147ebf4 Mon Sep 17 00:00:00 2001 From: Pavel Volokitin Date: Sat, 30 Mar 2013 18:39:17 +0600 Subject: [PATCH 1/5] Add 3rd party installation guide to cookbook. --- cookbook/bundles/index.rst | 1 + cookbook/bundles/installation.rst | 141 ++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 cookbook/bundles/installation.rst diff --git a/cookbook/bundles/index.rst b/cookbook/bundles/index.rst index 4a38dc56c62..68835ae2457 100644 --- a/cookbook/bundles/index.rst +++ b/cookbook/bundles/index.rst @@ -9,3 +9,4 @@ Bundles override remove extension + installation diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst new file mode 100644 index 00000000000..3148025d379 --- /dev/null +++ b/cookbook/bundles/installation.rst @@ -0,0 +1,141 @@ +.. index:: + single: Bundle; Installation + +How to install 3rd party bundles +================================ + +Most bundles provide a documentation of installation. However, most +steps are common for any bundle. + +Add composer dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting from Symfony2.1 dependencies are managed via Composer. It's +a good idea to learn some basics of Composer here: +http://getcomposer.org/doc/00-intro.md. + +Before you can use composer to install a bundle you should look for a +`Packagist`_ package of that bundle. For example, for the +`FOSUserBundle`_ you should look for a +``friendsofsymfony/user-bundle`` package and it does exists: +https://packagist.org/packages/friendsofsymfony/user-bundle. + +.. 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 achive 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 usefull site to begin searching for bundles. + +Now 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 should be in the README file (in +the Package, which you can view on Github or KnpBundles). If it isn't +in the README, you can use the version you want. In the case of +FOSUserBundle README file has a caution that version 1.2.0 must be +used for Symfony2.0 and 1.3 for Symfony2.1+. Let's use development +version for this exmaple. + +Now we can add the bundle to our composer.json file and update the +dependencies. You can do this manually: + +1. **Add it to the ``composer.json`` file:** + + .. code-block:: javascript + + { + ..., + "require": { + ..., + "friendsofsymfony/user-bundle": "dev-master" + } + } + +2. **Update the dependency:** + + .. code-block:: bash + + $ php composer.phar update friendsofsymfony/user-bundle + + or update all dependencies + + .. code-block:: bash + + $ php composer.phar update + +Or you can do this in one command: + +.. code-block:: bash + + $ php composer.phar require friendsofsymfony/user-bundle:dev-master + +Enable the bundle +~~~~~~~~~~~~~~~~~ + +Now the bundle is installed into our Symfony project (in +vendor/friendsofsymfony/) and the autoloader recognises this +bundle. The only thing we need to do now is registering the bundle in +the AppKernel: + +.. code-block:: php + + // app/AppKernel.php + + // ... + class AppKernel extends Kernel + { + // ... + + public function registerBundles() + { + $bundles = array( + ..., + new FOS\UserBundle\FOSUserBundle(), + ); + + // ... + } + } + +Configure the bundle +~~~~~~~~~~~~~~~~~~~~ + +Usually bundles require some configuration to be added to app's +app/config/config.yml file. Bundle's documentation will likely +describe that configuration. But you can also get a reference of the +bundle's config via ``config:dump-reference`` command. + +For instance, in order to look the reference of the assetic config we +can use this: + +.. code-block:: bash + + $ app/console config:dump-reference AsseticBundle + +or this: + +.. code-block:: bash + + $ app/console config:dump-reference assetic + +The output will look like this: + +.. code-block:: text + + assetic: + debug: %kernel.debug% + use_controller: + enabled: %kernel.debug% + profiler: false + read_from: %kernel.root_dir%/../web + write_to: %assetic.read_from% + java: /usr/bin/java + node: /usr/local/bin/node + node_paths: [] + ... + +.. _Packagist: https://packagist.org +.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle +.. _KnpBundles: http://knpbundles.com/ From 8c9df7b4e92d1934fa4f7e4e86287f24d50a97b8 Mon Sep 17 00:00:00 2001 From: Pavel Volokitin Date: Sat, 30 Mar 2013 20:47:30 +0600 Subject: [PATCH 2/5] Fixed first wave of errors. --- cookbook/bundles/installation.rst | 51 +++++++++++++++---------------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index 3148025d379..e030b77a9ad 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -8,13 +8,13 @@ Most bundles provide a documentation of installation. However, most steps are common for any bundle. Add composer dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- -Starting from Symfony2.1 dependencies are managed via Composer. It's -a good idea to learn some basics of Composer here: -http://getcomposer.org/doc/00-intro.md. +Starting from Symfony2.1 dependencies are managed with Composer. It's +a good idea to learn some basics of Composer in +`their documentation`_. -Before you can use composer to install a bundle you should look for a +Before you can use composer to install a bundle, you should look for a `Packagist`_ package of that bundle. For example, for the `FOSUserBundle`_ you should look for a ``friendsofsymfony/user-bundle`` package and it does exists: @@ -25,25 +25,25 @@ https://packagist.org/packages/friendsofsymfony/user-bundle. 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 achive of Symfony Bundles. If - a bundle contains a README file, it is displayed there and if it + 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 usefull site to begin searching for bundles. Now 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 should be in the README file (in +particular version of Symfony, this should be in the ``README`` file (in the Package, which you can view on Github or KnpBundles). If it isn't -in the README, you can use the version you want. In the case of -FOSUserBundle README file has a caution that version 1.2.0 must be +in the ``README``, you can use the version you want. In the case of the +FOSUserBundle, the ``README`` file has a caution that version 1.2.0 must be used for Symfony2.0 and 1.3 for Symfony2.1+. Let's use development version for this exmaple. -Now we can add the bundle to our composer.json file and update the +Now we can add the bundle to our ``composer.json`` file and update the dependencies. You can do this manually: 1. **Add it to the ``composer.json`` file:** - .. code-block:: javascript + .. code-block:: json { ..., @@ -72,14 +72,12 @@ Or you can do this in one command: $ php composer.phar require friendsofsymfony/user-bundle:dev-master Enable the bundle -~~~~~~~~~~~~~~~~~ +----------------- Now the bundle is installed into our Symfony project (in -vendor/friendsofsymfony/) and the autoloader recognises this +``vendor/friendsofsymfony/``) and the autoloader recognises this bundle. The only thing we need to do now is registering the bundle in -the AppKernel: - -.. code-block:: php +the ``AppKernel``:: // app/AppKernel.php @@ -88,10 +86,10 @@ the AppKernel: { // ... - public function registerBundles() - { - $bundles = array( - ..., + public function registerBundles() + { + $bundles = array( + // ..., new FOS\UserBundle\FOSUserBundle(), ); @@ -100,10 +98,10 @@ the AppKernel: } Configure the bundle -~~~~~~~~~~~~~~~~~~~~ +-------------------- Usually bundles require some configuration to be added to app's -app/config/config.yml file. Bundle's documentation will likely +``app/config/config.yml`` file. Bundle's documentation will likely describe that configuration. But you can also get a reference of the bundle's config via ``config:dump-reference`` command. @@ -134,8 +132,9 @@ The output will look like this: java: /usr/bin/java node: /usr/local/bin/node node_paths: [] - ... + # ... -.. _Packagist: https://packagist.org -.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle -.. _KnpBundles: http://knpbundles.com/ +.. _their documentation: http://getcomposer.org/doc/00-intro.md +.. _Packagist: https://packagist.org +.. _FOSUserBundle: https://github.com/FriendsOfSymfony/FOSUserBundle +.. _KnpBundles: http://knpbundles.com/ From e566ade1550bd1a6f6bbd799a319557da3659c1f Mon Sep 17 00:00:00 2001 From: Pavel Volokitin Date: Sat, 30 Mar 2013 21:57:45 +0600 Subject: [PATCH 3/5] Fix second wave. --- cookbook/bundles/installation.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index e030b77a9ad..94928de7d93 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -4,8 +4,8 @@ How to install 3rd party bundles ================================ -Most bundles provide a documentation of installation. However, most -steps are common for any bundle. +Most bundles provide their own installation instructions. However the +basic steps for installing a bundle are the same. Add composer dependencies ------------------------- @@ -29,14 +29,14 @@ https://packagist.org/packages/friendsofsymfony/user-bundle. has a Packagist package it shows a link to the package. It's a really usefull site to begin searching for bundles. -Now you have the package name, you should determine the version you +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 should be in the ``README`` file (in the Package, which you can view on Github or KnpBundles). If it isn't in the ``README``, you can use the version you want. In the case of the FOSUserBundle, the ``README`` file has a caution that version 1.2.0 must be -used for Symfony2.0 and 1.3 for Symfony2.1+. Let's use development -version for this exmaple. +used for Symfony2.0 and 1.3 for Symfony2.1+. Let's use the development +version for this example. Now we can add the bundle to our ``composer.json`` file and update the dependencies. You can do this manually: @@ -75,7 +75,7 @@ Enable the bundle ----------------- Now the bundle is installed into our Symfony project (in -``vendor/friendsofsymfony/``) and the autoloader recognises this +``vendor/friendsofsymfony/``) and the autoloader recognizes this bundle. The only thing we need to do now is registering the bundle in the ``AppKernel``:: @@ -101,7 +101,7 @@ Configure the bundle -------------------- Usually bundles require some configuration to be added to app's -``app/config/config.yml`` file. Bundle's documentation will likely +``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 ``config:dump-reference`` command. From db27a165e152d0fd297983f436d6b764d1e74f8d Mon Sep 17 00:00:00 2001 From: Pavel Volokitin Date: Sat, 30 Mar 2013 22:20:17 +0600 Subject: [PATCH 4/5] Fix third wave. --- cookbook/bundles/installation.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index 94928de7d93..e7dd4a2251b 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -4,21 +4,20 @@ How to install 3rd party bundles ================================ -Most bundles provide their own installation instructions. However the +Most bundles provide their own installation instructions. However, the basic steps for installing a bundle are the same. Add composer dependencies ------------------------- -Starting from Symfony2.1 dependencies are managed with Composer. It's -a good idea to learn some basics of Composer in -`their documentation`_. +Starting from Symfony 2.1 dependencies are managed with Composer. It's +a good idea to learn some basics of Composer in `their documentation`_. Before you can use composer to install a bundle, you should look for a `Packagist`_ package of that bundle. For example, for the `FOSUserBundle`_ you should look for a ``friendsofsymfony/user-bundle`` package and it does exists: -https://packagist.org/packages/friendsofsymfony/user-bundle. +https://packagist.org/packages/friendsofsymfony/user-bundle . .. note:: @@ -35,7 +34,7 @@ particular version of Symfony, this should be in the ``README`` file (in the Package, which you can view on Github or KnpBundles). If it isn't in the ``README``, you can use the version you want. In the case of the FOSUserBundle, the ``README`` file has a caution that version 1.2.0 must be -used for Symfony2.0 and 1.3 for Symfony2.1+. Let's use the development +used for Symfony 2.0 and 1.3 for Symfony 2.1+. Let's use the development version for this example. Now we can add the bundle to our ``composer.json`` file and update the From c20b6a62fb6df2e6b340abcc153544be2903ea97 Mon Sep 17 00:00:00 2001 From: Pavel Volokitin Date: Sat, 30 Mar 2013 22:52:58 +0600 Subject: [PATCH 5/5] Fix versions. --- cookbook/bundles/installation.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst index e7dd4a2251b..61c33c142d1 100644 --- a/cookbook/bundles/installation.rst +++ b/cookbook/bundles/installation.rst @@ -28,14 +28,16 @@ https://packagist.org/packages/friendsofsymfony/user-bundle . has a Packagist package it shows a link to the package. It's a really usefull 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 should be in the ``README`` file (in -the Package, which you can view on Github or KnpBundles). If it isn't -in the ``README``, you can use the version you want. 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+. Let's use the development -version for this example. +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 should be in the ``README`` file +(in the Package, which you can view on Github or KnpBundles). If it +isn't in the ``README``, you can use the version you want. 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 provides require statements for all existing +versions. For the current development version it is now +``"friendsofsymfony/user-bundle": "2.0.*@dev"``. Now we can add the bundle to our ``composer.json`` file and update the dependencies. You can do this manually: @@ -48,7 +50,7 @@ dependencies. You can do this manually: ..., "require": { ..., - "friendsofsymfony/user-bundle": "dev-master" + "friendsofsymfony/user-bundle": "2.0.*@dev" } } @@ -68,7 +70,7 @@ Or you can do this in one command: .. code-block:: bash - $ php composer.phar require friendsofsymfony/user-bundle:dev-master + $ php composer.phar require friendsofsymfony/user-bundle:2.0.*@dev Enable the bundle -----------------