From f5196360944e63c41fcd43b9c3e1200778d70354 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 17:19:07 +0200 Subject: [PATCH 01/10] [docs] Document the notify-on-install config option --- doc/04-schema.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/04-schema.md b/doc/04-schema.md index 2b7aef879..cc91d9905 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 is + installed. This option allows you to disable that behaviour. Example: From f6259263ad9c7118250b16630fba059f3adcf383 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 17:19:39 +0200 Subject: [PATCH 02/10] [docs] Update composer repository specification --- doc/05-repositories.md | 81 +++++++++++++++++++++++++++++++++++------- 1 file changed, 69 insertions(+), 12 deletions(-) diff --git a/doc/05-repositories.md b/doc/05-repositories.md index ba1272d21..cc633f439 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,60 @@ 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`. +> **Note:** Optionally packages can contain a `version_normalized` field, with +> the pre-parsed version. This improves performance for large repositories such +> as packagist, as the `version` field no longer has to be converted to the +> internal representation. + +#### 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 from the root `packages.json` 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. Do note that `includes` are not resolved recursively, they can +only be specified in the root `packages.json`. + +This field is optional. You probably don't need it for your own custom +repository. ### VCS From b14aac84aeb75629d35d17e589929b57a8912903 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 17:24:31 +0200 Subject: [PATCH 03/10] [docs] Document COMPOSER_HOME --- doc/03-cli.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/03-cli.md b/doc/03-cli.md index 4648aa42a..ecded9528 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,18 @@ 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 global (per-user on the machine) hidden directory that caches repository +data. + +By default it points to `$HOME/.composer` on *nix and `$APPDATA/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 60 seconds. + ← [Libraries](02-libraries.md) | [Schema](04-schema.md) → From 7b882479a7358fdb9627a8afad2fd2a19095a256 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 18:40:00 +0200 Subject: [PATCH 04/10] [docs] Aliases: branch-alias and inline aliasing --- doc/02-libraries.md | 8 ++++ doc/articles/aliases.md | 82 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 doc/articles/aliases.md 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/articles/aliases.md b/doc/articles/aliases.md new file mode 100644 index 000000000..bbde23b94 --- /dev/null +++ b/doc/articles/aliases.md @@ -0,0 +1,82 @@ + +# 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-dev` version. It is done by +specifying a `branch-alias` field under `extra` in `composer.json`: + + { + "extra": { + "branch-alias": { + "dev-master": "1.0-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` field. 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. + +Just add this to your project's root `composer.json`: + + { + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/you/monolog" + } + ], + "require": { + "monolog/monolog": "dev-bugfix as 1.0-dev" + } + } + +That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub +and alias it to `1.0-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-dev`, installing A will make B require `1.0-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`. From 1d3fd25cf2b9557a76622fca0e700fe72d0dece0 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 18:54:45 +0200 Subject: [PATCH 05/10] [docs] Improve description of COMPOSER_HOME --- doc/03-cli.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/03-cli.md b/doc/03-cli.md index ecded9528..8cceb71f6 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -213,11 +213,12 @@ Alternatively you can also define the git proxy using ### COMPOSER_HOME The `COMPOSER_HOME` var allows you to change the composer home directory. This -is a global (per-user on the machine) hidden directory that caches repository -data. +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 and `$APPDATA/Composer` on -Windows. +By default it points to `/home//.composer` on *nix, +`/Users//.composer` on OSX and +`C:\Users\\AppData\Roaming\Composer` on Windows. ### COMPOSER_PROCESS_TIMEOUT From bca2ab7836cf1024d7104b6f674b1a5d9135f8ea Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 18:59:09 +0200 Subject: [PATCH 06/10] [docs] Correct default process timeout --- doc/03-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/03-cli.md b/doc/03-cli.md index 8cceb71f6..94d5b001a 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -223,6 +223,6 @@ By default it points to `/home//.composer` on *nix, ### 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. +commands) to finish executing. The default value is 300 seconds (5 minutes). ← [Libraries](02-libraries.md) | [Schema](04-schema.md) → From 21b39f8e87b4082b392b375bae633ef704b80a77 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 19:00:55 +0200 Subject: [PATCH 07/10] [docs] Clarify that there is no cross-repo leakage with notify --- doc/04-schema.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/04-schema.md b/doc/04-schema.md index cc91d9905..7c0b03acc 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -369,8 +369,8 @@ The following options are supported: 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 is - installed. This option allows you to disable that behaviour. + 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: From 8dd2a72e8df79d846c3db559c6e3be542ba0c8e3 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 19:02:27 +0200 Subject: [PATCH 08/10] [docs] Remove mentions of version_normalized People will get it wrong so it would possibly cause more harm than good --- doc/05-repositories.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/05-repositories.md b/doc/05-repositories.md index cc633f439..48a253128 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -97,11 +97,6 @@ Here is a minimal package definition: It may include any of the other fields specified in the [schema](04-schema.md). -> **Note:** Optionally packages can contain a `version_normalized` field, with -> the pre-parsed version. This improves performance for large repositories such -> as packagist, as the `version` field no longer has to be converted to the -> internal representation. - #### notify The `notify` field allows you to specify an URL template for a URL that will From 3b407710897905c6107c03d44099d0c120677213 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 19:04:06 +0200 Subject: [PATCH 09/10] [docs] Remove false information about recursive include fields --- doc/05-repositories.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 48a253128..894e35230 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -121,8 +121,8 @@ This field is optional. #### includes For large repositories it is possible to split the `packages.json` into -multiple files. The `includes` field from the root `packages.json` allows you -to reference these additional files. +multiple files. The `includes` field allows you to reference these additional +files. An example: @@ -141,8 +141,7 @@ An example: } The SHA-1 sum of the file allows it to be cached and only re-requested if the -hash changed. Do note that `includes` are not resolved recursively, they can -only be specified in the root `packages.json`. +hash changed. This field is optional. You probably don't need it for your own custom repository. From 6a1843da38dbc8e2120549dbe07a9403b4853f84 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Thu, 26 Apr 2012 19:21:31 +0200 Subject: [PATCH 10/10] [docs] Change alias article according to comments 1.0.x-dev alias is safer than 1.0-dev. require-dev is also supported. Clarify that inline aliases are for matching constraints of deps. Tell users to avoid inline aliasing if possible. --- doc/articles/aliases.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/doc/articles/aliases.md b/doc/articles/aliases.md index bbde23b94..38e0e65ee 100644 --- a/doc/articles/aliases.md +++ b/doc/articles/aliases.md @@ -24,13 +24,13 @@ Enter aliases. 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-dev` version. It is done by +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-dev" + "dev-master": "1.0.x-dev" } } } @@ -52,10 +52,13 @@ 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` field. 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. +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`: @@ -67,16 +70,21 @@ Just add this to your project's root `composer.json`: } ], "require": { - "monolog/monolog": "dev-bugfix as 1.0-dev" + "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-dev`. +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-dev`, installing A will make B require `1.0-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`. +> 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.