Update basic docs on install/update, fixes #9754
Jordi Boggiano
parent
7d19930ca6
commit
fee22972ea
|
|
@ -20,14 +20,14 @@ to find the file at the top of your VCS repository.
|
|||
|
||||
### The `require` key
|
||||
|
||||
The first (and often only) thing you specify in `composer.json` is the
|
||||
The first thing you specify in `composer.json` is the
|
||||
[`require`](04-schema.md#require) key. You are telling Composer which
|
||||
packages your project depends on.
|
||||
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"monolog/monolog": "1.0.*"
|
||||
"monolog/monolog": "2.0.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -38,11 +38,11 @@ As you can see, [`require`](04-schema.md#require) takes an object that maps
|
|||
|
||||
Composer 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 repository. In the above example,
|
||||
since no other repository has been registered in the `composer.json` 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)).
|
||||
key, or in [Packagist.org](https://packagist.org), the default package repository.
|
||||
In the above example, since no other repository has been registered in the
|
||||
`composer.json` file, it is assumed that the `monolog/monolog` package is registered
|
||||
on Packagist.org. (See more about Packagist [below](#packagist), or read more
|
||||
about repositories [here](05-repositories.md)).
|
||||
|
||||
### Package names
|
||||
|
||||
|
|
@ -59,9 +59,9 @@ you to require certain versions of server software. See
|
|||
### Package version constraints
|
||||
|
||||
In our example, we are requesting the Monolog package with the version constraint
|
||||
[`1.0.*`](https://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*).
|
||||
This means any version in the `1.0` development branch, or any version that is
|
||||
greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`).
|
||||
[`2.0.*`](https://semver.mwl.be/#?package=monolog%2Fmonolog&version=2.0.*).
|
||||
This means any version in the `2.0` development branch, or any version that is
|
||||
greater than or equal to 2.0 and less than 2.1 (`>=2.0 <2.1`).
|
||||
|
||||
Please read [versions](articles/versions.md) for more in-depth information on
|
||||
versions, how versions relate to each other, and on version constraints.
|
||||
|
|
@ -71,9 +71,9 @@ versions, how versions relate to each other, and on version constraints.
|
|||
> and searches for it in any repositories that you have registered using the
|
||||
> [`repositories`](04-schema.md#repositories) key. If you have not registered
|
||||
> any extra repositories, or it does not find a package with that name in the
|
||||
> repositories you have specified, it falls back to Packagist (more [below](#packagist)).
|
||||
> repositories you have specified, it falls back to Packagist.org (more [below](#packagist)).
|
||||
>
|
||||
> When Composer finds the right package, either in Packagist or in a repo you have specified,
|
||||
> When Composer finds the right package, either in Packagist.org or in a repo you have specified,
|
||||
> it then uses the versioning features of the package's VCS (i.e., branches and tags)
|
||||
> to attempt to find the best match for the version constraint you have specified. Be sure to read
|
||||
> about versions and package resolution in the [versions article](articles/versions.md).
|
||||
|
|
@ -89,54 +89,35 @@ versions, how versions relate to each other, and on version constraints.
|
|||
|
||||
## Installing dependencies
|
||||
|
||||
To install the defined dependencies for your project, run the
|
||||
[`install`](03-cli.md#install-i) command.
|
||||
To initially install the defined dependencies for your project, you should run the
|
||||
[`update`](03-cli.md#update-u) command.
|
||||
|
||||
```sh
|
||||
php composer.phar install
|
||||
php composer.phar update
|
||||
```
|
||||
|
||||
When you run this command, one of two things may happen:
|
||||
This will make Composer do two things:
|
||||
|
||||
### Installing without `composer.lock`
|
||||
|
||||
If you have never run the command before and there is also no `composer.lock` file present,
|
||||
Composer resolves all dependencies listed in your `composer.json` file and downloads
|
||||
the latest version of their files into the `vendor` directory in your project. (The `vendor`
|
||||
- It resolves all dependencies listed in your `composer.json` file and writes all of the
|
||||
packages and their exact versions to the `composer.lock` file, locking the project to
|
||||
those specific versions. You should commit the `composer.lock` file to your project repo
|
||||
so that all people working on the project are locked to the same versions of dependencies
|
||||
(more below). This is the main role of the `update` command.
|
||||
- It then implicitly runs the [`install`](03-cli.md#install-i) command. This will download
|
||||
the dependencies' files into the `vendor` directory in your project. (The `vendor`
|
||||
directory is the conventional location for all third-party code in a project). In our
|
||||
example from above, you would end up with the Monolog source files in
|
||||
`vendor/monolog/monolog/`. If Monolog listed any dependencies, those would also be in
|
||||
folders under `vendor/`.
|
||||
`vendor/monolog/monolog/`. As Monolog has a dependency on `psr/log`, that package's files
|
||||
can also be found inside `vendor/`.
|
||||
|
||||
> **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
|
||||
> third-party code to your versioned repository.
|
||||
|
||||
When Composer has finished installing, it writes all of the packages and the exact versions
|
||||
of them that it downloaded to the `composer.lock` file, locking the project to those specific
|
||||
versions. You should commit the `composer.lock` file to your project repo so that all people
|
||||
working on the project are locked to the same versions of dependencies (more below).
|
||||
|
||||
### Installing with `composer.lock`
|
||||
|
||||
This brings us to the second scenario. If there is already a `composer.lock` file as well as a
|
||||
`composer.json` file when you run `composer install`, it means either you ran the
|
||||
`install` command before, or someone else on the project ran the `install` command and
|
||||
committed the `composer.lock` file to the project (which is good).
|
||||
|
||||
Either way, running `install` when a `composer.lock` file is present resolves and installs
|
||||
all dependencies that you listed in `composer.json`, but Composer uses the exact versions listed
|
||||
in `composer.lock` to ensure that the package versions are consistent for everyone
|
||||
working on your project. As a result you will have all dependencies requested by your
|
||||
`composer.json` file, but they may not all be at the very latest available versions
|
||||
(some of the dependencies listed in the `composer.lock` file may have released newer versions since
|
||||
the file was created). This is by design, it ensures that your project does not break because of
|
||||
unexpected changes in dependencies.
|
||||
|
||||
### Commit your `composer.lock` file to version control
|
||||
|
||||
Committing this file to VC is important because it will cause anyone who sets
|
||||
up the project to use the exact same
|
||||
Committing this file to version control is important because it will cause anyone
|
||||
who sets up the project to use the exact same
|
||||
versions of the dependencies that you are using. Your CI server, production
|
||||
machines, other developers in your team, everything and everyone runs on the
|
||||
same dependencies, which mitigates the potential for bugs affecting only some
|
||||
|
|
@ -148,14 +129,36 @@ still working even if your dependencies released many new versions since then.
|
|||
> **Note:** For libraries it is not necessary to commit the lock
|
||||
> file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
|
||||
|
||||
### Installing from `composer.lock`
|
||||
|
||||
If there is already a `composer.lock` file in the project folder, it means either
|
||||
you ran the `update` command before, or someone else on the project ran the `update`
|
||||
command and committed the `composer.lock` file to the project (which is good).
|
||||
|
||||
Either way, running `install` when a `composer.lock` file is present resolves and installs
|
||||
all dependencies that you listed in `composer.json`, but Composer uses the exact versions listed
|
||||
in `composer.lock` to ensure that the package versions are consistent for everyone
|
||||
working on your project. As a result you will have all dependencies requested by your
|
||||
`composer.json` file, but they may not all be at the very latest available versions
|
||||
(some of the dependencies listed in the `composer.lock` file may have released newer versions since
|
||||
the file was created). This is by design, it ensures that your project does not break because of
|
||||
unexpected changes in dependencies.
|
||||
|
||||
So after fetching new changes from your VCS repository it is recommended to run
|
||||
a Composer `install` to make sure the vendor directory is up in sync with your
|
||||
`composer.lock` file.
|
||||
|
||||
```sh
|
||||
php composer.phar install
|
||||
```
|
||||
|
||||
## Updating dependencies to their latest versions
|
||||
|
||||
As mentioned above, the `composer.lock` file prevents you from automatically getting
|
||||
the latest versions of your dependencies. To update to the latest versions, use the
|
||||
[`update`](03-cli.md#update-u) command. This will fetch the latest matching
|
||||
versions (according to your `composer.json` file) and update the lock file
|
||||
with the new versions. (This is equivalent to deleting the `composer.lock` file
|
||||
and running `install` again.)
|
||||
with the new versions.
|
||||
|
||||
```sh
|
||||
php composer.phar update
|
||||
|
|
@ -173,13 +176,13 @@ php composer.phar update monolog/monolog [...]
|
|||
|
||||
## Packagist
|
||||
|
||||
[Packagist](https://packagist.org/) is the main Composer repository. A Composer
|
||||
[Packagist.org](https://packagist.org/) is the main Composer repository. A Composer
|
||||
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
|
||||
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.org website](https://packagist.org/),
|
||||
you can browse and search for packages.
|
||||
|
||||
Any open source project using Composer is recommended to publish their packages
|
||||
|
|
@ -222,7 +225,7 @@ require __DIR__ . '/vendor/autoload.php';
|
|||
|
||||
$log = new Monolog\Logger('name');
|
||||
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
|
||||
$log->addWarning('Foo');
|
||||
$log->warning('Foo');
|
||||
```
|
||||
|
||||
You can even add your own code to the autoloader by adding an
|
||||
|
|
|
|||
|
|
@ -206,7 +206,7 @@ class Installer
|
|||
|
||||
// Force update if there is no lock file present
|
||||
if (!$this->update && !$this->locker->isLocked()) {
|
||||
$this->io->writeError('<warning>No lock file found. Updating dependencies instead of installing from lock file. Use composer update over composer install if you do not have a lock file.</warning>');
|
||||
$this->io->writeError('<warning>No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.</warning>');
|
||||
$this->update = true;
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue