From 3c25d180e63f9e0dd2f41c3e1a46a6027c0ba80e Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Tue, 13 Oct 2020 12:05:24 +0200 Subject: [PATCH] Add detailed notes about events in upgrade guide, add COMPOSER_DEBUG_EVENTS env var for debugging events --- UPGRADE-2.0.md | 28 +++++++++++++++++-- doc/03-cli.md | 5 ++++ doc/articles/plugins.md | 6 +++- .../EventDispatcher/EventDispatcher.php | 8 ++++++ 4 files changed, 44 insertions(+), 3 deletions(-) diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md index 2af90c13c..36bbfd2b0 100644 --- a/UPGRADE-2.0.md +++ b/UPGRADE-2.0.md @@ -30,7 +30,7 @@ - packages now contain an `"installed-path"` key which lists where they were installed - there is a top level `"dev"` key which stores whether dev requirements were installed or not - Removed `OperationInterface::getReason` as the data was not accurate. There is no replacement available. -- `PreFileDownloadEvent` now receives an `HttpDownloader` instance instead of `RemoteFilesystem`, and that instance cannot be overridden by listeners anymore +- `PreFileDownloadEvent` now receives an `HttpDownloader` instance instead of `RemoteFilesystem`, and that instance cannot be overridden by listeners anymore, you can however call setProcessedUrl or setCustomCacheKey. - `VersionSelector::findBestCandidate`'s third argument (phpVersion) was removed in favor of passing in a complete PlatformRepository instance into the constructor - `InitCommand::determineRequirements`'s fourth argument (phpVersion) should now receive a complete PlatformRepository instance or null if platform requirements are to be ignored - `IOInterface` now extends PSR-3's `LoggerInterface`, and has new `writeRaw` + `writeErrorRaw` methods @@ -46,8 +46,32 @@ - `prepare` (do user prompts or any checks which need to happen to make sure that install/update/remove will most likely succeed), `install` (should do the non-network part that `download` used to do) and `cleanup` (cleaning up anything that may be left over) were added as new steps in the package install flow - All packages get first downloaded, then all together prepared, then all together installed/updated/uninstalled, then finally cleanup is called for all. Therefore for error recovery it is important to avoid failing during install/update/uninstall as much as possible, and risky things or user prompts should happen in the prepare step rather. In case of failure, cleanup() will be called so that changes can be undone as much as possible. - If you used `RemoteFilesystem` you probably should use `HttpDownloader` instead now -- `PRE_DEPENDENCIES_SOLVING` and `POST_DEPENDENCIES_SOLVING` events have been removed, use the new `PRE_OPERATIONS_EXEC` or other existing events instead or talk to us if you think you really need this +- `PRE_DEPENDENCIES_SOLVING` and `POST_DEPENDENCIES_SOLVING` events have been removed, use the new `PRE_OPERATIONS_EXEC`, `PRE_POOL_CREATE` or other existing events instead or talk to us if you think you really need this. See below for more details. - The bundled composer/semver is now the 3.x range, see release notes for [2.0](https://github.com/composer/semver/releases/tag/2.0.0) and [3.0](https://github.com/composer/semver/releases/tag/3.0.0) for the minor breaking changes there +- Run Composer with COMPOSER_DEBUG_EVENTS=1 set in the environment to show which events happen which might help you. + +### Detailed differences in event flow during dependency resolution, composer updates and installs + +#### Composer v1 + +- Composer resolves dependencies (dispatching PRE/POST_DEPENDENCIES_SOLVING) +- It then iterates over all packages one by one (dispatching PRE_PACKAGE_INSTALL/UPDATE/UNINSTALL, then PRE_FILE_DOWNLOAD if needed, then POST_PACKAGE_*) +- And finally writes the lock file at the end + +#### Composer v2 + +The update and install process have been split up. + +Update does: + +- Composer resolves dependencies (dispatching PRE_POOL_CREATE) +- It then writes the lock file and that's the end of the update + +Install then does: + +- Dispatches PRE_OPERATIONS_EXEC with the full list of operations to be executed +- Downloads all the packages not in cache yet in parallel (dispatching PRE_FILE_DOWNLOAD for those not in cache yet) +- It then iterates over all packages and executes updates/installs/uninstalls in parallel (dispatching PRE_PACKAGE_INSTALL/UPDATE/UNINSTALL then POST_PACKAGE_* but one package started last may finish installing before another is done for example). ## For Composer repository implementors diff --git a/doc/03-cli.md b/doc/03-cli.md index add0663eb..009dfd947 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -1039,4 +1039,9 @@ to run Composer on a plane or a starship with poor connectivity. If set to `prime`, GitHub VCS repositories will prime the cache, so it can then be used fully offline with `1`. +### COMPOSER_DEBUG_EVENTS + +If set to `1`, outputs information about events being dispatched, which can be +useful for plugin authors to identify what is firing when exactly. + ← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/doc/articles/plugins.md b/doc/articles/plugins.md index 28b7c1475..d854f931e 100644 --- a/doc/articles/plugins.md +++ b/doc/articles/plugins.md @@ -94,6 +94,10 @@ and have it return an array. The array key must be the [event name](https://getcomposer.org/doc/articles/scripts.md#event-names) and the value is the name of the method in this class to be called. +> **Note:** If you don't know which event to listen to, you can run a Composer +> command with the COMPOSER_DEBUG_EVENTS=1 environment variable set, which might +> help you identify what event you are looking for. + ```php public static function getSubscribedEvents() { @@ -263,7 +267,7 @@ Now the `custom-plugin-command` is available alongside Composer commands. ## Running plugins manually -Plugins for an event can be run manually by the `run-script` command. This works the same way as +Plugins for an event can be run manually by the `run-script` command. This works the same way as [running scripts manually](scripts.md#running-scripts-manually). ## Using Plugins diff --git a/src/Composer/EventDispatcher/EventDispatcher.php b/src/Composer/EventDispatcher/EventDispatcher.php index 949aaf157..6a14b9778 100644 --- a/src/Composer/EventDispatcher/EventDispatcher.php +++ b/src/Composer/EventDispatcher/EventDispatcher.php @@ -144,6 +144,14 @@ class EventDispatcher */ protected function doDispatch(Event $event) { + if (getenv('COMPOSER_DEBUG_EVENTS')) { + $details = null; + if ($event instanceof PackageEvent) { + $details = (string) $event->getOperation(); + } + $this->io->writeError('Dispatching '.$event->getName().''.($details ? ' ('.$details.')' : '').' event'); + } + $listeners = $this->getListeners($event); $this->pushEvent($event);