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

Update basic docs on install/update, fixes #9754

pull/9911/head
Jordi Boggiano 2021-05-21 16:44:05 +02:00
parent 7d19930ca6
commit fee22972ea
No known key found for this signature in database
GPG Key ID: 7BBD42C429EC80BC
2 changed files with 57 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -20,14 +20,14 @@ to find the file at the top of your VCS repository.
### The `require` key ### 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 [`require`](04-schema.md#require) key. You are telling Composer which
packages your project depends on. packages your project depends on.
```json ```json
{ {
"require": { "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 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) "repositories" that you register using the [`repositories`](04-schema.md#repositories)
key, or in Packagist, the default package repository. In the above example, key, or in [Packagist.org](https://packagist.org), the default package repository.
since no other repository has been registered in the `composer.json` file, it is In the above example, since no other repository has been registered in the
assumed that the `monolog/monolog` package is registered on Packagist. (See more `composer.json` file, it is assumed that the `monolog/monolog` package is registered
about Packagist [below](#packagist), or read more about repositories on Packagist.org. (See more about Packagist [below](#packagist), or read more
[here](05-repositories.md)). about repositories [here](05-repositories.md)).
### Package names ### Package names
@ -59,9 +59,9 @@ you to require certain versions of server software. See
### Package version constraints ### Package version constraints
In our example, we are requesting the Monolog package with the version constraint 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.*). [`2.0.*`](https://semver.mwl.be/#?package=monolog%2Fmonolog&version=2.0.*).
This means any version in the `1.0` development branch, or any version that is This means any version in the `2.0` development branch, or any version that is
greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`). 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 Please read [versions](articles/versions.md) for more in-depth information on
versions, how versions relate to each other, and on version constraints. 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 > and searches for it in any repositories that you have registered using the
> [`repositories`](04-schema.md#repositories) key. If you have not registered > [`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 > 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) > 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 > 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). > 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 ## Installing dependencies
To install the defined dependencies for your project, run the To initially install the defined dependencies for your project, you should run the
[`install`](03-cli.md#install-i) command. [`update`](03-cli.md#update-u) command.
```sh ```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` - 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
If you have never run the command before and there is also no `composer.lock` file present, those specific versions. You should commit the `composer.lock` file to your project repo
Composer resolves all dependencies listed in your `composer.json` file and downloads so that all people working on the project are locked to the same versions of dependencies
the latest version of their files into the `vendor` directory in your project. (The `vendor` (more below). This is the main role of the `update` command.
directory is the conventional location for all third-party code in a project). In our - It then implicitly runs the [`install`](03-cli.md#install-i) command. This will download
example from above, you would end up with the Monolog source files in the dependencies' files into the `vendor` directory in your project. (The `vendor`
`vendor/monolog/monolog/`. If Monolog listed any dependencies, those would also be in directory is the conventional location for all third-party code in a project). In our
folders under `vendor/`. example from above, you would end up with the Monolog source files in
`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 > **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
> third-party code to your versioned repository. > 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 ### Commit your `composer.lock` file to version control
Committing this file to VC is important because it will cause anyone who sets Committing this file to version control is important because it will cause anyone
up the project to use the exact same who sets up the project to use the exact same
versions of the dependencies that you are using. Your CI server, production versions of the dependencies that you are using. Your CI server, production
machines, other developers in your team, everything and everyone runs on the machines, other developers in your team, everything and everyone runs on the
same dependencies, which mitigates the potential for bugs affecting only some 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 > **Note:** For libraries it is not necessary to commit the lock
> file, see also: [Libraries - Lock file](02-libraries.md#lock-file). > 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 ## Updating dependencies to their latest versions
As mentioned above, the `composer.lock` file prevents you from automatically getting 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 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 [`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 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 with the new versions.
and running `install` again.)
```sh ```sh
php composer.phar update php composer.phar update
@ -173,13 +176,13 @@ php composer.phar update monolog/monolog [...]
## Packagist ## 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 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. 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. you can browse and search for packages.
Any open source project using Composer is recommended to publish their 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 = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); $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 You can even add your own code to the autoloader by adding an

2
src/Composer/Installer.php
View File

@ -206,7 +206,7 @@ class Installer
// Force update if there is no lock file present // Force update if there is no lock file present
if (!$this->update && !$this->locker->isLocked()) { 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; $this->update = true;
} }