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

Merge pull request #319 from igorw/docs 

WIP: Docs
pull/336/head
Nils Adermann 2012-02-20 02:08:58 -08:00
parent 03a9e0dfee c42e37037a
commit 841f64335a
8 changed files with 1148 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/composer-schema.json → Resources/composer-schema.json
View File

@ -136,49 +136,56 @@
"description": "A set of additional repositories where packages can be found.",
"additionalProperties": true
},
"bin": {
"type": ["array"],
"description": "A set of files that should be treated as binaries and symlinked into bin-dir (from config).",
"items": {
"type": "string"
}
},
"scripts": {
"type": ["object"],
"description": "Scripts listeners that will be executed before/after some events.",
"properties": {
"pre-install-cmd": {
"type": ["array", "string"],
"description": "Occurs before the install command is executed, contains one or more Class::method callables.",
"description": "Occurs before the install command is executed, contains one or more Class::method callables."
},
"post-install-cmd": {
"type": ["array", "string"],
"description": "Occurs after the install command is executed, contains one or more Class::method callables.",
"description": "Occurs after the install command is executed, contains one or more Class::method callables."
},
"pre-update-cmd": {
"type": ["array", "string"],
"description": "Occurs before the update command is executed, contains one or more Class::method callables.",
"description": "Occurs before the update command is executed, contains one or more Class::method callables."
},
"post-update-cmd": {
"type": ["array", "string"],
"description": "Occurs after the update command is executed, contains one or more Class::method callables.",
"description": "Occurs after the update command is executed, contains one or more Class::method callables."
},
"pre-package-install": {
"type": ["array", "string"],
"description": "Occurs before a package is installed, contains one or more Class::method callables.",
"description": "Occurs before a package is installed, contains one or more Class::method callables."
},
"post-package-install": {
"type": ["array", "string"],
"description": "Occurs after a package is installed, contains one or more Class::method callables.",
"description": "Occurs after a package is installed, contains one or more Class::method callables."
},
"pre-package-update": {
"type": ["array", "string"],
"description": "Occurs before a package is updated, contains one or more Class::method callables.",
"description": "Occurs before a package is updated, contains one or more Class::method callables."
},
"post-package-update": {
"type": ["array", "string"],
"description": "Occurs after a package is updated, contains one or more Class::method callables.",
"description": "Occurs after a package is updated, contains one or more Class::method callables."
},
"pre-package-uninstall": {
"type": ["array", "string"],
"description": "Occurs before a package has been uninstalled, contains one or more Class::method callables.",
"description": "Occurs before a package has been uninstalled, contains one or more Class::method callables."
},
"post-package-uninstall": {
"type": ["array", "string"],
"description": "Occurs after a package has been uninstalled, contains one or more Class::method callables.",
"description": "Occurs after a package has been uninstalled, contains one or more Class::method callables."
}
}
}

65
doc/00-intro.md Normal file
View File

@ -0,0 +1,65 @@
# Introduction
Composer is a tool for dependency management in PHP. It allows you to declare
the dependencies of your project and will install these dependencies for you.
## Dependency management
One important distinction to make is that composer is not a package manager. It
deals with packages, but it manages them on a per-project basis. By default it
will never install anything globally. Thus, it is a dependency manager.
This idea is not new by any means. Composer is strongly inspired by
node's [npm](http://npmjs.org/) and ruby's [bundler](http://gembundler.com/).
But there has not been such a tool for PHP so far.
The problem that composer solves is the following. You have a project that
depends on a number of libraries. Some of libraries have dependencies of their
own. You declare the things you depend on. Composer will then go ahead and
find out which versions of which packages need to be installed, and install
them.
## Declaring dependencies
Let's say you are creating a project, and you need a library that does logging.
You decide to use [monolog](https://github.com/Seldaek/monolog). In order to
add it to your project, all you need to do is create a `composer.json` file
which describes the project's dependencies.
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
We are simply stating that our project requires the `monolog/monolog` package,
any version beginning with `1.0`.
## Installation
To actually get it, we need to do two things. The first one is installing
composer:
$ curl -s http://getcomposer.org/installer | php
This will just check a few PHP settings and then download `composer.phar` to
your working directory. This is the composer binary.
After that we run the command for installing all dependencies:
$ php composer.phar install
This will download monolog and dump it into `vendor/monolog/monolog`.
## Autoloading
After this you can just add the following line to your bootstrap code to get
autoloading:
```php
require 'vendor/.composer/autoload.php';
```
That's all it takes to have a basic setup.

189
doc/01-basic-usage.md Normal file
View File

@ -0,0 +1,189 @@
# Basic usage
## Installation
To install composer, simply run this command on the command line:
$ curl -s http://getcomposer.org/installer | php
This will perform some checks on your environment to make sure you can
actually run it.
This will download `composer.phar` and place it in your working directory.
`composer.phar` is the composer binary. It is a PHAR (PHP archive), which
is an archive format for PHP which can be run on the command line, amongst
other things.
You can place this file anywhere you wish. If you put it in your `PATH`,
you can access it globally. On unixy systems you can even make it
executable and invoke it without `php`.
To check if composer is working, just run the PHAR through `php`:
$ php composer.phar
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`.
>
> $ 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
other metadata as well.
The [JSON format](http://json.org/) is quite easy to write. It allows you to
define nested structures.
The first (and often only) thing you specify in `composer.json` is the
`require` key. You're simply telling composer which packages your project
depends on.
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
As you can see, `require` takes an object that maps package names to versions.
## Package names
The package name consists of a vendor name and the project's name. Often these
will be identical. The vendor name exists to prevent naming clashes. It allows
two different people to create a library named `json`, which would then just be
named `igorw/json` and `seldaek/json`.
Here we are requiring `monolog/monolog`, so the vendor name is the same as the
project's name. For projects with a unique name this is recommended. It also
allows adding more related projects under the same namespace later on. If you
are maintaining a library, this would make it really easy to split it up into
smaller decoupled parts.
## Package versions
We are also requiring the version `1.0.*` of monolog. This means any version
in the `1.0` development branch. It would match `1.0.0`, `1.0.2` and `1.0.20`.
Version constraints can be specified in a few different ways.
* **Exact version:** You can specify the exact version of a package, for
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`.
* **Wildcard:** You can specify a pattern with a `*` wildcard. `1.0.*` is the
equivalent of `>=1.0,<1.1-dev`.
## Installing dependencies
To fetch the defined dependencies into the local project, you simply run the
`install` command of `composer.phar`.
$ php composer.phar install
This will find the latest version of `monolog/monolog` that matches the
supplied version constraint and download it into the the `vendor` directory.
It's a convention to put third party code into a directory named `vendor`.
In case of monolog it will put it into `vendor/monolog/monolog`.
**Tip:** If you are using git for your project, you probably want to add
`vendor` into your `.gitignore`. You really don't want to add all of that
code to your repository.
Another thing that the `install` command does is it adds a `composer.lock`
file into your project root.
## Lock file
After installing the dependencies, composer writes the list of the exact
versions it installed into a `composer.lock` file. This locks the project
to those specific versions.
**Commit your project's `composer.lock` into version control.**
The reason is that anyone who sets up the project should get the same version.
The `install` command will check if a lock file is present. If it is, it will
use the versions specified there. If not, it will resolve the dependencies and
create a lock file.
If any of the dependencies gets a new version, you can update to that version
by using the `update` command. This will fetch the latest matching versions and
also update the lock file.
$ php composer.phar update
## 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.
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.
## 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.
```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.
```php
$log = new Monolog\Logger('name');
$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`.
```json
{
"autoload": {
"psr-0": {"Acme": "src/"}
}
}
```
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.
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.

168
doc/02-libraries.md Normal file
View File

@ -0,0 +1,168 @@
# Libraries
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.
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
{
"name": "acme/hello-world",
"require": {
"monolog/monolog": "1.0.*"
}
}
```
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.
## 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.
If you do want to specify it explicitly, you can just add a `version` field:
```json
{
"version": "1.0.0"
}
```
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.
Here are a few examples of valid tag names:
1.0.0
v1.0.0
1.10.5-RC1
v4.4.4beta2
v2.0.0-alpha
v2.0.4-p1
> **Note:** If you specify an explicit version in `composer.json`, the tag name must match the specified version.
### 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.
Here are some examples of version branch names:
1.0
1.*
1.1.x
1.1.*
> **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.
**Do not commit your library's `composer.lock` into version control.**
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`.
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
{
"name": "acme/blog",
"require": {
"acme/hello-world": "dev-master"
}
}
```
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`:
```json
{
"name": "acme/blog",
"repositories": {
"acme/hello-world": {
"vcs": { "url": "https://github.com/composer/hello-world" }
}
},
"require": {
"acme/hello-world": "dev-master"
}
}
```
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!
**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.
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.
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.

139
doc/03-cli.md Normal file
View File

@ -0,0 +1,139 @@
# 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.
## 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.
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`.
$ 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 no `composer.lock` file, composer will create one after dependency
resolution.
### Options
* **--prefer-source:** There are two ways of downloading a package: `source` and `dist`. For stable versions composer will use the `dist` by default. The `source` is a version control repository. If `--prefer-source` is enabled, composer will install from `source` if there is one. This is useful if you want to make a bugfix to a project and get a local git clone of the dependency directly.
* **--dry-run:** If you want to run through an installation without actually installing a package, you can use `--dry-run`. This will simulate the installation and show you what would happen.
* **--no-install-recommends:** By default composer will install all packages that are referenced by `recommend`. By passing this option you can disable that.
* **--install-suggests:** The packages referenced by `suggest` will not be installed by default. By passing this option, you can install them.
## update
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`.
### Options
* **--prefer-source:** Install packages from `source` when available.
* **--dry-run:** Simulate the command without actually doing anything.
* **--no-install-recommends:** Do not install packages referenced by `recommend`.
* **--install-suggests:** Install packages referenced by `suggest`.
## 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.
$ php composer.phar search monolog
You can also search for more than one term by passing multiple arguments.
## show
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.
$ php composer.phar show monolog/monolog
name : monolog/monolog
versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1
type : library
names : monolog/monolog
source : [git] http://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da
dist : [zip] http://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da
license : MIT
autoload
psr-0
Monolog : src/
requires
php >=5.3.0
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
### Options
* **--installed:** Will list the packages that are installed.
* **--platform:** Will list only [Platform packages].
## 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.
$ php composer.phar depends --link-type=require monolog/monolog
nrk/monolog-fluent
poc/poc
propel/propel
symfony/monolog-bridge
symfony/symfony
### Options
* **--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.
$ 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.
$ php composer.phar self-update
## help
To get more information about a certain command, just use `help`.
$ php composer.phar help install

417
doc/04-schema.md Normal file
View File

@ -0,0 +1,417 @@
# composer.json
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).
## Package root
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 `/`.
Examples:
* monolog/monolog
* igorw/event-source
Required for published packages (libraries).
## description
A short description of the package. Usually this is just one line long.
Optional but recommended.
## version
The version of the package.
This must follow the format of `X.Y.Z` with an optional suffix of `-dev`,
`alphaN`, `-betaN` or `-RCN`.
Examples:
1.0.0
1.0.2
1.1.0
0.2.5
1.0.0-dev
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.
## 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.
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.
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.
Examples:
logging
events
database
redis
templating
Optional.
## homepage
An URL to the website of the project.
Optional.
## time
Release date of the version.
Must be in `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` format.
Optional.
## license
The license of the package. This can be either a string or an array of strings.
The recommended notation for the most common licenses is:
MIT
BSD-2
BSD-3
BSD-4
GPLv2
GPLv3
LGPLv2
LGPLv3
Apache2
WTFPL
Optional, but it is highly recommended to supply this.
## authors
The authors of the package. This is an array of objects.
Each author object can have following properties:
* **name:** The author's name. Usually his real name.
* **email:** The author's email address.
* **homepage:** An URL to the author's website.
An example:
```json
{
"authors": [
{
"name": "Nils Adermann",
"email": "naderman@naderman.de",
"homepage": "http://www.naderman.de"
},
{
"name": "Jordi Boggiano",
"email": "j.boggiano@seld.be",
"homepage": "http://seld.be"
}
]
}
```
Optional, but highly recommended.
## Link types
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`.
Example:
```json
{
"require": {
"monolog/monolog": "1.0.*"
}
}
```
Optional.
## autoload
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.
Example:
```json
{
"autoload": {
"psr-0": { "Monolog": "src/" }
}
}
```
Optional, but it is highly recommended that you follow PSR-0 and use this.
## target-dir
Defines the installation target.
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`.
To do that, `autoload` and `target-dir` are defined as follows:
```json
{
"autoload": {
"psr-0": { "Symfony\\Component\\Yaml": "" }
},
"target-dir": "Symfony/Component/Yaml"
}
```
Optional.
## repositories
Custom package repositories to use.
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.
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.
For more information on any of these, see [Repositories].
Example:
```json
{
"repositories": [
{
"type": "composer",
"url": "http://packages.example.com"
},
{
"type": "vcs",
"url": "https://github.com/Seldaek/monolog"
},
{
"type": "pear",
"url": "http://pear2.php.net"
},
{
"type": "package",
"package": {
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
},
"source": {
"url": "http://smarty-php.googlecode.com/svn/",
"type": "svn",
"reference": "trunk"
}
}
}
]
}
```
> **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`.
```json
{
"repositories": [
{
"packagist": false
}
]
}
```
## config
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.
Example:
```json
{
"config": {
"bin-dir": "bin"
}
}
```
## scripts
Composer allows you to hook into various parts of the installation process through the use of scripts.
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.
For each of these events you can provide a static method on a class that will
handle it.
Example:
```json
{
"scripts": {
"post-install-cmd": [
"Acme\\ScriptHandler::doSomething"
]
}
}
```
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;
use Composer\Script\Event;
class ScriptHandler
{
static public function doSomething(Event $event)
{
// custom logic
}
}
```
## extra
Arbitrary extra data for consumption by `scripts`.
This can be virtually anything. To access it from within a script event
handler, you can do:
```php
$extra = $event->getComposer()->getPackage()->getExtra();
```
Optional.
## bin
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.
Optional.

153
doc/05-repositories.md Normal file
View File

@ -0,0 +1,153 @@
# Repositories
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.
### 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 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.
**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.
### Repository
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`.
## 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:
```json
{
"vendor/packageName": {
"name": "vendor/packageName",
"description": "Package description",
"versions": {
"master-dev": { @composer.json },
"1.0.0": { @composer.json }
}
}
}
```
The `@composer.json` marker would be the contents of the `composer.json` from
that package version including as a minimum:
* name
* version
* dist or source
Here is a minimal package definition:
```json
{
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
}
}
```
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`.
### 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.
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:
```json
{
"repositories": [
{
"type": "vcs",
"url": "http://github.com/igorw/monolog"
}
],
"require": {
"monolog/monolog": "dev-bugfix"
}
}
```
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:** [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.
* **GitHub:** [github.com](https://github.com) (Git)
* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)
The VCS driver to be used is detected automatically based on the URL.
### PEAR
### Package
## Hosting your own

0
doc/DefaultPolicy.md → doc/dev/DefaultPolicy.md
View File