Merge pull request #1612 from mihailges/MDL-88576_docs

MDL-88576 [docs] Add documentation for Composer runtime status checks…

Author: abgreeve

general/development/tools/composer.md

@@ -47,3 +47,75 @@ As far as there are a number of variables affecting how that lock file will be g
 1. Check that the `composer.lock` file, together with other changes, does include the changes you've performed in the `composer.json` file.
 1. Ideally, run both phpunit and behat tests and verify that there isn't any problem, using all the supported PHP versions.
 1. Done, you can send the changes for review, integration and, if everything goes ok, will be applied upstream without problem.
+
+## Runtime status checks {/* #runtime-status-checks */}
+
+<Since version="5.3" issueNumber="MDL-88576" />
+
+Moodle provides a Composer runtime status API for inspecting the state of Composer-managed dependencies.
+
+The API can be used to:
+
+- Check whether Composer dependencies are installed.
+- Verify that installed package versions match those recorded in `composer.lock`.
+- Identify missing packages.
+- Identify outdated packages.
+
+### Obtaining the service {/* #obtaining-the-service */}
+
+The Composer service must be obtained through Moodle's dependency injection container.
+
+```php
+$composer = \core\di::get(\core\composer::class);
+```
+
+### Checking Composer installation status {/* #checking-composer-installation-status */}
+
+To determine whether Composer dependencies are installed:
+
+```php
+if ($composer->is_installed()) {
+    echo 'Composer dependencies are installed.';
+}
+```
+
+### Retrieving overall status {/* #retrieving-overall-status */}
+
+The `get_status()` method returns a `\core\composer\status` object containing the overall Composer runtime status and the status of all packages defined in `composer.lock`.
+
+```php
+$status = $composer->get_status();
+
+if (!$status->installed) {
+    echo 'Composer dependencies are not installed.';
+} else if (!$status->current) {
+    echo 'One or more Composer packages require attention.';
+}
+```
+
+The status object also provides convenience methods for identifying packages in a particular state:
+
+```php
+$current = $status->current_packages();
+$missing = $status->missing_packages();
+$outdated = $status->outdated_packages();
+```
+
+### Checking a specific package {/* #checking-a-specific-package */}
+
+The `get_package_status()` method returns a `\core\composer\package_status` object containing information about the package's installation state and version information.
+
+```php
+$package = $composer->get_package_status('composer/installers');
+
+if (!$package->installed) {
+    echo 'Package is not installed.';
+}
+
+if (!$package->current) {
+    echo 'Package is not up to date.';
+}
+
+echo "Required version: {$package->requiredversion}";
+echo "Installed version: {$package->installedversion}";
+```