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

Merge pull request #367 from igorw/docs 

[docs] re-word some things, document env vars
pull/368/merge
Jordi Boggiano 2012-02-26 04:17:28 -08:00
parent d03fb4804c 672e7d85a1
commit 5f200db7b7
6 changed files with 96 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/00-intro.md
View File

@ -1,7 +1,7 @@
# 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.
the dependencies of your project and will install them for you.
## Dependency management
@ -45,7 +45,7 @@ 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.
your working directory. This file is the composer binary.
After that we run the command for installing all dependencies:

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

@ -9,10 +9,10 @@ To install composer, simply run this command on the command line:
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.
Then it 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
@ -94,9 +94,9 @@ 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.
> **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.
@ -145,7 +145,7 @@ this file and you will get autoloading for free.
require 'vendor/.composer/autoload.php';
```
This makes it really easy to use third party code, because you really just
This makes it really easy to use third party code, because you only
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.
@ -157,7 +157,7 @@ $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
You can even add your own code to the autoloader by adding an `autoload` field
to `composer.json`.
```json
@ -170,14 +170,14 @@ to `composer.json`.
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.
containing an `Acme\Foo` class.
After adding the `autoload` key, you have to re-run `install` to re-generate
After adding the `autoload` field, 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 store
the return value of the include call in a variable and add more namespaces.
This can be useful for autoloading classes in a test suite, for example.
```php
$loader = require 'vendor/.composer/autoload.php';

51
doc/03-cli.md
View File

@ -30,10 +30,20 @@ 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.
* **--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
@ -115,7 +125,7 @@ should be included in the listing.
### Options
* **--link-type:** The link types to match on, can be specified multiple
times.
times.
## validate
@ -137,3 +147,34 @@ command. It will replace your `composer.phar` with the latest version.
To get more information about a certain command, just use `help`.
$ php composer.phar help install
## Environment variables
You can set a number of environment variables that override certain settings.
Whenever possible it is recommended to specify these settings in the `config`
section of `composer.json` instead. It is worth noting that that the env vars
will always take precedence over the values specified in `composer.json`.
### COMPOSER
By setting the `COMPOSER` env variable is is possible to set the filename of
`composer.json` to something else.
For example:
$ COMPOSER=composer-other.json php composer.phar install
### COMPOSER_VENDOR_DIR
By setting this option you can make composer install the dependencies into a
directory other than `vendor`.
### COMPOSER_BIN_DIR
By setting this option you can change the `bin` ([articles/vendor-bins.md])
directory to something other than `vendor/bin`.
### COMPOSER_PROCESS_TIMEOUT
This env var controls the time composer waits for commands (such as git
commands) to finish executing. The default value is 60 seconds.

22
doc/04-schema.md
View File

@ -6,7 +6,7 @@ This chapter will explain all of the options available in `composer.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:
`validate` command. You can find it at:
[`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json).
## Package root
@ -58,9 +58,9 @@ 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.
`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types 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:
@ -242,14 +242,13 @@ 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:
The 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
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.
svn and hg repositories.
* **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
@ -335,7 +334,8 @@ Example:
## scripts
Composer allows you to hook into various parts of the installation process through the use of scripts.
Composer allows you to hook into various parts of the installation process
through the use of scripts.
These events are supported:
@ -388,6 +388,8 @@ class ScriptHandler
{
static public function doSomething(Event $event)
{
$composer = $event->getComposer();
// custom logic
}
}
@ -411,6 +413,6 @@ Optional.
A set of files that should be treated as binaries and symlinked into the `bin-
dir` (from config).
See [articles/bin.md] for more details.
See [articles/vendor-bins.md] for more details.
Optional.

40
doc/05-repositories.md
View File

@ -5,12 +5,12 @@ 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 exist, 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
Composer is a dependency manager. It installs packages locally. 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
@ -20,9 +20,9 @@ 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
In addition to the name and the version, there is useful data. The information
most relevant for installation is the source definition, which 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
@ -135,11 +135,11 @@ The following are supported:
* **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 get packages from these systems you need to have their respective clients
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)
@ -177,12 +177,12 @@ In this case the short name of the channel is `pear2`, so the
### Package
If you want to use a project that does not support composer through any of the
means above, you still can define the package yourself using a `package`
means above, you still can define the package yourself by using a `package`
repository.
Basically, you define the same information that is included in the `composer`
repository's `packages.json`, but only for a single package. Again, the
minimally required fields are `name`, `version`, and either of `dist` or
minimum required fields are `name`, `version`, and either of `dist` or
`source`.
Here is an example for the smarty template engine:
@ -231,8 +231,7 @@ there are some use cases for hosting your own repository.
When hosting your own package repository it is recommended to use a `composer`
one. This is type that is native to composer and yields the best performance.
There are a few different tools that can help you create a `composer`
repository.
There are a few tools that can help you create a `composer` repository.
### Packagist
@ -251,13 +250,12 @@ github repository](https://github.com/composer/packagist).
### Satis
Satis is a static `composer` repository generator. It is a bit like a ultra-
lightweight, file-based version of packagist.
Satis is a static `composer` repository generator. It is a bit like an ultra-
lightweight, static file-based version of packagist.
You give it a `composer.json` containing repositories, typically VCS and package
repository definitions. It will fetch all the packages that are `require`d from
these repositories and dump a `packages.json` that is your `composer`
repository.
You give it a `composer.json` containing repositories, typically VCS and
package repository definitions. It will fetch all the packages that are
`require`d and dump a `packages.json` that is your `composer` repository.
Check [the satis GitHub repository](https://github.com/composer/satis) for more
information.

6
doc/06-community.md
View File

@ -1,7 +1,7 @@
# Community
We have a lot of people using composer, and also many contributors to the
project.
There are a lot of people using composer already, quite a few are also already
contributing.
## Contributing
@ -22,7 +22,7 @@ The most important guidelines are described as follows:
## IRC / mailing list
The developer mailing list is on [google groups](http://groups.google.com/group/composer-dev/)
The developer mailing list is on [google groups](http://groups.google.com/group/composer-dev/)
IRC channels are available for discussion as well, on
irc.freenode.org [#composer](irc://irc.freenode.org/composer) for users and
[#composer-dev](irc://irc.freenode.org/composer-dev) for development.