Merge pull request #4171 from alcohol/split-schema-documentation
splitting up some docs, closes #4155pull/4178/head
Jordi Boggiano
commit
c43a39f733
|
|
@ -188,23 +188,23 @@ dependency in the `require` field.
|
|||
|
||||
## Publishing to packagist
|
||||
|
||||
Alright, so now you can publish packages. But specifying the vcs repository
|
||||
Alright, so now you can publish packages. But specifying the VCS repository
|
||||
every time is cumbersome. You don't want to force all your users to do that.
|
||||
|
||||
The other thing that you may have noticed is that we did not specify a package
|
||||
repository for `monolog/monolog`. How did that work? The answer is packagist.
|
||||
repository for `monolog/monolog`. How did that work? The answer is Packagist.
|
||||
|
||||
[Packagist](https://packagist.org/) is the main package repository for
|
||||
Composer, and it is enabled by default. Anything that is published on
|
||||
packagist is available automatically through Composer. Since monolog
|
||||
Packagist is available automatically through Composer. Since monolog
|
||||
[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend
|
||||
on it without having to specify any additional repositories.
|
||||
|
||||
If we wanted to share `hello-world` with the world, we would publish it on
|
||||
packagist as well. Doing so is really easy.
|
||||
Packagist as well. Doing so is really easy.
|
||||
|
||||
You simply hit the big "Submit Package" button and sign up. Then you submit
|
||||
the URL to your VCS repository, at which point packagist will start crawling
|
||||
the URL to your VCS repository, at which point Packagist will start crawling
|
||||
it. Once it is done, your package will be available to anyone.
|
||||
|
||||
← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) →
|
||||
|
|
|
|||
|
|
@ -64,30 +64,31 @@ 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
|
||||
everyone using the library will get the same versions of the dependencies.
|
||||
|
||||
If there is no `composer.lock` file, composer will create one after dependency
|
||||
If there is no `composer.lock` file, Composer will create one after dependency
|
||||
resolution.
|
||||
|
||||
### Options
|
||||
|
||||
* **--prefer-source:** There are two ways of downloading a package: `source`
|
||||
and `dist`. For stable versions composer will use the `dist` by default.
|
||||
and `dist`. For stable versions Composer will use the `dist` by default.
|
||||
The `source` is a version control repository. If `--prefer-source` is
|
||||
enabled, composer will install from `source` if there is one. This is
|
||||
enabled, Composer will install from `source` if there is one. This is
|
||||
useful if you want to make a bugfix to a project and get a local git
|
||||
clone of the dependency directly.
|
||||
* **--prefer-dist:** Reverse of `--prefer-source`, composer will install
|
||||
* **--prefer-dist:** Reverse of `--prefer-source`, Composer will install
|
||||
from `dist` if possible. This can speed up installs substantially on build
|
||||
servers and other use cases where you typically do not run updates of the
|
||||
vendors. It is also a way to circumvent problems with git if you do not
|
||||
have a proper setup.
|
||||
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||
requirements and force the installation even if the local machine does not
|
||||
fulfill these. See also the `platform` [config option](04-schema.md#config).
|
||||
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||
* **--dry-run:** If you want to run through an installation without actually
|
||||
installing a package, you can use `--dry-run`. This will simulate the
|
||||
installation and show you what would happen.
|
||||
* **--dev:** Install packages listed in `require-dev` (this is the default behavior).
|
||||
* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader generation skips the `autoload-dev` rules.
|
||||
* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader
|
||||
generation skips the `autoload-dev` rules.
|
||||
* **--no-autoloader:** Skips autoloader generation.
|
||||
* **--no-scripts:** Skips execution of scripts defined in `composer.json`.
|
||||
* **--no-plugins:** Disables plugins.
|
||||
|
|
@ -127,7 +128,7 @@ php composer.phar update vendor/*
|
|||
* **--prefer-dist:** Install packages from `dist` when available.
|
||||
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||
requirements and force the installation even if the local machine does not
|
||||
fulfill these. See also the `platform` [config option](04-schema.md#config).
|
||||
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||
* **--dry-run:** Simulate the command without actually doing anything.
|
||||
* **--dev:** Install packages listed in `require-dev` (this is the default behavior).
|
||||
* **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader generation skips the `autoload-dev` rules.
|
||||
|
|
@ -171,7 +172,7 @@ php composer.phar require vendor/package:2.* vendor/package2:dev-master
|
|||
* **--prefer-dist:** Install packages from `dist` when available.
|
||||
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||
requirements and force the installation even if the local machine does not
|
||||
fulfill these. See also the `platform` [config option](04-schema.md#config).
|
||||
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||
* **--dev:** Add packages to `require-dev`.
|
||||
* **--no-update:** Disables the automatic update of the dependencies.
|
||||
* **--no-progress:** Removes the progress display that can mess with some
|
||||
|
|
@ -195,7 +196,7 @@ uninstalled.
|
|||
### Options
|
||||
* **--ignore-platform-reqs:** ignore `php`, `hhvm`, `lib-*` and `ext-*`
|
||||
requirements and force the installation even if the local machine does not
|
||||
fulfill these. See also the `platform` [config option](04-schema.md#config).
|
||||
fulfill these. See also the [`platform`](06-config.md#platform) config option.
|
||||
* **--dev:** Remove packages from `require-dev`.
|
||||
* **--no-update:** Disables the automatic update of the dependencies.
|
||||
* **--no-progress:** Removes the progress display that can mess with some
|
||||
|
|
@ -326,7 +327,7 @@ php composer.phar validate
|
|||
|
||||
### Options
|
||||
|
||||
* **--no-check-all:** Whether or not composer do a complete validation.
|
||||
* **--no-check-all:** Whether or not Composer does a complete validation.
|
||||
|
||||
## status
|
||||
|
||||
|
|
@ -351,7 +352,7 @@ vendor/seld/jsonlint:
|
|||
|
||||
## self-update
|
||||
|
||||
To update composer itself to the latest version, just run the `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.
|
||||
|
||||
```sh
|
||||
|
|
@ -364,7 +365,7 @@ If you would like to instead update to a specific release simply specify it:
|
|||
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)),
|
||||
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
|
||||
|
||||
```sh
|
||||
|
|
@ -374,11 +375,12 @@ sudo composer self-update
|
|||
### Options
|
||||
|
||||
* **--rollback (-r):** Rollback to the last version you had installed.
|
||||
* **--clean-backups:** Delete old backups during an update. This makes the current version of composer the only backup available after the update.
|
||||
* **--clean-backups:** Delete old backups during an update. This makes the
|
||||
current version of Composer the only backup available after the update.
|
||||
|
||||
## config
|
||||
|
||||
The `config` command allows you to edit some basic composer settings in either
|
||||
The `config` command allows you to edit some basic Composer settings in either
|
||||
the local composer.json file or the global config.json file.
|
||||
|
||||
```sh
|
||||
|
|
@ -393,8 +395,7 @@ php composer.phar config --list
|
|||
configuration value. For settings that can take an array of values (like
|
||||
`github-protocols`), more than one setting-value arguments are allowed.
|
||||
|
||||
See the [config schema section](04-schema.md#config) for valid configuration
|
||||
options.
|
||||
See the [Config](06-config.md) chapter for valid configuration options.
|
||||
|
||||
### Options
|
||||
|
||||
|
|
@ -424,7 +425,7 @@ php composer.phar config repositories.foo vcs https://github.com/foo/bar
|
|||
## create-project
|
||||
|
||||
You can use Composer to create new projects from an existing package. This is
|
||||
the equivalent of doing a git clone/svn checkout followed by a composer install
|
||||
the equivalent of doing a git clone/svn checkout followed by a "composer install"
|
||||
of the vendors.
|
||||
|
||||
There are several applications for this:
|
||||
|
|
@ -434,7 +435,7 @@ There are several applications for this:
|
|||
3. Projects with multiple developers can use this feature to bootstrap the
|
||||
initial application for development.
|
||||
|
||||
To create a new project using composer you can use the "create-project" command.
|
||||
To create a new project using Composer you can use the "create-project" command.
|
||||
Pass it a package name, and the directory to create the project in. You can also
|
||||
provide a version as third argument, otherwise the latest version is used.
|
||||
|
||||
|
|
@ -574,7 +575,7 @@ not be guessed from VCS info and is not present in `composer.json`.
|
|||
|
||||
### COMPOSER_VENDOR_DIR
|
||||
|
||||
By setting this var you can make composer install the dependencies into a
|
||||
By setting this var you can make Composer install the dependencies into a
|
||||
directory other than `vendor`.
|
||||
|
||||
### COMPOSER_BIN_DIR
|
||||
|
|
@ -584,7 +585,7 @@ directory to something other than `vendor/bin`.
|
|||
|
||||
### http_proxy or HTTP_PROXY
|
||||
|
||||
If you are using composer from behind an HTTP proxy, you can use the standard
|
||||
If you are using Composer from behind an HTTP proxy, you can use the standard
|
||||
`http_proxy` or `HTTP_PROXY` env vars. Simply set it to the URL of your proxy.
|
||||
Many operating systems already set this variable for you.
|
||||
|
||||
|
|
@ -606,18 +607,18 @@ can also set it to `*` to ignore the proxy for all HTTP requests.
|
|||
### HTTP_PROXY_REQUEST_FULLURI
|
||||
|
||||
If you use a proxy but it does not support the request_fulluri flag, then you
|
||||
should set this env var to `false` or `0` to prevent composer from setting the
|
||||
should set this env var to `false` or `0` to prevent Composer from setting the
|
||||
request_fulluri option.
|
||||
|
||||
### HTTPS_PROXY_REQUEST_FULLURI
|
||||
|
||||
If you use a proxy but it does not support the request_fulluri flag for HTTPS
|
||||
requests, then you should set this env var to `false` or `0` to prevent composer
|
||||
requests, then you should set this env var to `false` or `0` to prevent Composer
|
||||
from setting the request_fulluri option.
|
||||
|
||||
### COMPOSER_HOME
|
||||
|
||||
The `COMPOSER_HOME` var allows you to change the composer home directory. This
|
||||
The `COMPOSER_HOME` var allows you to change the Composer home directory. This
|
||||
is a hidden, global (per-user on the machine) directory that is shared between
|
||||
all projects.
|
||||
|
||||
|
|
@ -631,32 +632,32 @@ You may put a `config.json` file into the location which `COMPOSER_HOME` points
|
|||
to. Composer will merge this configuration with your project's `composer.json`
|
||||
when you run the `install` and `update` commands.
|
||||
|
||||
This file allows you to set [configuration](04-schema.md#config) and
|
||||
[repositories](05-repositories.md) for the user's projects.
|
||||
This file allows you to set [repositories](05-repositories.md) and
|
||||
[configuration](06-config.md) for the user's projects.
|
||||
|
||||
In case global configuration matches _local_ configuration, the _local_
|
||||
configuration in the project's `composer.json` always wins.
|
||||
|
||||
### COMPOSER_CACHE_DIR
|
||||
|
||||
The `COMPOSER_CACHE_DIR` var allows you to change the composer cache directory,
|
||||
which is also configurable via the [`cache-dir`](04-schema.md#config) option.
|
||||
The `COMPOSER_CACHE_DIR` var allows you to change the Composer cache directory,
|
||||
which is also configurable via the [`cache-dir`](06-config.md#cache-dir) option.
|
||||
|
||||
By default it points to $COMPOSER_HOME/cache on \*nix and OSX, and
|
||||
`C:\Users\<user>\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows.
|
||||
|
||||
### COMPOSER_PROCESS_TIMEOUT
|
||||
|
||||
This env var controls the time composer waits for commands (such as git
|
||||
This env var controls the time Composer waits for commands (such as git
|
||||
commands) to finish executing. The default value is 300 seconds (5 minutes).
|
||||
|
||||
### COMPOSER_DISCARD_CHANGES
|
||||
|
||||
This env var controls the discard-changes [config option](04-schema.md#config).
|
||||
This env var controls the [`discard-changes`](06-config.md#discard-changes) config option.
|
||||
|
||||
### COMPOSER_NO_INTERACTION
|
||||
|
||||
If set to 1, this env var will make composer behave as if you passed the
|
||||
If set to 1, this env var will make Composer behave as if you passed the
|
||||
`--no-interaction` flag to every command. This can be set on build boxes/CI.
|
||||
|
||||
← [Libraries](02-libraries.md) | [Schema](04-schema.md) →
|
||||
|
|
|
|||
131
doc/04-schema.md
131
doc/04-schema.md
|
|
@ -20,9 +20,6 @@ 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.
|
||||
|
||||
> **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 clone `monolog` from GitHub in order to
|
||||
|
|
@ -87,7 +84,7 @@ that needs some special logic, you can define a custom type. This could be a
|
|||
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:
|
||||
Out of the box, Composer supports four types:
|
||||
|
||||
- **library:** This is the default. It will simply copy the files to `vendor`.
|
||||
- **project:** This denotes a project rather than a library. For example
|
||||
|
|
@ -272,7 +269,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 +332,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 +552,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 +625,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 +640,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,11 +649,11 @@ 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.
|
||||
|
||||
By default composer just uses the packagist repository. By specifying
|
||||
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
|
||||
|
|
@ -665,14 +662,14 @@ ignored.
|
|||
|
||||
The following repository types are supported:
|
||||
|
||||
* **composer:** A composer repository is simply a `packages.json` file served
|
||||
* **composer:** A Composer repository is simply a `packages.json` file served
|
||||
via the network (HTTP, FTP, SSH), that contains a list of `composer.json`
|
||||
objects with additional `dist` and/or `source` information. The `packages.json`
|
||||
file is loaded using a PHP stream. You can set extra options on that stream
|
||||
using the `options` parameter.
|
||||
* **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
|
||||
* **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`
|
||||
|
|
@ -731,107 +728,12 @@ 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>
|
||||
### config <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
A set of configuration options. It is only used for projects.
|
||||
A set of configuration options. It is only used for projects. See
|
||||
[Config](06-config.md) for a description of each individual option.
|
||||
|
||||
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>
|
||||
### scripts <span>([root-only](04-schema.md#root-package))</span>
|
||||
|
||||
Composer allows you to hook into various parts of the installation process
|
||||
through the use of scripts.
|
||||
|
|
@ -889,10 +791,11 @@ 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.
|
||||
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
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ of repositories are available, and how they work.
|
|||
## Concepts
|
||||
|
||||
Before we look at the different types of repositories that exist, we need to
|
||||
understand some of the basic concepts that composer is built on.
|
||||
understand some of the basic concepts that Composer is built on.
|
||||
|
||||
### Package
|
||||
|
||||
|
|
@ -16,8 +16,8 @@ code, but in theory it could be anything. And it contains a package
|
|||
description which has a name and a version. The name and the version are used
|
||||
to identify the package.
|
||||
|
||||
In fact, internally composer sees every version as a separate package. While
|
||||
this distinction does not matter when you are using composer, it's quite
|
||||
In fact, internally Composer sees every version as a separate package. While
|
||||
this distinction does not matter when you are using Composer, it's quite
|
||||
important when you want to change it.
|
||||
|
||||
In addition to the name and the version, there is useful metadata. The information
|
||||
|
|
@ -312,7 +312,7 @@ should you need to specify one for whatever reason, you can use `git`, `svn` or
|
|||
|
||||
If you set the `no-api` key to `true` on a github repository it will clone the
|
||||
repository as it would with any other git repository instead of using the
|
||||
GitHub API. But unlike using the `git` driver directly, composer will still
|
||||
GitHub API. But unlike using the `git` driver directly, Composer will still
|
||||
attempt to use github's zip files.
|
||||
|
||||
#### Subversion Options
|
||||
|
|
@ -341,7 +341,7 @@ If you have no branches or tags directory you can disable them entirely by
|
|||
setting the `branches-path` or `tags-path` to `false`.
|
||||
|
||||
If the package is in a sub-directory, e.g. `/trunk/foo/bar/composer.json` and
|
||||
`/tags/1.0/foo/bar/composer.json`, then you can make composer access it by
|
||||
`/tags/1.0/foo/bar/composer.json`, then you can make Composer access it by
|
||||
setting the `"package-path"` option to the sub-directory, in this example it
|
||||
would be `"package-path": "foo/bar/"`.
|
||||
|
||||
|
|
@ -462,7 +462,7 @@ and `IntermediatePackage` from a Github repository:
|
|||
|
||||
### Package
|
||||
|
||||
If you want to use a project that does not support composer through any of the
|
||||
If you want to use a project that does not support Composer through any of the
|
||||
means above, you still can define the package yourself by using a `package`
|
||||
repository.
|
||||
|
||||
|
|
@ -517,7 +517,7 @@ Typically you would leave the source part off, as you don't really need it.
|
|||
While you will probably want to put your packages on packagist most of the time,
|
||||
there are some use cases for hosting your own repository.
|
||||
|
||||
* **Private company packages:** If you are part of a company that uses composer
|
||||
* **Private company packages:** If you are part of a company that uses Composer
|
||||
for their packages internally, you might want to keep those packages private.
|
||||
|
||||
* **Separate ecosystem:** If you have a project which has its own ecosystem,
|
||||
|
|
@ -538,15 +538,16 @@ supported use case and changes will happen without caring for third parties
|
|||
using the code.
|
||||
|
||||
Packagist is a Symfony2 application, and it is [available on
|
||||
GitHub](https://github.com/composer/packagist). It uses composer internally and
|
||||
acts as a proxy between VCS repositories and the composer users. It holds a list
|
||||
of all VCS packages, periodically re-crawls them, and exposes them as a composer
|
||||
GitHub](https://github.com/composer/packagist). It uses Composer internally and
|
||||
acts as a proxy between VCS repositories and the Composer users. It holds a list
|
||||
of all VCS packages, periodically re-crawls them, and exposes them as a Composer
|
||||
repository.
|
||||
|
||||
### Toran Proxy
|
||||
|
||||
[Toran Proxy](https://toranproxy.com/) is a web app much like Packagist but
|
||||
providing private package hosting as well as mirroring/proxying of GitHub and packagist.org. Check its homepage and the [Satis/Toran Proxy article](articles/handling-private-packages-with-satis.md)
|
||||
providing private package hosting as well as mirroring/proxying of GitHub and
|
||||
packagist.org. Check its homepage and the [Satis/Toran Proxy article](articles/handling-private-packages-with-satis.md)
|
||||
for more information.
|
||||
|
||||
### Satis
|
||||
|
|
@ -616,4 +617,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,171 @@
|
|||
# Config
|
||||
|
||||
This chapter will describe the `config` section of the `composer.json`
|
||||
[schema](04-schema.md).
|
||||
|
||||
## 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. Example: `{"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.
|
||||
|
||||
← [Repositories](05-repositories.md) | [Community](07-community.md) →
|
||||
|
|
@ -1,12 +1,14 @@
|
|||
# Community
|
||||
|
||||
There are many people using composer already, and quite a few of them are
|
||||
There are many people using Composer already, and quite a few of them are
|
||||
contributing.
|
||||
|
||||
## Contributing
|
||||
|
||||
If you would like to contribute to composer, please read the
|
||||
[README](https://github.com/composer/composer).
|
||||
If you would like to contribute to Composer, please read the
|
||||
[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)
|
||||
|
|
@ -48,7 +48,7 @@ This is a list of common pitfalls on using Composer, and how to avoid them.
|
|||
1. Check the ["Package not found"](#package-not-found) item above.
|
||||
|
||||
2. If the package tested is a dependency of one of its dependencies (cyclic
|
||||
dependency), the problem might be that composer is not able to detect the version
|
||||
dependency), the problem might be that Composer is not able to detect the version
|
||||
of the package properly. If it is a git clone it is generally alright and Composer
|
||||
will detect the version of the current branch, but travis does shallow clones so
|
||||
that process can fail when testing pull requests and feature branches in general.
|
||||
|
|
@ -61,7 +61,14 @@ This is a list of common pitfalls on using Composer, and how to avoid them.
|
|||
## Package not found in a Jenkins-build
|
||||
|
||||
1. Check the ["Package not found"](#package-not-found) item above.
|
||||
2. Reason for failing is similar to the problem which can occur on travis-ci.org: The git-clone / checkout within Jenkins leaves the branch in a "detached HEAD"-state. As a result, composer is not able to identify the version of the current checked out branch and may not be able to resolve a cyclic dependency. To solve this problem, you can use the "Additional Behaviours" -> "Check out to specific local branch" in your Git-settings for your Jenkins-job, where your "local branch" shall be the same branch as you are checking out. Using this, the checkout will not be in detached state any more and cyclic dependency is recognized correctly.
|
||||
2. Reason for failing is similar to the problem which can occur on travis-ci.org: The
|
||||
git-clone / checkout within Jenkins leaves the branch in a "detached HEAD"-state. As
|
||||
a result, Composer is not able to identify the version of the current checked out branch
|
||||
and may not be able to resolve a cyclic dependency. To solve this problem, you can use
|
||||
the "Additional Behaviours" -> "Check out to specific local branch" in your Git-settings
|
||||
for your Jenkins-job, where your "local branch" shall be the same branch as you are
|
||||
checking out. Using this, the checkout will not be in detached state any more and cyclic
|
||||
dependency is recognized correctly.
|
||||
|
||||
## Need to override a package version
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue