splitting up some docs, closes #4155
Rob Bast
parent
d0ff01698d
commit
016cc7ee19
202
doc/04-schema.md
202
doc/04-schema.md
|
|
@ -272,7 +272,7 @@ Example:
|
|||
|
||||
All links are optional fields.
|
||||
|
||||
`require` and `require-dev` additionally support stability flags (root-only).
|
||||
`require` and `require-dev` additionally support stability flags ([root-only](04-schema.md#root-package)).
|
||||
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
|
||||
|
|
@ -335,7 +335,7 @@ aliases article](articles/aliases.md).
|
|||
Lists packages required by this package. The package will not be installed
|
||||
unless those requirements can be met.
|
||||
|
||||
#### require-dev <span>(root-only)</span>
|
||||
#### require-dev <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
Lists packages required for developing this package, or running
|
||||
tests, etc. The dev requirements of the root package are installed by default.
|
||||
|
|
@ -555,7 +555,7 @@ Example:
|
|||
}
|
||||
```
|
||||
|
||||
### autoload-dev <span>(root-only)</span>
|
||||
### autoload-dev <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
This section allows to define autoload rules for development purposes.
|
||||
|
||||
|
|
@ -628,7 +628,7 @@ To do that, `autoload` and `target-dir` are defined as follows:
|
|||
|
||||
Optional.
|
||||
|
||||
### minimum-stability <span>(root-only)</span>
|
||||
### minimum-stability <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
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
|
||||
|
|
@ -643,7 +643,7 @@ a given package can be done in `require` or `require-dev` (see
|
|||
Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`,
|
||||
and `stable`.
|
||||
|
||||
### prefer-stable <span>(root-only)</span>
|
||||
### prefer-stable <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
When this is enabled, Composer will prefer more stable packages over unstable
|
||||
ones when finding compatible stable packages is possible. If you require a
|
||||
|
|
@ -652,7 +652,7 @@ selected granted that the minimum-stability allows for it.
|
|||
|
||||
Use `"prefer-stable": true` to enable.
|
||||
|
||||
### repositories <span>(root-only)</span>
|
||||
### repositories <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
Custom package repositories to use.
|
||||
|
||||
|
|
@ -731,194 +731,4 @@ 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 <span>(root-only)</span>
|
||||
|
||||
A set of configuration options. It is only used for projects.
|
||||
|
||||
The following options are supported:
|
||||
|
||||
* **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.
|
||||
* **use-include-path:** Defaults to `false`. If true, the Composer autoloader
|
||||
will also look for classes in the PHP include path.
|
||||
* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or
|
||||
`auto`. This option allows you to set the install method Composer will prefer to
|
||||
use.
|
||||
* **store-auths:** What to do after prompting for authentication, one of:
|
||||
`true` (always store), `false` (do not store) and `"prompt"` (ask every
|
||||
time), defaults to `"prompt"`.
|
||||
* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to
|
||||
use when cloning from github.com, in priority order. You can reconfigure it to
|
||||
for example prioritize the https protocol if you are behind a proxy or have somehow
|
||||
bad performances with the git protocol.
|
||||
* **github-oauth:** A list of domain names and oauth keys. For example using
|
||||
`{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken`
|
||||
to access private repositories on github and to circumvent the low IP-based
|
||||
rate limiting of their API.
|
||||
[Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
|
||||
on how to get an OAuth token for GitHub.
|
||||
* **http-basic:** A list of domain names and username/passwords to authenticate
|
||||
against them. For example using
|
||||
`{"example.org": {"username": "alice", "password": "foo"}` as the value of this
|
||||
option will let composer authenticate against example.org.
|
||||
* **platform:** Lets you fake platform packages (PHP and extensions) so that
|
||||
you can emulate a production env or define your target platform in the
|
||||
config. e.g. `{"php": "5.4", "ext-something": "4.0"}`.
|
||||
* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a
|
||||
different directory if you want to. `$HOME` and `~` will be replaced by your
|
||||
home directory's path in vendor-dir and all `*-dir` options below.
|
||||
* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they
|
||||
will be symlinked into this directory.
|
||||
* **cache-dir:** Defaults to `$COMPOSER_HOME/cache` on unix systems and
|
||||
`C:\Users\<user>\AppData\Local\Composer` on Windows. Stores all the caches
|
||||
used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
|
||||
* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives
|
||||
of packages.
|
||||
* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata
|
||||
for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`.
|
||||
* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for
|
||||
loading VCS repository metadata for the `git`/`hg` types and to speed up installs.
|
||||
* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all
|
||||
dist (zip, tar, ..) packages that it downloads. Those are purged after six
|
||||
months of being unused by default. This option allows you to tweak this
|
||||
duration (in seconds) or disable it completely by setting it to 0.
|
||||
* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all
|
||||
dist (zip, tar, ..) packages that it downloads. When the garbage collection
|
||||
is periodically ran, this is the maximum size the cache will be able to use.
|
||||
Older (less used) files will be removed first until the cache fits.
|
||||
* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader
|
||||
will not be prepended to existing autoloaders. This is sometimes required to fix
|
||||
interoperability issues with other autoloaders.
|
||||
* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for
|
||||
the generated Composer autoloader. When null a random one will be generated.
|
||||
* **optimize-autoloader** Defaults to `false`. Always optimize when dumping
|
||||
the autoloader.
|
||||
* **classmap-authoritative:** Defaults to `false`. If true, the composer
|
||||
autoloader will not scan the filesystem for classes that are not found in
|
||||
the class map. Implies 'optimize-autoloader'.
|
||||
* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in
|
||||
github mode. This is used for GitHub Enterprise setups.
|
||||
* **github-expose-hostname:** Defaults to `true`. If set to false, the OAuth
|
||||
tokens created to access the github API will have a date instead of the
|
||||
machine hostname.
|
||||
* **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.
|
||||
* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or
|
||||
`"stash"`. This option allows you to set the default style of handling dirty
|
||||
updates when in non-interactive mode. `true` will always discard changes in
|
||||
vendors, while `"stash"` will try to stash and reapply. Use this for CI
|
||||
servers or deploy scripts if you tend to have modified vendors.
|
||||
* **archive-format:** Defaults to `tar`. Composer allows you to add a default
|
||||
archive format when the workflow needs to create a dedicated archiving format.
|
||||
* **archive-dir:** Defaults to `.`. Composer allows you to add a default
|
||||
archive directory when the workflow needs to create a dedicated archiving format.
|
||||
Or for easier development between modules.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"bin-dir": "bin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Authentication-related config options like `http-basic` and
|
||||
> `github-oauth` can also be specified inside a `auth.json` file that goes
|
||||
> besides your `composer.json`. That way you can gitignore it and every
|
||||
> developer can place their own credentials in there.
|
||||
|
||||
### scripts <span>(root-only)</span>
|
||||
|
||||
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:
|
||||
|
||||
```php
|
||||
$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 Binaries](articles/vendor-binaries.md) for more details.
|
||||
|
||||
Optional.
|
||||
|
||||
### archive
|
||||
|
||||
A set of options for creating package archives.
|
||||
|
||||
The following options are supported:
|
||||
|
||||
* **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:
|
||||
|
||||
```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`.
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"non-feature-branches": ["latest-.*"]
|
||||
}
|
||||
```
|
||||
|
||||
Then "composer show -s" will give you `versions : * dev-latest-testing`.
|
||||
|
||||
Optional.
|
||||
|
||||
← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) →
|
||||
|
|
|
|||
|
|
@ -616,4 +616,4 @@ You can disable the default Packagist repository by adding this to your
|
|||
}
|
||||
```
|
||||
|
||||
← [Schema](04-schema.md) | [Community](06-community.md) →
|
||||
← [Schema](04-schema.md) | [Config](06-config.md) →
|
||||
|
|
|
|||
|
|
@ -0,0 +1,195 @@
|
|||
# Config
|
||||
|
||||
This chapter will describe the `config` section of the `composer.json` schema.
|
||||
|
||||
### config <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
A set of configuration options. It is only used for projects.
|
||||
|
||||
The following options are supported:
|
||||
|
||||
* **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.
|
||||
* **use-include-path:** Defaults to `false`. If true, the Composer autoloader
|
||||
will also look for classes in the PHP include path.
|
||||
* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or
|
||||
`auto`. This option allows you to set the install method Composer will prefer to
|
||||
use.
|
||||
* **store-auths:** What to do after prompting for authentication, one of:
|
||||
`true` (always store), `false` (do not store) and `"prompt"` (ask every
|
||||
time), defaults to `"prompt"`.
|
||||
* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to
|
||||
use when cloning from github.com, in priority order. You can reconfigure it to
|
||||
for example prioritize the https protocol if you are behind a proxy or have somehow
|
||||
bad performances with the git protocol.
|
||||
* **github-oauth:** A list of domain names and oauth keys. For example using
|
||||
`{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken`
|
||||
to access private repositories on github and to circumvent the low IP-based
|
||||
rate limiting of their API.
|
||||
[Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
|
||||
on how to get an OAuth token for GitHub.
|
||||
* **http-basic:** A list of domain names and username/passwords to authenticate
|
||||
against them. For example using
|
||||
`{"example.org": {"username": "alice", "password": "foo"}` as the value of this
|
||||
option will let composer authenticate against example.org.
|
||||
* **platform:** Lets you fake platform packages (PHP and extensions) so that
|
||||
you can emulate a production env or define your target platform in the
|
||||
config. e.g. `{"php": "5.4", "ext-something": "4.0"}`.
|
||||
* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a
|
||||
different directory if you want to. `$HOME` and `~` will be replaced by your
|
||||
home directory's path in vendor-dir and all `*-dir` options below.
|
||||
* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they
|
||||
will be symlinked into this directory.
|
||||
* **cache-dir:** Defaults to `$COMPOSER_HOME/cache` on unix systems and
|
||||
`C:\Users\<user>\AppData\Local\Composer` on Windows. Stores all the caches
|
||||
used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
|
||||
* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives
|
||||
of packages.
|
||||
* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata
|
||||
for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`.
|
||||
* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for
|
||||
loading VCS repository metadata for the `git`/`hg` types and to speed up installs.
|
||||
* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all
|
||||
dist (zip, tar, ..) packages that it downloads. Those are purged after six
|
||||
months of being unused by default. This option allows you to tweak this
|
||||
duration (in seconds) or disable it completely by setting it to 0.
|
||||
* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all
|
||||
dist (zip, tar, ..) packages that it downloads. When the garbage collection
|
||||
is periodically ran, this is the maximum size the cache will be able to use.
|
||||
Older (less used) files will be removed first until the cache fits.
|
||||
* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader
|
||||
will not be prepended to existing autoloaders. This is sometimes required to fix
|
||||
interoperability issues with other autoloaders.
|
||||
* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for
|
||||
the generated Composer autoloader. When null a random one will be generated.
|
||||
* **optimize-autoloader** Defaults to `false`. Always optimize when dumping
|
||||
the autoloader.
|
||||
* **classmap-authoritative:** Defaults to `false`. If true, the composer
|
||||
autoloader will not scan the filesystem for classes that are not found in
|
||||
the class map. Implies 'optimize-autoloader'.
|
||||
* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in
|
||||
github mode. This is used for GitHub Enterprise setups.
|
||||
* **github-expose-hostname:** Defaults to `true`. If set to false, the OAuth
|
||||
tokens created to access the github API will have a date instead of the
|
||||
machine hostname.
|
||||
* **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.
|
||||
* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or
|
||||
`"stash"`. This option allows you to set the default style of handling dirty
|
||||
updates when in non-interactive mode. `true` will always discard changes in
|
||||
vendors, while `"stash"` will try to stash and reapply. Use this for CI
|
||||
servers or deploy scripts if you tend to have modified vendors.
|
||||
* **archive-format:** Defaults to `tar`. Composer allows you to add a default
|
||||
archive format when the workflow needs to create a dedicated archiving format.
|
||||
* **archive-dir:** Defaults to `.`. Composer allows you to add a default
|
||||
archive directory when the workflow needs to create a dedicated archiving format.
|
||||
Or for easier development between modules.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"bin-dir": "bin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Authentication-related config options like `http-basic` and
|
||||
> `github-oauth` can also be specified inside a `auth.json` file that goes
|
||||
> besides your `composer.json`. That way you can gitignore it and every
|
||||
> developer can place their own credentials in there.
|
||||
|
||||
### scripts <span>(root-only)</span>
|
||||
|
||||
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:
|
||||
|
||||
```php
|
||||
$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 Binaries](articles/vendor-binaries.md) for more details.
|
||||
|
||||
Optional.
|
||||
|
||||
### archive
|
||||
|
||||
A set of options for creating package archives.
|
||||
|
||||
The following options are supported:
|
||||
|
||||
* **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:
|
||||
|
||||
```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`.
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"non-feature-branches": ["latest-.*"]
|
||||
}
|
||||
```
|
||||
|
||||
Then "composer show -s" will give you `versions : * dev-latest-testing`.
|
||||
|
||||
Optional.
|
||||
|
||||
← [Repositories](05-repositories.md) | [Community](07-community.md) →
|
||||
|
|
@ -6,7 +6,9 @@ contributing.
|
|||
## Contributing
|
||||
|
||||
If you would like to contribute to composer, please read the
|
||||
[README](https://github.com/composer/composer).
|
||||
[README](https://github.com/composer/composer) and
|
||||
[CONTRIBUTING](https://github.com//composer/composer/blob/master/CONTRIBUTING.md)
|
||||
documents.
|
||||
|
||||
The most important guidelines are described as follows:
|
||||
|
||||
|
|
@ -31,4 +33,4 @@ for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for developme
|
|||
Stack Overflow has a growing collection of
|
||||
[Composer related questions](https://stackoverflow.com/questions/tagged/composer-php).
|
||||
|
||||
← [Repositories](05-repositories.md)
|
||||
← [Config](06-config.md)
|
||||
Loading…
Reference in New Issue