hugo
/
composer
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #367 from igorw/docs

Browse Source 
[docs] re-word some things, document env vars
main
Jordi Boggiano 13 years ago
parent d03fb4804c 672e7d85a1
commit 5f200db7b7
6 changed files with 96 additions and 55 deletions
Show Stats Download Patch File Download Diff File

4
doc/00-intro.md
Unescape Escape View File

@ -1,7 +1,7 @@
# Introduction # Introduction
Composer is a tool for dependency management in PHP. It allows you to declare 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 ## Dependency management
@ -45,7 +45,7 @@ composer:
$ curl -s http://getcomposer.org/installer | php $ curl -s http://getcomposer.org/installer | php
This will just check a few PHP settings and then download `composer.phar` to 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: After that we run the command for installing all dependencies:

28
doc/01-basic-usage.md
Unescape Escape 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 This will perform some checks on your environment to make sure you can
actually run it. actually run it.
This will download `composer.phar` and place it in your working directory. 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 `composer.phar` is the composer binary. It is a PHAR (PHP archive), which is
is an archive format for PHP which can be run on the command line, amongst an archive format for PHP which can be run on the command line, amongst other
other things. things.
You can place this file anywhere you wish. If you put it in your `PATH`, 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 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`. 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`. 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 > **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 > `vendor` into your `.gitignore`. You really don't want to add all of that
code to your repository. > code to your repository.
Another thing that the `install` command does is it adds a `composer.lock` Another thing that the `install` command does is it adds a `composer.lock`
file into your project root. file into your project root.
@ -145,7 +145,7 @@ this file and you will get autoloading for free.
require 'vendor/.composer/autoload.php'; 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 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 means that we can just start using classes from it, and they will be
autoloaded. autoloaded.
@ -157,7 +157,7 @@ $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Logger::WARNING))
$log->addWarning('Foo'); $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`. to `composer.json`.
```json ```json
@ -170,14 +170,14 @@ to `composer.json`.
This is a mapping from namespaces to directories. The `src` directory would be 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` 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. the `vendor/.composer/autoload.php` file.
Including that file will also return the autoloader instance, so you can add Including that file will also return the autoloader instance, so you can store
retrieve it and add more namespaces. This can be useful for autoloading the return value of the include call in a variable and add more namespaces.
classes in a test suite, for example. This can be useful for autoloading classes in a test suite, for example.
```php ```php
$loader = require 'vendor/.composer/autoload.php'; $loader = require 'vendor/.composer/autoload.php';

51
doc/03-cli.md
Unescape Escape View File

@ -30,10 +30,20 @@ resolution.
### Options ### 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. * **--prefer-source:** There are two ways of downloading a package: `source`
* **--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. and `dist`. For stable versions composer will use the `dist` by default.
* **--no-install-recommends:** By default composer will install all packages that are referenced by `recommend`. By passing this option you can disable that. The `source` is a version control repository. If `--prefer-source` is
* **--install-suggests:** The packages referenced by `suggest` will not be installed by default. By passing this option, you can install them. 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 ## update
@ -115,7 +125,7 @@ should be included in the listing.
### Options ### Options
* **--link-type:** The link types to match on, can be specified multiple * **--link-type:** The link types to match on, can be specified multiple
times. times.
## validate ## 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`. To get more information about a certain command, just use `help`.
$ php composer.phar help install $ 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.

20
doc/04-schema.md
Unescape Escape View File

@ -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 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 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 `symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will
specific to certain projects, and they will need to provide an installer all be specific to certain projects, and they will need to provide an
capable of installing packages of that type. installer capable of installing packages of that type.
Out of the box, composer supports two types: 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 `composer.json`. Repository declarations of dependencies' `composer.json`s are
ignored. ignored.
Following repository types are supported: The following repository types are supported:
* **composer:** A composer repository is simply a `packages.json` file served * **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. `dist` and/or `source` information.
* **vcs:** The version control system repository can fetch packages from git, * **vcs:** The version control system repository can fetch packages from git,
svn and hg repositories. Note the distinction between package repository and svn and hg repositories.
version control repository.
* **pear:** With this you can import any pear repository into your composer * **pear:** With this you can import any pear repository into your composer
project. project.
* **package:** If you depend on a project that does not have any support for * **package:** If you depend on a project that does not have any support for
@ -335,7 +334,8 @@ Example:
## scripts ## 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: These events are supported:
@ -388,6 +388,8 @@ class ScriptHandler
{ {
static public function doSomething(Event $event) static public function doSomething(Event $event)
{ {
$composer = $event->getComposer();
// custom logic // custom logic
} }
} }
@ -411,6 +413,6 @@ Optional.
A set of files that should be treated as binaries and symlinked into the `bin- A set of files that should be treated as binaries and symlinked into the `bin-
dir` (from config). dir` (from config).
See [articles/bin.md] for more details. See [articles/vendor-bins.md] for more details.
Optional. Optional.

40
doc/05-repositories.md
Unescape Escape View File

@ -5,12 +5,12 @@ of repositories are available, and how they work.
## Concepts ## Concepts
Before we look at the different types of repositories that we can have, we Before we look at the different types of repositories that exist, we need to
need to understand some of the basic concepts that composer is built on. understand some of the basic concepts that composer is built on.
### Package ### 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 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 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 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 this distinction does not matter when you are using composer, it's quite
important when you want to change it. important when you want to change it.
In addition to the name and the version, there is useful data. The only really In addition to the name and the version, there is useful data. The information
important piece of information is the package source, that describes where to most relevant for installation is the source definition, which describes where
get the package contents. The package data points to the contents of the to get the package contents. The package data points to the contents of the
package. And there are two options here: dist and source. package. And there are two options here: dist and source.
**Dist:** The dist is a packaged version of the package data. Usually a **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) * **Subversion:** [subversion.apache.org](http://subversion.apache.org)
* **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com) * **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com)
To use these systems you need to have them installed. That can be To get packages from these systems you need to have their respective clients
invonvenient. And for this reason there is special support for GitHub and installed. That can be invonvenient. And for this reason there is special
BitBucket that use the APIs provided by these sites, to fetch the packages support for GitHub and BitBucket that use the APIs provided by these sites, to
without having to install the version control system. The VCS repository fetch the packages without having to install the version control system. The
provides `dist`s for them that fetch the packages as zips. VCS repository provides `dist`s for them that fetch the packages as zips.
* **GitHub:** [github.com](https://github.com) (Git) * **GitHub:** [github.com](https://github.com) (Git)
* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial) * **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 ### Package
If you want to use a project that does not support composer through any of the 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. repository.
Basically, you define the same information that is included in the `composer` Basically, you define the same information that is included in the `composer`
repository's `packages.json`, but only for a single package. Again, the 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`. `source`.
Here is an example for the smarty template engine: 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` 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. 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` There are a few tools that can help you create a `composer` repository.
repository.
### Packagist ### Packagist
@ -251,13 +250,12 @@ github repository](https://github.com/composer/packagist).
### Satis ### Satis
Satis is a static `composer` repository generator. It is a bit like a ultra- Satis is a static `composer` repository generator. It is a bit like an ultra-
lightweight, file-based version of packagist. lightweight, static file-based version of packagist.
You give it a `composer.json` containing repositories, typically VCS and package You give it a `composer.json` containing repositories, typically VCS and
repository definitions. It will fetch all the packages that are `require`d from package repository definitions. It will fetch all the packages that are
these repositories and dump a `packages.json` that is your `composer` `require`d and dump a `packages.json` that is your `composer` repository.
repository.
Check [the satis GitHub repository](https://github.com/composer/satis) for more Check [the satis GitHub repository](https://github.com/composer/satis) for more
information. information.

4
doc/06-community.md
Unescape Escape View File

@ -1,7 +1,7 @@
# Community # Community
We have a lot of people using composer, and also many contributors to the There are a lot of people using composer already, quite a few are also already
project. contributing.
## Contributing ## Contributing

Write Preview
Loading…
Cancel
Save