The composer.json schema
Introduction
In this tutorial, we will look at the Json schema of the composer.json file. Here we will explain the fields available in the composer.json file.
#Json Schema: This documents the format of the composer.json file. It is used to validate our composer.json file when the “validate” composer command is used.
#Root Package: The composer.json file defines the root package at the root of our project. The root package is “root-only” . This implies that the config field defined in this package is ignored in our dependencies
#Properties: This consist of the following:
#name: The name of our package. The name comprises of the vendor name and project name, which is separated by “/”. They are recommended to all be in lower caps. Example: “hellocomposer/hellocomposer”. This is essential for published libraries.
#description: This is a short description about the package, and usually it does not exceed on line long. This is essential for published libraries.
#version: In most cases this is not required, and thus should be skipped especially when our packages are to be hosted in a version control system like Git.
If they must be included, it should appear in this format “A.B.C” or “vA.B.C” with an optional suffix of “-dev”,”-patch”,”-p”,”-alpha”,”-a”,”-beta”,”-b”.
#type: this defaults to “library”, but this could be changed to “project”, “metapackage” or “composer-plugin”. It is recommended to omit this field unless your project will require a custom type of logic during installation.
#keywords: These are just an array of words that our package is related to. Eg tags, events, compose etc.
#hompage: The website URL of our project. This field is also an optional field.
#readme: A relative part to access the read me file. This field is an optional field.
#time: This Is the release date of the package, which could also be omitted.
#license: The licensing of our package. This field is optional, but if available, it could be a string, or an array of strings as shown in the following code snippet:
{
"license": "SCI"
}
The above code snippet shows the license as a string. When two or more licenses are required in a package, commonly known as disjunctive license, an array of license could be given as shown
{
"license": [
"LGPL-2.1-only",
"GPL-3.0-or-later"
]
}
Alternatively, they could also be separated with “or” as shown
{
"license": "(LGPL-2.1-only or GPL-3.0-or-later)"
}
#authors: This author detail is an array of objects which could contain one of the following details: name, email, homepage and role. This field thought optional is highly recommended. An example is shown in the code snippet below:
{
"authors": [
{
"name": "Ogbonna Vitalis",
"email": "[email protected]",
"homepage": "http://www.w3resource.com",
"role": "Developer"
},
{
"name": "Jordi Bogdanov",
"email": "[email protected] ",
"homepage": "https:// w3resource.com ",
"role": "Developer"
}
]
}
#support: These includes various links to get support about the library. It includes: email, issues, forum, wiki, irc, source, docs, rss and chat. This field is also optional.
{
"support": {
"email": "[email protected]",
"irc": "irc://irc.freenode.org/composer"
}
}
#Package links: This takes an object, which maps the package name to the package version via version constraints. This includes:
#require: This lists all the packages required by the package. A package will not successfully install unless all the packages specified here are downloaded.
{
"require": {
"monolog/monolog": "1.0.*"
}
}
#require-dev: This list only the packages required for developing the package or for running unit tests. Packages here are not installed by default.
{
"require": {
"monolog/monolog": "1.0.*@beta",
"acme/foo": "@dev"
}
}
#conflict: This lists packages that conflict with the version of our package. These packages will not be allowed to be installed in our package.
#replace: This is used to list packages that would be replaced. This makes ir possible to publish a forked package under a different name while all the packages depending on the original package works well with the forked package, since this forked package replaces the original package.
#provide: This where the list of all the packages provided by this package is listed. It is useful for common interfaces. Assuming a package depends on some virtual logger package, then any package that implements this logger interface would be listed in the “provide”.
#suggest: Packages that can enhance or work well with this package are listed here. This are displayed after our package, telling the users some of the additional packages they could install. This is also an optional field. Example:
{
"suggest": {
"monolog/monolog": "Allows more advanced logging",
"ext-xml": "Needed for XML support"
}
}
#autoload: This provides for a PHP autoloader. The two types of auto load is “PSR-4” and “PSR-0”
#PSR-4”: Under the “psr-4” key. In PSR-4 namespaces are mapped to paths, relative to the package root. When autoloading a class like “Vita\\Foo\\Baz “ pointing to a directory scr/ means that the autoloader will look for a file with the name scr/Bar/Baz.php and include it if present. This is preferred to the PSR-O style where the prefix Vita\\ is not present in the file path.
Namespaces prefixes are to end in “\\” to avoid conflicts between similar prefixes. The trailing backlashes solve the problem conflicts making class names like “Foo\\” and “Foosaa\\” distinct. Example
{
"autoload": {
"psr-4": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": ""
}
}
}
#PSR-0: In the PSR-0, keys are mapped from name spaces to the path, relative to the package root. PSR-0 supports the PEAR-style non-namespaced convention.
Example:
{
"autoload": {
"psr-0": {
"Monolog\\": "src/",
"Vendor\\Namespace\\": "src/",
"Vendor_Namespace_": "src/"
}
}
}
#classmap: The classmap references all combined during install\update into a single array of keys and values. This generated class map can be found in “vendor/composer/autoload_classmap.php”. This map is generated by scanning all the “.php” and “.inc” files in the given directories.
{
"autoload": {
"classmap": ["src/", "lib/", "Something.php"]
}
}
#files: This is filed enables the requirement of files explicitly on requests. The are extremely impoetant for PHP functions that cannot be autoloaded by PHP.
{
"autoload": {
"files": ["src/MyLibrary/functions.php"]
}
}
#minimum-stability: This determines the minimum stability status of packages to be installed. The default is stable. It is recommended to always specify this if you relay on the dev package.
#prefer-stable: When enabled, the composer prefers more stable packages, over non stable ones. To enable, use( “prefer-stable” :true)
#repositories: This defines the custom repositories to be used. Since by default, the composer uses Packagist, defining these repositories will make composer search for packages in the specified repositories.
"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": "https://pear2.php.net"
},
{
"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/"
}
}
}
]
}
In the listing of repositories above, the order is very important, as composer searches from top to bottom, and includes files found on the go. By default, Packagist is included last do that others an overwrite it.
We have looked at the composer.json schema and the fields described in them, feel free to use these fields in your packages.
Previous:
The concept of composer packages and repositories
Next:
Composer Command Line Interface and Commands(Part 1)
- Weekly Trends and Language Statistics
- Weekly Trends and Language Statistics