diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 83bb68e25..8cad96f6c 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -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 diff --git a/doc/02-libraries.md b/doc/02-libraries.md index 0749ac53f..da5725e4d 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -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! ← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) →