From fee22972eacb394fed3ab3fcca0535d9c5ada799 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Fri, 21 May 2021 16:44:05 +0200 Subject: [PATCH] Update basic docs on install/update, fixes #9754 --- doc/01-basic-usage.md | 107 +++++++++++++++++++------------------ src/Composer/Installer.php | 2 +- 2 files changed, 56 insertions(+), 53 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index c34da1886..4ccc50965 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -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,40 +89,51 @@ 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` -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/`. +- 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/`. 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). +### Commit your `composer.lock` file to version control + +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 +parts of the deployments. Even if you develop alone, in six months when +reinstalling the project you can feel confident the dependencies installed are +still working even if your dependencies released many new versions since then. +(See note below about using the `update` command.) + +> **Note:** For libraries it is not necessary to commit the lock +> file, see also: [Libraries - Lock file](02-libraries.md#lock-file). -### Installing with `composer.lock` +### Installing from `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). +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 @@ -133,20 +144,13 @@ working on your project. As a result you will have all dependencies requested by 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 -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 -parts of the deployments. Even if you develop alone, in six months when -reinstalling the project you can feel confident the dependencies installed are -still working even if your dependencies released many new versions since then. -(See note below about using the `update` command.) +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. -> **Note:** For libraries it is not necessary to commit the lock -> file, see also: [Libraries - Lock file](02-libraries.md#lock-file). +```sh +php composer.phar install +``` ## Updating dependencies to their latest versions @@ -154,8 +158,7 @@ As mentioned above, the `composer.lock` file prevents you from automatically get 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 diff --git a/src/Composer/Installer.php b/src/Composer/Installer.php index e856aeb39..8afe1c386 100644 --- a/src/Composer/Installer.php +++ b/src/Composer/Installer.php @@ -206,7 +206,7 @@ class Installer // Force update if there is no lock file present if (!$this->update && !$this->locker->isLocked()) { - $this->io->writeError('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.'); + $this->io->writeError('No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.'); $this->update = true; }