From a8ed352b3141345292b7b750f927152251808f6e Mon Sep 17 00:00:00 2001
From: Jordi Boggiano <j.boggiano@seld.be>
Date: Tue, 28 Dec 2021 22:04:22 +0100
Subject: [PATCH] Add docs for the new bin-dir access and bump runtime-api,
 refs #10402

---
 doc/07-runtime.md               |  9 +++++++++
 doc/articles/vendor-binaries.md | 34 +++++++++++++++++++++++++++++++++
 src/Composer/Composer.php       |  2 +-
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/doc/07-runtime.md b/doc/07-runtime.md
index f4d4c8da4..fef0b3923 100644
--- a/doc/07-runtime.md
+++ b/doc/07-runtime.md
@@ -162,4 +162,13 @@ This is set by the binary proxy and as such is not made available to projects
 by Composer's `vendor/autoload.php`, which would be useless as it would point back
 to itself.
 
+## Binary (bin-dir) path in binaries
+
+composer-runtime-api 2.2.2 introduced a new `$_composer_bin_dir` global
+variable set when running binaries installed with Composer. Read more
+about this [on the vendor binaries docs](articles/vendor-binaries.md#finding-the-composer-bin-dir-from-a-binary).
+
+This is set by the binary proxy and as such is not made available to projects
+by Composer's `vendor/autoload.php`.
+
 &larr; [Config](06-config.md)  |  [Community](08-community.md) &rarr;
diff --git a/doc/articles/vendor-binaries.md b/doc/articles/vendor-binaries.md
index 120b73dec..f55c92692 100644
--- a/doc/articles/vendor-binaries.md
+++ b/doc/articles/vendor-binaries.md
@@ -93,6 +93,40 @@ If you want to rely on this in your package you should however make sure to
 also require `"composer-runtime-api": "^2.2"` to ensure that the package
 gets installed with a Composer version supporting the feature.
 
+## Finding the Composer bin-dir from a binary
+
+As of Composer 2.2.2, a new `$_composer_bin_dir` global variable
+is defined by the bin proxy file, so that when your binary gets executed
+it can use it to easily locate the project's autoloader.
+
+For non-PHP binaries, the bin proxy sets a `COMPOSER_BIN_DIR` environment
+variable.
+
+This global variable will not be available however when running binaries defined
+by the root package itself, so you need to have a fallback in place.
+
+This can look like this for example:
+
+```php
+<?php
+
+$binDir = $_composer_bin_dir ?? __DIR__ . '/../vendor/bin';
+```
+
+```php
+#!/bin/bash
+
+if [[ -z "$COMPOSER_BIN_DIR" ]]; then
+  BIN_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+else
+  BIN_DIR="$COMPOSER_BIN_DIR"
+fi
+```
+
+If you want to rely on this in your package you should however make sure to
+also require `"composer-runtime-api": "^2.2.2"` to ensure that the package
+gets installed with a Composer version supporting the feature.
+
 ## What about Windows and .bat files?
 
 Packages managed entirely by Composer do not *need* to contain any
diff --git a/src/Composer/Composer.php b/src/Composer/Composer.php
index 362ea0bcd..624e02507 100644
--- a/src/Composer/Composer.php
+++ b/src/Composer/Composer.php
@@ -66,7 +66,7 @@ class Composer
      *
      * @var string
      */
-    const RUNTIME_API_VERSION = '2.2.0';
+    const RUNTIME_API_VERSION = '2.2.2';
 
     /**
      * @return string