public-mirrors
/
composer
mirror of https://github.com/composer/composer
1
0
Fork 0
Code

[docs] wrap all lines to 80 chars

pull/319/head
Igor Wiedler 2012-02-20 11:08:18 +01:00
parent cabe1c2949
commit c42e37037a
5 changed files with 304 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
doc/01-basic-usage.md
View File

@ -24,13 +24,15 @@ To check if composer is working, just run the PHAR through `php`:
This should give you a list of available commands. This should give you a list of available commands.
> **Note:** You can also perform the checks only without downloading composer by using the `--check` option. For more information, just use `--help`. > **Note:** You can also perform the checks only without downloading composer
> by using the `--check` option. For more information, just use `--help`.
> >
> $ curl -s http://getcomposer.org/installer | php -- --help > $ curl -s http://getcomposer.org/installer | php -- --help
## Project setup ## Project setup
To start using composer in your project, all you need is a `composer.json` file. This file describes the dependencies of your project and may contain To start using composer in your project, all you need is a `composer.json`
file. This file describes the dependencies of your project and may contain
other metadata as well. other metadata as well.
The [JSON format](http://json.org/) is quite easy to write. It allows you to The [JSON format](http://json.org/) is quite easy to write. It allows you to
@ -74,10 +76,11 @@ Version constraints can be specified in a few different ways.
example `1.0.2`. This is not used very often, but can be useful. example `1.0.2`. This is not used very often, but can be useful.
* **Range:** By using comparison operators you can specify ranges of valid * **Range:** By using comparison operators you can specify ranges of valid
versions. Valid operators are `>`, `>=`, `<`, `<=`. An example range would be `>=1.0`. You can define multiple of these, separated by comma: versions. Valid operators are `>`, `>=`, `<`, `<=`. An example range would be
`>=1.0,<2.0`. `>=1.0`. You can define multiple of these, separated by comma: `>=1.0,<2.0`.
* **Wildcard:** You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0,<1.1-dev`. * **Wildcard:** You can specify a pattern with a `*` wildcard. `1.0.*` is the
equivalent of `>=1.0,<1.1-dev`.
## Installing dependencies ## Installing dependencies
@ -95,8 +98,8 @@ In case of monolog it will put it into `vendor/monolog/monolog`.
`vendor` into your `.gitignore`. You really don't want to add all of that `vendor` into your `.gitignore`. You really don't want to add all of that
code to your repository. code to your repository.
Another thing that the `install` command does is it adds a `composer.lock` file Another thing that the `install` command does is it adds a `composer.lock`
into your project root. file into your project root.
## Lock file ## Lock file
@ -119,22 +122,33 @@ also update the lock file.
## Packagist ## Packagist
[Packagist](http://packagist.org/) is the main composer repository. A composer repository is basically a package source. A place where you can get packages from. Packagist aims to be the central repository that everybody uses. This means that you can automatically `require` any package that is available there. [Packagist](http://packagist.org/) is the main composer repository. A composer
repository is basically a package source. A place where you can get packages
from. Packagist aims to be the central repository that everybody uses. This
means that you can automatically `require` any package that is available
there.
If you go to the [packagist website](http://packagist.org/) (packagist.org), you can browse and search for packages. If you go to the [packagist website](http://packagist.org/) (packagist.org),
you can browse and search for packages.
Any open source project using composer should publish their packages on packagist. Any open source project using composer should publish their packages on
packagist.
## Autoloading ## Autoloading
For libraries that follow the [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) naming standard, composer generates For libraries that follow the [PSR-0](https://github.com/php-fig/fig-
a `vendor/.composer/autoload.php` file for autoloading. You can simply include this file and you will get autoloading for free. standards/blob/master/accepted/PSR-0.md) naming standard, composer generates a
`vendor/.composer/autoload.php` file for autoloading. You can simply include
this file and you will get autoloading for free.
```php ```php
require 'vendor/.composer/autoload.php'; require 'vendor/.composer/autoload.php';
``` ```
This makes it really easy to use third party code, because you really just 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. This makes it really easy to use third party code, because you really just
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.
```php ```php
$log = new Monolog\Logger('name'); $log = new Monolog\Logger('name');
@ -143,7 +157,8 @@ $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Logger::WARNING))
$log->addWarning('Foo'); $log->addWarning('Foo');
``` ```
You can even add your own code to the autoloader by adding an `autoload` key to `composer.json`. You can even add your own code to the autoloader by adding an `autoload` key
to `composer.json`.
```json ```json
{ {
@ -153,15 +168,22 @@ You can even add your own code to the autoloader by adding an `autoload` key to
} }
``` ```
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. 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.
After adding the `autoload` key, you have to re-run `install` to re-generate the `vendor/.composer/autoload.php` file. After adding the `autoload` key, 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 add
retrieve it and add more namespaces. This can be useful for autoloading
classes in a test suite, for example.
```php ```php
$loader = require 'vendor/.composer/autoload.php'; $loader = require 'vendor/.composer/autoload.php';
$loader->add('Acme\Test', __DIR__); $loader->add('Acme\Test', __DIR__);
``` ```
> **Note:** Composer provides its own autoloader. If you don't want to use that one, you can just include `vendor/.composer/autoload_namespaces.php`, which returns an associative array mapping namespaces to directories. > **Note:** Composer provides its own autoloader. If you don't want to use
that one, you can just include `vendor/.composer/autoload_namespaces.php`,
which returns an associative array mapping namespaces to directories.

89
doc/02-libraries.md
View File

@ -4,9 +4,13 @@ This chapter will tell you how to make your library installable through composer
## Every project is a package ## Every project is a package
As soon as you have a `composer.json` in a directory, that directory is a package. When you add a `require` to a project, you are making a package that depends on other packages. The only difference between your project and libraries is that your project is a package without a name. As soon as you have a `composer.json` in a directory, that directory is a
package. When you add a `require` to a project, you are making a package that
depends on other packages. The only difference between your project and
libraries is that your project is a package without a name.
In order to make that package installable you need to give it a name. You do this by adding a `name` to `composer.json`: In order to make that package installable you need to give it a name. You do
this by adding a `name` to `composer.json`:
```json ```json
{ {
@ -17,13 +21,18 @@ In order to make that package installable you need to give it a name. You do thi
} }
``` ```
In this case the project name is `acme/hello-world`, where `acme` is the vendor name. Supplying a vendor name is mandatory. In this case the project name is `acme/hello-world`, where `acme` is the
vendor name. Supplying a vendor name is mandatory.
> **Note:** If you don't know what to use as a vendor name, your GitHub username is usually a good bet. While package names are case insensitive, the convention is all lowercase and dashes for word separation. > **Note:** If you don't know what to use as a vendor name, your GitHub
username is usually a good bet. While package names are case insensitive, the
convention is all lowercase and dashes for word separation.
## Specifying the version ## Specifying the version
You need to specify the version some way. Depending on the type of repository you are using, it might be possible to omit it from `composer.json`, because the repository is able to infer the version from elsewhere. You need to specify the version some way. Depending on the type of repository
you are using, it might be possible to omit it from `composer.json`, because
the repository is able to infer the version from elsewhere.
If you do want to specify it explicitly, you can just add a `version` field: If you do want to specify it explicitly, you can just add a `version` field:
@ -33,11 +42,14 @@ If you do want to specify it explicitly, you can just add a `version` field:
} }
``` ```
However if you are using git, svn or hg, you don't have to specify it. Composer will detect versions as follows: However if you are using git, svn or hg, you don't have to specify it.
Composer will detect versions as follows:
### Tags ### Tags
For every tag that looks like a version, a package version of that tag will be created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix for RC, beta, alpha or patch. For every tag that looks like a version, a package version of that tag will be
created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix for RC,
beta, alpha or patch.
Here are a few examples of valid tag names: Here are a few examples of valid tag names:
@ -52,7 +64,11 @@ Here are a few examples of valid tag names:
### Branches ### Branches
For every branch, a package development version will be created. If the branch name looks like a version, the version will be `{branchname}-dev`. For example a branch `2.0` will get a version `2.0-dev`. If the branch does not look like a version, it will be `dev-{branchname}`. `master` results in a `dev-master` version. For every branch, a package development version will be created. If the branch
name looks like a version, the version will be `{branchname}-dev`. For example
a branch `2.0` will get a version `2.0-dev`. If the branch does not look like
a version, it will be `dev-{branchname}`. `master` results in a `dev-master`
version.
Here are some examples of version branch names: Here are some examples of version branch names:
@ -61,11 +77,16 @@ Here are some examples of version branch names:
1.1.x 1.1.x
1.1.* 1.1.*
> **Note:** When you install a dev version, it will install it from source. See [Repositories] for more information. > **Note:** When you install a dev version, it will install it from source.
See [Repositories] for more information.
## Lock file ## Lock file
For projects it is recommended to commit the `composer.lock` file into version control. For libraries this is not the case. You do not want your library to be tied to exact versions of the dependencies. It should work with any compatible version, so make sure you specify your version constraints so that they include all compatible versions. For projects it is recommended to commit the `composer.lock` file into version
control. For libraries this is not the case. You do not want your library to
be tied to exact versions of the dependencies. It should work with any
compatible version, so make sure you specify your version constraints so that
they include all compatible versions.
**Do not commit your library's `composer.lock` into version control.** **Do not commit your library's `composer.lock` into version control.**
@ -73,9 +94,16 @@ If you are using git, add it to the `.gitignore`.
## Publishing to a VCS ## Publishing to a VCS
Once you have a vcs repository (version control system, e.g. git) containing a `composer.json` file, your library is already composer-installable. In this example we will publish the `acme/hello-world` library on GitHub under `github.com/composer/hello-world`. Once you have a vcs repository (version control system, e.g. git) containing a
`composer.json` file, your library is already composer-installable. In this
example we will publish the `acme/hello-world` library on GitHub under
`github.com/composer/hello-world`.
Now, To test installing the `acme/hello-world` package, we create a new project locally. We will call it `acme/blog`. This blog will depend on `acme/hello-world`, which in turn depends on `monolog/monolog`. We can accomplish this by creating a new `blog` directory somewhere, containing a `composer.json`: Now, To test installing the `acme/hello-world` package, we create a new
project locally. We will call it `acme/blog`. This blog will depend on `acme
/hello-world`, which in turn depends on `monolog/monolog`. We can accomplish
this by creating a new `blog` directory somewhere, containing a
`composer.json`:
```json ```json
{ {
@ -86,9 +114,13 @@ Now, To test installing the `acme/hello-world` package, we create a new project
} }
``` ```
The name is not needed in this case, since we don't want to publish the blog as a library. It is added here to clarify which `composer.json` is being described. The name is not needed in this case, since we don't want to publish the blog
as a library. It is added here to clarify which `composer.json` is being
described.
Now we need to tell the blog app where to find the `hello-world` dependency. We do this by adding a package repository specification to the blog's `composer.json`: Now we need to tell the blog app where to find the `hello-world` dependency.
We do this by adding a package repository specification to the blog's
`composer.json`:
```json ```json
{ {
@ -104,20 +136,33 @@ Now we need to tell the blog app where to find the `hello-world` dependency. We
} }
``` ```
For more details on how package repositories work and what other types are available, see [Repositories]. For more details on how package repositories work and what other types are
available, see [Repositories].
That's all. You can now install the dependencies by running composer's `install` command! That's all. You can now install the dependencies by running composer's
`install` command!
**Recap:** Any git/svn/hg repository containing a `composer.json` can be added to your project by specifying the package repository and declaring the dependency in the `require` field. **Recap:** Any git/svn/hg repository containing a `composer.json` can be added
to your project by specifying the package repository and declaring the
dependency in the `require` field.
## Publishing to packagist ## Publishing to packagist
Alright, so now you can publish packages. But specifying the vcs repository every time is cumbersome. You don't want to force all your users to do that. Alright, so now you can publish packages. But specifying the vcs repository
every time is cumbersome. You don't want to force all your users to do that.
The other thing that you may have noticed is that we did not specify a package repository for `monolog/monolog`. How did that work? The answer is packagist. The other thing that you may have noticed is that we did not specify a package
repository for `monolog/monolog`. How did that work? The answer is packagist.
Packagist is the main package repository for composer, and it is enabled by default. Anything that is published on packagist is available automatically through composer. Since monolog [is on packagist](http://packagist.org/packages/monolog/monolog), we can depend on it without having to specify any additional repositories. Packagist is the main package repository for composer, and it is enabled by
default. Anything that is published on packagist is available automatically
through composer. Since monolog [is on
packagist](http://packagist.org/packages/monolog/monolog), we can depend on it
without having to specify any additional repositories.
Assuming we want to share `hello-world` with the world, we would want to publish it on packagist as well. And this is really easy. Assuming we want to share `hello-world` with the world, we would want to
publish it on packagist as well. And this is really easy.
You simply hit the big "Submit Package" button and sign up. Then you submit the URL to your VCS, at which point packagist will start crawling it. Once it is done, your package will be available to anyone. You simply hit the big "Submit Package" button and sign up. Then you submit
the URL to your VCS, at which point packagist will start crawling it. Once it
is done, your package will be available to anyone.

50
doc/03-cli.md
View File

@ -1,24 +1,32 @@
# Command-line interface # Command-line interface
You've already learned how to use the command-line interface to do some things. This chapter documents all the available commands. You've already learned how to use the command-line interface to do some
things. This chapter documents all the available commands.
## init ## init
In the [Libraries] chapter we looked at how to create a `composer.json` by hand. There is also an `init` command available that makes it a bit easier to do this. In the [Libraries] chapter we looked at how to create a `composer.json` by
hand. There is also an `init` command available that makes it a bit easier to
do this.
When you run the command it will interactively ask you to fill in the fields, while using some smart defaults. When you run the command it will interactively ask you to fill in the fields,
while using some smart defaults.
$ php composer.phar init $ php composer.phar init
## install ## install
The `install` command reads the `composer.json` file from the current directory, resolves the dependencies, and installs them into `vendor`. The `install` command reads the `composer.json` file from the current
directory, resolves the dependencies, and installs them into `vendor`.
$ php composer.phar install $ php composer.phar install
If there is a `composer.lock` file in the current directory, it will use the exact versions from there instead of resolving them. This ensures that everyone using the library will get the same versions of the dependencies. If there is a `composer.lock` file in the current directory, it will use the
exact versions from there instead of resolving them. This ensures that
everyone using the library will get the same versions of the dependencies.
If there is no `composer.lock` file, composer will create one after dependency resolution. If there is no `composer.lock` file, composer will create one after dependency
resolution.
### Options ### Options
@ -29,11 +37,13 @@ If there is no `composer.lock` file, composer will create one after dependency r
## update ## update
In order to get the latest versions of the dependencies and to update the `composer.lock` file, you should use the `update` command. In order to get the latest versions of the dependencies and to update the
`composer.lock` file, you should use the `update` command.
$ php composer.phar update $ php composer.phar update
This will resolve all dependencies of the project and write the exact versions into `composer.lock`. This will resolve all dependencies of the project and write the exact versions
into `composer.lock`.
### Options ### Options
@ -44,7 +54,9 @@ This will resolve all dependencies of the project and write the exact versions i
## search ## search
The search command allows you to search through the current project's package repositories. Usually this will be just packagist. You simply pass it the terms you want to search for. The search command allows you to search through the current project's package
repositories. Usually this will be just packagist. You simply pass it the
terms you want to search for.
$ php composer.phar search monolog $ php composer.phar search monolog
@ -56,7 +68,8 @@ To list all of the available packages, you can use the `show` command.
$ php composer.phar show $ php composer.phar show
If you want to see the details of a certain package, you can pass the package name. If you want to see the details of a certain package, you can pass the package
name.
$ php composer.phar show monolog/monolog $ php composer.phar show monolog/monolog
@ -75,7 +88,8 @@ If you want to see the details of a certain package, you can pass the package na
requires requires
php >=5.3.0 php >=5.3.0
You can even pass the package version, which will tell you the details of that specific version. You can even pass the package version, which will tell you the details of that
specific version.
$ php composer.phar show monolog/monolog 1.0.2 $ php composer.phar show monolog/monolog 1.0.2
@ -86,7 +100,9 @@ You can even pass the package version, which will tell you the details of that s
## depends ## depends
The `depends` command tells you which other packages depend on a certain package. You can specify which link types (`require`, `recommend`, `suggest`) should be included in the listing. The `depends` command tells you which other packages depend on a certain
package. You can specify which link types (`require`, `recommend`, `suggest`)
should be included in the listing.
$ php composer.phar depends --link-type=require monolog/monolog $ php composer.phar depends --link-type=require monolog/monolog
@ -98,17 +114,21 @@ The `depends` command tells you which other packages depend on a certain package
### Options ### Options
* **--link-type:** The link types to match on, can be specified multiple times. * **--link-type:** The link types to match on, can be specified multiple
times.
## validate ## validate
You should always run the `validate` command before you commit your `composer.json` file, and before you tag a release. It will check if your `composer.json` is valid. You should always run the `validate` command before you commit your
`composer.json` file, and before you tag a release. It will check if your
`composer.json` is valid.
$ php composer.phar validate $ php composer.phar validate
## self-update ## self-update
To update composer itself to the latest version, just run the `self-update` command. It will replace your `composer.phar` with the latest version. To update composer itself to the latest version, just run the `self-update`
command. It will replace your `composer.phar` with the latest version.
$ php composer.phar self-update $ php composer.phar self-update

142
doc/04-schema.md
View File

@ -4,7 +4,11 @@ This chapter will explain all of the options available in `composer.json`.
## JSON schema ## JSON schema
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: [`Resources/composer-schema.json`](https://github.com/composer/composer/blob/docs/Resources/composer-schema.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: [`Resources/composer-
schema.json`](https://github.com/composer/composer/blob/docs/Resources
/composer-schema.json).
## Package root ## Package root
@ -12,7 +16,8 @@ The root of the package definition is a JSON object.
## name ## name
The name of the package. It consists of vendor name and project name, separated by `/`. The name of the package. It consists of vendor name and project name,
separated by `/`.
Examples: Examples:
@ -31,7 +36,8 @@ Optional but recommended.
The version of the package. The version of the package.
This must follow the format of `X.Y.Z` with an optional suffix of `-dev`, `alphaN`, `-betaN` or `-RCN`. This must follow the format of `X.Y.Z` with an optional suffix of `-dev`,
`alphaN`, `-betaN` or `-RCN`.
Examples: Examples:
@ -43,24 +49,36 @@ Examples:
1.0.0-beta2 1.0.0-beta2
1.0.0-RC5 1.0.0-RC5
Optional if the package repository can infer the version from somewhere, such as the VCS tag name in the VCS repository. In that case it is also recommended to omit it. Optional if the package repository can infer the version from somewhere, such
as the VCS tag name in the VCS repository. In that case it is also recommended
to omit it.
## type ## type
The type of the package. It defaults to `library`. 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. 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.
Out of the box, composer supports two types: Out of the box, composer supports two types:
* **library:** This is the default. It will simply copy the files to `vendor`. * **library:** This is the default. It will simply copy the files to `vendor`.
* **composer-installer:** A package of type `composer-installer` provides an installer for other packages that have a custom type. Symfony could supply a `symfony/bundle-installer` package, which every bundle would depend on. Whenever you install a bundle, it will fetch the installer and register it, in order to be able to install the bundle. * **composer-installer:** A package of type `composer-installer` provides an
installer for other packages that have a custom type. Symfony could supply a
`symfony/bundle-installer` package, which every bundle would depend on.
Whenever you install a bundle, it will fetch the installer and register it, in
order to be able to install the bundle.
Only use a custom type if you need custom logic during installation. It is recommended to omit this field and have it just default to `library`. Only use a custom type if you need custom logic during installation. It is
recommended to omit this field and have it just default to `library`.
## keywords ## keywords
An array of keywords that the package is related to. These can be used for searching and filtering. An array of keywords that the package is related to. These can be used for
searching and filtering.
Examples: Examples:
@ -142,10 +160,17 @@ Each of these takes an object which maps package names to version constraints.
* **require:** Packages required by this package. * **require:** Packages required by this package.
* **recommend:** Recommended packages, installed by default. * **recommend:** Recommended packages, installed by default.
* **suggest:** Suggested packages. These are displayed after installation, but not installed by default. * **suggest:** Suggested packages. These are displayed after installation,
* **conflict:** Mark this version of this package as conflicting with other packages. but not installed by default.
* **replace:** Packages that can be replaced by this package. This is useful for large repositories with subtree splits. It allows the main package to replace all of it's child packages. * **conflict:** Mark this version of this package as conflicting with other
* **provide:** List of other packages that are provided by this package. This is mostly useful for common interfaces. A package could depend on some virtual `logger` package, any library that provides this logger, would simply list it in `provide`. packages.
* **replace:** Packages that can be replaced by this package. This is useful
for large repositories with subtree splits. It allows the main package to
replace all of it's child packages.
* **provide:** List of other packages that are provided by this package. This
is mostly useful for common interfaces. A package could depend on some virtual
`logger` package, any library that provides this logger, would simply list it
in `provide`.
Example: Example:
@ -163,7 +188,10 @@ Optional.
Autoload mapping for a PHP autoloader. Autoload mapping for a PHP autoloader.
Currently only [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) autoloading is supported. Under the `psr-0` key you define a mapping from namespaces to paths, relative to the package root. Currently only [PSR-0](https://github.com/php-fig/fig-
standards/blob/master/accepted/PSR-0.md) autoloading is supported. Under the
`psr-0` key you define a mapping from namespaces to paths, relative to the
package root.
Example: Example:
@ -181,9 +209,15 @@ Optional, but it is highly recommended that you follow PSR-0 and use this.
Defines the installation target. Defines the installation target.
In case the package root is below the namespace declaration you cannot autoload properly. `target-dir` solves this problem. In case the package root is below the namespace declaration you cannot
autoload properly. `target-dir` solves this problem.
An example is Symfony. There are individual packages for the components. The Yaml component is under `Symfony\Component\Yaml`. The package root is that `Yaml` directory. To make autoloading possible, we need to make sure that it is not installed into `vendor/symfony/yaml`, but instead into `vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load it from `vendor/symfony/yaml`. An example is Symfony. There are individual packages for the components. The
Yaml component is under `Symfony\Component\Yaml`. The package root is that
`Yaml` directory. To make autoloading possible, we need to make sure that it
is not installed into `vendor/symfony/yaml`, but instead into
`vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load
it from `vendor/symfony/yaml`.
To do that, `autoload` and `target-dir` are defined as follows: To do that, `autoload` and `target-dir` are defined as follows:
@ -202,16 +236,26 @@ Optional.
Custom package repositories to use. Custom package repositories to use.
By default composer just uses the packagist repository. By specifying repositories you can get packages from elsewhere. By default composer just uses the packagist repository. By specifying
repositories you can get packages from elsewhere.
Repositories are not resolved recursively. You can only add them to your main `composer.json`. Repository declarations of dependencies' `composer.json`s are ignored. 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: 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 `dist` and/or `source` information. * **composer:** A composer repository is simply a `packages.json` file served
* **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. via HTTP that contains a list of `composer.json` objects with additional
* **pear:** With this you can import any pear repository into your composer project. `dist` and/or `source` information.
* **package:** If you depend on a project that does not have any support for composer whatsoever you can define the package inline using a `package` repository. You basically just inline the `composer.json` object. * **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.
* **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
composer whatsoever you can define the package inline using a `package`
repository. You basically just inline the `composer.json` object.
For more information on any of these, see [Repositories]. For more information on any of these, see [Repositories].
@ -252,9 +296,12 @@ Example:
} }
``` ```
> **Note:** Order is significant here. Repositories added later will take precedence. This also means that custom repositories can override packages that exist on packagist. > **Note:** Order is significant here. Repositories added later will take
precedence. This also means that custom repositories can override packages
that exist on packagist.
You can also disable the packagist repository by setting `packagist` to `false`. You can also disable the packagist repository by setting `packagist` to
`false`.
```json ```json
{ {
@ -272,8 +319,10 @@ A set of configuration options. It is only used for projects.
The following options are supported: The following options are supported:
* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a different directory if you want to. * **vendor-dir:** Defaults to `vendor`. You can install dependencies into a
* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they will be symlinked into this directory. different directory if you want to.
* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they
will be symlinked into this directory.
Example: Example:
@ -291,18 +340,29 @@ Composer allows you to hook into various parts of the installation process throu
These events are supported: These events are supported:
* **pre-install-cmd:** Occurs before the install command is executed, contains one or more Class::method callables. * **pre-install-cmd:** Occurs before the install command is executed, contains
* **post-install-cmd:** Occurs after the install command is executed, contains one or more Class::method callables. one or more Class::method callables.
* **pre-update-cmd:** Occurs before the update command is executed, contains one or more Class::method callables. * **post-install-cmd:** Occurs after the install command is executed, contains
* **post-update-cmd:** Occurs after the update command is executed, contains one or more Class::method callables. one or more Class::method callables.
* **pre-package-install:** Occurs before a package is installed, contains one or more Class::method callables. * **pre-update-cmd:** Occurs before the update command is executed, contains
* **post-package-install:** Occurs after a package is installed, contains one or more Class::method callables. one or more Class::method callables.
* **pre-package-update:** Occurs before a package is updated, contains one or more Class::method callables. * **post-update-cmd:** Occurs after the update command is executed, contains
* **post-package-update:** Occurs after a package is updated, contains one or more Class::method callables. one or more Class::method callables.
* **pre-package-uninstall:** Occurs before a package has been uninstalled, contains one or more Class::method callables. * **pre-package-install:** Occurs before a package is installed, contains one
* **post-package-uninstall:** Occurs after a package has been uninstalled, contains one or more Class::method callables. or more Class::method callables.
* **post-package-install:** Occurs after a package is installed, contains one
or more Class::method callables.
* **pre-package-update:** Occurs before a package is updated, contains one or
more Class::method callables.
* **post-package-update:** Occurs after a package is updated, contains one or
more Class::method callables.
* **pre-package-uninstall:** Occurs before a package has been uninstalled,
contains one or more Class::method callables.
* **post-package-uninstall:** Occurs after a package has been uninstalled,
contains one or more Class::method callables.
For each of these events you can provide a static method on a class that will handle it. For each of these events you can provide a static method on a class that will
handle it.
Example: Example:
@ -316,7 +376,9 @@ Example:
} }
``` ```
The event handler receives a `Composer\Script\Event` object as an argument, which gives you access to the `Composer\Composer` instance through the `getComposer` method. The event handler receives a `Composer\Script\Event` object as an argument,
which gives you access to the `Composer\Composer` instance through the
`getComposer` method.
```php ```php
namespace Acme; namespace Acme;
@ -336,7 +398,8 @@ class ScriptHandler
Arbitrary extra data for consumption by `scripts`. Arbitrary extra data for consumption by `scripts`.
This can be virtually anything. To access it from within a script event handler, you can do: This can be virtually anything. To access it from within a script event
handler, you can do:
```php ```php
$extra = $event->getComposer()->getPackage()->getExtra(); $extra = $event->getComposer()->getPackage()->getExtra();
@ -346,7 +409,8 @@ Optional.
## bin ## bin
A set of files that should be treated as binaries and symlinked into the `bin-dir` (from config). A set of files that should be treated as binaries and symlinked into the `bin-
dir` (from config).
See [faq/bin.md] for more details. See [faq/bin.md] for more details.

77
doc/05-repositories.md
View File

@ -1,36 +1,56 @@
# Repositories # Repositories
This chapter will explain the concept of packages and repositories, what kinds of repositories are available, and how they work. This chapter will explain the concept of packages and repositories, what kinds
of repositories are available, and how they work.
## Concepts ## 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 we can have, we
need to understand some of the basic concepts that composer is built on.
### Package ### Package
Composer is a dependency manager. It installs packages. 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 to identify the package. Composer is a dependency manager. It installs packages. 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
to identify the package.
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 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 package. And there are two options here: dist and source. 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
package. And there are two options here: dist and source.
**Dist:** The dist is a packaged version of the package data. Usually a released version, usually a stable release. **Dist:** The dist is a packaged version of the package data. Usually a
released version, usually a stable release.
**Source:** The source is used for development. This will usually originate from a source code repository, such as git. You can fetch this when you want to modify the downloaded package. **Source:** The source is used for development. This will usually originate
from a source code repository, such as git. You can fetch this when you want
to modify the downloaded package.
Packages can supply either of these, or even both. Depending on certain factors, such as user-supplied options and stability of the package, one will be preferred. Packages can supply either of these, or even both. Depending on certain
factors, such as user-supplied options and stability of the package, one will
be preferred.
### Repository ### Repository
A repository is a package source. It's a list of packages, of which you can pick some to install. A repository is a package source. It's a list of packages, of which you can
pick some to install.
You can also add more repositories to your project by declaring them in `composer.json`. You can also add more repositories to your project by declaring them in
`composer.json`.
## Types ## Types
### Composer ### 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: 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:
```json ```json
{ {
@ -45,7 +65,8 @@ The main repository type is the `composer` repository. It uses a single `package
} }
``` ```
The `@composer.json` marker would be the contents of the `composer.json` from that package version including as a minimum: The `@composer.json` marker would be the contents of the `composer.json` from
that package version including as a minimum:
* name * name
* version * version
@ -66,13 +87,27 @@ Here is a minimal package definition:
It may include any of the other fields specified in the [schema]. It may include any of the other fields specified in the [schema].
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.org` the repository URL would be `http://example.org`. 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.org` the repository URL would be
`http://example.org`.
### VCS ### VCS
VCS stands for version control system. This includes versioning systems like git, svn or hg. Composer has a repository type for installing packages from these systems. VCS stands for version control system. This includes versioning systems like
git, svn or hg. Composer has a repository type for installing packages from
these systems.
There are a few use cases for this. The most common one is maintaining your own fork of a third party library. If you are using a certain library for your project and you decide to change something in the library, you will want your project to use the patched version. If the library is on GitHub (this is the case most of the time), you can simply fork it there and push your changes to your fork. After that you update the project's `composer.json`. All you have to do is add your fork as a repository and update the version constraint to point to your custom branch. There are a few use cases for this. The most common one is maintaining your
own fork of a third party library. If you are using a certain library for your
project and you decide to change something in the library, you will want your
project to use the patched version. If the library is on GitHub (this is the
case most of the time), you can simply fork it there and push your changes to
your fork. After that you update the project's `composer.json`. All you have
to do is add your fork as a repository and update the version constraint to
point to your custom branch.
Example assuming you patched monolog to fix a bug in the `bugfix` branch: Example assuming you patched monolog to fix a bug in the `bugfix` branch:
@ -90,15 +125,21 @@ Example assuming you patched monolog to fix a bug in the `bugfix` branch:
} }
``` ```
When you run `php composer.phar update`, you should get your modified version of `monolog/monolog` instead of the one from packagist. When you run `php composer.phar update`, you should get your modified version
of `monolog/monolog` instead of the one from packagist.
Git is not the only version control system supported by the VCS repository. The following are supported: Git is not the only version control system supported by the VCS repository.
The following are supported:
* **Git:** [git-scm.com](http://git-scm.com) * **Git:** [git-scm.com](http://git-scm.com)
* **Subversion:** [subversion.apache.org](http://subversion.apache.org) * **Subversion:** [subversion.apache.org](http://subversion.apache.org)
* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) * **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 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.
* **GitHub:** [github.com](https://github.com) (Git) * **GitHub:** [github.com](https://github.com) (Git)
* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) * **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)