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

Merge pull request #452 from weaverryan/beginning-doc-changes 

Proofreading the first and second chapters of the very well-written docs
pull/424/merge
Jordi Boggiano 2012-03-15 05:57:55 -07:00
parent 30c880e5ff caf29268be
commit ac36d0c396
2 changed files with 84 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
doc/00-intro.md
View File

@ -1,23 +1,30 @@
# Introduction
Composer is a tool for dependency management in PHP. It allows you to declare
the dependencies of your project and will install them for you.
the dependent libraries your project needs and it will install them in your
project 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.
Composer is not a package manager. Yes, it deals with "packages" or libraries, but
it manages them on a per-project basis, installing them in a directory (e.g. `vendor`)
inside your project. 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.
This idea is not new and 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.
The problem that composer solves is the following. You have a project that
depends on a number of libraries. Some of those 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.
The problem that Composer solves is this:
a) You have a project that depends on a number of libraries.
b) Some of those libraries depend on other libraries .
c) You declare the things you depend on
d) Composer finds out which versions of which packages need to be installed, and
installs them (meaning it downloads them into your project).
## Declaring dependencies
@ -32,37 +39,50 @@ which describes the project's dependencies.
}
}
We are simply stating that our project requires the `monolog/monolog` package,
We are simply stating that our project requires some `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:
### 1) Downloading the Composer Executable
To actually get Composer, we need to do two things. The first one is installing
Composer (again, this mean downloading it into your project):
$ 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 file is the composer binary.
your working directory. This file 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 install composer to a specific directory by using the `--install-dir`
You can install Composer to a specific directory by using the `--install-dir`
option and providing a target directory (it can be an absolute or relative path):
$ curl -s http://getcomposer.org/installer | php -- --install-dir=bin
After that we run the command for installing all dependencies:
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`.
### 2) Using Composer
Next, run the command the `install` command to resolve and download dependencies:
$ php composer.phar install
This will download monolog and dump it into `vendor/monolog/monolog`.
This will download monolog into the `vendor/monolog/monolog` directory.
## Autoloading
After this you can just add the following line to your bootstrap code to get
autoloading:
Besides downloading the library, Composer also prepares an autoload file that's
capable of autoloading all of the classes in any of the libraries that it
downloads. To use it, just add the following line to your code's bootstrap
process:
require 'vendor/.composer/autoload.php';
That's all it takes to have a basic setup.
Woh! Now start using monolog! To keep learning more about Composer, keep
reading the "Basic Usage" chapter.
[Basic Usage](01-basic-usage.md) →

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

@ -2,49 +2,36 @@
## Installation
To install composer, simply run this command on the command line:
To install Composer, you just need to download the `composer.phar` executable.
$ curl -s http://getcomposer.org/installer | php
This will perform some checks on your environment to make sure you can
actually run it.
For the details, see the [Introduction](00-intro.md) chapter.
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
executable and invoke it without `php`.
You can install composer to a specific directory by using the `--install-dir`
option and providing a target directory (it can be an absolute or relative path):
$ curl -s http://getcomposer.org/installer | php -- --install-dir=bin
To check if composer is working, just run the PHAR through `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
> **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
## `composer.json`: Project Setup
To start using composer in your project, all you need is a `composer.json`
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 `require` Key
The first (and often only) thing you specify in `composer.json` is the
`require` key. You're simply telling composer which packages your project
`require` key. You're simply telling Composer which packages your project
depends on.
{
@ -53,12 +40,13 @@ depends on.
}
}
As you can see, `require` takes an object that maps package names to versions.
As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
to **package versions** (e.g. `1.0.*`).
## Package names
### 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
will be identical - the vendor name just 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`.
@ -68,10 +56,10 @@ 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
### 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`.
We are requiring version `1.0.*` of monolog. This means any version in the `1.0`
development branch. It would match `1.0.0`, `1.0.2` or `1.0.20`.
Version constraints can be specified in a few different ways.
@ -80,14 +68,14 @@ Version constraints can be specified in a few different ways.
* **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`.
`>=1.0`. You can define multiple ranges, separated by a 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
## Installing Dependencies
To fetch the defined dependencies into the local project, you simply run the
To fetch the defined dependencies into your local project, just run the
`install` command of `composer.phar`.
$ php composer.phar install
@ -104,29 +92,33 @@ In case of monolog it will put it into `vendor/monolog/monolog`.
Another thing that the `install` command does is it adds a `composer.lock`
file into your project root.
## Lock file
## `composer.lock` - The Lock File
After installing the dependencies, composer writes the list of the exact
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.**
**Commit your project's `composer.lock` (along with `composer.json`) 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.
This is important because the `install` command checks if a lock file is present,
and if it is, it downloads the versions specified there (regardless of what `composer.json`
says). This means that anyone who sets up the project will download the exact
same version of the dependencies.
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.
If no `composer.json` lock file exists, it will read the dependencies and
versions from `composer.json` and create the lock file.
This means that if any of the dependencies get a new version, you won't get the updates.
automatically. To update to the new version, use `update` command. This will fetch
the latest matching versions (according to your `composer.json` file) and also update
the lock file with the new version.
$ 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
[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.
@ -134,20 +126,20 @@ 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.
Any open source project using Composer should publish their packages on
packagist. A library doesn't need to be on packagist to be used by Composer,
but it makes life quite a bit simpler.
## 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.
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.
require 'vendor/.composer/autoload.php';
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
This makes it really easy to use third party code: For monolog, it
means that we can just start using classes from it, and they will be
autoloaded.