Merge pull request #5747 from alcohol/remove-includes-from-docs
remove 'includes' references from docspull/5739/head
Jordi Boggiano
GitHub
commit
af41a814b5
|
|
@ -20,10 +20,10 @@ 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
|
this distinction does not matter when you are using Composer, it's quite
|
||||||
important when you want to change it.
|
important when you want to change it.
|
||||||
|
|
||||||
In addition to the name and the version, there is useful metadata. The information
|
In addition to the name and the version, there is useful metadata. The
|
||||||
most relevant for installation is the source definition, which describes where
|
information most relevant for installation is the source definition, which
|
||||||
to get the package contents. The package data points to the contents of the
|
describes where to get the package contents. The package data points to the
|
||||||
package. And there are two options here: dist and source.
|
contents of the package. And there are two options here: dist and source.
|
||||||
|
|
||||||
**Dist:** The dist is a packaged version of the package data. Usually a
|
**Dist:** The dist is a packaged version of the package data. Usually a
|
||||||
released version, usually a stable release.
|
released version, usually a stable release.
|
||||||
|
|
@ -132,45 +132,15 @@ number.
|
||||||
|
|
||||||
This field is optional.
|
This field is optional.
|
||||||
|
|
||||||
#### includes
|
|
||||||
|
|
||||||
For larger repositories it is possible to split the `packages.json` into
|
|
||||||
multiple files. The `includes` field allows you to reference these additional
|
|
||||||
files.
|
|
||||||
|
|
||||||
An example:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"includes": {
|
|
||||||
"packages-2011.json": {
|
|
||||||
"sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17"
|
|
||||||
},
|
|
||||||
"packages-2012-01.json": {
|
|
||||||
"sha1": "897cde726f8a3918faf27c803b336da223d400dd"
|
|
||||||
},
|
|
||||||
"packages-2012-02.json": {
|
|
||||||
"sha1": "26f911ad717da26bbcac3f8f435280d13917efa5"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The SHA-1 sum of the file allows it to be cached and only re-requested if the
|
|
||||||
hash changed.
|
|
||||||
|
|
||||||
This field is optional. You probably don't need it for your own custom
|
|
||||||
repository.
|
|
||||||
|
|
||||||
#### provider-includes and providers-url
|
#### provider-includes and providers-url
|
||||||
|
|
||||||
For very large repositories like packagist.org using the so-called provider
|
The `provider-includes` field allows you to list a set of files that list
|
||||||
files is the preferred method. The `provider-includes` field allows you to
|
package names provided by this repository. The hash should be a sha256 of
|
||||||
list a set of files that list package names provided by this repository. The
|
the files in this case.
|
||||||
hash should be a sha256 of the files in this case.
|
|
||||||
|
|
||||||
The `providers-url` describes how provider files are found on the server. It
|
The `providers-url` describes how provider files are found on the server. It
|
||||||
is an absolute path from the repository root.
|
is an absolute path from the repository root. It must contain the placeholders
|
||||||
|
`%package%` and `%hash%`.
|
||||||
|
|
||||||
An example:
|
An example:
|
||||||
|
|
||||||
|
|
@ -206,24 +176,25 @@ integrity, for example:
|
||||||
|
|
||||||
The file above declares that acme/foo and acme/bar can be found in this
|
The file above declares that acme/foo and acme/bar can be found in this
|
||||||
repository, by loading the file referenced by `providers-url`, replacing
|
repository, by loading the file referenced by `providers-url`, replacing
|
||||||
`%package%` by the package name and `%hash%` by the sha256 field. Those files
|
`%package%` by the vendor namespaced package name and `%hash%` by the
|
||||||
themselves just contain package definitions as described [above](#packages).
|
sha256 field. Those files themselves just contain package definitions as
|
||||||
|
described [above](#packages).
|
||||||
|
|
||||||
This field is optional. You probably don't need it for your own custom
|
These fields are optional. You probably don't need them for your own custom
|
||||||
repository.
|
repository.
|
||||||
|
|
||||||
#### stream options
|
#### stream options
|
||||||
|
|
||||||
The `packages.json` file is loaded using a PHP stream. You can set extra options
|
The `packages.json` file is loaded using a PHP stream. You can set extra
|
||||||
on that stream using the `options` parameter. You can set any valid PHP stream
|
options on that stream using the `options` parameter. You can set any valid
|
||||||
context option. See [Context options and parameters](https://php.net/manual/en/context.php)
|
PHP stream context option. See [Context options and
|
||||||
for more information.
|
parameters](https://php.net/manual/en/context.php) for more information.
|
||||||
|
|
||||||
### VCS
|
### VCS
|
||||||
|
|
||||||
VCS stands for version control system. This includes versioning systems like
|
VCS stands for version control system. This includes versioning systems like
|
||||||
git, svn, fossil or hg. Composer has a repository type for installing packages from
|
git, svn, fossil or hg. Composer has a repository type for installing packages
|
||||||
these systems.
|
from these systems.
|
||||||
|
|
||||||
#### Loading a package from a VCS repository
|
#### Loading a package from a VCS repository
|
||||||
|
|
||||||
|
|
@ -234,7 +205,8 @@ project to use the patched version. If the library is on GitHub (this is the
|
||||||
case most of the time), you can simply fork it there and push your changes to
|
case most of the time), you can simply fork it there and push your changes to
|
||||||
your fork. After that you update the project's `composer.json`. All you have
|
your fork. After that you update the project's `composer.json`. All you have
|
||||||
to do is add your fork as a repository and update the version constraint to
|
to do is add your fork as a repository and update the version constraint to
|
||||||
point to your custom branch. Your custom branch name must be prefixed with `"dev-"`. For version constraint naming conventions see
|
point to your custom branch. Your custom branch name must be prefixed with
|
||||||
|
`"dev-"`. For version constraint naming conventions see
|
||||||
[Libraries](02-libraries.md) for more information.
|
[Libraries](02-libraries.md) for more information.
|
||||||
|
|
||||||
Example assuming you patched monolog to fix a bug in the `bugfix` branch:
|
Example assuming you patched monolog to fix a bug in the `bugfix` branch:
|
||||||
|
|
@ -312,8 +284,8 @@ VCS repository provides `dist`s for them that fetch the packages as zips.
|
||||||
* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)
|
* **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)
|
||||||
|
|
||||||
The VCS driver to be used is detected automatically based on the URL. However,
|
The VCS driver to be used is detected automatically based on the URL. However,
|
||||||
should you need to specify one for whatever reason, you can use `fossil`, `git`,
|
should you need to specify one for whatever reason, you can use `fossil`,
|
||||||
`svn` or `hg` as the repository type instead of `vcs`.
|
`git`, `svn` or `hg` as the repository type instead of `vcs`.
|
||||||
|
|
||||||
If you set the `no-api` key to `true` on a github repository it will clone the
|
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
|
repository as it would with any other git repository instead of using the
|
||||||
|
|
@ -384,8 +356,9 @@ for this server will be overwritten. To change this behavior by setting the
|
||||||
### PEAR
|
### PEAR
|
||||||
|
|
||||||
It is possible to install packages from any PEAR channel by using the `pear`
|
It is possible to install packages from any PEAR channel by using the `pear`
|
||||||
repository. Composer will prefix all package names with `pear-{channelName}/` to
|
repository. Composer will prefix all package names with `pear-{channelName}/`
|
||||||
avoid conflicts. All packages are also aliased with prefix `pear-{channelAlias}/`
|
to avoid conflicts. All packages are also aliased with prefix
|
||||||
|
`pear-{channelAlias}/`.
|
||||||
|
|
||||||
Example using `pear2.php.net`:
|
Example using `pear2.php.net`:
|
||||||
|
|
||||||
|
|
@ -422,7 +395,8 @@ following packages:
|
||||||
|
|
||||||
* `BasePackage`
|
* `BasePackage`
|
||||||
* `IntermediatePackage`, which depends on `BasePackage`
|
* `IntermediatePackage`, which depends on `BasePackage`
|
||||||
* `TopLevelPackage1` and `TopLevelPackage2` which both depend on `IntermediatePackage`
|
* `TopLevelPackage1` and `TopLevelPackage2` which both depend
|
||||||
|
on `IntermediatePackage`
|
||||||
|
|
||||||
Without a vendor alias, Composer will use the PEAR channel name as the
|
Without a vendor alias, Composer will use the PEAR channel name as the
|
||||||
vendor portion of the package name:
|
vendor portion of the package name:
|
||||||
|
|
@ -519,8 +493,8 @@ Typically you would leave the source part off, as you don't really need it.
|
||||||
|
|
||||||
## Hosting your own
|
## Hosting your own
|
||||||
|
|
||||||
While you will probably want to put your packages on packagist most of the time,
|
While you will probably want to put your packages on packagist most of the
|
||||||
there are some use cases for hosting your own repository.
|
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.
|
for their packages internally, you might want to keep those packages private.
|
||||||
|
|
@ -537,23 +511,24 @@ There are a few tools that can help you create a `composer` repository.
|
||||||
|
|
||||||
### Packagist
|
### Packagist
|
||||||
|
|
||||||
The underlying application used by packagist is open source. This means that you
|
The underlying application used by packagist is open source. This means that
|
||||||
can technically install your own copy of packagist. However it is not a
|
you can technically install your own copy of packagist. However it is not a
|
||||||
supported use case and changes will happen without caring for third parties
|
supported use case and changes will happen without caring for third parties
|
||||||
using the code.
|
using the code.
|
||||||
|
|
||||||
Packagist is a Symfony2 application, and it is [available on
|
Packagist is a Symfony2 application, and it is [available on
|
||||||
GitHub](https://github.com/composer/packagist). It uses Composer internally and
|
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
|
acts as a proxy between VCS repositories and the Composer users. It holds a
|
||||||
of all VCS packages, periodically re-crawls them, and exposes them as a Composer
|
list of all VCS packages, periodically re-crawls them, and exposes them as a
|
||||||
repository.
|
Composer repository.
|
||||||
|
|
||||||
### Toran Proxy
|
### Toran Proxy
|
||||||
|
|
||||||
[Toran Proxy](https://toranproxy.com/) is a web app much like Packagist but
|
[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
|
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)
|
packagist.org. Check its homepage and the [Satis/Toran Proxy
|
||||||
for more information.
|
article](articles/handling-private-packages-with-satis.md) for more
|
||||||
|
information.
|
||||||
|
|
||||||
### Satis
|
### Satis
|
||||||
|
|
||||||
|
|
@ -623,8 +598,8 @@ For instance, if you have the following directory structure in your repository:
|
||||||
\_ composer.json
|
\_ composer.json
|
||||||
```
|
```
|
||||||
|
|
||||||
Then, to add the package `my/package` as a dependency, in your `apps/my-app/composer.json`
|
Then, to add the package `my/package` as a dependency, in your
|
||||||
file, you can use the following configuration:
|
`apps/my-app/composer.json` file, you can use the following configuration:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -650,9 +625,10 @@ the console will read `Symlinked from ../../packages/my-package`. If symlinking
|
||||||
is _not_ possible the package will be copied. In that case, the console will
|
is _not_ possible the package will be copied. In that case, the console will
|
||||||
output `Mirrored from ../../packages/my-package`.
|
output `Mirrored from ../../packages/my-package`.
|
||||||
|
|
||||||
Instead of default fallback strategy you can force to use symlink with `"symlink": true`
|
Instead of default fallback strategy you can force to use symlink with
|
||||||
or mirroring with `"symlink": false` option.
|
`"symlink": true` or mirroring with `"symlink": false` option. Forcing
|
||||||
Forcing mirroring can be useful when deploying or generating package from a monolithic repository.
|
mirroring can be useful when deploying or generating package from a
|
||||||
|
monolithic repository.
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -1,20 +1,23 @@
|
||||||
`Composer` type repository fixtures
|
# `Composer` type repository fixtures
|
||||||
=======================
|
|
||||||
|
|
||||||
This directory contains some examples of what `composer` type repositories can look like. They serve as illustrating examples accompanying the docs, but can also be used as (initial) fixtures for tests.
|
This directory contains some examples of what `composer` type repositories can
|
||||||
|
look like. They serve as illustrating examples accompanying the docs, but can
|
||||||
|
also be used as (initial) fixtures for tests.
|
||||||
|
|
||||||
* `repo-composer-plain` is a simple, plain `packages.json` file
|
* `repo-composer-plain` is a simple, plain `packages.json` file
|
||||||
* `repo-composer-with-includes` uses the `includes` mechanism
|
* `repo-composer-with-includes` uses the `includes` mechanism
|
||||||
* `repo-composer-with-providers` uses the `providers` mechanism
|
* `repo-composer-with-providers` uses the `providers` mechanism
|
||||||
|
|
||||||
Sample Packages used in these fixtures
|
## Sample Packages used in these fixtures
|
||||||
-------
|
|
||||||
|
|
||||||
All these repositories contain the following packages.
|
All these repositories contain the following packages.
|
||||||
|
|
||||||
* `foo/bar` versions 1.0.0, 1.0.1 and 1.1.0; dev-default and 1.0.x-dev branches. On dev-default and in 1.1.0, `bar/baz` ~1.0 is required.
|
* `foo/bar` versions 1.0.0, 1.0.1 and 1.1.0; dev-default and 1.0.x-dev branches.
|
||||||
|
On dev-default and in 1.1.0, `bar/baz` ~1.0 is required.
|
||||||
* `qux/quux` only has a dev-default branch. It `replace`s `gar/nix`.
|
* `qux/quux` only has a dev-default branch. It `replace`s `gar/nix`.
|
||||||
* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced by `qux/quux`.
|
* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced
|
||||||
* `bar/baz` has a 1.0.0 version and 1.0.x-dev as well as dev-default branches. Additionally, 1.1.x-dev is a branch alias for dev-default.
|
by `qux/quux`.
|
||||||
|
* `bar/baz` has a 1.0.0 version and 1.0.x-dev as well as dev-default branches.
|
||||||
|
Additionally, 1.1.x-dev is a branch alias for dev-default.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,158 +0,0 @@
|
||||||
{
|
|
||||||
"packages": {
|
|
||||||
"bar/baz": {
|
|
||||||
"1.0.0": {
|
|
||||||
"name": "bar/baz",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"version_normalized": "1.0.0.0",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "35810817c14d"
|
|
||||||
},
|
|
||||||
"time": "2014-10-13 12:04:55",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"1.0.x-dev": {
|
|
||||||
"name": "bar/baz",
|
|
||||||
"version": "1.0.x-dev",
|
|
||||||
"version_normalized": "1.0.9999999.9999999-dev",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "ffff9aae6ed5"
|
|
||||||
},
|
|
||||||
"time": "2014-10-13 12:05:37",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"dev-default": {
|
|
||||||
"name": "bar/baz",
|
|
||||||
"version": "dev-default",
|
|
||||||
"version_normalized": "9999999-dev",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "f317e556f2e2"
|
|
||||||
},
|
|
||||||
"time": "2014-10-13 12:06:45",
|
|
||||||
"type": "library",
|
|
||||||
"extra": {
|
|
||||||
"branch-alias": {
|
|
||||||
"dev-default": "1.1.x-dev"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"foo/bar": {
|
|
||||||
"1.0.0": {
|
|
||||||
"name": "foo/bar",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"version_normalized": "1.0.0.0",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "249dec95a52a"
|
|
||||||
},
|
|
||||||
"time": "2014-10-11 15:42:00",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"1.0.1": {
|
|
||||||
"name": "foo/bar",
|
|
||||||
"version": "1.0.1",
|
|
||||||
"version_normalized": "1.0.1.0",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "21e3328295d4"
|
|
||||||
},
|
|
||||||
"time": "2014-10-11 15:45:56",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"1.0.x-dev": {
|
|
||||||
"name": "foo/bar",
|
|
||||||
"version": "1.0.x-dev",
|
|
||||||
"version_normalized": "1.0.9999999.9999999-dev",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "14dc17c8e860"
|
|
||||||
},
|
|
||||||
"time": "2014-10-11 15:45:59",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"1.1.0": {
|
|
||||||
"name": "foo/bar",
|
|
||||||
"version": "1.1.0",
|
|
||||||
"version_normalized": "1.1.0.0",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "d2fa3e69ad5b"
|
|
||||||
},
|
|
||||||
"require": {
|
|
||||||
"bar/baz": "~1.0"
|
|
||||||
},
|
|
||||||
"time": "2014-10-11 15:43:16",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"dev-default": {
|
|
||||||
"name": "foo/bar",
|
|
||||||
"version": "dev-default",
|
|
||||||
"version_normalized": "9999999-dev",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "8e5a5c224336"
|
|
||||||
},
|
|
||||||
"require": {
|
|
||||||
"bar/baz": "~1.0"
|
|
||||||
},
|
|
||||||
"time": "2014-10-11 15:43:18",
|
|
||||||
"type": "library"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"gar/nix": {
|
|
||||||
"1.0.0": {
|
|
||||||
"name": "gar/nix",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"version_normalized": "1.0.0.0",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "44977145d64e"
|
|
||||||
},
|
|
||||||
"time": "2014-10-13 12:03:33",
|
|
||||||
"type": "library"
|
|
||||||
},
|
|
||||||
"dev-default": {
|
|
||||||
"name": "gar/nix",
|
|
||||||
"version": "dev-default",
|
|
||||||
"version_normalized": "9999999-dev",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "51cca95a31c2"
|
|
||||||
},
|
|
||||||
"time": "2014-10-13 12:03:35",
|
|
||||||
"type": "library"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"qux/quux": {
|
|
||||||
"dev-default": {
|
|
||||||
"name": "qux/quux",
|
|
||||||
"version": "dev-default",
|
|
||||||
"version_normalized": "9999999-dev",
|
|
||||||
"source": {
|
|
||||||
"type": "hg",
|
|
||||||
"url": "http://some.where/over/the/rainbow/",
|
|
||||||
"reference": "4a10a567baa5"
|
|
||||||
},
|
|
||||||
"replace": {
|
|
||||||
"gar/nix": "1.0.*"
|
|
||||||
},
|
|
||||||
"time": "2014-10-11 15:48:15",
|
|
||||||
"type": "library"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
@ -1,10 +0,0 @@
|
||||||
{
|
|
||||||
"packages": [
|
|
||||||
|
|
||||||
],
|
|
||||||
"includes": {
|
|
||||||
"include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json": {
|
|
||||||
"sha1": "5fa86b937f0502d92f776072cd49c002dca742b9"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
Loading…
Reference in New Issue