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 first (and often only) thing you specify in `composer.json` is the
`require` key. You're simply telling Composer which packages your project
depends on.
[`require`](04-schema.md#require) key. You're simply telling Composer which
packages your project depends on.
```json
{
@ -29,8 +29,9 @@ depends on.
}
```
As you can see, `require` takes an object that maps **package names**
(e.g. `monolog/monolog`) to **version constraints** (e.g. `1.0.*`).
As you can see, [`require`](04-schema.md#require) takes an object that maps
**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g.
`1.0.*`).
### Package Names
@ -49,7 +50,7 @@ smaller decoupled parts.
In the previous example we were requiring version
[`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`.
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
To install the defined dependencies for your project, just run the
`install` command.
[`install`](03-cli.md#install) command.
```sh
php composer.phar install
@ -75,13 +76,14 @@ php composer.phar install
This will find the latest version of `monolog/monolog` that matches the
supplied version constraint and download it into 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`.
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` in your `.gitignore`. You really don't want to add all of that
> 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
@ -92,9 +94,9 @@ to those specific versions.
**Commit your application's `composer.lock` (along with `composer.json`)
into version control.**
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 is important because the [`install`](03-cli.md#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. 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
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
updates automatically. To update to the new version, use the `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.
updates automatically. To update to the new version, use the
[`update`](03-cli.md#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.
```sh
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 [...]
```
> **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).
## 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
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.
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.
Any open source project using Composer is recommended to publish their packages
on Packagist. A library doesn't need to be on Packagist to be used by Composer,
but it enables discovery and adoption by other developers more quickly.
## Autoloading
@ -153,18 +156,17 @@ require 'vendor/autoload.php';
```
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.
```php
$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->addWarning('Foo');
```
You can even add your own code to the autoloader by adding an `autoload` field
to `composer.json`.
You can even add your own code to the autoloader by adding an
[`autoload`](04-schema.md#autoload) field to `composer.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
filename would be `src/Foo.php` containing an `Acme\Foo` class.
After adding the `autoload` field, you have to re-run `dump-autoload` to
re-generate the `vendor/autoload.php` file.
After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run
[`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
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__);
```
In addition to PSR-4 autoloading, classmap is also supported. This allows
classes to be autoloaded even if they do not conform to PSR-4. See the [autoload
reference](04-schema.md#autoload) for more details.
In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and
files autoloading. See the [`autoload`](04-schema.md#autoload) reference for
more information.
> **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

76
doc/02-libraries.md
View File

@ -1,16 +1,17 @@
# 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
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
depends on other packages. The only difference between your project and
libraries is that your project is a package without a name.
package. When you add a [`require`](04-schema.md#require) to a project, you are
making a package that depends on other packages. The only difference between
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
this by adding a `name` to `composer.json`:
this by adding the [`name`](04-schema.md#name) property in `composer.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
vendor name. Supplying a vendor name is mandatory.
In this case the project name is `acme/hello-world`, where `acme` is the vendor
name. Supplying a vendor name is mandatory.
> **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
convention is all lowercase and dashes for word separation.
> username is usually a good bet. While package names are case insensitive, the
> convention is all lowercase and dashes for word separation.
## Platform packages
@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
`openssl`, `pcre`, `uuid`, `xsl`.
You can use `composer show --platform` to get a list of your locally available
platform packages.
You can use [`show --platform`](03-cli.md#show) to get a list of your locally
available platform packages.
## Specifying the version
You need to specify the package's version some way. When you publish your
package on Packagist, it is able to infer the version from the VCS (git, svn,
hg) information, so in that case you do not have to specify it, and it is
recommended not to. See [tags](#tags) and [branches](#branches) to see how
When you publish your package on Packagist, it is able to infer the version
from the VCS (git, svn, hg) information. This means you don't have to
explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how
version numbers are extracted from these.
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
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
of `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffixes
can also be followed by a number.
created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of
`-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also
be followed by a number.
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.4-p1
> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions)
> in a `require` statement has to be specified without prefix
> (e.g. tag `v1.0.0` will result in version `1.0.0`).
> **Note:** Even if your tag is prefixed with `v`, a
> [version constraint](01-basic-usage.md#package-versions) in a `require`
> statement has to be specified without prefix (e.g. tag `v1.0.0` will result
> in version `1.0.0`).
### Branches
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,
the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for technical
reasons, to make sure it is recognized as a branch). The `2.0.x` branch would also
be valid and be turned into `2.0.x-dev` as well. If the branch does not look
like a version, it will be `dev-{branchname}`. `master` results in a
`dev-master` version.
the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for
technical reasons, to make sure it is recognized as a branch). The `2.0.x`
branch would also be valid and be turned into `2.0.x-dev` as well. If the
branch does not look like a version, it will be `dev-{branchname}`. `master`
results in a `dev-master` version.
Here are some examples of version branch names:
@ -116,8 +117,8 @@ Here are some examples of version branch names:
### Aliases
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
the packages.
`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in
all the packages.
See [Aliases](articles/aliases.md) for more information.
@ -133,7 +134,7 @@ the `.gitignore`.
## 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
example we will publish the `acme/hello-world` library on GitHub under
`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).
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
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
@ -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
Composer, and it is enabled by default. Anything that is published on
Packagist is available automatically through Composer. Since monolog
[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend
on it without having to specify any additional repositories.
Packagist is available automatically through Composer. Since
[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
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
Packagist as well. Doing so is really easy.
You simply hit the big "Submit Package" button and sign up. Then you 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.
You simply visit [Packagist](https://packagist.org) and hit the "Submit". This
will prompt you to sign up if you haven't already, and then allows you to
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;