# composer.json This chapter will explain all of the fields available in `composer.json`. ## JSON schema We have a [JSON schema](http://json-schema.org) that documents the format and can also be used to validate your `composer.json`. In fact, it is used by the `validate` command. You can find it at: [`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). ## Root Package The root package is the package defined by the `composer.json` at the root of your project. It is the main `composer.json` that defines your project requirements. Certain fields only apply when in the root package context. One example of this is the `config` field. Only the root package can define configuration. The config of dependencies is ignored. This makes the `config` field `root-only`. If you clone one of those dependencies to work on it, then that package is the root package. The `composer.json` is identical, but the context is different. ## Properties ### name The name of the package. It consists of vendor name and project name, separated by `/`. Examples: * monolog/monolog * igorw/event-source Required for published packages (libraries). ### description A short description of the package. Usually this is just one line long. Required for published packages (libraries). ### version The version of the package. This must follow the format of `X.Y.Z` with an optional suffix of `-dev`, `alphaN`, `-betaN` or `-RCN`. Examples: 1.0.0 1.0.2 1.1.0 0.2.5 1.0.0-dev 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 to omit it. ### type The type of the package. It defaults to `library`. Package types are used for custom installation logic. If you have a package that needs some special logic, you can define a custom type. This could be a `symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will all be specific to certain projects, and they will need to provide an installer capable of installing packages of that type. Out of the box, composer supports two types: - **library:** This is the default. It will simply copy the files to `vendor`. - **metapackage:** An empty package that contains requirements and will trigger their installation, but contains no files and will not write anything to the filesystem. As such, it does not require a dist or source key to be installable. - **composer-installer:** A package of type `composer-installer` provides an installer for other packages that have a custom type. Read more in the [dedicated article](articles/custom-installers.md). Only use a custom type if you need custom logic during installation. It is recommended to omit this field and have it just default to `library`. ### keywords An array of keywords that the package is related to. These can be used for searching and filtering. Examples: logging events database redis templating Optional. ### homepage An URL to the website of the project. Optional. ### time Release date of the version. Must be in `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` format. Optional. ### license 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.0 LGPL-2.0+ 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/). An Example: { "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.0", "GPL-3.0+" ] } Alternatively they can be separated with "or" and enclosed in brackets; { "license": "(LGPL-2.0 or GPL-3.0+)" } Similarly when multiple licenses need to be applied ("conjunctive license"), they should be separated with "and" and enclosed in brackets. ### authors The authors of the package. This is an array of objects. Each author object can have following properties: * **name:** The author's name. Usually his real name. * **email:** The author's email address. * **homepage:** An URL to the author's website. * **role:** The authors' role in the project (e.g. developer or translator) 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" } ] } Optional, but highly recommended. ### Package links All of the following take an object which maps package names to [version constraints](01-basic-usage.md#package-versions). Example: { "require": { "monolog/monolog": "1.0.*" } } All links are optional fields. `require` and `require-dev` additionally support stability flags (root-only). These allow you to further restrict or expand the stability of a package beyond the scope of the [minimum-stability](#minimum-stability) setting. You can apply them to a constraint, or just apply them to an empty constraint if you want to allow unstable packages of a dependency's dependency for example. Example: { "require": { "monolog/monolog": "1.0.*@beta" "acme/foo": "@dev" } } `require` and `require-dev` additionally support explicit references (i.e. commit) for dev versions to make sure they are blocked to a given state, even when you run update. These only work if you explicitly require a dev version and append the reference with `#`. Note that while this is convenient at times, it should not really be how you use packages in the long term. You should always try to switch to tagged releases as soon as you can, especially if the project you work on will not be touched for a while. Example: { "require": { "monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7" "acme/foo": "1.0.x-dev#abc123" } } #### require Lists packages required by this package. The package will not be installed unless those requirements can be met. #### require-dev Lists packages required for developing this package, or running tests, etc. They are installed if install or update is ran with `--dev`. Packages listed here and their dependencies can not overrule the resolution found with the packages listed in require. This is even true if a different version of a package would be installable and solve the conflict. The reason is that `install --dev` produces the exact same state as just `install`, apart from the additional dev packages. If you run into such a conflict, you can specify the conflicting package in the require section and require the right version number to resolve the conflict. #### conflict Lists packages that conflict with this version of this package. They will not be allowed to be installed together with your package. #### replace Lists packages that are replaced by this package. This allows you to fork a package, publish it under a different name with its own version numbers, while packages requiring the original package continue to work with your fork because it replaces the original package. This is also useful for packages that contain sub-packages, for example the main symfony/symfony package contains all the Symfony Components which are also available as individual packages. If you require the main package it will automatically fulfill any requirement of one of the individual components, since it replaces them. Caution is advised when using replace for the sub-package purpose explained above. You should then typically only replace using `self.version` as a version constraint, to make sure the main package only replaces the sub-packages of that exact version, and not any other version, which would be incorrect. #### provide List of other packages that are provided by this package. This is mostly useful for common interfaces. A package could depend on some virtual `logger` package, any library that implements this logger interface would simply list it in `provide`. ### suggest Suggested packages that can enhance or work well with this package. These are just informational and are displayed after the package is installed, to give your users a hint that they could add more packages, even though they are not strictly required. The format is like package links above, except that the values are free text and not version constraints. Example: { "suggest": { "monolog/monolog": "Allows more advanced logging of the application flow" } } ### autoload Autoload mapping for a PHP autoloader. Currently [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) autoloading and classmap generation are supported. PSR-0 is the recommended way though since it offers greater flexibility (no need to regenerate the autoloader when you add classes). Under the `psr-0` key you define a mapping from namespaces to paths, relative to the package root. Note that this also supports the PEAR-style convention. Example: { "autoload": { "psr-0": { "Monolog": "src/", "Vendor\\Namespace": "src/", "Pear_Style": "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/"] } } } If you want to have a fallback directory where any namespace can be, you can use an empty prefix like: { "autoload": { "psr-0": { "": "src/" } } } You can use the classmap generation support to define autoloading for all libraries that do not follow PSR-0. To configure this you specify all directories or files to search for classes. Example: { "autoload: { "classmap": ["src/", "lib/", "Something.php"] } } ### include-path > **DEPRECATED**: This is only present to support legacy projects, and all new code > should preferably use autoloading. As such it is a deprecated practice, but the > feature itself will not likely disappear from Composer. A list of paths which should get appended to PHP's `include_path`. Example: { "include-path": ["lib/"] } Optional. ### target-dir Defines the installation target. In case the package root is below the namespace declaration you cannot autoload properly. `target-dir` solves this problem. An example is Symfony. There are individual packages for the components. The Yaml component is under `Symfony\Component\Yaml`. The package root is that `Yaml` directory. To make autoloading possible, we need to make sure that it is not installed into `vendor/symfony/yaml`, but instead into `vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load 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" } Optional. ### minimum-stability (root-only) This defines the default behavior for filtering packages by stability. This defaults to `dev` but in the future will be switched to `stable`. As such if you rely on a default of `dev` you should specify it in your file to avoid surprises. All versions of each package is checked for stability, and those that are less stable than the `minimum-stability` setting will be ignored when resolving your project dependencies. Specific changes to the stability requirements of a given package can be done in `require` or `require-dev` (see [package links](#package-links)). ### repositories (root-only) Custom package repositories to use. By default composer just uses the packagist repository. By specifying repositories you can get packages from elsewhere. Repositories are not resolved recursively. You can only add them to your main `composer.json`. Repository declarations of dependencies' `composer.json`s are ignored. The following repository types are supported: * **composer:** A composer repository is simply a `packages.json` file served via HTTP, that contains a list of `composer.json` objects with additional `dist` and/or `source` information. * **vcs:** The version control system repository can fetch packages from git, svn and hg repositories. * **pear:** With this you can import any pear repository into your composer project. * **package:** If you depend on a project that does not have any support for composer whatsoever you can define the package inline using a `package` repository. You basically just inline the `composer.json` object. For more information on any of these, see [Repositories](05-repositories.md). Example: { "repositories": [ { "type": "composer", "url": "http://packages.example.com" }, { "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. By default Packagist is added last which means that custom repositories can override packages from it. ### config (root-only) A set of configuration options. It is only used for projects. The following options are supported: * **vendor-dir:** Defaults to `vendor`. You can install dependencies into a different directory if you want to. * **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they will be symlinked into this directory. * **process-timeout:** Defaults to `300`. The duration processes like git clones can run before Composer assumes they died out. You may need to make this higher if you have a slow connection or huge vendors. * **notify-on-install:** Defaults to `true`. Composer allows repositories to define a notification URL, so that they get notified whenever a package from that repository is installed. This option allows you to disable that behaviour. Example: { "config": { "bin-dir": "bin" } } ### scripts (root-only) Composer allows you to hook into various parts of the installation process through the use of scripts. See [Scripts](articles/scripts.md) for events details and examples. ### extra 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(); Optional. ### bin A set of files that should be treated as binaries and symlinked into the `bin-dir` (from config). See [Vendor Bins](articles/vendor-bins.md) for more details. Optional. ← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) →