From 2c8e6490f3d5dabd859e40ca35c5370f116e31c7 Mon Sep 17 00:00:00 2001 From: Brett Taylor Date: Tue, 20 Oct 2015 12:46:58 +1300 Subject: [PATCH] [php-composer/en] Add new tool document for Composer, PHP's dependency manager. --- php-composer.html.markdown | 167 +++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 php-composer.html.markdown 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/)