Merge pull request #319 from igorw/docs

WIP: Docs

doc/composer-schema.json → Resources/composer-schema.json

@@ -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."
                 }
             }
         }

doc/00-intro.md

@@ -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.

doc/01-basic-usage.md

@@ -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.

doc/02-libraries.md

@@ -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.

doc/03-cli.md

@@ -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

doc/04-schema.md

@@ -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.

doc/05-repositories.md

@@ -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