- JSON schema
- Root Package
-
Properties
- name
- description
- version
- type
- keywords
- homepage
- readme
- time
- license
- authors
- support
- funding
- Package links
- autoload
- autoload-dev (root-only)
- include-path
- target-dir
- minimum-stability (root-only)
- prefer-stable (root-only)
- repositories (root-only)
- config (root-only)
- scripts (root-only)
- extra
- bin
- archive
- abandoned
- _comment
- non-feature-branches
The composer.json schema#
This chapter will explain all of the fields available in composer.json
.
JSON schema#
We have a JSON schema 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: https://getcomposer.org/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
.
Note: A package can be the root package or not, depending on the context. For example, if your project depends on the
monolog
library, your project is the root package. However, if you clonemonolog
from GitHub in order to fix a bug in it, thenmonolog
is the root package.
Properties#
name#
The name of the package. It consists of vendor name and project name,
separated by /
. Examples:
- monolog/monolog
- igorw/event-source
The name must be lowercase and consist of words separated by -
, .
or _
.
The complete name should match ^[a-z0-9]([_.-]?[a-z0-9]+)*/[a-z0-9](([_.]|-{1,2})?[a-z0-9]+)*$
.
The name
property is required for published packages (libraries).
Note: Before Composer version 2.0, a name could contain any character, including white spaces.
description#
A short description of the package. Usually this is one line long.
Required for published packages (libraries).
version#
The version of the package. In most cases this is not required and should be omitted (see below).
This must follow the format of X.Y.Z
or vX.Y.Z
with an optional suffix
of -dev
, -patch
(-p
), -alpha
(-a
), -beta
(-b
) or -RC
.
The patch, alpha, beta and 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
- v2.0.4-p1
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.
Note: Packagist uses VCS repositories, so the statement above is very much true for Packagist as well. Specifying the version yourself will most likely end up creating problems at some point due to human error.
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-cms-extension
. 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 four types:
- library: This is the default. It will copy the files to
vendor
. - project: This denotes a project rather than a library. For example application shells like the Symfony standard edition, CMSs like the Silverstripe installer or full fledged applications distributed as packages. This can for example be used by IDEs to provide listings of projects to initialize when creating a new workspace.
- 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-plugin: A package of type
composer-plugin
may provide an installer for other packages that have a custom type. Read more in the dedicated article. - php-ext and php-ext-zend: These names are reserved for PHP extension packages which are written in C. Do not use these types for packages written in PHP.
Only use a custom type if you need custom logic during installation. It is
recommended to omit this field and have it 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
Note: Some special keywords trigger
composer require
without the--dev
option to prompt users if they would like to add these packages torequire-dev
instead ofrequire
. These are:dev
,testing
,static analysis
.Note: The range of characters allowed inside the string is restricted to unicode letters or numbers, space
" "
, dot.
, underscore_
and dash-
. (Regex:'{^[\p{N}\p{L} ._-]+$}u'
) Using other characters will emit a warning when runningcomposer validate
and will cause the package to fail updating on Packagist.org.
Optional.
homepage#
A URL to the website of the project.
Optional.
readme#
A relative path to the readme document. Defaults to README.md
.
This is mainly useful for packages not on GitHub, as for GitHub packages Packagist.org will use the readme API to fetch the one detected by GitHub.
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-only / GPL-2.0-or-later
- GPL-3.0-only / GPL-3.0-or-later
- LGPL-2.1-only / LGPL-2.1-or-later
- LGPL-3.0-only / LGPL-3.0-or-later
- MIT
Optional, but it is highly recommended to supply this. More identifiers are listed at the SPDX Open Source License Registry.
Note: For closed-source software, you may use
"proprietary"
as the license identifier.
An Example:
{
"license": "MIT"
}
For a package, when there is a choice between licenses ("disjunctive license"), multiple can be specified as an array.
An Example for disjunctive licenses:
{
"license": [
"LGPL-2.1-only",
"GPL-3.0-or-later"
]
}
Alternatively they can be separated with "or" and enclosed in parentheses;
{
"license": "(LGPL-2.1-only or GPL-3.0-or-later)"
}
Similarly, when multiple licenses need to be applied ("conjunctive license"), they should be separated with "and" and enclosed in parentheses.
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 their real name.
- email: The author's email address.
- homepage: URL to the author's website.
- role: The author's role in the project (e.g. developer or translator)
An example:
{
"authors": [
{
"name": "Nils Adermann",
"email": "naderman@naderman.de",
"homepage": "https://www.naderman.de",
"role": "Developer"
},
{
"name": "Jordi Boggiano",
"email": "j.boggiano@seld.be",
"homepage": "https://seld.be",
"role": "Developer"
}
]
}
Optional, but highly recommended.
support#
Various information to get support about the project.
Support information includes the following:
- email: Email address for support.
- issues: URL to the issue tracker.
- forum: URL to the forum.
- wiki: URL to the wiki.
- irc: IRC channel for support, as irc://server/channel.
- source: URL to browse or download the sources.
- docs: URL to the documentation.
- rss: URL to the RSS feed.
- chat: URL to the chat channel.
- security: URL to the vulnerability disclosure policy (VDP).
An example:
{
"support": {
"email": "support@example.org",
"irc": "irc://irc.freenode.org/composer"
}
}
Optional.
funding#
A list of URLs to provide funding to the package authors for maintenance and development of new functionality.
Each entry consists of the following
- type: The type of funding, or the platform through which funding can be provided, e.g. patreon, opencollective, tidelift or github.
- url: URL to a website with details, and a way to fund the package.
An example:
{
"funding": [
{
"type": "patreon",
"url": "https://www.patreon.com/phpdoctrine"
},
{
"type": "tidelift",
"url": "https://tidelift.com/subscription/pkg/packagist-doctrine_doctrine-bundle"
},
{
"type": "other",
"url": "https://www.doctrine-project.org/sponsorship.html"
}
]
}
Optional.
Package links#
All of the following take an object which maps package names to versions of the package via version constraints. Read more about versions here.
Example:
{
"require": {
"monolog/monolog": "1.0.*"
}
}
All links are optional fields.
require
and require-dev
additionally support stability flags (root-only).
They take the form "constraint@stability flag".
These allow you to further restrict or expand the stability of a package beyond
the scope of the minimum-stability setting. You can apply
them to a constraint, or apply them to an empty constraint if you want to
allow unstable packages of a dependency for example.
Example:
{
"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:
Assuming doctrine/doctrine-fixtures-bundle
requires "doctrine/data-fixtures": "dev-master"
then inside the root composer.json you need to add the second line below to allow dev
releases for the doctrine/data-fixtures
package :
{
"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
when you run update. These only work if you explicitly require a dev version
and append the reference with #<ref>
. This is also a
root-only feature and will be ignored in
dependencies.
Example:
{
"require": {
"monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7",
"acme/foo": "1.0.x-dev#abc123"
}
}
Note: This feature has severe technical limitations, as the composer.json metadata will still be read from the branch name you specify before the hash. You should therefore only use this as a temporary solution during development to remediate transient issues, until you can switch to tagged releases. The Composer team does not actively support this feature and will not accept bug reports related to it.
It is also possible to inline-alias a package constraint so that it matches a constraint that it otherwise would not. For more information see the aliases article.
require
and require-dev
also support references to specific PHP versions
and PHP extensions your project needs to run successfully.
Example:
{
"require": {
"php": ">=7.4",
"ext-mbstring": "*"
}
}
Note: It is important to list PHP extensions your project requires. Not all PHP installations are created equal: some may miss extensions you may consider as standard (such as
ext-mysqli
which is not installed by default in Fedora/CentOS minimal installation systems). Failure to list required PHP extensions may lead to a bad user experience: Composer will install your package without any errors but it will then fail at run-time. Thecomposer show --platform
command lists all PHP extensions available on your system. You may use it to help you compile the list of extensions you use and require. Alternatively you may use third party tools to analyze your project for the list of extensions used.
require#
Map of packages required by this package. The package will not be installed unless those requirements can be met.
require-dev (root-only)#
Map of packages required for developing this package, or running
tests, etc. The dev requirements of the root package are installed by default.
Both install
or update
support the --no-dev
option that prevents dev
dependencies from being installed.
conflict#
Map of packages that conflict with this version of this package. They will not be allowed to be installed together with your package.
Note that when specifying ranges like <1.0 >=1.1
in a conflict
link,
this will state a conflict with all versions that are less than 1.0 and equal
or newer than 1.1 at the same time, which is probably not what you want. You
probably want to go for <1.0 || >=1.1
in this case.
replace#
Map of 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#
Map of packages that are provided by this package. This is mostly
useful for implementations of common interfaces. A package could depend on
some virtual package e.g. psr/log-implementation
, any library that implements
this logger interface would list it in provide
. Implementors can then
be found on Packagist.org.
Using provide
with the name of an actual package rather than a virtual one
implies that the code of that package is also shipped, in which case replace
is generally a better choice. A common convention for packages providing an
interface and relying on other packages to provide an implementation (for
instance the PSR interfaces) is to use a -implementation
suffix for the
name of the virtual package corresponding to the interface package.
suggest#
Suggested packages that can enhance or work well with this package. These are 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",
"ext-xml": "Needed to support XML format in class Foo"
}
}
autoload#
Autoload mapping for a PHP autoloader.
PSR-4
and PSR-0
autoloading, classmap
generation and files
includes are supported.
PSR-4 is the recommended way since it offers greater ease of use (no need to regenerate the autoloader when you add classes).
PSR-4#
Under the psr-4
key you define a mapping from namespaces to paths, relative to the
package root. When autoloading a class like Foo\\Bar\\Baz
a namespace prefix
Foo\\
pointing to a directory src/
means that the autoloader will look for a
file named src/Bar/Baz.php
and include it if present. Note that as opposed to
the older PSR-0 style, the prefix (Foo\\
) is not present in the file path.
Namespace prefixes must end in \\
to avoid conflicts between similar prefixes.
For example Foo
would match classes in the FooBar
namespace so the trailing
backslashes solve the problem: Foo\\
and FooBar\\
are distinct.
The PSR-4 references are all combined, during install/update, into a single
key => value array which may be found in the generated file
vendor/composer/autoload_psr4.php
.
Example:
{
"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/"] }
}
}
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/" }
}
}
PSR-0#
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 non-namespaced convention.
Please note namespace declarations should end in \\
to make sure the autoloader
responds exactly. For example Foo
would match in FooBar
so the trailing
backslashes solve the problem: Foo\\
and FooBar\\
are distinct.
The PSR-0 references are all combined, during install/update, into a single key => value
array which may be found in the generated file vendor/composer/autoload_namespaces.php
.
Example:
{
"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/"] }
}
}
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": "" }
}
}
If you want to have a fallback directory where any namespace can be, you can use an empty prefix like:
{
"autoload": {
"psr-0": { "": "src/" }
}
}
Classmap#
The classmap
references are all combined, during install/update, into a single
key => value array which may be found in the generated file
vendor/composer/autoload_classmap.php
. This map is built by scanning for
classes in all .php
and .inc
files in the given directories/files.
You can use the classmap generation support to define autoloading for all libraries that do not follow PSR-0/4. To configure this you specify all directories or files to search for classes.
Example:
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
}
Wildcards (*
) are also supported in a classmap paths, and expand to match any directory name:
Example:
{
"autoload": {
"classmap": ["src/addons/*/lib/", "3rd-party/*", "Something.php"]
}
}
Files#
If you want to require certain files explicitly on every request then you can use
the files
autoloading mechanism. This is useful if your package includes PHP functions
that cannot be autoloaded by PHP.
Example:
{
"autoload": {
"files": ["src/MyLibrary/functions.php"]
}
}
Files autoload rules are included whenever vendor/autoload.php
is included, right after
the autoloader is registered. The order of inclusion depends on package dependencies so that
if package A depends on B, files in package B will be included first to ensure package B is fully
initialized and ready to be used when files from package A are included.
If two packages have the same amount of dependents or no dependencies, the order is alphabetical.
Files from the root package are always loaded last, and you cannot use files autoloading
yourself to override functions from your dependencies. If you want to achieve that we recommend
you include your own functions before including Composer's vendor/autoload.php
.
Exclude files from classmaps#
If you want to exclude some files or folders from the classmap you can use the exclude-from-classmap
property.
This might be useful to exclude test classes in your live environment, for example, as those will be skipped
from the classmap even when building an optimized autoloader.
The classmap generator will ignore all files in the paths configured here. The paths are absolute from the package
root directory (i.e. composer.json location), and support *
to match anything but a slash, and **
to
match anything. **
is implicitly added to the end of the paths.
Example:
{
"autoload": {
"exclude-from-classmap": ["/Tests/", "/test/", "/tests/"]
}
}
Optimizing the autoloader#
The autoloader can have quite a substantial impact on your request time (50-100ms per request in large frameworks using a lot of classes). See the article about optimizing the autoloader for more details on how to reduce this impact.
autoload-dev (root-only)#
This section allows defining autoload rules for development purposes.
Classes needed to run the test suite should not be included in the main autoload rules to avoid polluting the autoloader in production and when other people use your package as a dependency.
Therefore, it is a good idea to rely on a dedicated path for your unit tests and to add it within the autoload-dev section.
Example:
{
"autoload": {
"psr-4": { "MyLibrary\\": "src/" }
},
"autoload-dev": {
"psr-4": { "MyLibrary\\Tests\\": "tests/" }
}
}
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#
DEPRECATED: This is only present to support legacy PSR-0 style autoloading, and all new code should preferably use PSR-4 without target-dir and projects using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead.
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 stable
, so if you rely on a dev
package, you should specify
it in your file to avoid surprises.
All versions of each package are checked for stability, and those that are less
stable than the minimum-stability
setting will be ignored when resolving
your project dependencies. (Note that you can also specify stability requirements
on a per-package basis using stability flags in the version constraints that you
specify in a require
block (see package links for more details).
Available options (in order of stability) are dev
, alpha
, beta
, RC
,
and stable
.
prefer-stable (root-only)#
When this is enabled, Composer will prefer more stable packages over unstable ones when finding compatible stable packages is possible. If you require a dev version or only alphas are available for a package, those will still be selected granted that the minimum-stability allows for it.
Use "prefer-stable": true
to enable.
repositories (root-only)#
Custom package repositories to use.
By default Composer only 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 a
packages.json
file served via the network (HTTP, FTP, SSH), that contains a list ofcomposer.json
objects with additionaldist
and/orsource
information. Thepackages.json
file is loaded using a PHP stream. You can set extra options on that stream using theoptions
parameter. - vcs: The version control system repository can fetch packages from git, svn, fossil and hg repositories.
- 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 inline thecomposer.json
object.
For more information on any of these, see Repositories.
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": "package",
"package": {
"name": "smarty/smarty",
"version": "3.1.7",
"dist": {
"url": "https://www.smarty.net/files/Smarty-3.1.7.zip",
"type": "zip"
},
"source": {
"url": "https://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.
Using JSON object notation is also possible. However, JSON key/value pairs are to be considered unordered so consistent behaviour cannot be guaranteed.
{
"repositories": {
"foo": {
"type": "composer",
"url": "http://packages.foo.com"
}
}
}
config (root-only)#
A set of configuration options. It is only used for projects. See Config for a description of each individual option.
scripts (root-only)#
Composer allows you to hook into various parts of the installation process through the use of scripts.
See Scripts 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 made available
into the bin-dir
(from config).
See Vendor Binaries for more details.
Optional.
archive#
A set of options for creating package archives.
The following options are supported:
- name: Allows configuring base name for archive.
By default (if not configured, and
--file
is not passed as command-line argument),preg_replace('#[^a-z0-9-_]#i', '-', name)
is used.
Example:
{
"name": "org/strangeName",
"archive": {
"name": "Strange_name"
}
}
- exclude: Allows configuring a list of patterns for excluded paths. The pattern syntax matches .gitignore files. A leading exclamation mark (!) will result in any matching files to be included even if a previous pattern excluded them. A leading slash will only match at the beginning of the project relative path. An asterisk will not expand to a directory separator.
Example:
{
"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
.
Optional.
abandoned#
Indicates whether this package has been abandoned.
It can be boolean or a package name/URL pointing to a recommended alternative.
Examples:
Use "abandoned": true
to indicate this package is abandoned.
Use "abandoned": "monolog/monolog"
to indicate this package is abandoned, and that
the recommended alternative is monolog/monolog
.
Defaults to false.
Optional.
_comment#
Top level key used as a place to store comments (it can be a string or array of strings).
{
"_comment": [
"The package foo/bar was required for business logic",
"Remove package foo/baz when removing foo/bar"
]
}
Defaults to empty.
Optional.
non-feature-branches#
A list of regex patterns of branch names that are non-numeric (e.g. "latest" or something), that will NOT be handled as feature branches. This is an array of strings.
If you have non-numeric branch names, for example like "latest", "current", "latest-stable" or something, that do not look like a version number, then Composer handles such branches as feature branches. This means it searches for parent branches, that look like a version or ends at special branches (like master), and the root package version number becomes the version of the parent branch or at least master or something.
To handle non-numeric named branches as versions instead of searching for a parent branch with a valid version or special branch name like master, you can set patterns for branch names that should be handled as dev version branches.
This is really helpful when you have dependencies using "self.version", so that not dev-master, but the same branch is installed (in the example: latest-testing).
An example:
If you have a testing branch, that is heavily maintained during a testing phase and is
deployed to your staging environment, normally composer show -s
will give you versions : * dev-master
.
If you configure latest-.*
as a pattern for non-feature-branches like this:
{
"non-feature-branches": ["latest-.*"]
}
Then composer show -s
will give you versions : * dev-latest-testing
.
Optional.
← Command-line interface | Repositories →
Found a typo? Something is wrong in this documentation? Fork and edit it!