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

added some links and some restructuring

pull/4172/head
Rob Bast 2015-06-23 08:47:30 +02:00
parent 50db9393e5
commit d8d2bcadde
2 changed files with 71 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -18,8 +18,8 @@ other metadata as well.
### The `require` Key ### The `require` Key
The first (and often only) thing you specify in `composer.json` is the 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`](04-schema.md#require) key. You're simply telling Composer which
depends on. packages your project depends on.
```json ```json
{ {
@ -29,8 +29,9 @@ depends on.
} }
``` ```
As you can see, `require` takes an object that maps **package names** As you can see, [`require`](04-schema.md#require) takes an object that maps
(e.g. `monolog/monolog`) to **version constraints** (e.g. `1.0.*`). **package names** (e.g. `monolog/monolog`) to **version constraints** (e.g.
`1.0.*`).
### Package Names ### Package Names
@ -49,7 +50,7 @@ smaller decoupled parts.
In the previous example we were requiring version In the previous example we were requiring version
[`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of
monolog. This means any version in the `1.0` development branch. It is the Monolog. This means any version in the `1.0` development branch. It is the
equivalent of saying versions that match `>=1.0 <1.1`. equivalent of saying versions that match `>=1.0 <1.1`.
Version constraints can be specified in several ways, read Version constraints can be specified in several ways, read
@ -66,7 +67,7 @@ all packages instead of doing per dependency you can also use the
## Installing Dependencies ## Installing Dependencies
To install the defined dependencies for your project, just run the To install the defined dependencies for your project, just run the
`install` command. [`install`](03-cli.md#install) command.
```sh ```sh
php composer.phar install php composer.phar install
@ -75,13 +76,14 @@ php composer.phar install
This will find the latest version of `monolog/monolog` that matches the This will find the latest version of `monolog/monolog` that matches the
supplied version constraint and download it into the `vendor` directory. supplied version constraint and download it into 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` in your `.gitignore`. You really don't want to add all of that > `vendor` in your `.gitignore`. You really don't want to add all of that
> code to your repository. > code to your repository.
You will notice the `install` command also created a `composer.lock` file. You will notice the [`install`](03-cli.md#install) command also created a
`composer.lock` file.
## `composer.lock` - The Lock File ## `composer.lock` - The Lock File
@ -92,9 +94,9 @@ to those specific versions.
**Commit your application's `composer.lock` (along with `composer.json`) **Commit your application's `composer.lock` (along with `composer.json`)
into version control.** into version control.**
This is important because the `install` command checks if a lock file is This is important because the [`install`](03-cli.md#install) command checks
present, and if it is, it downloads the versions specified there (regardless if a lock file is present, and if it is, it downloads the versions specified
of what `composer.json` says). there (regardless of what `composer.json` says).
This means that anyone who sets up the project will download the exact same This means that anyone who sets up the project will download the exact same
version of the dependencies. Your CI server, production machines, other version of the dependencies. Your CI server, production machines, other
@ -106,12 +108,13 @@ if your dependencies released many new versions since then.
If no `composer.lock` file exists, Composer will read the dependencies and If no `composer.lock` file exists, Composer will read the dependencies and
versions from `composer.json` and create the lock file after executing the versions from `composer.json` and create the lock file after executing the
`update` or the `install` command. [`update`](03-cli.md#update) or the [`install`](03-cli.md#install) command.
This means that if any of the dependencies get a new version, you won't get the 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 the `update` command. updates automatically. To update to the new version, use the
This will fetch the latest matching versions (according to your `composer.json` [`update`](03-cli.md#update) command. This will fetch the latest matching
file) and also update the lock file with the new version. versions (according to your `composer.json` file) and also update the lock file
with the new version.
```sh ```sh
php composer.phar update php composer.phar update
@ -125,7 +128,7 @@ If you only want to install or update one dependency, you can whitelist them:
php composer.phar update monolog/monolog [...] php composer.phar update monolog/monolog [...]
``` ```
> **Note:** For libraries it is not necessarily recommended to commit the lock > **Note:** For libraries it is not necessary to commit the lock
> file, see also: [Libraries - Lock file](02-libraries.md#lock-file). > file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
## Packagist ## Packagist
@ -135,12 +138,12 @@ 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 from. Packagist aims to be the central repository that everybody uses. This
means that you can automatically `require` any package that is available there. means that you can automatically `require` any package that is available there.
If you go to the [packagist website](https://packagist.org/) (packagist.org), If you go to the [Packagist website](https://packagist.org/) (packagist.org),
you can browse and search for packages. you can browse and search for packages.
Any open source project using Composer should publish their packages on Any open source project using Composer is recommended to publish their packages
packagist. A library doesn't need to be on packagist to be used by Composer, but on Packagist. A library doesn't need to be on Packagist to be used by Composer,
it makes life quite a bit simpler. but it enables discovery and adoption by other developers more quickly.
## Autoloading ## Autoloading
@ -153,18 +156,17 @@ require 'vendor/autoload.php';
``` ```
This makes it really easy to use third party code. For example: If your project This makes it really easy to use third party code. For example: If your project
depends on monolog, you can just start using classes from it, and they will be depends on Monolog, you can just start using classes from it, and they will be
autoloaded. autoloaded.
```php ```php
$log = new Monolog\Logger('name'); $log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->addWarning('Foo'); $log->addWarning('Foo');
``` ```
You can even add your own code to the autoloader by adding an `autoload` field You can even add your own code to the autoloader by adding an
to `composer.json`. [`autoload`](04-schema.md#autoload) field to `composer.json`.
```json ```json
{ {
@ -181,8 +183,9 @@ You define a mapping from namespaces to directories. The `src` directory would
be in your project root, on the same level as `vendor` directory is. An example be in your project root, on the same level as `vendor` directory is. An example
filename would be `src/Foo.php` containing an `Acme\Foo` class. filename would be `src/Foo.php` containing an `Acme\Foo` class.
After adding the `autoload` field, you have to re-run `dump-autoload` to After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run
re-generate the `vendor/autoload.php` file. [`dump-autoload`](03-cli.md#dump-autoload) to re-generate the
`vendor/autoload.php` file.
Including that file will also return the autoloader instance, so you can store 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. the return value of the include call in a variable and add more namespaces.
@ -193,9 +196,9 @@ $loader = require 'vendor/autoload.php';
$loader->add('Acme\\Test\\', __DIR__); $loader->add('Acme\\Test\\', __DIR__);
``` ```
In addition to PSR-4 autoloading, classmap is also supported. This allows In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and
classes to be autoloaded even if they do not conform to PSR-4. See the [autoload files autoloading. See the [`autoload`](04-schema.md#autoload) reference for
reference](04-schema.md#autoload) for more details. more information.
> **Note:** Composer provides its own autoloader. If you don't want to use that > **Note:** Composer provides its own autoloader. If you don't want to use that
> one, you can just include `vendor/composer/autoload_*.php` files, which return > one, you can just include `vendor/composer/autoload_*.php` files, which return

76
doc/02-libraries.md
View File

@ -1,16 +1,17 @@
# Libraries # Libraries
This chapter will tell you how to make your library installable through Composer. This chapter will tell you how to make your library installable through
Composer.
## Every project is a package ## Every project is a package
As soon as you have a `composer.json` in a directory, that directory is a 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 package. When you add a [`require`](04-schema.md#require) to a project, you are
depends on other packages. The only difference between your project and making a package that depends on other packages. The only difference between
libraries is that your project is a package without a name. 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 In order to make that package installable you need to give it a name. You do
this by adding a `name` to `composer.json`: this by adding the [`name`](04-schema.md#name) property in `composer.json`:
```json ```json
{ {
@ -21,12 +22,12 @@ this by adding a `name` to `composer.json`:
} }
``` ```
In this case the project name is `acme/hello-world`, where `acme` is the In this case the project name is `acme/hello-world`, where `acme` is the vendor
vendor name. Supplying a vendor name is mandatory. name. Supplying a vendor name is mandatory.
> **Note:** If you don't know what to use as a vendor name, your GitHub > **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 > username is usually a good bet. While package names are case insensitive, the
convention is all lowercase and dashes for word separation. > convention is all lowercase and dashes for word separation.
## Platform packages ## Platform packages
@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`, PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
`openssl`, `pcre`, `uuid`, `xsl`. `openssl`, `pcre`, `uuid`, `xsl`.
You can use `composer show --platform` to get a list of your locally available You can use [`show --platform`](03-cli.md#show) to get a list of your locally
platform packages. available platform packages.
## Specifying the version ## Specifying the version
You need to specify the package's version some way. When you publish your When you publish your package on Packagist, it is able to infer the version
package on Packagist, it is able to infer the version from the VCS (git, svn, from the VCS (git, svn, hg) information. This means you don't have to
hg) information, so in that case you do not have to specify it, and it is explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how
recommended not to. See [tags](#tags) and [branches](#branches) to see how
version numbers are extracted from these. version numbers are extracted from these.
If you are creating packages by hand and really have to specify it explicitly, If you are creating packages by hand and really have to specify it explicitly,
@ -76,9 +76,9 @@ you can just add a `version` field:
### Tags ### Tags
For every tag that looks like a version, a package version of that tag will be 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 created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of
of `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffixes `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also
can also be followed by a number. be followed by a number.
Here are a few examples of valid tag names: Here are a few examples of valid tag names:
@ -89,19 +89,20 @@ Here are a few examples of valid tag names:
- v2.0.0-alpha - v2.0.0-alpha
- v2.0.4-p1 - v2.0.4-p1
> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions) > **Note:** Even if your tag is prefixed with `v`, a
> in a `require` statement has to be specified without prefix > [version constraint](01-basic-usage.md#package-versions) in a `require`
> (e.g. tag `v1.0.0` will result in version `1.0.0`). > statement has to be specified without prefix (e.g. tag `v1.0.0` will result
> in version `1.0.0`).
### Branches ### Branches
For every branch, a package development version will be created. If the branch 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, name looks like a version, the version will be `{branchname}-dev`. For example,
the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for technical the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for
reasons, to make sure it is recognized as a branch). The `2.0.x` branch would also technical reasons, to make sure it is recognized as a branch). The `2.0.x`
be valid and be turned into `2.0.x-dev` as well. If the branch does not look branch would also be valid and be turned into `2.0.x-dev` as well. If the
like a version, it will be `dev-{branchname}`. `master` results in a branch does not look like a version, it will be `dev-{branchname}`. `master`
`dev-master` version. results in a `dev-master` version.
Here are some examples of version branch names: Here are some examples of version branch names:
@ -116,8 +117,8 @@ Here are some examples of version branch names:
### Aliases ### Aliases
It is possible to alias branch names to versions. For example, you could alias It is possible to alias branch names to versions. For example, you could alias
`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all `dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in
the packages. all the packages.
See [Aliases](articles/aliases.md) for more information. See [Aliases](articles/aliases.md) for more information.
@ -133,7 +134,7 @@ the `.gitignore`.
## Publishing to a VCS ## Publishing to a VCS
Once you have a vcs repository (version control system, e.g. git) containing a 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 `composer.json` file, your library is already composer-installable. In this
example we will publish the `acme/hello-world` library on GitHub under example we will publish the `acme/hello-world` library on GitHub under
`github.com/username/hello-world`. `github.com/username/hello-world`.
@ -180,11 +181,11 @@ For more details on how package repositories work and what other types are
available, see [Repositories](05-repositories.md). available, see [Repositories](05-repositories.md).
That's all. You can now install the dependencies by running Composer's That's all. You can now install the dependencies by running Composer's
`install` command! [`install`](03-cli.md#install) command!
**Recap:** Any git/svn/hg repository containing a `composer.json` can be added **Recap:** Any git/svn/hg repository containing a `composer.json` can be added
to your project by specifying the package repository and declaring the to your project by specifying the package repository and declaring the
dependency in the `require` field. dependency in the [`require`](04-schema.md#require) field.
## Publishing to packagist ## Publishing to packagist
@ -196,15 +197,16 @@ repository for `monolog/monolog`. How did that work? The answer is Packagist.
[Packagist](https://packagist.org/) is the main package repository for [Packagist](https://packagist.org/) is the main package repository for
Composer, and it is enabled by default. Anything that is published on Composer, and it is enabled by default. Anything that is published on
Packagist is available automatically through Composer. Since monolog Packagist is available automatically through Composer. Since
[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend [Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
on it without having to specify any additional repositories. can depend on it without having to specify any additional repositories.
If we wanted to share `hello-world` with the world, we would publish it on If we wanted to share `hello-world` with the world, we would publish it on
Packagist as well. Doing so is really easy. Packagist as well. Doing so is really easy.
You simply hit the big "Submit Package" button and sign up. Then you submit You simply visit [Packagist](https://packagist.org) and hit the "Submit". This
the URL to your VCS repository, at which point Packagist will start crawling will prompt you to sign up if you haven't already, and then allows you to
it. Once it is done, your package will be available to anyone. submit the URL to your VCS repository, at which point Packagist will start
crawling it. Once it is done, your package will be available to anyone!
&larr; [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) &rarr; &larr; [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) &rarr;