hugo
/
composer
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

remove 'includes' references from docs

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

Also reflowed some lines.
main
Rob Bast 8 years ago
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

112
doc/05-repositories.md
Unescape Escape 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 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
{ {

19
doc/fixtures/fixtures.md
Unescape Escape 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-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.

158
doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json
Unescape Escape 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
Unescape Escape View File

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