From 672e7d85a1cb2c2c9eaf5f89f33f886ac8b183f8 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Sun, 26 Feb 2012 12:40:35 +0100 Subject: [PATCH] [docs] re-word some things, document env vars --- doc/00-intro.md | 4 ++-- doc/01-basic-usage.md | 28 +++++++++++------------ doc/03-cli.md | 51 +++++++++++++++++++++++++++++++++++++----- doc/04-schema.md | 22 +++++++++--------- doc/05-repositories.md | 40 ++++++++++++++++----------------- doc/06-community.md | 6 ++--- 6 files changed, 96 insertions(+), 55 deletions(-) diff --git a/doc/00-intro.md b/doc/00-intro.md index 4d35b6924..7c96b27de 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -1,7 +1,7 @@ # Introduction Composer is a tool for dependency management in PHP. It allows you to declare -the dependencies of your project and will install these dependencies for you. +the dependencies of your project and will install them for you. ## Dependency management @@ -45,7 +45,7 @@ composer: $ curl -s http://getcomposer.org/installer | php This will just check a few PHP settings and then download `composer.phar` to -your working directory. This is the composer binary. +your working directory. This file is the composer binary. After that we run the command for installing all dependencies: diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 0ec7afd53..994d4a46e 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -9,10 +9,10 @@ To install composer, simply run this command on the command line: This will perform some checks on your environment to make sure you can actually run it. -This will download `composer.phar` and place it in your working directory. -`composer.phar` is the composer binary. It is a PHAR (PHP archive), which -is an archive format for PHP which can be run on the command line, amongst -other things. +Then it will download `composer.phar` and place it in your working directory. +`composer.phar` is the composer binary. It is a PHAR (PHP archive), which is +an archive format for PHP which can be run on the command line, amongst other +things. You can place this file anywhere you wish. If you put it in your `PATH`, you can access it globally. On unixy systems you can even make it @@ -94,9 +94,9 @@ supplied version constraint and download it into the the `vendor` directory. It's a convention to put third party code into a directory named `vendor`. In case of monolog it will put it into `vendor/monolog/monolog`. -**Tip:** If you are using git for your project, you probably want to add -`vendor` into your `.gitignore`. You really don't want to add all of that -code to your repository. +> **Tip:** If you are using git for your project, you probably want to add +> `vendor` into your `.gitignore`. You really don't want to add all of that +> code to your repository. Another thing that the `install` command does is it adds a `composer.lock` file into your project root. @@ -145,7 +145,7 @@ this file and you will get autoloading for free. require 'vendor/.composer/autoload.php'; ``` -This makes it really easy to use third party code, because you really just +This makes it really easy to use third party code, because you only have to add one line to `composer.json` and run `install`. For monolog, it means that we can just start using classes from it, and they will be autoloaded. @@ -157,7 +157,7 @@ $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Logger::WARNING)) $log->addWarning('Foo'); ``` -You can even add your own code to the autoloader by adding an `autoload` key +You can even add your own code to the autoloader by adding an `autoload` field to `composer.json`. ```json @@ -170,14 +170,14 @@ to `composer.json`. This is a mapping from namespaces to directories. The `src` directory would be in your project root. An example filename would be `src/Acme/Foo.php` -containing a `Acme\Foo` class. +containing an `Acme\Foo` class. -After adding the `autoload` key, you have to re-run `install` to re-generate +After adding the `autoload` field, you have to re-run `install` to re-generate the `vendor/.composer/autoload.php` file. -Including that file will also return the autoloader instance, so you can add -retrieve it and add more namespaces. This can be useful for autoloading -classes in a test suite, for example. +Including that file will also return the autoloader instance, so you can store +the return value of the include call in a variable and add more namespaces. +This can be useful for autoloading classes in a test suite, for example. ```php $loader = require 'vendor/.composer/autoload.php'; diff --git a/doc/03-cli.md b/doc/03-cli.md index 99b507deb..911b0677b 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -30,10 +30,20 @@ resolution. ### Options -* **--prefer-source:** There are two ways of downloading a package: `source` and `dist`. For stable versions composer will use the `dist` by default. The `source` is a version control repository. If `--prefer-source` is enabled, composer will install from `source` if there is one. This is useful if you want to make a bugfix to a project and get a local git clone of the dependency directly. -* **--dry-run:** If you want to run through an installation without actually installing a package, you can use `--dry-run`. This will simulate the installation and show you what would happen. -* **--no-install-recommends:** By default composer will install all packages that are referenced by `recommend`. By passing this option you can disable that. -* **--install-suggests:** The packages referenced by `suggest` will not be installed by default. By passing this option, you can install them. +* **--prefer-source:** There are two ways of downloading a package: `source` + and `dist`. For stable versions composer will use the `dist` by default. + The `source` is a version control repository. If `--prefer-source` is + enabled, composer will install from `source` if there is one. This is + useful if you want to make a bugfix to a project and get a local git + clone of the dependency directly. +* **--dry-run:** If you want to run through an installation without actually + installing a package, you can use `--dry-run`. This will simulate the + installation and show you what would happen. +* **--no-install-recommends:** By default composer will install all packages + that are referenced by `recommend`. By passing this option you can disable + that. +* **--install-suggests:** The packages referenced by `suggest` will not be + installed by default. By passing this option, you can install them. ## update @@ -115,7 +125,7 @@ should be included in the listing. ### Options * **--link-type:** The link types to match on, can be specified multiple -times. + times. ## validate @@ -137,3 +147,34 @@ command. It will replace your `composer.phar` with the latest version. To get more information about a certain command, just use `help`. $ php composer.phar help install + +## Environment variables + +You can set a number of environment variables that override certain settings. +Whenever possible it is recommended to specify these settings in the `config` +section of `composer.json` instead. It is worth noting that that the env vars +will always take precedence over the values specified in `composer.json`. + +### COMPOSER + +By setting the `COMPOSER` env variable is is possible to set the filename of +`composer.json` to something else. + +For example: + + $ COMPOSER=composer-other.json php composer.phar install + +### COMPOSER_VENDOR_DIR + +By setting this option you can make composer install the dependencies into a +directory other than `vendor`. + +### COMPOSER_BIN_DIR + +By setting this option you can change the `bin` ([articles/vendor-bins.md]) +directory to something other than `vendor/bin`. + +### COMPOSER_PROCESS_TIMEOUT + +This env var controls the time composer waits for commands (such as git +commands) to finish executing. The default value is 60 seconds. diff --git a/doc/04-schema.md b/doc/04-schema.md index 909041bdd..ea0d502a5 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -6,7 +6,7 @@ This chapter will explain all of the options available in `composer.json`. We have a [JSON schema](http://json-schema.org) that documents the format and can also be used to validate your `composer.json`. In fact, it is used by the -`validate` command. You can find it at: +`validate` command. You can find it at: [`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). ## Package root @@ -58,9 +58,9 @@ The type of the package. It defaults to `library`. Package types are used for custom installation logic. If you have a package that needs some special logic, you can define a custom type. This could be a -`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These will all be -specific to certain projects, and they will need to provide an installer -capable of installing packages of that type. +`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will +all be specific to certain projects, and they will need to provide an +installer capable of installing packages of that type. Out of the box, composer supports two types: @@ -242,14 +242,13 @@ Repositories are not resolved recursively. You can only add them to your main `composer.json`. Repository declarations of dependencies' `composer.json`s are ignored. -Following repository types are supported: +The following repository types are supported: * **composer:** A composer repository is simply a `packages.json` file served - via HTTP that contains a list of `composer.json` objects with additional + via HTTP, that contains a list of `composer.json` objects with additional `dist` and/or `source` information. * **vcs:** The version control system repository can fetch packages from git, - svn and hg repositories. Note the distinction between package repository and - version control repository. + svn and hg repositories. * **pear:** With this you can import any pear repository into your composer project. * **package:** If you depend on a project that does not have any support for @@ -335,7 +334,8 @@ Example: ## scripts -Composer allows you to hook into various parts of the installation process through the use of scripts. +Composer allows you to hook into various parts of the installation process +through the use of scripts. These events are supported: @@ -388,6 +388,8 @@ class ScriptHandler { static public function doSomething(Event $event) { + $composer = $event->getComposer(); + // custom logic } } @@ -411,6 +413,6 @@ Optional. A set of files that should be treated as binaries and symlinked into the `bin- dir` (from config). -See [articles/bin.md] for more details. +See [articles/vendor-bins.md] for more details. Optional. diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 4cdcf866a..97aeb4b09 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -5,12 +5,12 @@ of repositories are available, and how they work. ## Concepts -Before we look at the different types of repositories that we can have, we -need to understand some of the basic concepts that composer is built on. +Before we look at the different types of repositories that exist, we need to +understand some of the basic concepts that composer is built on. ### Package -Composer is a dependency manager. It installs packages. A package is +Composer is a dependency manager. It installs packages locally. A package is essentially just a directory containing something. In this case it is PHP code, but in theory it could be anything. And it contains a package description which has a name and a version. The name and the version are used @@ -20,9 +20,9 @@ In fact, internally composer sees every version as a separate package. While this distinction does not matter when you are using composer, it's quite important when you want to change it. -In addition to the name and the version, there is useful data. The only really -important piece of information is the package source, that describes where to -get the package contents. The package data points to the contents of the +In addition to the name and the version, there is useful data. The information +most relevant for installation is the source definition, which describes where +to get the package contents. The package data points to the contents of the package. And there are two options here: dist and source. **Dist:** The dist is a packaged version of the package data. Usually a @@ -135,11 +135,11 @@ The following are supported: * **Subversion:** [subversion.apache.org](http://subversion.apache.org) * **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) -To use these systems you need to have them installed. That can be -invonvenient. And for this reason there is special support for GitHub and -BitBucket that use the APIs provided by these sites, to fetch the packages -without having to install the version control system. The VCS repository -provides `dist`s for them that fetch the packages as zips. +To get packages from these systems you need to have their respective clients +installed. That can be invonvenient. And for this reason there is special +support for GitHub and BitBucket that use the APIs provided by these sites, to +fetch the packages without having to install the version control system. The +VCS repository provides `dist`s for them that fetch the packages as zips. * **GitHub:** [github.com](https://github.com) (Git) * **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) @@ -177,12 +177,12 @@ In this case the short name of the channel is `pear2`, so the ### Package If you want to use a project that does not support composer through any of the -means above, you still can define the package yourself using a `package` +means above, you still can define the package yourself by using a `package` repository. Basically, you define the same information that is included in the `composer` repository's `packages.json`, but only for a single package. Again, the -minimally required fields are `name`, `version`, and either of `dist` or +minimum required fields are `name`, `version`, and either of `dist` or `source`. Here is an example for the smarty template engine: @@ -231,8 +231,7 @@ there are some use cases for hosting your own repository. When hosting your own package repository it is recommended to use a `composer` one. This is type that is native to composer and yields the best performance. -There are a few different tools that can help you create a `composer` -repository. +There are a few tools that can help you create a `composer` repository. ### Packagist @@ -251,13 +250,12 @@ github repository](https://github.com/composer/packagist). ### Satis -Satis is a static `composer` repository generator. It is a bit like a ultra- -lightweight, file-based version of packagist. +Satis is a static `composer` repository generator. It is a bit like an ultra- +lightweight, static file-based version of packagist. -You give it a `composer.json` containing repositories, typically VCS and package -repository definitions. It will fetch all the packages that are `require`d from -these repositories and dump a `packages.json` that is your `composer` -repository. +You give it a `composer.json` containing repositories, typically VCS and +package repository definitions. It will fetch all the packages that are +`require`d and dump a `packages.json` that is your `composer` repository. Check [the satis GitHub repository](https://github.com/composer/satis) for more information. diff --git a/doc/06-community.md b/doc/06-community.md index cdf394295..575d6ca3b 100644 --- a/doc/06-community.md +++ b/doc/06-community.md @@ -1,7 +1,7 @@ # Community -We have a lot of people using composer, and also many contributors to the -project. +There are a lot of people using composer already, quite a few are also already +contributing. ## Contributing @@ -22,7 +22,7 @@ The most important guidelines are described as follows: ## IRC / mailing list -The developer mailing list is on [google groups](http://groups.google.com/group/composer-dev/) +The developer mailing list is on [google groups](http://groups.google.com/group/composer-dev/) IRC channels are available for discussion as well, on irc.freenode.org [#composer](irc://irc.freenode.org/composer) for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development.