diff --git a/doc/02-libraries.md b/doc/02-libraries.md index 990246537..81d665fda 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -76,6 +76,14 @@ Here are some examples of version branch names: > **Note:** When you install a dev version, it will install it from source. See [Repositories](05-repositories.md) for more information. +### Aliases + +It is possible alias branch names to versions. For example, you could alias +`dev-master` to `1.0-dev`, which would allow you to require `1.0-dev` in all +the packages. + +See [Aliases](articles/aliases.md) for more information. + ## Lock file For your library you may commit the `composer.lock` file if you want to. This diff --git a/doc/03-cli.md b/doc/03-cli.md index 4648aa42a..94d5b001a 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -199,11 +199,6 @@ directory other than `vendor`. By setting this option you can change the `bin` ([Vendor Bins](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. - ### http_proxy or HTTP_PROXY If you are using composer from behind an HTTP proxy, you can use the standard @@ -215,4 +210,19 @@ some tools like git or curl will only use the lower-cased `http_proxy` version. Alternatively you can also define the git proxy using `git config --global http.proxy `. +### COMPOSER_HOME + +The `COMPOSER_HOME` var allows you to change the composer home directory. This +is a hidden, global (per-user on the machine) directory that is shared between +all projects. + +By default it points to `/home//.composer` on *nix, +`/Users//.composer` on OSX and +`C:\Users\\AppData\Roaming\Composer` on Windows. + +### COMPOSER_PROCESS_TIMEOUT + +This env var controls the time composer waits for commands (such as git +commands) to finish executing. The default value is 300 seconds (5 minutes). + ← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/doc/04-schema.md b/doc/04-schema.md index 2b7aef879..7c0b03acc 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -368,6 +368,9 @@ The following options are supported: * **process-timeout:** Defaults to `300`. The duration processes like git clones can run before Composer assumes they died out. You may need to make this higher if you have a slow connection or huge vendors. +* **notify-on-install:** Defaults to `true`. Composer allows repositories to + define a notification URL, so that they get notified whenever a package from + that repository is installed. This option allows you to disable that behaviour. Example: diff --git a/doc/05-repositories.md b/doc/05-repositories.md index ba1272d21..894e35230 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -54,15 +54,24 @@ want to learn why. ### Composer The main repository type is the `composer` repository. It uses a single -`packages.json` file that contains all of the package metadata. The JSON -format is as follows: +`packages.json` file that contains all of the package metadata. + +This is also the repository type that packagist uses. To reference a +`composer` repository, just supply the path before the `packages.json` file. +In case of packagist, that file is located at `/packages.json`, so the URL of +the repository would be `packagist.org`. For `example.org/packages.json` the +repository URL would be `example.org`. + +#### packages + +The only required field is `packages`. The JSON structure is as follows: { - "vendor/packageName": { - "name": "vendor/packageName", - "description": "Package description", - "versions": { + "packages": { + "vendor/packageName": { "master-dev": { @composer.json }, + "1.0.x-dev": { @composer.json }, + "0.0.1": { @composer.json }, "1.0.0": { @composer.json } } } @@ -88,12 +97,54 @@ Here is a minimal package definition: It may include any of the other fields specified in the [schema](04-schema.md). -The `composer` repository is also what packagist uses. To reference a -`composer` repository, just supply the path before the `packages.json` file. -In case of packagist, that file is located at `/packages.json`, so the URL of -the repository would be `http://packagist.org`. For -`http://example.org/packages.json` the repository URL would be -`http://example.org`. +#### notify + +The `notify` field allows you to specify an URL template for a URL that will +be called every time a user installs a package. + +An example value: + + { + "notify": "/downloads/%package%" + } + +For `example.org/packages.json` containing a `monolog/monolog` package, this +would send a `POST` request to `example.org/downloads/monolog/monolog` with +following parameters: + +* **version:** The version of the package. +* **version_normalized:** The normalized internal representation of the + version. + +This field is optional. + +#### includes + +For large repositories it is possible to split the `packages.json` into +multiple files. The `includes` field allows you to reference these additional +files. + +An example: + + { + "includes": { + "packages-2011.json": { + "sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17" + }, + "packages-2012-01.json": { + "sha1": "897cde726f8a3918faf27c803b336da223d400dd" + }, + "packages-2012-02.json": { + "sha1": "26f911ad717da26bbcac3f8f435280d13917efa5" + } + } + } + +The SHA-1 sum of the file allows it to be cached and only re-requested if the +hash changed. + +This field is optional. You probably don't need it for your own custom +repository. ### VCS diff --git a/doc/articles/aliases.md b/doc/articles/aliases.md new file mode 100644 index 000000000..38e0e65ee --- /dev/null +++ b/doc/articles/aliases.md @@ -0,0 +1,90 @@ + +# Aliases + +## Why aliases? + +When you are using a VCS repository, you will only get comparable versions for +branches that look like versions, such as `2.0`. For your `master` branch, you +will get a `dev-master` version. For your `bugfix` branch, you will get a +`dev-bugfix` version. + +If your `master` branch is used to tag releases of the `1.0` development line, +i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will +probably require version `1.0.*`. + +If anyone wants to require the latest `dev-master`, they have a problem: Other +packages may require `1.0.*`, so requiring that dev version will lead to +conflicts, since `dev-master` does not match the `1.0.*` constraint. + +Enter aliases. + +## Branch alias + +The `dev-master` branch is one in your main VCS repo. It is rather common that +someone will want the latest master dev version. Thus, Composer allows you to +alias your `dev-master` branch to a `1.0.x-dev` version. It is done by +specifying a `branch-alias` field under `extra` in `composer.json`: + + { + "extra": { + "branch-alias": { + "dev-master": "1.0.x-dev" + } + } + } + +The branch version must begin with `dev-` (non-comparable version), the alias +must be a comparable dev version. The `branch-alias` must be present on the +branch that it references. For `dev-master`, you need to commit it on the +`master` branch. + +As a result, you can now require `1.0.*` and it will happily install +`dev-master` for you. + +## Require inline alias + +Branch aliases are great for aliasing main development lines. But in order to +use them you need to have control over the source repository, and you need to +commit changes to version control. + +This is not really fun when you just want to try a bugfix of some library that +is a dependency of your local project. + +For this reason, you can alias packages in your `require` and `require-dev` +fields. Let's say you found a bug in the `monolog/monolog` package. You cloned +Monolog on GitHub and fixed the issue in a branch named `bugfix`. Now you want +to install that version of monolog in your local project. + +You are using `symfony/monolog-bundle` which requires `monolog/monolog` version +`1.*`. So you need your `dev-bugfix` to match that constraint. + +Just add this to your project's root `composer.json`: + + { + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/you/monolog" + } + ], + "require": { + "symfony/monolog-bundle": "2.0", + "monolog/monolog": "dev-bugfix as 1.0.x-dev" + } + } + +That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub +and alias it to `1.0.x-dev`. + +> **Note:** If a package with inline aliases is required, the alias (right of +> the `as`) is used as the version constraint. The part left of the `as` is +> discarded. As a consequence, if A requires B and B requires `monolog/monolog` +> version `dev-bugfix as 1.0.x-dev`, installing A will make B require +> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If +> it does not, it must be re-inline-aliased in A's `composer.json`. + +> **Note:** Inline aliasing should be avoided, especially for published +> packages. If you found a bug, try and get your fix merged upstream. This +> helps to avoid issues for users of your package.