From 0071bc1ec0c97420f322a96a65f1fa96b0480bbc Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Fri, 1 May 2020 10:18:54 +0200 Subject: [PATCH] Add docs about new runtime features --- CHANGELOG.md | 4 +- doc/04-schema.md | 2 +- doc/06-config.md | 2 +- doc/07-runtime.md | 95 ++++++++++++++++++++++++ doc/{07-community.md => 08-community.md} | 2 +- doc/articles/autoloader-optimization.md | 2 +- 6 files changed, 101 insertions(+), 6 deletions(-) create mode 100644 doc/07-runtime.md rename doc/{07-community.md => 08-community.md} (97%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 13cb7866e..a3d3d84f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,8 +5,8 @@ * The update command is now much more deterministic as it does not take the already installed packages into account * Package installation now performs all network operations first before doing any changes on disk, to reduce the chances of ending up with a partially updated vendor dir * Partial updates and require/remove are now much faster as they only load the metadata required for the updated packages - * Added a platform-check step when vendor/autoload.php gets initialized which checks the current PHP version/extensions match what is expected and fails hard otherwise. Can be disabled with the platform-check config option - * Added a [`Composer\InstalledVersions`](https://github.com/composer/composer/blob/d89342dc434d52c88e0e06ce3982da739a467f13/src/Composer/InstalledVersions.php) class which is autoloaded in every project and lets you check which packages/versions are present at runtime + * Added a [platform-check step](doc/07-runtime.md#platform-check) when vendor/autoload.php gets initialized which checks the current PHP version/extensions match what is expected and fails hard otherwise. Can be disabled with the platform-check config option + * Added a [`Composer\InstalledVersions`](doc/07-runtime.md#installed-versions) class which is autoloaded in every project and lets you check which packages/versions are present at runtime * Added a `composer-runtime-api` virtual package which you can require (as e.g. `^2.0`) to ensure things like the InstalledVersions class above are present. It will effectively force people to use Composer 2.x to install your project * Added support for parallel downloads of package metadata and zip files, this requires that the curl extension is present and we thus strongly recommend enabling curl * Added much clearer dependency resolution error reporting for common error cases diff --git a/doc/04-schema.md b/doc/04-schema.md index 130394e7a..d237282e3 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -1,4 +1,4 @@ -# The composer.json Schema +# The composer.json schema This chapter will explain all of the fields available in `composer.json`. diff --git a/doc/06-config.md b/doc/06-config.md index a79f3fe5d..1b0a8e648 100644 --- a/doc/06-config.md +++ b/doc/06-config.md @@ -312,4 +312,4 @@ file. Defaults to `true`. If set to `false`, Composer will not create and require a `platform_check.php` file as part of the autoloader bootstrap. -← [Repositories](05-repositories.md) | [Community](07-community.md) → +← [Repositories](05-repositories.md) | [Runtime](07-runtime.md) → diff --git a/doc/07-runtime.md b/doc/07-runtime.md new file mode 100644 index 000000000..f1e2cb52e --- /dev/null +++ b/doc/07-runtime.md @@ -0,0 +1,95 @@ +# Runtime Composer utilities + +While Composer is mostly used around your project to install its dependencies, +there are a few things which are made available to you at runtime. + +If you need to rely on some of these in a specific version, you can require +the `composer-runtime-api` package. + +## Autoload + +The autoloader is the most used one, and is already covered in our +[basic usage guide](#01-basic-usage.md#autoloading). It is available in all +Composer versions. + +## Installed versions + +composer-runtime-api 2.0 introduced a new `Composer\InstalledVersions` class which offers +a few static methods to inspect which versions are currently installed. This is +automatically available to your code as long as you include the Composer autoloader. + +The main use cases for this class are the following: + +### Knowing whether package X (or virtual package) is present + +```php +\Composer\InstalledVersions::isInstalled('vendor/package'); // returns bool +\Composer\InstalledVersions::isInstalled('psr/log-implementation'); // returns bool +``` + +Note that this can not be used to check whether platform packages are installed. + +### Knowing whether package X is installed in version Y + +> **Note:** To use this, your package must require `"composer/semver": "^2.0"`. + +```php +use Composer\Semver\VersionParser; + +\Composer\InstalledVersions::satisfies(new VersionParser, 'vendor/package', '2.0.*'); +\Composer\InstalledVersions::satisfies(new VersionParser, 'psr/log-implementation', '^1.0'); +``` + +This will return true if e.g. vendor/package is installed in a version matching +`2.0.*`, but also if the given package name is replaced or provided by some other +package. + +### Knowing the version of package X + +> **Note:** This will return `null` if the package name you ask for is not itself installed +> but merely provided or replaced by another package. We therefore recommend using satisfies() +> in library code at least. In application code you have a bit more control and it is less +> important. + +```php +// returns a normalized version (e.g. 1.2.3.0) if vendor/package is installed, +// or null if it is provided/replaced, +// or throws OutOfBoundsException if the package is not installed at all +\Composer\InstalledVersions::getVersion('vendor/package'); +``` + +```php +// returns the original version (e.g. v1.2.3) if vendor/package is installed, +// or null if it is provided/replaced, +// or throws OutOfBoundsException if the package is not installed at all +\Composer\InstalledVersions::getPrettyVersion('vendor/package'); +``` + +```php +// returns the package dist or source reference (e.g. a git commit hash) if vendor/package is installed, +// or null if it is provided/replaced, +// or throws OutOfBoundsException if the package is not installed at all +\Composer\InstalledVersions::getReference('vendor/package'); +``` + +A few other methods are available for more complex usages, please refer to the +source/docblocks of the class itself. + +## Platform check + +composer-runtime-api 2.0 introduced a new `vendor/composer/platform_check.php` file, which +is included automatically when you include the Composer autoloader. + +It verifies that platform requirements (i.e. php and php extensions) are fulfilled +by the PHP process currently running. If the requirements are not met, the script +prints a warning with the missing requirements and exits with code 104. + +To avoid an unexpected white page of death with some obscure PHP extension warning in +production, you can run `composer check-platform-reqs` as part of your deployment/build +and if that returns a non-0 code you should abort. + +If you for some reason do not want to use this safety check, and would rather +risk runtime errors when your code executes, you can disable this by setting the +[`platform-check`](06-config.md#platform-check) config option to `false`. + +← [Config](06-config.md) | [Community](08-community.md) → diff --git a/doc/07-community.md b/doc/08-community.md similarity index 97% rename from doc/07-community.md rename to doc/08-community.md index 0a45827ec..fc140e0c7 100644 --- a/doc/07-community.md +++ b/doc/08-community.md @@ -32,4 +32,4 @@ for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for developme Stack Overflow has a growing collection of [Composer related questions](https://stackoverflow.com/questions/tagged/composer-php). -← [Config](06-config.md) +← [Config](07-runtime.md) diff --git a/doc/articles/autoloader-optimization.md b/doc/articles/autoloader-optimization.md index 41bd4a6cb..11faac8a7 100644 --- a/doc/articles/autoloader-optimization.md +++ b/doc/articles/autoloader-optimization.md @@ -2,7 +2,7 @@ tagline: How to reduce the performance impact of the autoloader --> -# Autoloader Optimization +# Autoloader optimization By default, the Composer autoloader runs relatively fast. However, due to the way PSR-4 and PSR-0 autoloading rules are set up, it needs to check the filesystem