public-mirrors
/
composer
mirror of https://github.com/composer/composer
1
0
Fork 0
Code

remove 'includes' references from docs 

Relates to #5739 - we do not want to mention attributes/properties that
are considered legacy and/or deprecated.

Also reflowed some lines.
pull/5747/head
Rob Bast 2016-10-03 10:14:57 +02:00
parent 32e3464e02
commit 7377db32ae
No known key found for this signature in database
GPG Key ID: 73076E35E6165F39
4 changed files with 55 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
doc/05-repositories.md
View File

@ -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
important when you want to change it.
In addition to the name and the version, there is useful metadata. The information
most relevant for installation is the source definition, which describes where
to get the package contents. The package data points to the contents of the
package. And there are two options here: dist and source.
In addition to the name and the version, there is useful metadata. The
information most relevant for installation is the source definition, which
describes where to get the package contents. The package data points to the
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
released version, usually a stable release.
@ -132,45 +132,15 @@ number.
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
For very large repositories like packagist.org using the so-called provider
files is the preferred method. The `provider-includes` field allows you to
list a set of files that list package names provided by this repository. The
hash should be a sha256 of the files in this case.
The `provider-includes` field allows you to list a set of files that list
package names provided by this repository. The hash should be a sha256 of
the files in this case.
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:
@ -206,24 +176,25 @@ integrity, for example:
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
`%package%` by the package name and `%hash%` by the sha256 field. Those files
themselves just contain package definitions as described [above](#packages).
`%package%` by the vendor namespaced package name and `%hash%` by the
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.
#### stream options
The `packages.json` file is loaded using a PHP stream. You can set extra options
on that stream using the `options` parameter. You can set any valid PHP stream
context option. See [Context options and parameters](https://php.net/manual/en/context.php)
for more information.
The `packages.json` file is loaded using a PHP stream. You can set extra
options on that stream using the `options` parameter. You can set any valid
PHP stream context option. See [Context options and
parameters](https://php.net/manual/en/context.php) for more information.
### VCS
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
these systems.
git, svn, fossil or hg. Composer has a repository type for installing packages
from these systems.
#### 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
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
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.
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)
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`,
`svn` or `hg` as the repository type instead of `vcs`.
should you need to specify one for whatever reason, you can use `fossil`,
`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
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
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
avoid conflicts. All packages are also aliased with prefix `pear-{channelAlias}/`
repository. Composer will prefix all package names with `pear-{channelName}/`
to avoid conflicts. All packages are also aliased with prefix
`pear-{channelAlias}/`.
Example using `pear2.php.net`:
@ -422,7 +395,8 @@ following packages:
* `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
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
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.
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
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
The underlying application used by packagist is open source. This means that you
can technically install your own copy of packagist. However it is not a
The underlying application used by packagist is open source. This means that
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
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
repository.
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)
for more information.
packagist.org. Check its homepage and the [Satis/Toran Proxy
article](articles/handling-private-packages-with-satis.md) for more
information.
### Satis
@ -623,8 +598,8 @@ For instance, if you have the following directory structure in your repository:
\_ composer.json
```
Then, to add the package `my/package` as a dependency, in your `apps/my-app/composer.json`
file, you can use the following configuration:
Then, to add the package `my/package` as a dependency, in your
`apps/my-app/composer.json` file, you can use the following configuration:
```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
output `Mirrored from ../../packages/my-package`.
Instead of default fallback strategy you can force to use symlink with `"symlink": true`
or mirroring with `"symlink": false` option.
Forcing mirroring can be useful when deploying or generating package from a monolithic repository.
Instead of default fallback strategy you can force to use symlink with
`"symlink": true` or mirroring with `"symlink": false` option. Forcing
mirroring can be useful when deploying or generating package from a
monolithic repository.
```json
{

19
doc/fixtures/fixtures.md
View File

@ -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-with-includes` uses the `includes` 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.
* `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`.
* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced 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.
* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced
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.

158
doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json
View File

@ -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"
}
}
}
}

10
doc/fixtures/repo-composer-with-includes/packages.json
View File

@ -1,10 +0,0 @@
{
"packages": [
],
"includes": {
"include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json": {
"sha1": "5fa86b937f0502d92f776072cd49c002dca742b9"
}
}
}