From 0c85ca426d6e8235366340f29ad0e6aab1747b83 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Mon, 19 May 2014 12:17:07 +0200 Subject: [PATCH] Add code-fences to examples for syntax highlighting --- doc/00-intro.md | 60 ++- doc/01-basic-usage.md | 62 ++- doc/02-libraries.md | 72 +-- doc/03-cli.md | 149 ++++-- doc/04-schema.md | 427 ++++++++++-------- doc/05-repositories.md | 336 +++++++------- doc/articles/aliases.md | 34 +- doc/articles/custom-installers.md | 122 ++--- .../handling-private-packages-with-satis.md | 139 +++--- doc/articles/plugins.md | 106 +++-- doc/articles/scripts.md | 70 +-- doc/articles/troubleshooting.md | 51 ++- doc/articles/vendor-binaries.md | 41 +- ...ckage-to-a-custom-path-for-my-framework.md | 26 +- 14 files changed, 976 insertions(+), 719 deletions(-) diff --git a/doc/00-intro.md b/doc/00-intro.md index fbb8c3613..343546269 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -33,11 +33,13 @@ 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. - { - "require": { - "monolog/monolog": "1.2.*" - } +```json +{ + "require": { + "monolog/monolog": "1.2.*" } +} +``` We are simply stating that our project requires some `monolog/monolog` package, any version beginning with `1.2`. @@ -63,12 +65,16 @@ Linux and OSX. To actually get Composer, we need to do two things. The first one is installing Composer (again, this means downloading it into your project): - $ curl -sS https://getcomposer.org/installer | php - +```sh +curl -sS https://getcomposer.org/installer | php +``` + > **Note:** If the above fails for some reason, you can download the installer > with `php` instead: - $ php -r "readfile('https://getcomposer.org/installer');" | php +```sh +php -r "readfile('https://getcomposer.org/installer');" | php +``` This will just check a few PHP settings and then download `composer.phar` to your working directory. This file is the Composer binary. It is a PHAR (PHP @@ -78,7 +84,9 @@ 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): - $ curl -sS https://getcomposer.org/installer | php -- --install-dir=bin +```sh +curl -sS https://getcomposer.org/installer | php -- --install-dir=bin +``` #### Globally @@ -88,8 +96,10 @@ executable and invoke it without `php`. You can run these commands to easily access `composer` from anywhere on your system: - $ curl -sS https://getcomposer.org/installer | php - $ mv composer.phar /usr/local/bin/composer +```sh +curl -sS https://getcomposer.org/installer | php +mv composer.phar /usr/local/bin/composer +``` > **Note:** If the above fails due to permissions, run the `mv` line > again with sudo. @@ -123,21 +133,25 @@ just call `composer` from any directory in your command line. Change to a directory on your `PATH` and run the install snippet to download composer.phar: - C:\Users\username>cd C:\bin - C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php +```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 Create a new `composer.bat` file alongside `composer.phar`: - C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat +```sh +C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat +``` Close your current terminal. Test usage with a new terminal: - C:\Users\username>composer -V - Composer version 27d8904 - - C:\Users\username> +```sh +C:\Users\username>composer -V +Composer version 27d8904 +``` ## Using Composer @@ -147,12 +161,16 @@ don't have a `composer.json` file in the current directory please skip to the To resolve and download dependencies, run the `install` command: - $ php composer.phar install +```sh +php composer.phar install +``` If you did a global install and do not have the phar in that directory run this instead: - $ composer install +```sh +composer install +``` Following the [example above](#declaring-dependencies), this will download monolog into the `vendor/monolog/monolog` directory. @@ -164,7 +182,9 @@ capable of autoloading all of the classes in any of the libraries that it downloads. To use it, just add the following line to your code's bootstrap process: - require 'vendor/autoload.php'; +```php +require 'vendor/autoload.php'; +``` Woah! Now start using monolog! To keep learning more about Composer, keep reading the "Basic Usage" chapter. diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 8ac5066fc..270a6d50a 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -4,20 +4,26 @@ To install Composer, you just need to download the `composer.phar` executable. - $ curl -sS https://getcomposer.org/installer | php +```sh +curl -sS https://getcomposer.org/installer | php +``` For the details, see the [Introduction](00-intro.md) chapter. To check if Composer is working, just run the PHAR through `php`: - $ php composer.phar +```sh +php composer.phar +``` This should give you a list of available commands. > **Note:** You can also perform the checks only without downloading Composer > by using the `--check` option. For more information, just use `--help`. > -> $ curl -sS https://getcomposer.org/installer | php -- --help +> ```sh +> curl -sS https://getcomposer.org/installer | php -- --help +> ``` ## `composer.json`: Project Setup @@ -34,11 +40,13 @@ 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": { - "monolog/monolog": "1.0.*" - } +```json +{ + "require": { + "monolog/monolog": "1.0.*" } +} +``` As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`) to **package versions** (e.g. `1.0.*`). @@ -99,7 +107,9 @@ packages instead of doing per dependency you can also use the To fetch the defined dependencies into your local project, just run the `install` command of `composer.phar`. - $ php composer.phar install +```sh +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. @@ -141,11 +151,15 @@ automatically. To update to the new version, use `update` command. This will fet the latest matching versions (according to your `composer.json` file) and also update the lock file with the new version. - $ php composer.phar update +```sh +php composer.phar update +``` If you only want to install or update one dependency, you can whitelist them: - $ php composer.phar update monolog/monolog [...] +```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). @@ -171,25 +185,31 @@ 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. - require 'vendor/autoload.php'; +```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. - $log = new Monolog\Logger('name'); - $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); +```php +$log = new Monolog\Logger('name'); +$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 to `composer.json`. - { - "autoload": { - "psr-4": {"Acme\\": "src/"} - } +```json +{ + "autoload": { + "psr-4": {"Acme\\": "src/"} } +} +``` Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader for the `Acme` namespace. @@ -205,8 +225,10 @@ 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. This can be useful for autoloading classes in a test suite, for example. - $loader = require 'vendor/autoload.php'; - $loader->add('Acme\\Test\\', __DIR__); +```php +$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 diff --git a/doc/02-libraries.md b/doc/02-libraries.md index 10612c660..81ec3edaa 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -12,12 +12,14 @@ 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`: - { - "name": "acme/hello-world", - "require": { - "monolog/monolog": "1.0.*" - } +```json +{ + "name": "acme/hello-world", + "require": { + "monolog/monolog": "1.0.*" } +} +``` In this case the project name is `acme/hello-world`, where `acme` is the vendor name. Supplying a vendor name is mandatory. @@ -62,9 +64,11 @@ version numbers are extracted from these. If you are creating packages by hand and really have to specify it explicitly, you can just add a `version` field: - { - "version": "1.0.0" - } +```json +{ + "version": "1.0.0" +} +``` > **Note:** You should avoid specifying the version field explicitly, because > for tags the value must match the tag name. @@ -78,12 +82,12 @@ a number. Here are a few examples of valid tag names: - 1.0.0 - v1.0.0 - 1.10.5-RC1 - v4.4.4beta2 - v2.0.0-alpha - v2.0.4-p1 +- 1.0.0 +- v1.0.0 +- 1.10.5-RC1 +- v4.4.4beta2 +- 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 @@ -101,9 +105,9 @@ like a version, it will be `dev-{branchname}`. `master` results in a Here are some examples of version branch names: - 1.x - 1.0 (equals 1.0.x) - 1.1.x +- 1.x +- 1.0 (equals 1.0.x) +- 1.1.x > **Note:** When you install a development version, it will be automatically > pulled from its `source`. See the [`install`](03-cli.md#install) command @@ -140,12 +144,14 @@ project locally. We will call it `acme/blog`. This blog will depend on accomplish this by creating a new `blog` directory somewhere, containing a `composer.json`: - { - "name": "acme/blog", - "require": { - "acme/hello-world": "dev-master" - } +```json +{ + "name": "acme/blog", + "require": { + "acme/hello-world": "dev-master" } +} +``` The name is not needed in this case, since we don't want to publish the blog as a library. It is added here to clarify which `composer.json` is being @@ -155,18 +161,20 @@ Now we need to tell the blog app where to find the `hello-world` dependency. We do this by adding a package repository specification to the blog's `composer.json`: - { - "name": "acme/blog", - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/username/hello-world" - } - ], - "require": { - "acme/hello-world": "dev-master" +```json +{ + "name": "acme/blog", + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/username/hello-world" } + ], + "require": { + "acme/hello-world": "dev-master" } +} +``` For more details on how package repositories work and what other types are available, see [Repositories](05-repositories.md). diff --git a/doc/03-cli.md b/doc/03-cli.md index acbd470e2..517c9648a 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -36,7 +36,9 @@ it a bit easier to do this. When you run the command it will interactively ask you to fill in the fields, while using some smart defaults. - $ php composer.phar init +```sh +php composer.phar init +``` ### Options @@ -54,7 +56,9 @@ while using some smart defaults. The `install` command reads the `composer.json` file from the current directory, resolves the dependencies, and installs them into `vendor`. - $ php composer.phar install +```sh +php composer.phar install +``` If there is a `composer.lock` file in the current directory, it will use the exact versions from there instead of resolving them. This ensures that @@ -94,18 +98,24 @@ resolution. In order to get the latest versions of the dependencies and to update the `composer.lock` file, you should use the `update` command. - $ php composer.phar update +```sh +php composer.phar update +``` This will resolve all dependencies of the project and write the exact versions into `composer.lock`. If you just want to update a few packages and not all, you can list them as such: - $ php composer.phar update vendor/package vendor/package2 +```sh +php composer.phar update vendor/package vendor/package2 +``` You can also use wildcards to update a bunch of packages at once: - $ php composer.phar update vendor/* +```sh +php composer.phar update vendor/* +``` ### Options @@ -131,7 +141,9 @@ You can also use wildcards to update a bunch of packages at once: The `require` command adds new packages to the `composer.json` file from the current directory. - $ php composer.phar require +```sh +php composer.phar require +``` After adding/changing the requirements, the modified requirements will be installed or updated. @@ -139,7 +151,9 @@ installed or updated. If you do not want to choose requirements interactively, you can just pass them to the command. - $ php composer.phar require vendor/package:2.* vendor/package2:dev-master +```sh +php composer.phar require vendor/package:2.* vendor/package2:dev-master +``` ### Options @@ -162,13 +176,17 @@ This can be used to install CLI utilities globally and if you add `$COMPOSER_HOME/vendor/bin` to your `$PATH` environment variable. Here is an example: - $ php composer.phar global require fabpot/php-cs-fixer:dev-master +```sh +php composer.phar global require fabpot/php-cs-fixer:dev-master +``` Now the `php-cs-fixer` binary is available globally (assuming you adjusted your PATH). If you wish to update the binary later on you can just run a global update: - $ php composer.phar global update +```sh +php composer.phar global update +``` ## search @@ -176,7 +194,9 @@ The search command allows you to search through the current project's package repositories. Usually this will be just packagist. You simply pass it the terms you want to search for. - $ php composer.phar search monolog +```sh +php composer.phar search monolog +``` You can also search for more than one term by passing multiple arguments. @@ -188,32 +208,38 @@ You can also search for more than one term by passing multiple arguments. To list all of the available packages, you can use the `show` command. - $ php composer.phar show +```sh +php composer.phar show +``` If you want to see the details of a certain package, you can pass the package name. - $ php composer.phar show monolog/monolog +```sh +php composer.phar show monolog/monolog - name : monolog/monolog - versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1 - type : library - names : monolog/monolog - source : [git] http://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da - dist : [zip] http://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da - license : MIT +name : monolog/monolog +versions : master-dev, 1.0.2, 1.0.1, 1.0.0, 1.0.0-RC1 +type : library +names : monolog/monolog +source : [git] http://github.com/Seldaek/monolog.git 3d4e60d0cbc4b888fe5ad223d77964428b1978da +dist : [zip] http://github.com/Seldaek/monolog/zipball/3d4e60d0cbc4b888fe5ad223d77964428b1978da 3d4e60d0cbc4b888fe5ad223d77964428b1978da +license : MIT - autoload - psr-0 - Monolog : src/ +autoload +psr-0 +Monolog : src/ - requires - php >=5.3.0 +requires +php >=5.3.0 +``` You can even pass the package version, which will tell you the details of that specific version. - $ php composer.phar show monolog/monolog 1.0.2 +```sh +php composer.phar show monolog/monolog 1.0.2 +``` ### Options @@ -227,13 +253,15 @@ The `depends` command tells you which other packages depend on a certain package. You can specify which link types (`require`, `require-dev`) should be included in the listing. By default both are used. - $ php composer.phar depends --link-type=require monolog/monolog +```sh +php composer.phar depends --link-type=require monolog/monolog - nrk/monolog-fluent - poc/poc - propel/propel - symfony/monolog-bridge - symfony/symfony +nrk/monolog-fluent +poc/poc +propel/propel +symfony/monolog-bridge +symfony/symfony +``` ### Options @@ -246,7 +274,9 @@ You should always run the `validate` command before you commit your `composer.json` file, and before you tag a release. It will check if your `composer.json` is valid. - $ php composer.phar validate +```sh +php composer.phar validate +``` ### Options @@ -258,31 +288,42 @@ If you often need to modify the code of your dependencies and they are installed from source, the `status` command allows you to check if you have local changes in any of them. - $ php composer.phar status +```sh +php composer.phar status +``` With the `--verbose` option you get some more information about what was changed: - $ php composer.phar status -v - You have changes in the following dependencies: - vendor/seld/jsonlint: - M README.mdown +```sh +php composer.phar status -v + +You have changes in the following dependencies: +vendor/seld/jsonlint: + M README.mdown +``` ## self-update To update composer itself to the latest version, just run the `self-update` command. It will replace your `composer.phar` with the latest version. - $ php composer.phar self-update +```sh +php composer.phar self-update +``` If you would like to instead update to a specific release simply specify it: - $ composer self-update 1.0.0-alpha7 +```sh +php composer.phar self-update 1.0.0-alpha7 +``` If you have installed composer for your entire system (see [global installation](00-intro.md#globally)), you may have to run the command with `root` privileges - $ sudo composer self-update +```sh +sudo composer self-update +``` ### Options @@ -294,7 +335,9 @@ you may have to run the command with `root` privileges The `config` command allows you to edit some basic composer settings in either the local composer.json file or the global config.json file. - $ php composer.phar config --list +```sh +php composer.phar config --list +``` ### Usage @@ -326,7 +369,9 @@ the global config file. In addition to modifying the config section, the `config` command also supports making changes to the repositories section by using it the following way: - $ php composer.phar config repositories.foo vcs http://github.com/foo/bar +```sh +php composer.phar config repositories.foo vcs http://github.com/foo/bar +``` ## create-project @@ -347,7 +392,9 @@ provide a version as third argument, otherwise the latest version is used. If the directory does not currently exist, it will be created during installation. - php composer.phar create-project doctrine/orm path 2.2.* +```sh +php composer.phar create-project doctrine/orm path 2.2.* +``` It is also possible to run the command without params in a directory with an existing `composer.json` file to bootstrap a project. @@ -409,7 +456,9 @@ If you think you found a bug, or something is behaving strangely, you might want to run the `diagnose` command to perform automated checks for many common problems. - $ php composer.phar diagnose +```sh +php composer.phar diagnose +``` ## archive @@ -417,7 +466,9 @@ This command is used to generate a zip/tar archive for a given package in a given version. It can also be used to archive your entire project without excluded/ignored files. - $ php composer.phar archive vendor/package 2.0.21 --format=zip +```sh +php composer.phar archive vendor/package 2.0.21 --format=zip +``` ### Options @@ -429,7 +480,9 @@ excluded/ignored files. To get more information about a certain command, just use `help`. - $ php composer.phar help install +```sh +php composer.phar help install +``` ## Environment variables @@ -445,7 +498,9 @@ By setting the `COMPOSER` env variable it is possible to set the filename of For example: - $ COMPOSER=composer-other.json php composer.phar install +```sh +COMPOSER=composer-other.json php composer.phar install +``` ### COMPOSER_ROOT_VERSION diff --git a/doc/04-schema.md b/doc/04-schema.md index 906075372..0ce4d4fdb 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -59,14 +59,14 @@ RC suffixes can also be followed by a number. Examples: - 1.0.0 - 1.0.2 - 1.1.0 - 0.2.5 - 1.0.0-dev - 1.0.0-alpha3 - 1.0.0-beta2 - 1.0.0-RC5 +- 1.0.0 +- 1.0.2 +- 1.1.0 +- 0.2.5 +- 1.0.0-dev +- 1.0.0-alpha3 +- 1.0.0-beta2 +- 1.0.0-RC5 Optional if the package repository can infer the version from somewhere, such as the VCS tag name in the VCS repository. In that case it is also recommended @@ -113,11 +113,11 @@ searching and filtering. Examples: - logging - events - database - redis - templating +- logging +- events +- database +- redis +- templating Optional. @@ -141,19 +141,19 @@ The license of the package. This can be either a string or an array of strings. The recommended notation for the most common licenses is (alphabetical): - Apache-2.0 - BSD-2-Clause - BSD-3-Clause - BSD-4-Clause - GPL-2.0 - GPL-2.0+ - GPL-3.0 - GPL-3.0+ - LGPL-2.1 - LGPL-2.1+ - LGPL-3.0 - LGPL-3.0+ - MIT +- Apache-2.0 +- BSD-2-Clause +- BSD-3-Clause +- BSD-4-Clause +- GPL-2.0 +- GPL-2.0+ +- GPL-3.0 +- GPL-3.0+ +- LGPL-2.1 +- LGPL-2.1+ +- LGPL-3.0 +- LGPL-3.0+ +- MIT Optional, but it is highly recommended to supply this. More identifiers are listed at the [SPDX Open Source License Registry](http://www.spdx.org/licenses/). @@ -162,28 +162,33 @@ For closed-source software, you may use `"proprietary"` as the license identifie An Example: - { - "license": "MIT" - } - +```json +{ + "license": "MIT" +} +``` For a package, when there is a choice between licenses ("disjunctive license"), multiple can be specified as array. An Example for disjunctive licenses: - { - "license": [ - "LGPL-2.1", - "GPL-3.0+" - ] - } +```json +{ + "license": [ + "LGPL-2.1", + "GPL-3.0+" + ] +} +``` Alternatively they can be separated with "or" and enclosed in parenthesis; - { - "license": "(LGPL-2.1 or GPL-3.0+)" - } +```json +{ + "license": "(LGPL-2.1 or GPL-3.0+)" +} +``` Similarly when multiple licenses need to be applied ("conjunctive license"), they should be separated with "and" and enclosed in parenthesis. @@ -201,22 +206,24 @@ Each author object can have following properties: An example: - { - "authors": [ - { - "name": "Nils Adermann", - "email": "naderman@naderman.de", - "homepage": "http://www.naderman.de", - "role": "Developer" - }, - { - "name": "Jordi Boggiano", - "email": "j.boggiano@seld.be", - "homepage": "http://seld.be", - "role": "Developer" - } - ] - } +```json +{ + "authors": [ + { + "name": "Nils Adermann", + "email": "naderman@naderman.de", + "homepage": "http://www.naderman.de", + "role": "Developer" + }, + { + "name": "Jordi Boggiano", + "email": "j.boggiano@seld.be", + "homepage": "http://seld.be", + "role": "Developer" + } + ] +} +``` Optional, but highly recommended. @@ -235,12 +242,14 @@ Support information includes the following: An example: - { - "support": { - "email": "support@example.org", - "irc": "irc://irc.freenode.org/composer" - } +```json +{ + "support": { + "email": "support@example.org", + "irc": "irc://irc.freenode.org/composer" } +} +``` Optional. @@ -251,11 +260,13 @@ All of the following take an object which maps package names to Example: - { - "require": { - "monolog/monolog": "1.0.*" - } +```json +{ + "require": { + "monolog/monolog": "1.0.*" } +} +``` All links are optional fields. @@ -267,24 +278,28 @@ allow unstable packages of a dependency for example. Example: - { - "require": { - "monolog/monolog": "1.0.*@beta", - "acme/foo": "@dev" - } +```json +{ + "require": { + "monolog/monolog": "1.0.*@beta", + "acme/foo": "@dev" } +} +``` If one of your dependencies has a dependency on an unstable package you need to explicitly require it as well, along with its sufficient stability flag. Example: - { - "require": { - "doctrine/doctrine-fixtures-bundle": "dev-master", - "doctrine/data-fixtures": "@dev" - } +```json +{ + "require": { + "doctrine/doctrine-fixtures-bundle": "dev-master", + "doctrine/data-fixtures": "@dev" } +} +``` `require` and `require-dev` additionally support explicit references (i.e. commit) for dev versions to make sure they are locked to a given state, even @@ -293,12 +308,14 @@ and append the reference with `#`. Example: - { - "require": { - "monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7", - "acme/foo": "1.0.x-dev#abc123" - } +```json +{ + "require": { + "monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7", + "acme/foo": "1.0.x-dev#abc123" } +} +``` > **Note:** While this is convenient at times, it should not be how you use > packages in the long term because it comes with a technical limitation. The @@ -370,11 +387,13 @@ and not version constraints. Example: - { - "suggest": { - "monolog/monolog": "Allows more advanced logging of the application flow" - } +```json +{ + "suggest": { + "monolog/monolog": "Allows more advanced logging of the application flow" } +} +``` ### autoload @@ -403,32 +422,38 @@ key => value array which may be found in the generated file Example: - { - "autoload": { - "psr-4": { - "Monolog\\": "src/", - "Vendor\\Namespace\\": "" - } +```json +{ + "autoload": { + "psr-4": { + "Monolog\\": "src/", + "Vendor\\Namespace\\": "" } } +} +``` If you need to search for a same prefix in multiple directories, you can specify them as an array as such: - { - "autoload": { - "psr-4": { "Monolog\\": ["src/", "lib/"] } - } +```json +{ + "autoload": { + "psr-4": { "Monolog\\": ["src/", "lib/"] } } +} +``` If you want to have a fallback directory where any namespace will be looked for, you can use an empty prefix like: - { - "autoload": { - "psr-4": { "": "src/" } - } +```json +{ + "autoload": { + "psr-4": { "": "src/" } } +} +``` #### PSR-0 @@ -444,44 +469,52 @@ array which may be found in the generated file `vendor/composer/autoload_namespa Example: - { - "autoload": { - "psr-0": { - "Monolog\\": "src/", - "Vendor\\Namespace\\": "src/", - "Vendor_Namespace_": "src/" - } +```json +{ + "autoload": { + "psr-0": { + "Monolog\\": "src/", + "Vendor\\Namespace\\": "src/", + "Vendor_Namespace_": "src/" } } +} +``` If you need to search for a same prefix in multiple directories, you can specify them as an array as such: - { - "autoload": { - "psr-0": { "Monolog\\": ["src/", "lib/"] } - } +```json +{ + "autoload": { + "psr-0": { "Monolog\\": ["src/", "lib/"] } } +} +``` The PSR-0 style is not limited to namespace declarations only but may be specified right down to the class level. This can be useful for libraries with only one class in the global namespace. If the php source file is also located in the root of the package, for example, it may be declared like this: - { - "autoload": { - "psr-0": { "UniqueGlobalClass": "" } - } +```json +{ + "autoload": { + "psr-0": { "UniqueGlobalClass": "" } } +} +``` If you want to have a fallback directory where any namespace can be, you can use an empty prefix like: - { - "autoload": { - "psr-0": { "": "src/" } - } +```json +{ + "autoload": { + "psr-0": { "": "src/" } } +} +``` #### Classmap @@ -496,11 +529,13 @@ to search for classes. Example: - { - "autoload": { - "classmap": ["src/", "lib/", "Something.php"] - } +```json +{ + "autoload": { + "classmap": ["src/", "lib/", "Something.php"] } +} +``` #### Files @@ -510,11 +545,13 @@ that cannot be autoloaded by PHP. Example: - { - "autoload": { - "files": ["src/MyLibrary/functions.php"] - } +```json +{ + "autoload": { + "files": ["src/MyLibrary/functions.php"] } +} +``` ### autoload-dev (root-only) @@ -529,14 +566,16 @@ and to add it within the autoload-dev section. Example: - { - "autoload": { - "psr-4": { "MyLibrary\\": "src/" } - }, - "autoload-dev": { - "psr-4": { "MyLibrary\\Tests\\": "tests/" } - } +```json +{ + "autoload": { + "psr-4": { "MyLibrary\\": "src/" } + }, + "autoload-dev": { + "psr-4": { "MyLibrary\\Tests\\": "tests/" } } +} +``` ### include-path @@ -548,9 +587,11 @@ A list of paths which should get appended to PHP's `include_path`. Example: - { - "include-path": ["lib/"] - } +```json +{ + "include-path": ["lib/"] +} +``` Optional. @@ -574,12 +615,14 @@ it from `vendor/symfony/yaml`. To do that, `autoload` and `target-dir` are defined as follows: - { - "autoload": { - "psr-0": { "Symfony\\Component\\Yaml\\": "" } - }, - "target-dir": "Symfony/Component/Yaml" - } +```json +{ + "autoload": { + "psr-0": { "Symfony\\Component\\Yaml\\": "" } + }, + "target-dir": "Symfony/Component/Yaml" +} +``` Optional. @@ -637,47 +680,49 @@ For more information on any of these, see [Repositories](05-repositories.md). Example: - { - "repositories": [ - { - "type": "composer", - "url": "http://packages.example.com" - }, - { - "type": "composer", - "url": "https://packages.example.com", - "options": { - "ssl": { - "verify_peer": "true" - } - } - }, - { - "type": "vcs", - "url": "https://github.com/Seldaek/monolog" - }, - { - "type": "pear", - "url": "http://pear2.php.net" - }, - { - "type": "package", - "package": { - "name": "smarty/smarty", - "version": "3.1.7", - "dist": { - "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", - "type": "zip" - }, - "source": { - "url": "http://smarty-php.googlecode.com/svn/", - "type": "svn", - "reference": "tags/Smarty_3_1_7/distribution/" - } +```json +{ + "repositories": [ + { + "type": "composer", + "url": "http://packages.example.com" + }, + { + "type": "composer", + "url": "https://packages.example.com", + "options": { + "ssl": { + "verify_peer": "true" } } - ] - } + }, + { + "type": "vcs", + "url": "https://github.com/Seldaek/monolog" + }, + { + "type": "pear", + "url": "http://pear2.php.net" + }, + { + "type": "package", + "package": { + "name": "smarty/smarty", + "version": "3.1.7", + "dist": { + "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", + "type": "zip" + }, + "source": { + "url": "http://smarty-php.googlecode.com/svn/", + "type": "svn", + "reference": "tags/Smarty_3_1_7/distribution/" + } + } + } + ] +} +``` > **Note:** Order is significant here. When looking for a package, Composer will look from the first to the last repository, and pick the first match. @@ -749,11 +794,13 @@ The following options are supported: Example: - { - "config": { - "bin-dir": "bin" - } +```json +{ + "config": { + "bin-dir": "bin" } +} +``` ### scripts (root-only) @@ -769,7 +816,9 @@ Arbitrary extra data for consumption by `scripts`. This can be virtually anything. To access it from within a script event handler, you can do: - $extra = $event->getComposer()->getPackage()->getExtra(); +```php +$extra = $event->getComposer()->getPackage()->getExtra(); +``` Optional. @@ -796,11 +845,13 @@ The following options are supported: Example: - { - "archive": { - "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"] - } +```json +{ + "archive": { + "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"] } +} +``` The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`, `/foo/my.test` but it will exclude `/foo/bar/any`, `/foo/baz`, and `/my.test`. diff --git a/doc/05-repositories.md b/doc/05-repositories.md index a4e92d7ed..049a05170 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -66,16 +66,18 @@ repository URL would be `example.org`. The only required field is `packages`. The JSON structure is as follows: - { - "packages": { - "vendor/package-name": { - "dev-master": { @composer.json }, - "1.0.x-dev": { @composer.json }, - "0.0.1": { @composer.json }, - "1.0.0": { @composer.json } - } +```json +{ + "packages": { + "vendor/package-name": { + "dev-master": { @composer.json }, + "1.0.x-dev": { @composer.json }, + "0.0.1": { @composer.json }, + "1.0.0": { @composer.json } } } +} +``` The `@composer.json` marker would be the contents of the `composer.json` from that package version including as a minimum: @@ -86,14 +88,16 @@ that package version including as a minimum: Here is a minimal package definition: - { - "name": "smarty/smarty", - "version": "3.1.7", - "dist": { - "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", - "type": "zip" - } +```json +{ + "name": "smarty/smarty", + "version": "3.1.7", + "dist": { + "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", + "type": "zip" } +} +``` It may include any of the other fields specified in the [schema](04-schema.md). @@ -105,19 +109,23 @@ every time a user installs a package. The URL can be either an absolute path An example value: - { - "notify-batch": "/downloads/" - } +```json +{ + "notify-batch": "/downloads/" +} +``` For `example.org/packages.json` containing a `monolog/monolog` package, this would send a `POST` request to `example.org/downloads/` with following JSON request body: - { - "downloads": [ - {"name": "monolog/monolog", "version": "1.2.1.0"}, - ] - } +```json +{ + "downloads": [ + {"name": "monolog/monolog", "version": "1.2.1.0"}, + ] +} +``` The version field will contain the normalized representation of the version number. @@ -132,19 +140,21 @@ files. An example: - { - "includes": { - "packages-2011.json": { - "sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17" - }, - "packages-2012-01.json": { - "sha1": "897cde726f8a3918faf27c803b336da223d400dd" - }, - "packages-2012-02.json": { - "sha1": "26f911ad717da26bbcac3f8f435280d13917efa5" - } +```json +{ + "includes": { + "packages-2011.json": { + "sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17" + }, + "packages-2012-01.json": { + "sha1": "897cde726f8a3918faf27c803b336da223d400dd" + }, + "packages-2012-02.json": { + "sha1": "26f911ad717da26bbcac3f8f435280d13917efa5" } } +} +``` The SHA-1 sum of the file allows it to be cached and only re-requested if the hash changed. @@ -164,31 +174,35 @@ is an absolute path from the repository root. An example: - { - "provider-includes": { - "providers-a.json": { - "sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c" - }, - "providers-b.json": { - "sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac" - } +```json +{ + "provider-includes": { + "providers-a.json": { + "sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c" }, - "providers-url": "/p/%package%$%hash%.json" - } + "providers-b.json": { + "sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac" + } + }, + "providers-url": "/p/%package%$%hash%.json" +} +``` Those files contain lists of package names and hashes to verify the file integrity, for example: - { - "providers": { - "acme/foo": { - "sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82" - }, - "acme/bar": { - "sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233" - } +```json +{ + "providers": { + "acme/foo": { + "sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82" + }, + "acme/bar": { + "sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233" } } +} +``` The file above declares that acme/foo and acme/bar can be found in this repository, by loading the file referenced by `providers-url`, replacing @@ -225,17 +239,19 @@ point to your custom branch. For version constraint naming conventions see Example assuming you patched monolog to fix a bug in the `bugfix` branch: - { - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/igorw/monolog" - } - ], - "require": { - "monolog/monolog": "dev-bugfix" +```json +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/igorw/monolog" } + ], + "require": { + "monolog/monolog": "dev-bugfix" } +} +``` When you run `php composer.phar update`, you should get your modified version of `monolog/monolog` instead of the one from packagist. @@ -256,17 +272,19 @@ For more information [see the aliases article](articles/aliases.md). Exactly the same solution allows you to work with your private repositories at GitHub and BitBucket: - { - "require": { - "vendor/my-private-repo": "dev-master" - }, - "repositories": [ - { - "type": "vcs", - "url": "git@bitbucket.org:vendor/my-private-repo.git" - } - ] - } +```json +{ + "require": { + "vendor/my-private-repo": "dev-master" + }, + "repositories": [ + { + "type": "vcs", + "url": "git@bitbucket.org:vendor/my-private-repo.git" + } + ] +} +``` The only requirement is the installation of SSH keys for a git client. @@ -305,17 +323,19 @@ by default that code is located in `$url/trunk`, `$url/branches` and values. For example if you used capitalized names you could configure the repository like this: - { - "repositories": [ - { - "type": "vcs", - "url": "http://svn.example.org/projectA/", - "trunk-path": "Trunk", - "branches-path": "Branches", - "tags-path": "Tags" - } - ] - } +```json +{ + "repositories": [ + { + "type": "vcs", + "url": "http://svn.example.org/projectA/", + "trunk-path": "Trunk", + "branches-path": "Branches", + "tags-path": "Tags" + } + ] +} +``` If you have no branches or tags directory you can disable them entirely by setting the `branches-path` or `tags-path` to `false`. @@ -333,18 +353,20 @@ avoid conflicts. All packages are also aliased with prefix `pear-{channelAlias}/ Example using `pear2.php.net`: - { - "repositories": [ - { - "type": "pear", - "url": "http://pear2.php.net" - } - ], - "require": { - "pear-pear2.php.net/PEAR2_Text_Markdown": "*", - "pear-pear2/PEAR2_HTTP_Request": "*" +```json +{ + "repositories": [ + { + "type": "pear", + "url": "http://pear2.php.net" } + ], + "require": { + "pear-pear2.php.net/PEAR2_Text_Markdown": "*", + "pear-pear2/PEAR2_HTTP_Request": "*" } +} +``` In this case the short name of the channel is `pear2`, so the `PEAR2_HTTP_Request` package name becomes `pear-pear2/PEAR2_HTTP_Request`. @@ -387,23 +409,25 @@ To illustrate, the following example would get the `BasePackage`, `TopLevelPackage1`, and `TopLevelPackage2` packages from your PEAR repository and `IntermediatePackage` from a Github repository: - { - "repositories": [ - { - "type": "git", - "url": "https://github.com/foobar/intermediate.git" - }, - { - "type": "pear", - "url": "http://pear.foobar.repo", - "vendor-alias": "foobar" - } - ], - "require": { - "foobar/TopLevelPackage1": "*", - "foobar/TopLevelPackage2": "*" +```json +{ + "repositories": [ + { + "type": "git", + "url": "https://github.com/foobar/intermediate.git" + }, + { + "type": "pear", + "url": "http://pear.foobar.repo", + "vendor-alias": "foobar" } + ], + "require": { + "foobar/TopLevelPackage1": "*", + "foobar/TopLevelPackage2": "*" } +} +``` ### Package @@ -418,32 +442,34 @@ minimum required fields are `name`, `version`, and either of `dist` or Here is an example for the smarty template engine: - { - "repositories": [ - { - "type": "package", - "package": { - "name": "smarty/smarty", - "version": "3.1.7", - "dist": { - "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", - "type": "zip" - }, - "source": { - "url": "http://smarty-php.googlecode.com/svn/", - "type": "svn", - "reference": "tags/Smarty_3_1_7/distribution/" - }, - "autoload": { - "classmap": ["libs/"] - } +```json +{ + "repositories": [ + { + "type": "package", + "package": { + "name": "smarty/smarty", + "version": "3.1.7", + "dist": { + "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", + "type": "zip" + }, + "source": { + "url": "http://smarty-php.googlecode.com/svn/", + "type": "svn", + "reference": "tags/Smarty_3_1_7/distribution/" + }, + "autoload": { + "classmap": ["libs/"] } } - ], - "require": { - "smarty/smarty": "3.1.*" } + ], + "require": { + "smarty/smarty": "3.1.*" } +} +``` Typically you would leave the source part off, as you don't really need it. @@ -512,25 +538,30 @@ of the times they are private. To simplify maintenance, one can simply use a repository of type `artifact` with a folder containing ZIP archives of those private packages: - { - "repositories": [ - { - "type": "artifact", - "url": "path/to/directory/with/zips/" - } - ], - "require": { - "private-vendor-one/core": "15.6.2", - "private-vendor-two/connectivity": "*", - "acme-corp/parser": "10.3.5" +```json +{ + "repositories": [ + { + "type": "artifact", + "url": "path/to/directory/with/zips/" } + ], + "require": { + "private-vendor-one/core": "15.6.2", + "private-vendor-two/connectivity": "*", + "acme-corp/parser": "10.3.5" } +} +``` Each zip artifact is just a ZIP archive with `composer.json` in root folder: - $ unzip -l acme-corp-parser-10.3.5.zip - composer.json - ... +```sh +unzip -l acme-corp-parser-10.3.5.zip + +composer.json +... +``` If there are two archives with different versions of a package, they are both imported. When an archive with a newer version is added in the artifact folder @@ -542,13 +573,14 @@ update to the latest version. You can disable the default Packagist repository by adding this to your `composer.json`: - { - "repositories": [ - { - "packagist": false - } - ] - } - +```json +{ + "repositories": [ + { + "packagist": false + } + ] +} +``` ← [Schema](04-schema.md) | [Community](06-community.md) → diff --git a/doc/articles/aliases.md b/doc/articles/aliases.md index 9e8f3da89..2b436322f 100644 --- a/doc/articles/aliases.md +++ b/doc/articles/aliases.md @@ -28,13 +28,15 @@ someone will want the latest master dev version. Thus, Composer allows you to alias your `dev-master` branch to a `1.0.x-dev` version. It is done by specifying a `branch-alias` field under `extra` in `composer.json`: - { - "extra": { - "branch-alias": { - "dev-master": "1.0.x-dev" - } +```json +{ + "extra": { + "branch-alias": { + "dev-master": "1.0.x-dev" } } +} +``` The branch version must begin with `dev-` (non-comparable version), the alias must be a comparable dev version (i.e. start with numbers, and end with @@ -68,18 +70,20 @@ You are using `symfony/monolog-bundle` which requires `monolog/monolog` version Just add this to your project's root `composer.json`: - { - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/you/monolog" - } - ], - "require": { - "symfony/monolog-bundle": "2.0", - "monolog/monolog": "dev-bugfix as 1.0.x-dev" +```json +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/you/monolog" } + ], + "require": { + "symfony/monolog-bundle": "2.0", + "monolog/monolog": "dev-bugfix as 1.0.x-dev" } +} +``` That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub and alias it to `1.0.x-dev`. diff --git a/doc/articles/custom-installers.md b/doc/articles/custom-installers.md index feeebe52c..98a9a2212 100644 --- a/doc/articles/custom-installers.md +++ b/doc/articles/custom-installers.md @@ -34,13 +34,15 @@ An example use-case would be: An example composer.json of such a template package would be: - { - "name": "phpdocumentor/template-responsive", - "type": "phpdocumentor-template", - "require": { - "phpdocumentor/template-installer-plugin": "*" - } +```json +{ + "name": "phpdocumentor/template-responsive", + "type": "phpdocumentor-template", + "require": { + "phpdocumentor/template-installer-plugin": "*" } +} +``` > **IMPORTANT**: to make sure that the template installer is present at the > time the template package is installed, template packages should require @@ -70,20 +72,22 @@ requirements: Example: - { - "name": "phpdocumentor/template-installer-plugin", - "type": "composer-plugin", - "license": "MIT", - "autoload": { - "psr-0": {"phpDocumentor\\Composer": "src/"} - }, - "extra": { - "class": "phpDocumentor\\Composer\\TemplateInstallerPlugin" - }, - "require": { - "composer-plugin-api": "1.0.0" - } +```json +{ + "name": "phpdocumentor/template-installer-plugin", + "type": "composer-plugin", + "license": "MIT", + "autoload": { + "psr-0": {"phpDocumentor\\Composer": "src/"} + }, + "extra": { + "class": "phpDocumentor\\Composer\\TemplateInstallerPlugin" + }, + "require": { + "composer-plugin-api": "1.0.0" } +} +``` ### The Plugin class @@ -96,20 +100,24 @@ autoloadable and matches the `extra.class` element in the package definition. Example: - namespace phpDocumentor\Composer; +```php +getInstallationManager()->addInstaller($installer); - } + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); } +} +``` ### The Custom Installer class @@ -138,39 +146,43 @@ source for the exact signature): Example: - namespace phpDocumentor\Composer; +```php +getPrettyName(), 0, 23); - if ('phpdocumentor/template-' !== $prefix) { - throw new \InvalidArgumentException( - 'Unable to install template, phpdocumentor templates ' - .'should always start their package name with ' - .'"phpdocumentor/template-"' - ); - } - - return 'data/templates/'.substr($package->getPrettyName(), 23); + $prefix = substr($package->getPrettyName(), 0, 23); + if ('phpdocumentor/template-' !== $prefix) { + throw new \InvalidArgumentException( + 'Unable to install template, phpdocumentor templates ' + .'should always start their package name with ' + .'"phpdocumentor/template-"' + ); } - /** - * {@inheritDoc} - */ - public function supports($packageType) - { - return 'phpdocumentor-template' === $packageType; - } + return 'data/templates/'.substr($package->getPrettyName(), 23); } + /** + * {@inheritDoc} + */ + public function supports($packageType) + { + return 'phpdocumentor-template' === $packageType; + } +} +``` + The example demonstrates that it is quite simple to extend the [`Composer\Installer\LibraryInstaller`][5] class to strip a prefix (`phpdocumentor/template-`) and use the remaining part to assemble a completely diff --git a/doc/articles/handling-private-packages-with-satis.md b/doc/articles/handling-private-packages-with-satis.md index 01fe63494..69da38196 100644 --- a/doc/articles/handling-private-packages-with-satis.md +++ b/doc/articles/handling-private-packages-with-satis.md @@ -25,34 +25,38 @@ repositories you defined. The default file Satis looks for is `satis.json` in the root of the repository. - { - "name": "My Repository", - "homepage": "http://packages.example.org", - "repositories": [ - { "type": "vcs", "url": "http://github.com/mycompany/privaterepo" }, - { "type": "vcs", "url": "http://svn.example.org/private/repo" }, - { "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" } - ], - "require-all": true - } +```json +{ + "name": "My Repository", + "homepage": "http://packages.example.org", + "repositories": [ + { "type": "vcs", "url": "http://github.com/mycompany/privaterepo" }, + { "type": "vcs", "url": "http://svn.example.org/private/repo" }, + { "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" } + ], + "require-all": true +} +``` If you want to cherry pick which packages you want, you can list all the packages you want to have in your satis repository inside the classic composer `require` key, using a `"*"` constraint to make sure all versions are selected, or another constraint if you want really specific versions. - { - "repositories": [ - { "type": "vcs", "url": "http://github.com/mycompany/privaterepo" }, - { "type": "vcs", "url": "http://svn.example.org/private/repo" }, - { "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" } - ], - "require": { - "company/package": "*", - "company/package2": "*", - "company/package3": "2.0.0" - } +```json +{ + "repositories": [ + { "type": "vcs", "url": "http://github.com/mycompany/privaterepo" }, + { "type": "vcs", "url": "http://svn.example.org/private/repo" }, + { "type": "vcs", "url": "http://github.com/mycompany/privaterepo2" } + ], + "require": { + "company/package": "*", + "company/package2": "*", + "company/package3": "2.0.0" } +} +``` Once you did this, you just run `php bin/satis build `. For example `php bin/satis build config.json web/` would read the `config.json` @@ -80,14 +84,16 @@ everything should work smoothly. You don't need to copy all your repositories in every project anymore. Only that one unique repository that will update itself. - { - "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ], - "require": { - "company/package": "1.2.0", - "company/package2": "1.5.2", - "company/package3": "dev-master" - } +```json +{ + "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ], + "require": { + "company/package": "1.2.0", + "company/package2": "1.5.2", + "company/package3": "dev-master" } +} +``` ### Security @@ -97,39 +103,43 @@ connection options for the server. Example using a custom repository using SSH (requires the SSH2 PECL extension): - { - "repositories": [ - { - "type": "composer", - "url": "ssh2.sftp://example.org", - "options": { - "ssh2": { - "username": "composer", - "pubkey_file": "/home/composer/.ssh/id_rsa.pub", - "privkey_file": "/home/composer/.ssh/id_rsa" - } +```json +{ + "repositories": [ + { + "type": "composer", + "url": "ssh2.sftp://example.org", + "options": { + "ssh2": { + "username": "composer", + "pubkey_file": "/home/composer/.ssh/id_rsa.pub", + "privkey_file": "/home/composer/.ssh/id_rsa" } } - ] - } + } + ] +} +``` > **Tip:** See [ssh2 context options](http://www.php.net/manual/en/wrappers.ssh2.php#refsect1-wrappers.ssh2-options) for more information. Example using HTTP over SSL using a client certificate: - { - "repositories": [ - { - "type": "composer", - "url": "https://example.org", - "options": { - "ssl": { - "local_cert": "/home/composer/.ssl/composer.pem" - } +```json +{ + "repositories": [ + { + "type": "composer", + "url": "https://example.org", + "options": { + "ssl": { + "local_cert": "/home/composer/.ssl/composer.pem" } } - ] - } + } + ] +} +``` > **Tip:** See [ssl context options](http://www.php.net/manual/en/context.ssl.php) for more information. @@ -145,14 +155,16 @@ Subversion) will not have downloads available and thus installations usually tak To enable your satis installation to create downloads for all (Git, Mercurial and Subversion) your packages, add the following to your `satis.json`: - { - "archive": { - "directory": "dist", - "format": "tar", - "prefix-url": "https://amazing.cdn.example.org", - "skip-dev": true - } +```json +{ + "archive": { + "directory": "dist", + "format": "tar", + "prefix-url": "https://amazing.cdn.example.org", + "skip-dev": true } +} +``` #### Options explained @@ -178,10 +190,11 @@ It is possible to make satis automatically resolve and add all dependencies for with the Downloads functionality to have a complete local mirror of packages. Just add the following to your `satis.json`: - - { - "require-dependencies": true - } +```json +{ + "require-dependencies": true +} +``` When searching for packages, satis will attempt to resolve all the required packages from the listed repositories. Therefore, if you are requiring a package from Packagist, you will need to define it in your `satis.json`. diff --git a/doc/articles/plugins.md b/doc/articles/plugins.md index 75706f711..65884fd18 100644 --- a/doc/articles/plugins.md +++ b/doc/articles/plugins.md @@ -35,13 +35,15 @@ current composer plugin API version is 1.0.0. For example - { - "name": "my/plugin-package", - "type": "composer-plugin", - "require": { - "composer-plugin-api": "1.0.0" - } +```json +{ + "name": "my/plugin-package", + "type": "composer-plugin", + "require": { + "composer-plugin-api": "1.0.0" } +} +``` ### Plugin Class @@ -54,20 +56,24 @@ be read and all internal objects and state can be manipulated as desired. Example: - namespace phpDocumentor\Composer; +```php +getInstallationManager()->addInstaller($installer); - } + $installer = new TemplateInstaller($io, $composer); + $composer->getInstallationManager()->addInstaller($installer); } +} +``` ## Event Handler @@ -88,46 +94,50 @@ The events available for plugins are: Example: - namespace Naderman\Composer\AWS; +```php +composer = $composer; + $this->io = $io; + } - public function activate(Composer $composer, IOInterface $io) - { - $this->composer = $composer; - $this->io = $io; - } + public static function getSubscribedEvents() + { + return array( + PluginEvents::PRE_FILE_DOWNLOAD => array( + array('onPreFileDownload', 0) + ), + ); + } - public static function getSubscribedEvents() - { - return array( - PluginEvents::PRE_FILE_DOWNLOAD => array( - array('onPreFileDownload', 0) - ), - ); - } + public function onPreFileDownload(PreFileDownloadEvent $event) + { + $protocol = parse_url($event->getProcessedUrl(), PHP_URL_SCHEME); - public function onPreFileDownload(PreFileDownloadEvent $event) - { - $protocol = parse_url($event->getProcessedUrl(), PHP_URL_SCHEME); - - if ($protocol === 's3') { - $awsClient = new AwsClient($this->io, $this->composer->getConfig()); - $s3RemoteFilesystem = new S3RemoteFilesystem($this->io, $event->getRemoteFilesystem()->getOptions(), $awsClient); - $event->setRemoteFilesystem($s3RemoteFilesystem); - } + if ($protocol === 's3') { + $awsClient = new AwsClient($this->io, $this->composer->getConfig()); + $s3RemoteFilesystem = new S3RemoteFilesystem($this->io, $event->getRemoteFilesystem()->getOptions(), $awsClient); + $event->setRemoteFilesystem($s3RemoteFilesystem); } } +} +``` ## Using Plugins diff --git a/doc/articles/scripts.md b/doc/articles/scripts.md index ff9c8b5bc..ccd8caf44 100644 --- a/doc/articles/scripts.md +++ b/doc/articles/scripts.md @@ -67,48 +67,52 @@ autoload functionality. Script definition example: - { - "scripts": { - "post-update-cmd": "MyVendor\\MyClass::postUpdate", - "post-package-install": [ - "MyVendor\\MyClass::postPackageInstall" - ], - "post-install-cmd": [ - "MyVendor\\MyClass::warmCache", - "phpunit -c app/" - ] - } +```json +{ + "scripts": { + "post-update-cmd": "MyVendor\\MyClass::postUpdate", + "post-package-install": [ + "MyVendor\\MyClass::postPackageInstall" + ], + "post-install-cmd": [ + "MyVendor\\MyClass::warmCache", + "phpunit -c app/" + ] } +} +``` Using the previous definition example, here's the class `MyVendor\MyClass` that might be used to execute the PHP callbacks: - getComposer(); - // do stuff - } - - public static function postPackageInstall(Event $event) - { - $installedPackage = $event->getOperation()->getPackage(); - // do stuff - } - - public static function warmCache(Event $event) - { - // make cache toasty - } + $composer = $event->getComposer(); + // do stuff } + public static function postPackageInstall(Event $event) + { + $installedPackage = $event->getOperation()->getPackage(); + // do stuff + } + + public static function warmCache(Event $event) + { + // make cache toasty + } +} +``` + When an event is fired, Composer's internal event handler receives a `Composer\Script\Event` object, which is passed as the first argument to your PHP callback. This `Event` object has getters for other contextual objects: @@ -122,6 +126,8 @@ PHP callback. This `Event` object has getters for other contextual objects: If you would like to run the scripts for an event manually, the syntax is: - $ composer run-script [--dev] [--no-dev] script +```sh +composer run-script [--dev] [--no-dev] script +``` For example `composer run-script post-install-cmd` will run any **post-install-cmd** scripts that have been defined. diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md index c1c5e2d61..838b7611c 100644 --- a/doc/articles/troubleshooting.md +++ b/doc/articles/troubleshooting.md @@ -63,12 +63,14 @@ You can fix this by aliasing version 0.11 to 0.1: composer.json: - { - "require": { - "A": "0.2", - "B": "0.11 as 0.1" - } +```json +{ + "require": { + "A": "0.2", + "B": "0.11 as 0.1" } +} +``` See [aliases](aliases.md) for more information. @@ -76,7 +78,7 @@ See [aliases](aliases.md) for more information. If composer shows memory errors on some commands: - PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...> +`PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...>` The PHP `memory_limit` should be increased. @@ -86,17 +88,23 @@ The PHP `memory_limit` should be increased. To get the current `memory_limit` value, run: - php -r "echo ini_get('memory_limit').PHP_EOL;" +```sh +php -r "echo ini_get('memory_limit').PHP_EOL;" +``` Try increasing the limit in your `php.ini` file (ex. `/etc/php5/cli/php.ini` for Debian-like systems): - ; Use -1 for unlimited or define an explicit value like 512M - memory_limit = -1 +```ini +; Use -1 for unlimited or define an explicit value like 512M +memory_limit = -1 +``` Or, you can increase the limit with a command-line argument: - php -d memory_limit=-1 composer.phar <...> +```sh +php -d memory_limit=-1 composer.phar <...> +``` ## "The system cannot find the path specified" (Windows) @@ -123,18 +131,23 @@ Now Composer should install/update without asking for authentication. ## proc_open(): fork failed errors If composer shows proc_open() fork failed on some commands: - PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar +`PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar` This could be happening because the VPS runs out of memory and has no Swap space enabled. - [root@my_tiny_vps htdocs]# free -m - total used free shared buffers cached - Mem: 2048 357 1690 0 0 237 - -/+ buffers/cache: 119 1928 - Swap: 0 0 0 +```sh +free -m + +total used free shared buffers cached +Mem: 2048 357 1690 0 0 237 +-/+ buffers/cache: 119 1928 +Swap: 0 0 0 +``` To enable the swap you can use for example: - /bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024 - /sbin/mkswap /var/swap.1 - /sbin/swapon /var/swap.1 +```sh +/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024 +/sbin/mkswap /var/swap.1 +/sbin/swapon /var/swap.1 +``` diff --git a/doc/articles/vendor-binaries.md b/doc/articles/vendor-binaries.md index b258dccb7..75087b5b8 100644 --- a/doc/articles/vendor-binaries.md +++ b/doc/articles/vendor-binaries.md @@ -20,10 +20,11 @@ It is defined by adding the `bin` key to a project's `composer.json`. It is specified as an array of files so multiple binaries can be added for any given project. - { - "bin": ["bin/my-script", "bin/my-other-script"] - } - +```json +{ + "bin": ["bin/my-script", "bin/my-other-script"] +} +``` ## What does defining a vendor binary in composer.json do? @@ -46,22 +47,26 @@ symlink is created from each dependency's binaries to `vendor/bin`. Say package `my-vendor/project-a` has binaries setup like this: - { - "name": "my-vendor/project-a", - "bin": ["bin/project-a-bin"] - } +```json +{ + "name": "my-vendor/project-a", + "bin": ["bin/project-a-bin"] +} +``` Running `composer install` for this `composer.json` will not do anything with `bin/project-a-bin`. Say project `my-vendor/project-b` has requirements setup like this: - { - "name": "my-vendor/project-b", - "require": { - "my-vendor/project-a": "*" - } +```json +{ + "name": "my-vendor/project-b", + "require": { + "my-vendor/project-a": "*" } +} +``` Running `composer install` for this `composer.json` will look at all of project-b's dependencies and install them to `vendor/bin`. @@ -95,11 +100,13 @@ Yes, there are two ways an alternate vendor binary location can be specified: An example of the former looks like this: - { - "config": { - "bin-dir": "scripts" - } +```json +{ + "config": { + "bin-dir": "scripts" } +} +``` Running `composer install` for this `composer.json` will result in all of the vendor binaries being installed in `scripts/` instead of diff --git a/doc/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md b/doc/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md index b5956ca19..bd38d1e40 100644 --- a/doc/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md +++ b/doc/faqs/how-do-i-install-a-package-to-a-custom-path-for-my-framework.md @@ -11,13 +11,15 @@ This is common if your package is intended for a specific framework such as CakePHP, Drupal or WordPress. Here is an example composer.json file for a WordPress theme: - { - "name": "you/themename", - "type": "wordpress-theme", - "require": { - "composer/installers": "~1.0" - } +```json +{ + "name": "you/themename", + "type": "wordpress-theme", + "require": { + "composer/installers": "~1.0" } +} +``` Now when your theme is installed with Composer it will be placed into `wp-content/themes/themename/` folder. Check the @@ -30,13 +32,15 @@ useful example would be for a Drupal multisite setup where the package should be installed into your sites subdirectory. Here we are overriding the install path for a module that uses composer/installers: - { - "extra": { - "installer-paths": { - "sites/example.com/modules/{$name}": ["vendor/package"] - } +```json +{ + "extra": { + "installer-paths": { + "sites/example.com/modules/{$name}": ["vendor/package"] } } +} +``` Now the package would be installed to your folder location, rather than the default composer/installers determined location.