From c42e37037a3de7ab2ba0c4d30a55cd4f476f7ef1 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Mon, 20 Feb 2012 11:08:18 +0100 Subject: [PATCH] [docs] wrap all lines to 80 chars --- doc/01-basic-usage.md | 58 +++++++++++------ doc/02-libraries.md | 89 +++++++++++++++++++------- doc/03-cli.md | 50 ++++++++++----- doc/04-schema.md | 142 ++++++++++++++++++++++++++++++----------- doc/05-repositories.md | 77 ++++++++++++++++------ 5 files changed, 304 insertions(+), 112 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index d483daa51..5c17048e9 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -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. -> **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 ## 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. 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. * **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: - `>=1.0,<2.0`. + versions. Valid operators are `>`, `>=`, `<`, `<=`. An example range would be + `>=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 @@ -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 code to your repository. -Another thing that the `install` command does is it adds a `composer.lock` file -into your project root. +Another thing that the `install` command does is it adds a `composer.lock` +file into your project root. ## Lock file @@ -119,22 +122,33 @@ also update the lock file. ## 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 -For libraries that follow the [PSR-0](https://github.com/php-fig/fig-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. +For libraries that follow the [PSR-0](https://github.com/php-fig/fig- +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 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 $log = new Monolog\Logger('name'); @@ -143,7 +157,8 @@ $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 to `composer.json`. +You can even add your own code to the autoloader by adding an `autoload` key +to `composer.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 $loader = require 'vendor/.composer/autoload.php'; $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. diff --git a/doc/02-libraries.md b/doc/02-libraries.md index 28b1dc2e8..adfe88c91 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -4,9 +4,13 @@ This chapter will tell you how to make your library installable through composer ## 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 { @@ -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 -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: @@ -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 -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: @@ -52,7 +64,11 @@ Here are a few examples of valid tag names: ### 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: @@ -61,11 +77,16 @@ Here are some examples of version branch names: 1.1.x 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 -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.** @@ -73,9 +94,16 @@ If you are using git, add it to the `.gitignore`. ## 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 { @@ -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 { @@ -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 -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. diff --git a/doc/03-cli.md b/doc/03-cli.md index 56989c466..99b507deb 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -1,24 +1,32 @@ # 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 -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 ## 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 -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 @@ -29,11 +37,13 @@ If there is no `composer.lock` file, composer will create one after dependency r ## 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 -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 @@ -44,7 +54,9 @@ This will resolve all dependencies of the project and write the exact versions i ## 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 @@ -56,7 +68,8 @@ To list all of the available packages, you can use the `show` command. $ 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 @@ -75,7 +88,8 @@ If you want to see the details of a certain package, you can pass the package na requires 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 @@ -86,7 +100,9 @@ You can even pass the package version, which will tell you the details of that s ## 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 @@ -98,17 +114,21 @@ The `depends` command tells you which other packages depend on a certain package ### 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 -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 ## 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 diff --git a/doc/04-schema.md b/doc/04-schema.md index b48c5f798..2c9383ee3 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -4,7 +4,11 @@ This chapter will explain all of the options available in `composer.json`. ## 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 @@ -12,7 +16,8 @@ The root of the package definition is a JSON object. ## 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: @@ -31,7 +36,8 @@ Optional but recommended. 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: @@ -43,24 +49,36 @@ Examples: 1.0.0-beta2 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 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: * **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 -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: @@ -142,10 +160,17 @@ Each of these takes an object which maps package names to version constraints. * **require:** Packages required by this package. * **recommend:** Recommended packages, installed by default. -* **suggest:** Suggested packages. These are displayed after installation, but not installed by default. -* **conflict:** Mark this version of this package as conflicting with other 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`. +* **suggest:** Suggested packages. These are displayed after installation, + but not installed by default. +* **conflict:** Mark this version of this package as conflicting with other + 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: @@ -163,7 +188,10 @@ Optional. 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: @@ -181,9 +209,15 @@ Optional, but it is highly recommended that you follow PSR-0 and use this. 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: @@ -202,16 +236,26 @@ Optional. 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: -* **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. -* **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. +* **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. +* **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]. @@ -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 { @@ -272,8 +319,10 @@ A set of configuration options. It is only used for projects. The following options are supported: -* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a different directory if you want to. -* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they will be symlinked into this directory. +* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a + 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: @@ -291,18 +340,29 @@ Composer allows you to hook into various parts of the installation process throu These events are supported: -* **pre-install-cmd:** Occurs before the install command is executed, contains one or more Class::method callables. -* **post-install-cmd:** Occurs after the install command is executed, contains one or more Class::method callables. -* **pre-update-cmd:** Occurs before the update command is executed, contains one or more Class::method callables. -* **post-update-cmd:** Occurs after the update command is executed, contains one or more Class::method callables. -* **pre-package-install:** Occurs before a package is installed, contains one 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. +* **pre-install-cmd:** Occurs before the install command is executed, contains + one or more Class::method callables. +* **post-install-cmd:** Occurs after the install command is executed, contains + one or more Class::method callables. +* **pre-update-cmd:** Occurs before the update command is executed, contains + one or more Class::method callables. +* **post-update-cmd:** Occurs after the update command is executed, contains + one or more Class::method callables. +* **pre-package-install:** Occurs before a package is installed, contains one + 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: @@ -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 namespace Acme; @@ -336,7 +398,8 @@ class ScriptHandler 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 $extra = $event->getComposer()->getPackage()->getExtra(); @@ -346,7 +409,8 @@ Optional. ## 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. diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 3fb20f3a7..6c465cdff 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -1,36 +1,56 @@ # 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 -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 -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 -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 ### 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 { @@ -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 * version @@ -66,13 +87,27 @@ Here is a minimal package definition: 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 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: @@ -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) * **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 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) * **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)