From 4ddd5aa37f2db325aea3de827c37e1f66c8c1969 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Mon, 22 Jun 2015 14:31:33 +0200 Subject: [PATCH 1/6] cleaned up intro page a bit --- doc/00-intro.md | 137 ++++++++++++++++++----------------------------- doc/06-config.md | 16 +++--- 2 files changed, 61 insertions(+), 92 deletions(-) diff --git a/doc/00-intro.md b/doc/00-intro.md index 0496390ca..c0fe1c4dc 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -1,54 +1,41 @@ # Introduction Composer is a tool for dependency management in PHP. It allows you to declare -the dependent libraries your project needs and it will install them in your -project for you. +the libraries your project depends on and it will manage (install/update) them +for you. ## Dependency management -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. +Composer is **not** a package manager in the same sense as Yum or Apt are. 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 and Composer is strongly inspired by node's [npm](https://npmjs.org/) -and ruby's [bundler](http://bundler.io/). But there has not been such a tool -for PHP. +This idea is not new and Composer is strongly inspired by node's +[npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/). -The problem that Composer solves is this: +Suppose: 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. +Composer: -d) Composer finds out which versions of which packages need to be installed, and +c) Enables you to declare the libraries you depend on. + +d) Finds out which versions of which packages can and need to be installed, and installs them (meaning it downloads them into your project). -## Declaring dependencies - -Let's say you are creating a project, and you need a library that does logging. -You decide to use [monolog](https://github.com/Seldaek/monolog). In order to -add it to your project, all you need to do is create a `composer.json` file -which describes the project's dependencies. - -```json -{ - "require": { - "monolog/monolog": "1.2.*" - } -} -``` - -We are simply stating that our project requires some `monolog/monolog` package, -any version beginning with `1.2`. +See the [Basic usage](01-basic-usage.md) chapter for more details on declaring +dependencies. ## System Requirements Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile -flags are also required, but when using the installer you will be warned about any -incompatibilities. +flags are also required, but when using the installer you will be warned about +any incompatibilities. To install packages from sources instead of simple zip archives, you will need git, svn or hg depending on how the package is version-controlled. @@ -79,37 +66,48 @@ curl -sS https://getcomposer.org/installer | php php -r "readfile('https://getcomposer.org/installer');" | php ``` -The installer will just check a few PHP settings and then download `composer.phar` -to 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. +The installer will just check a few PHP settings and then download +`composer.phar` to 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` -option and providing a target directory (it can be an absolute or relative path): +option and providing a target directory (it can be an absolute or relative +path): ```sh curl -sS https://getcomposer.org/installer | php -- --install-dir=bin ``` +Now just run `php composer.phar` in order to run Composer. + #### Globally -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 place the Composer PHAR anywhere you wish. If you put it in a directory +that is part of your `PATH`, you can access it globally. On unixy systems you +can even make it executable and invoke it without directly using the `php` +interpreter. -You can run these commands to easily access `composer` from anywhere on your system: +Run these commands to globally install `composer` on your system: ```sh curl -sS https://getcomposer.org/installer | php mv composer.phar /usr/local/bin/composer +chmod 755 /usr/local/bin/composer ``` -> **Note:** If the above fails due to permissions, run the `mv` line +> **Note:** If the above fails due to permissions, run the `mv` and `chmod` line > again with sudo. -> **Note:** In OSX Yosemite the `/usr` directory does not exist by default. If you receive the error "/usr/local/bin/composer: No such file or directory" then you must create `/usr/local/bin/` manually before proceeding. +> **Note:** On some versions of OSX the `/usr` directory does not exist by +> default. If you receive the error "/usr/local/bin/composer: No such file or +> directory" then you must create the directory manually before proceeding: +> `mkdir -p /usr/local/bin`. -Then, just run `composer` in order to run Composer instead of `php composer.phar`. +> **Note:** For information on changing your PATH, please read the +> [Wikipedia article](https://en.wikipedia.org/wiki/PATH_(variable)) and/or use Google. + +Now just run `composer` in order to run Composer instead of `php composer.phar`. ## Installation - Windows @@ -117,24 +115,26 @@ Then, just run `composer` in order to run Composer instead of `php composer.phar This is the easiest way to get Composer set up on your machine. -Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe), -it will install the latest Composer version and set up your PATH so that you can -just call `composer` from any directory in your command line. +Download and run +[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will +install the latest Composer version and set up your PATH so that you can just +call `composer` from any directory in your command line. -> **Note:** Close your current terminal. Test usage with a new terminal: -> That is important since the PATH only gets loaded when the terminal starts. +> **Note:** Close your current terminal. Test usage with a new terminal: This is +> important since the PATH only gets loaded when the terminal starts. ### Manual Installation Change to a directory on your `PATH` and run the install snippet to download -composer.phar: +`composer.phar`: ```sh C:\Users\username>cd C:\bin C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php ``` -> **Note:** If the above fails due to readfile, use the `http` url or enable php_openssl.dll in php.ini +> **Note:** If the above fails due to readfile, use the `http` url or enable +> php_openssl.dll in php.ini Create a new `composer.bat` file alongside `composer.phar`: @@ -153,38 +153,7 @@ Composer version 27d8904 ## Using Composer -We will now use Composer to install the dependencies of the project. If you -don't have a `composer.json` file in the current directory please skip to the -[Basic Usage](01-basic-usage.md) chapter. +Now that you've installed Composer, you are ready to use it! Head on over to the +next chapter for a short and simple demonstration. -To resolve and download dependencies, run the `install` command: - -```sh -php composer.phar install -``` - -If you did a global install and do not have the phar in that directory -run this instead: - -```sh -composer install -``` - -Following the [example above](#declaring-dependencies), this will download -monolog into the `vendor/monolog/monolog` directory. - -## 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: - -```php -require __DIR__ . '/vendor/autoload.php'; -``` - -Woah! Now start using monolog! To keep learning more about Composer, keep -reading the "Basic Usage" chapter. - -[Basic Usage](01-basic-usage.md) → +[Basic usage](01-basic-usage.md) → diff --git a/doc/06-config.md b/doc/06-config.md index 1dbcf7be2..2564fefef 100644 --- a/doc/06-config.md +++ b/doc/06-config.md @@ -46,6 +46,11 @@ A list of domain names and username/passwords to authenticate against them. For example using `{"example.org": {"username": "alice", "password": "foo"}` as the value of this option will let Composer authenticate against example.org. +> **Note:** Authentication-related config options like `http-basic` and +> `github-oauth` can also be specified inside a `auth.json` file that goes +> besides your `composer.json`. That way you can gitignore it and every +> developer can place their own credentials in there. + ## platform Lets you fake platform packages (PHP and extensions) so that you can emulate a @@ -99,7 +104,7 @@ first until the cache fits. ## prepend-autoloader -Defaults to `true`. If false, the Composer autoloader will not be prepended to +Defaults to `true`. If `false`, the Composer autoloader will not be prepended to existing autoloaders. This is sometimes required to fix interoperability issues with other autoloaders. @@ -110,7 +115,7 @@ autoloader. When null a random one will be generated. ## optimize-autoloader -Defaults to `false`. Always optimize when dumping the autoloader. +Defaults to `false`. If `true`, always optimize when dumping the autoloader. ## classmap-authoritative @@ -125,7 +130,7 @@ used for GitHub Enterprise setups. ## github-expose-hostname -Defaults to `true`. If set to `false`, the OAuth tokens created to access the +Defaults to `true`. If `false`, the OAuth tokens created to access the github API will have a date instead of the machine hostname. ## notify-on-install @@ -163,9 +168,4 @@ Example: } ``` -> **Note:** Authentication-related config options like `http-basic` and -> `github-oauth` can also be specified inside a `auth.json` file that goes -> besides your `composer.json`. That way you can gitignore it and every -> developer can place their own credentials in there. - ← [Repositories](05-repositories.md) | [Community](07-community.md) → From eb98613672e536c2a2b342f9e6e98878ece59071 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Tue, 30 Jun 2015 08:43:54 +0200 Subject: [PATCH 2/6] add installer information --- doc/00-intro.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/00-intro.md b/doc/00-intro.md index c0fe1c4dc..4aca7ab17 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -47,6 +47,12 @@ Linux and OSX. ### Downloading the Composer Executable +Composer offers a convenient installer that you can execute directly from the +commandline. Feel free to [download this file](https://getcomposer.org/installer) +or review it on [GitHub](https://github.com/composer/getcomposer.org/blob/master/web/installer) +if you wish to know more about the inner workings of the installer. The source +is plain PHP. + There are in short, two ways to install Composer. Locally as part of your project, or globally as a system wide executable. @@ -93,11 +99,16 @@ Run these commands to globally install `composer` on your system: ```sh curl -sS https://getcomposer.org/installer | php mv composer.phar /usr/local/bin/composer -chmod 755 /usr/local/bin/composer ``` -> **Note:** If the above fails due to permissions, run the `mv` and `chmod` line -> again with sudo. +> **Note:** If the above fails due to permissions, run the `mv` line again +> with sudo. + +A quick copy-paste version including sudo: + +```sh +curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer +``` > **Note:** On some versions of OSX the `/usr` directory does not exist by > default. If you receive the error "/usr/local/bin/composer: No such file or From 10b813fc40dd32f27b1bb2f1a201f2cf79b49832 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Mon, 22 Jun 2015 16:24:59 +0200 Subject: [PATCH 3/6] reworking basic usage, added versions article --- doc/00-intro.md | 9 ++- doc/01-basic-usage.md | 167 ++++++++++++++++----------------------- doc/articles/versions.md | 99 +++++++++++++++++++++++ 3 files changed, 171 insertions(+), 104 deletions(-) create mode 100644 doc/articles/versions.md diff --git a/doc/00-intro.md b/doc/00-intro.md index 4aca7ab17..d984eb7b9 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -77,15 +77,16 @@ The installer will just check a few PHP settings and then download is a PHAR (PHP archive), which is an archive format for PHP which can be run on the command line, amongst other things. +Now just run `php composer.phar` in order to run Composer. + 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): +option and additionally (re)name it as well using the `--filename` option: ```sh -curl -sS https://getcomposer.org/installer | php -- --install-dir=bin +curl -sS https://getcomposer.org/installer | php -- --install-dir=bin --filename=composer ``` -Now just run `php composer.phar` in order to run Composer. +Now just run `php bin/composer` in order to run Composer. #### Globally diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index f5f45346c..d52a7d735 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -1,8 +1,12 @@ # Basic usage -## Installing +## Introduction -If you have not yet installed Composer, refer to the [Intro](00-intro.md) chapter. +If you have not yet installed Composer, refer to the [Intro](00-intro.md) +chapter. For our basic usage introduction, we will be installing +`monolog/monolog`, a logging library. Note that for the sake of simplicity, +this introduction will assume you have performed a [local](00-intro.md#locally) +install of Composer. ## `composer.json`: Project Setup @@ -10,9 +14,6 @@ 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 @@ -27,15 +28,15 @@ depends on. } ``` -As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`) -to **package versions** (e.g. `1.0.*`). +As you can see, `require` takes an object that maps **package names** +(e.g. `monolog/monolog`) to **version constraints** (e.g. `1.0.*`). ### Package Names The package name consists of a vendor name and the project's name. Often these -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`. +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`. Here we are requiring `monolog/monolog`, so the vendor name is the same as the project's name. For projects with a unique name this is recommended. It also @@ -45,53 +46,20 @@ smaller decoupled parts. ### Package Versions -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 would match `1.0.0`, -`1.0.2` or `1.0.20`. +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 +equivalent of saying versions that match `>=1.0 <1.1`. -Version constraints can be specified in a few different ways. - -Name | Example | Description --------------- | ------------------------------------------------------------------------ | ----------- -Exact version | `1.0.2` | You can specify the exact version of a package. -Range | `>=1.0` `>=1.0 <2.0` >=1.0 <1.1 || >=1.2 | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`.
You can define multiple ranges. Ranges separated by a space ( ) or comma (`,`) will be treated as a **logical AND**. A double pipe (||) will be treated as a **logical OR**. AND has higher precedence than OR. -Hyphen Range | `1.0 - 2.0` | Inclusive set of versions. Partial versions on the right include are completed with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the `2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to `>=1.0.0 <=2.1.0`. -Wildcard | `1.0.*` | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0 <1.1`. -Tilde Operator | `~1.2` | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2 <2.0`. For more details, read the next section below. -Caret Operator | `^1.2.3` | Very useful for projects that follow semantic versioning. `^1.2.3` is equivalent to `>=1.2.3 <2.0`. For more details, read the next section below. - -### Next Significant Release (Tilde and Caret Operators) - -The `~` operator is best explained by example: `~1.2` is equivalent to -`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see -it is mostly useful for projects respecting [semantic -versioning](http://semver.org/). A common usage would be to mark the minimum -minor version you depend on, like `~1.2` (which allows anything up to, but not -including, 2.0). Since in theory there should be no backwards compatibility -breaks until 2.0, that works well. Another way of looking at it is that using -`~` specifies a minimum version, but allows the last digit specified to go up. - -The `^` operator behaves very similarly but it sticks closer to semantic -versioning, and will always allow non-breaking updates. For example `^1.2.3` -is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should -break backwards compatibility. For pre-1.0 versions it also acts with safety -in mind and treats `^0.3` as `>=0.3.0 <0.4.0` - -> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint -> like `~1.2` would not install it. As said above `~1.2` only means the `.2` -> can change but the `1.` part is fixed. - -> **Note:** The `~` operator has an exception on its behavior for the major -> release number. This means for example that `~1` is the same as `~1.0` as -> it will not allow the major number to increase trying to keep backwards -> compatibility. +Version constraints can be specified in several ways, read +[versions](articles/versions.md) for more in-depth information on this topic. ### Stability -By default only stable releases are taken into consideration. If you would like -to also get RC, beta, alpha or dev versions of your dependencies you can do -so using [stability flags](04-schema.md#package-links). To change that for all -packages instead of doing per dependency you can also use the +By default only stable releases are taken into consideration. If you would +like to also get RC, beta, alpha or dev versions of your dependencies you can +do so using [stability flags](04-schema.md#package-links). To change that for +all packages instead of doing per dependency you can also use the [minimum-stability](04-schema.md#minimum-stability) setting. If you are using range comparisons when selecting non-stable packages, and you @@ -119,15 +87,15 @@ the `minimum-stability` setting and each package's stability flags. ### Test version constraints -You can test version constraints using [semver.mwl.be](http://semver.mwl.be). Fill in -a package name and it will autofill the default version constraint which Composer would add -to your `composer.json` file. You can adjust the version constraint and the tool will highlight -all releases that match. +You can test version constraints using [semver.mwl.be](http://semver.mwl.be). +Fill in a package name and it will autofill the default version constraint +which Composer would add to your `composer.json` file. You can adjust the +version constraint and the tool will highlight all releases that match. ## Installing Dependencies -To fetch the defined dependencies into your local project, just run the -`install` command of `composer.phar`. +To install the defined dependencies for your project, just run the +`install` command. ```sh php composer.phar install @@ -139,11 +107,10 @@ 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`. > **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` in your `.gitignore`. You really don't want to add all of that > code to your repository. -Another thing that the `install` command does is it adds a `composer.lock` -file into your project root. +You will notice the `install` command also created a `composer.lock` file. ## `composer.lock` - The Lock File @@ -151,72 +118,72 @@ 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 application's `composer.lock` (along with `composer.json`) into version control.** +**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` 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 -developers in your team, everything and everyone runs on the same dependencies, which -mitigates the potential for bugs affecting only some parts of the deployments. Even if you -develop alone, in six months when reinstalling the project you can feel confident the -dependencies installed are still working even if your dependencies released -many new versions since then. +This means that anyone who sets up the project will download the exact same +version of the dependencies. Your CI server, production machines, other +developers in your team, everything and everyone runs on the same dependencies, +which mitigates the potential for bugs affecting only some parts of the +deployments. Even if you develop alone, in six months when reinstalling the +project you can feel confident the dependencies installed are still working even +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. +versions from `composer.json` and create the lock file after executing the +`update` or the `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. +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. ```sh php composer.phar update ``` -> **Note:** Composer will display a Warning when executing an `install` command if - `composer.lock` and `composer.json` are not synchronized. - +> **Note:** Composer will display a Warning when executing an `install` command +> if `composer.lock` and `composer.json` are not synchronized. + If you only want to install or update one dependency, you can whitelist them: ```sh php composer.phar update monolog/monolog [...] ``` -> **Note:** For libraries it is not necessarily recommended to commit the lock file, -> see also: [Libraries - Lock file](02-libraries.md#lock-file). +> **Note:** For libraries it is not necessarily recommended to commit the lock +> file, see also: [Libraries - Lock file](02-libraries.md#lock-file). ## Packagist [Packagist](https://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. +means that you can automatically `require` any package that is available there. 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. +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 specify autoload information, Composer generates a -`vendor/autoload.php` file. You can simply include this file and you -will get autoloading for free. +`vendor/autoload.php` file. You can simply include this file and you will get +autoloading for free. ```php 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 autoloaded. +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 +autoloaded. ```php $log = new Monolog\Logger('name'); @@ -243,8 +210,8 @@ 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` field, you have to re-run `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. @@ -256,11 +223,11 @@ $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. +classes to be autoloaded even if they do not conform to PSR-4. See the [autoload +reference](04-schema.md#autoload) for more details. -> **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 associative arrays allowing you to configure your own autoloader. +> **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 +> associative arrays allowing you to configure your own autoloader. ← [Intro](00-intro.md) | [Libraries](02-libraries.md) → diff --git a/doc/articles/versions.md b/doc/articles/versions.md new file mode 100644 index 000000000..eae9da9be --- /dev/null +++ b/doc/articles/versions.md @@ -0,0 +1,99 @@ + + +# Versions + +## Basic Constraints + +### Exact + +You can specify the exact version of a package. This will tell Composer to +install this version and this version only. If other dependencies require +a different version, the solver will ultimately fail and abort any install +or update procedures. + +Example: `1.0.2` + +### Range + +By using comparison operators you can specify ranges of valid versions. Valid +operators are `>`, `>=`, `<`, `<=`, `!=`.
You can define multiple ranges. +Ranges separated by a space ( ) or comma (`,`) will be treated as +a **logical AND**. A double pipe (||) will be treated as +a **logical OR**. AND has higher precedence than OR. + +Example: `>=1.0` `>=1.0 <2.0` `>=1.0 <1.1 || >=1.2` + +### Range (Hyphen) + +Inclusive set of versions. Partial versions on the right include are completed +with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the +`2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to +`>=1.0.0 <=2.1.0`. + +Example: `1.0 - 2.0` + +### Wildcard + +You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of +`>=1.0 <1.1`. + +Example: `1.0.*` + +## Next Significant Release Operators + +### Tilde + +The `~` operator is best explained by example: `~1.2` is equivalent to +`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see +it is mostly useful for projects respecting [semantic +versioning](http://semver.org/). A common usage would be to mark the minimum +minor version you depend on, like `~1.2` (which allows anything up to, but not +including, 2.0). Since in theory there should be no backwards compatibility +breaks until 2.0, that works well. Another way of looking at it is that using +`~` specifies a minimum version, but allows the last digit specified to go up. + +Example: `~1.2` + +> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint +> like `~1.2` would not install it. As said above `~1.2` only means the `.2` +> can change but the `1.` part is fixed. + +> **Note:** The `~` operator has an exception on its behavior for the major +> release number. This means for example that `~1` is the same as `~1.0` as +> it will not allow the major number to increase trying to keep backwards +> compatibility. + +### Caret + +The `^` operator behaves very similarly but it sticks closer to semantic +versioning, and will always allow non-breaking updates. For example `^1.2.3` +is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should +break backwards compatibility. For pre-1.0 versions it also acts with safety +in mind and treats `^0.3` as `>=0.3.0 <0.4.0`. + +Example: `^1.2.3` + +## Stability + +If you are using a constraint that does not explicitly define a stability, +Composer will default interally to `-dev` or `-stable`, depending on the +operator(s) used. This happens transparently. + +If you wish to explicitly consider only the stable release in the comparison, +add the suffix `-stable`. + +Examples: + + Constraint | Internally +---------------------------------------------- + `1.2.3` | `=1.2.3.0-stable` + `>1.2` | `>1.2.0.0-stable` + `>=1.2` | `>=1.2.0.0-dev` + `>=1.2-stable` | `>=1.2.0.0-stable` + `<1.3` | `<1.3.0.0-dev` + `<=1.3` | `<=1.3.0.0-stable` + `1 - 2` | `>=1.0.0.0-dev <3.0.0.0-dev` + `~1.3` | `>=1.3.0.0-dev <2.0.0.0-dev` + `1.4.*` | `>=1.4.0.0-dev <1.5.0.0-dev` From 50db9393e5d852efa00737c2d71d77f91bde0ac3 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Mon, 22 Jun 2015 22:01:20 +0200 Subject: [PATCH 4/6] better phrasing / structure + moved version testing link --- doc/01-basic-usage.md | 41 ++++++---------------------------------- doc/articles/versions.md | 36 ++++++++++++++++++++++++----------- 2 files changed, 31 insertions(+), 46 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index d52a7d735..83bb68e25 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -2,11 +2,12 @@ ## Introduction -If you have not yet installed Composer, refer to the [Intro](00-intro.md) -chapter. For our basic usage introduction, we will be installing -`monolog/monolog`, a logging library. Note that for the sake of simplicity, -this introduction will assume you have performed a [local](00-intro.md#locally) -install of Composer. +For our basic usage introduction, we will be installing `monolog/monolog`, +a logging library. If you have not yet installed Composer, refer to the +[Intro](00-intro.md) chapter. + +> **Note:** for the sake of simplicity, this introduction will assume you +> have performed a [local](00-intro.md#locally) install of Composer. ## `composer.json`: Project Setup @@ -62,36 +63,6 @@ do so using [stability flags](04-schema.md#package-links). To change that for all packages instead of doing per dependency you can also use the [minimum-stability](04-schema.md#minimum-stability) setting. -If you are using range comparisons when selecting non-stable packages, and you -specify a numeric version number (that is, no suffix indicating alpha, beta, -rc, or stable), then both non-stable and stable versions of a particular -release number will be treated as equally valid. - - * `>=`/`<=` will accept non-stable releases as well as the stable release. - * `<`/`>` will reject non-stable releasese as well as the stable release. - -If you wish to consider only the stable release in the comparison, add the -suffix `-stable` to the version number. - -Here are some examples: - - Example | Interpretation - --------------- | -------------- -`>=1.0.0` | Any release, stable or non-, of 1.0.0 will be allowed -`>=1.0.0-stable` | Only the stable release of 1.0.0 will be allowed -`<2.0.0` | Neither release, stable or non-, of 2.0.0 will be allowed -`<2.0.0-stable` | Only the stable release of 2.0.0 will be disallowed; non-stable releases will be allowed - -Note that the packages matched by these constraints are still checked against -the `minimum-stability` setting and each package's stability flags. - -### Test version constraints - -You can test version constraints using [semver.mwl.be](http://semver.mwl.be). -Fill in a package name and it will autofill the default version constraint -which Composer would add to your `composer.json` file. You can adjust the -version constraint and the tool will highlight all releases that match. - ## Installing Dependencies To install the defined dependencies for your project, just run the diff --git a/doc/articles/versions.md b/doc/articles/versions.md index eae9da9be..b59e5e70e 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -8,7 +8,7 @@ ### Exact -You can specify the exact version of a package. This will tell Composer to +You can specify the exact version of a package. This will tell Composer to install this version and this version only. If other dependencies require a different version, the solver will ultimately fail and abort any install or update procedures. @@ -17,26 +17,32 @@ Example: `1.0.2` ### Range -By using comparison operators you can specify ranges of valid versions. Valid -operators are `>`, `>=`, `<`, `<=`, `!=`.
You can define multiple ranges. -Ranges separated by a space ( ) or comma (`,`) will be treated as -a **logical AND**. A double pipe (||) will be treated as -a **logical OR**. AND has higher precedence than OR. +By using comparison operators you can specify ranges of valid versions. Valid +operators are `>`, `>=`, `<`, `<=`, `!=`. -Example: `>=1.0` `>=1.0 <2.0` `>=1.0 <1.1 || >=1.2` +You can define multiple ranges. Ranges separated by a space ( ) or +comma (`,`) will be treated as a **logical AND**. A double pipe +(||) will be treated as a **logical OR**. AND has higher +precedence than OR. + +Examples: + +* `>=1.0` +* `>=1.0 <2.0` +* `>=1.0 <1.1 || >=1.2` ### Range (Hyphen) -Inclusive set of versions. Partial versions on the right include are completed -with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the -`2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to +Inclusive set of versions. Partial versions on the right include are completed +with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the +`2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to `>=1.0.0 <=2.1.0`. Example: `1.0 - 2.0` ### Wildcard -You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of +You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0 <1.1`. Example: `1.0.*` @@ -97,3 +103,11 @@ Examples: `1 - 2` | `>=1.0.0.0-dev <3.0.0.0-dev` `~1.3` | `>=1.3.0.0-dev <2.0.0.0-dev` `1.4.*` | `>=1.4.0.0-dev <1.5.0.0-dev` + +## Test version constraints + +You can test version constraints using [semver.mwl.be](http://semver.mwl.be). +Fill in a package name and it will autofill the default version constraint +which Composer would add to your `composer.json` file. You can adjust the +version constraint and the tool will highlight all releases that match. + From d8d2bcadde5071aa3f4fc54f17324d368f89c15b Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Tue, 23 Jun 2015 08:47:30 +0200 Subject: [PATCH 5/6] added some links and some restructuring --- doc/01-basic-usage.md | 61 +++++++++++++++++----------------- doc/02-libraries.md | 76 ++++++++++++++++++++++--------------------- 2 files changed, 71 insertions(+), 66 deletions(-) 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) → From 16a7cf19fcb694c7dac5dd61bdcac332ba041180 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Tue, 23 Jun 2015 11:20:10 +0200 Subject: [PATCH 6/6] outside of table, no need to escape --- doc/articles/versions.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/articles/versions.md b/doc/articles/versions.md index b59e5e70e..50af64e7d 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -20,10 +20,9 @@ Example: `1.0.2` By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. -You can define multiple ranges. Ranges separated by a space ( ) or -comma (`,`) will be treated as a **logical AND**. A double pipe -(||) will be treated as a **logical OR**. AND has higher -precedence than OR. +You can define multiple ranges. Ranges separated by a space (` `) or comma (`,`) +will be treated as a **logical AND**. A double pipe (`||`) will be treated as a +**logical OR**. AND has higher precedence than OR. Examples: