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

Added some useful overview information about repositories in the Basic Usage documentation.

pull/6097/head
Kael Shipman 2017-01-19 19:04:24 -06:00
parent 64b9423df3
commit 7a9f24b913
1 changed files with 43 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
doc/01-basic-usage.md
View File

@ -33,18 +33,21 @@ As you can see, [`require`](04-schema.md#require) takes an object that maps
**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g. **package names** (e.g. `monolog/monolog`) to **version constraints** (e.g.
`1.0.*`). `1.0.*`).
It uses this information to search for the right set of files in package
"repositories" that you register using the [`repositories`](04-schema.md#repositories)
key, or in Packagist, the default package respository. In the above example,
since no other repository is registered in the file, it is assumed that the
`monolog/monolog` package is registered on Packagist. (See more about Packagist
[below](#packagist), or read more about repositories [here](05-repositories.md).
### Package Names ### Package Names
The package name consists of a vendor name and the project's name. Often these The package name consists of a vendor name and the project's name. Often these
will be identical - the vendor name just exists to prevent naming clashes. It will be identical - the vendor name just exists to prevent naming clashes. For
allows two different people to create a library named `json`, which would then example, it would allow two different people to create a library named `json`.
just be named `igorw/json` and `seldaek/json`. One might be named `igorw/json` while the other might be `seldaek/json`.
Here we are requiring `monolog/monolog`, so the vendor name is the same as the Read more about publishing packages and package naming [here](02-libraries.md)
project's name. For projects with a unique name this is recommended. It also
allows adding more related projects under the same namespace later on. If you
are maintaining a library, this would make it really easy to split it up into
smaller decoupled parts.
### Package Versions ### Package Versions
@ -53,16 +56,30 @@ In the previous example we were requiring version
Monolog. This means any version in the `1.0` development branch. It is the Monolog. This means any version in the `1.0` development branch. It is the
equivalent of saying versions that match `>=1.0 <1.1`. equivalent of saying versions that match `>=1.0 <1.1`.
Version constraints can be specified in several ways, read Version constraints can be specified in several ways; please read
[versions](articles/versions.md) for more in-depth information on this topic. [versions](articles/versions.md) for more in-depth information on this topic.
### Stability > **How does Composer download the right files?** When you specify a dependency in
> `composer.json`, Composer, first takes the name of the package that you've requested
> and searches for it in any repositories that you've registered using the
> [`repositories`](04-schema.md#repositories) key. If you haven't registered
> any extra repositories, or it doesn't find a package with that name in the
> repositories you've specified, it falls back to Packagist (more [below](#packagist)).
>
> When it finds the right package, either in Packagist or in a repo you've specified,
> it then uses the versioning features of the package's VCS to attempt to find the
> best match for the version you've specified. Read more on package resolution
> [here](articles/versions.md).
By default only stable releases are taken into consideration. If you would > **Note:** If you're trying to require a package but Composer throws an error
like to also get RC, beta, alpha or dev versions of your dependencies you can > regarding package stability, the version you've specified may not meet the
do so using [stability flags](04-schema.md#package-links). To change that for > default minimum stability requirements that Composer establishes. By default
all packages instead of doing per dependency you can also use the > only stable releases are taken into consideration when searching for package
[minimum-stability](04-schema.md#minimum-stability) setting. > versions in your VCS.
>
> You might run into this if you're trying to require dev, alpha, beta, or RC
> versions of a package. Read more about stability flags and the `minimum-stability`
> key on the [schema page](04-schema.md).
## Installing Dependencies ## Installing Dependencies
@ -76,7 +93,7 @@ php composer.phar install
This will find the latest version of `monolog/monolog` that matches the This will find the latest version of `monolog/monolog` that matches the
supplied version constraint and download it into the `vendor` directory. supplied version constraint and download it into the `vendor` directory.
It's a convention to put third party code into a directory named `vendor`. It's a convention to put third party code into a directory named `vendor`.
In case of Monolog it will put it into `vendor/monolog/monolog`. In the case of Monolog it will put it into `vendor/monolog/monolog`.
> **Tip:** If you are using git for your project, you probably want to add > **Tip:** If you are using git for your project, you probably want to add
> `vendor` in your `.gitignore`. You really don't want to add all of that > `vendor` in your `.gitignore`. You really don't want to add all of that
@ -99,16 +116,16 @@ if a lock file is present, and if it is, it downloads the versions specified
there (regardless of what `composer.json` says). there (regardless of what `composer.json` says).
This means that anyone who sets up the project will download the exact same This means that anyone who sets up the project will download the exact same
version of the dependencies. Your CI server, production machines, other versions of the dependencies that you're using. Your CI server, production
developers in your team, everything and everyone runs on the same dependencies, machines, other developers in your team, everything and everyone runs on the
which mitigates the potential for bugs affecting only some parts of the same dependencies, which mitigates the potential for bugs affecting only some
deployments. Even if you develop alone, in six months when reinstalling the parts of the deployments. Even if you develop alone, in six months when
project you can feel confident the dependencies installed are still working even reinstalling the project you can feel confident the dependencies installed are
if your dependencies released many new versions since then. still working even if your dependencies released many new versions since then.
(See note below about using the `update` command.)
If no `composer.lock` file exists, Composer will read the dependencies and If no `composer.lock` file exists, Composer will read the dependencies and
versions from `composer.json` and create the lock file after executing the versions from `composer.json` and create the lock file after executing.
[`update`](03-cli.md#update) or the [`install`](03-cli.md#install) command.
This means that if any of the dependencies get a new version, you won't get the This means that if any of the dependencies get a new version, you won't get the
updates automatically. To update to the new version, use the updates automatically. To update to the new version, use the
@ -136,7 +153,8 @@ php composer.phar update monolog/monolog [...]
[Packagist](https://packagist.org/) is the main Composer repository. A Composer [Packagist](https://packagist.org/) is the main Composer repository. A Composer
repository is basically a package source: a place where you can get packages repository is basically a package source: a place where you can get packages
from. Packagist aims to be the central repository that everybody uses. This from. Packagist aims to be the central repository that everybody uses. This
means that you can automatically `require` any package that is available there. means that you can automatically `require` any package that is available there,
without further specifying where Composer should look for the package.
If you go to the [Packagist website](https://packagist.org/) (packagist.org), If you go to the [Packagist website](https://packagist.org/) (packagist.org),
you can browse and search for packages. you can browse and search for packages.