Merge pull request #1669 from Glutnix/php-composer

[php-composer/en] Add new tool document for Composer, PHP's dependency manager

1 files changed, 167 insertions, 0 deletions

diff --git a/php-composer.html.markdown b/php-composer.html.markdown
new file mode 100644
index 00000000..16fed582
--- /dev/null
+++ b/php-composer.html.markdown
@@ -0,0 +1,167 @@
+---
+category: tool
+tool: composer
+contributors:
+    - ["Brett Taylor", "https://github.com/glutnix"]
+filename: LearnComposer.sh
+---
+
+[Composer](https://getcomposer.org/) is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
+
+# Installing
+
+```sh
+# Installs the composer.phar binary into the current directory
+curl -sS https://getcomposer.org/installer | php
+# If you use this approach, you will need to invoke composer like this:
+php composer.phar about
+
+# Installs the binary into ~/bin/composer
+# Note: make sure ~/bin is in your shell's PATH environment variable
+curl -sS https://getcomposer.org/installer | php -- --install-dir=~/bin --filename=composer
+```
+
+Windows users should follow the [Windows installation instructions](https://getcomposer.org/doc/00-intro.md#installation-windows)
+
+## Confirming installation
+
+```sh
+# Check version and list options
+composer
+
+# Get more help for options
+composer help require
+
+# Check if Composer is able to do the things it needs, and if it's up to date
+composer diagnose
+composer diag # shorthand
+
+# Updates the Composer binary to the latest version
+composer self-update
+composer self # shorthand
+```
+
+# Usage
+
+Composer stores your project dependencies in `composer.json`. You can edit this file, but it is best to let Composer manage it for you.
+
+```sh
+# Create a new project in the current folder
+composer init
+# runs an interactive questionnaire asking you for details about your project.  Leaving them blank is fine unless you are making other projects dependent on this one.
+
+# If a composer.json file already exists, download the dependencies
+composer install
+
+# To download the just the production dependencies, i.e. excluding development dependencies
+composer install --no-dev
+
+# Add a production dependency to this project
+composer require guzzlehttp/guzzle
+# will figure out what the latest version of guzzlehttp/guzzle is, download it, and add the new dependency to composer.json's require field.
+
+composer require guzzlehttp/guzzle:6.0.*
+# will download the latest version matching the pattern (eg. 6.0.2) and add the dependency to composer.json's require field
+
+composer require --dev phpunit/phpunit:~4.5.0
+# will require as a development dependency. Will use the latest version >=4.5.0 and < 4.6.0
+
+composer require-dev phpunit/phpunit:^4.5.0
+# will require as a development dependency. Will use the latest version >=4.5.0 and < 5.0
+
+# For more information on Composer version matching, see [Composer's documentation on Versions](https://getcomposer.org/doc/articles/versions.md) for more details
+
+# To see what packages are available to install and currently installed
+composer show
+
+# To see what packages are currently installed
+composer show --installed
+
+# To find a package with 'mailgun' in its name or description
+composer search mailgun
+```
+
+[Packagist.org](https://packagist.org/) is the main repository for Composer packages. Search there for existing third-party packages.
+
+## `composer.json` vs `composer.lock`
+
+The `composer.json` file stores your project's floating version preferences for each dependency, along with other information.
+
+The `composer.lock` file stores exactly which version it has downloaded for each dependency. Never edit this file.
+
+If you include the `composer.lock` file in your git repository, every developer will install the currently used version of the dependency. Even when a new version of a dependency is released, Composer will continue to download the version recorded in the lock file.
+
+```sh
+# If you want to update all the dependencies to their newest version still matching your version preferences
+composer update
+
+# If you want the new version of a particular dependency:
+composer update phpunit/phpunit
+
+# If you wish to migrate a package to a newer version preference, you may need to remove the older package and its dependencies first.
+composer remove --dev phpunit/phpunit
+composer require --dev phpunit/phpunit:^5.0
+
+```
+
+## Autoloader
+
+Composer creates an autoloader class you can require from your application. You can make instances of classes via their namespace.
+
+```php
+require __DIR__ . '/vendor/autoload.php';
+
+$mailgun = new Mailgun\Mailgun("key");
+```
+
+### PSR-4 Autoloader
+
+You can add your own namespaces to the autoloader.
+
+In `composer.json`, add a 'autoload' field:
+
+```json
+{
+  "autoload": {
+    "psr-4": {"Acme\\": "src/"}
+  }
+}
+```
+This will tell the autoloader to look for anything in the `\Acme\` namespace within the `src` folder.
+
+You can also [use PSR-0, a Classmap or just a list of files to include](https://getcomposer.org/doc/04-schema.md#autoload). There is also the `autoload-dev` field for development-only namespaces.
+
+When adding or modifying the autoload key, you will need to rebuild the autoloader:
+
+```sh
+composer dump-autoload
+composer dump # shorthand
+
+# Optimizes PSR0 and PSR4 packages to be loaded with classmaps too. Slow to run, but improves performance on production.
+composer dump-autoload --optimize --no-dev
+```
+
+# Composer's Cache
+
+```sh
+# Composer will retain downloaded packages to use in the future. Clear it with:
+composer clear-cache
+```
+
+# Troubleshooting
+
+```sh
+composer diagnose
+composer self-update
+composer clear-cache
+```
+
+## Topics not (yet) covered in this tutorial
+
+* Creating and distributing your own packages on Packagist.org or elsewhere
+* Pre- and post- script hooks: run tasks when certain composer events take place
+
+### References
+
+* [Composer - Dependency Manager for PHP](https://getcomposer.org/)
+* [Packagist.org](https://packagist.org/)