Add docs about new runtime features

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

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`.
 

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) →

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) →

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)

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