[docs] re-word some things, document env vars
Igor Wiedler
parent
d03fb4804c
commit
672e7d85a1
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue