PluginConfig.php

<?php
declare(strict_types=1);

/**
 * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
 * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 *
 * Licensed under The MIT License
 * For full copyright and license information, please see the LICENSE.txt
 * Redistributions of files must retain the above copyright notice.
 *
 * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 * @link          https://cakephp.org CakePHP(tm) Project
 * @since         5.1.0
 * @license       https://opensource.org/licenses/mit-license.php MIT License
 */
namespace Cake\Core;

use Cake\Core\Exception\CakeException;
use Cake\Utility\Hash;

/**
 * PluginConfig contains all available plugins and their config if/how they should be loaded
 *
 * @internal
 */
class PluginConfig
{
    /**
     * Cache for installed plugins to avoid re-reading files
     *
     * @var array<string, array<string, mixed>>|null
     */
    private static ?array $cachedPlugins = null;

    /**
     * Load the path information stored in vendor/cakephp-plugins.php
     *
     * This file is generated by the cakephp/plugin-installer package and used
     * to locate plugins on the filesystem as applications can use `extra.plugin-paths`
     * in their composer.json file to move plugin outside of vendor/
     *
     * @internal
     * @return void
     */
    public static function loadInstallerConfig(): void
    {
        if (Configure::check('plugins')) {
            return;
        }
        $vendorFile = dirname(__DIR__, 2) . DIRECTORY_SEPARATOR . 'cakephp-plugins.php';
        if (!is_file($vendorFile)) {
            $vendorFile = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'cakephp-plugins.php';
            if (!is_file($vendorFile)) {
                Configure::write(['plugins' => []]);

                return;
            }
        }

        $config = require $vendorFile;
        Configure::write($config);
    }

    /**
     * Get an array of all installed plugins and their configuration options.
     *
     * Returns an array of plugin configurations with keys:
     * - bootstrap: Enable bootstrap hook (if isLoaded)
     * - console: Enable console hook (if isLoaded)
     * - events: Enable events hook (if isLoaded)
     * - isLoaded: Whether plugin is configured to load
     * - isUnknown: Present and set to true when a plugin is configured but not found in the installed plugins list
     * - middleware: Enable middleware hook (if isLoaded)
     * - onlyCli: Load only in CLI mode (if isLoaded)
     * - onlyDebug: Load only in debug mode (if isLoaded)
     * - optional: Plugin is optional (if isLoaded)
     * - path: Plugin filesystem path (only present for installed plugins, not for unknown ones)
     * - routes: Enable routes hook (if isLoaded)
     * - services: Enable services hook (if isLoaded)
     *
     * @return array<string, array<string, mixed>> Plugin name => configuration
     */
    public static function getInstalledPlugins(): array
    {
        if (self::$cachedPlugins !== null) {
            return self::$cachedPlugins;
        }

        self::loadInstallerConfig();

        // phpcs:ignore
        $pluginLoadConfig = @include CONFIG . 'plugins.php';
        if (is_array($pluginLoadConfig)) {
            $pluginLoadConfig = Hash::normalize($pluginLoadConfig);
        } else {
            $pluginLoadConfig = [];
        }

        $result = [];
        $availablePlugins = Configure::read('plugins', []);
        if ($availablePlugins && is_array($availablePlugins)) {
            foreach ($availablePlugins as $pluginName => $pluginPath) {
                if ($pluginLoadConfig && array_key_exists($pluginName, $pluginLoadConfig)) {
                    $options = $pluginLoadConfig[$pluginName];
                    $hooks = PluginInterface::VALID_HOOKS;
                    $mainConfig = [
                        'path' => $pluginPath,
                        'isLoaded' => true,
                        'onlyDebug' => $options['onlyDebug'] ?? false,
                        'onlyCli' => $options['onlyCli'] ?? false,
                        'optional' => $options['optional'] ?? false,
                    ];
                    foreach ($hooks as $hook) {
                        $mainConfig[$hook] = $options[$hook] ?? true;
                    }
                    $result[$pluginName] = $mainConfig;
                } else {
                    $result[$pluginName] = [
                        'path' => $pluginPath,
                        'isLoaded' => false,
                    ];
                }
            }
        }

        $diff = array_diff(array_keys($pluginLoadConfig), array_keys($availablePlugins));
        foreach ($diff as $unknownPlugin) {
            $result[$unknownPlugin]['isLoaded'] = false;
            $result[$unknownPlugin]['isUnknown'] = true;
        }

        return self::$cachedPlugins = $result;
    }

    /**
     * Clear the cached plugins data. Useful for testing.
     *
     * @return void
     */
    public static function clearCache(): void
    {
        self::$cachedPlugins = null;
    }

    /**
     * Get the config how plugins should be loaded with enriched package metadata.
     *
     * @param string|null $path The absolute path to the composer.lock file to retrieve the versions from
     * @return array<string, array<string, mixed>> Plugin name => enriched configuration with package metadata
     */
    public static function getAppConfig(?string $path = null): array
    {
        // Get base plugin configuration (paths and load config)
        $result = self::getInstalledPlugins();

        try {
            $composerVersions = self::getVersions($path);
        } catch (CakeException) {
            $composerVersions = [];
        }

        // Enrich with package metadata and versions
        foreach ($result as $pluginName => $config) {
            // Skip unknown plugins (no path available)
            if (!isset($config['path'])) {
                continue;
            }

            try {
                $packageName = self::getPackageNameFromPath($config['path']);
                $result[$pluginName]['packagePath'] = $config['path'];
                $result[$pluginName]['package'] = $packageName;
            } catch (CakeException) {
                $packageName = null;
            }

            if ($composerVersions && $packageName) {
                foreach (['packages' => false, 'devPackages' => true] as $key => $isDev) {
                    if (array_key_exists($packageName, $composerVersions[$key])) {
                        $result[$pluginName]['version'] = $composerVersions[$key][$packageName];
                        $result[$pluginName]['isDevPackage'] = $isDev;
                        break;
                    }
                }
            }

            // Remove 'path' key to maintain BC (getAppConfig uses packagePath instead)
            unset($result[$pluginName]['path']);
        }

        return $result;
    }

    /**
     * Get package versions from composer.lock file.
     *
     * @param string|null $path The absolute path to the composer.lock file to retrieve the versions from
     * @return array{packages: array<string, string>, devPackages: array<string, string>} Array with 'packages' and 'devPackages' keys
     * @throws \Cake\Core\Exception\CakeException When composer.lock is missing, unreadable, or invalid
     */
    public static function getVersions(?string $path = null): array
    {
        $lockFilePath = $path ?? ROOT . DIRECTORY_SEPARATOR . 'composer.lock';
        if (!file_exists($lockFilePath)) {
            throw new CakeException(sprintf('composer.lock does not exist in %s', $lockFilePath));
        }
        $lockFile = file_get_contents($lockFilePath);
        if ($lockFile === false) {
            throw new CakeException(sprintf('Could not read composer.lock: %s', $lockFilePath));
        }
        $lockFileJson = json_decode($lockFile, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new CakeException(sprintf(
                'Error parsing composer.lock: %s',
                json_last_error_msg(),
            ));
        }

        $packages = Hash::combine($lockFileJson['packages'], '{n}.name', '{n}.version');
        $devPackages = Hash::combine($lockFileJson['packages-dev'], '{n}.name', '{n}.version');

        return [
            'packages' => $packages,
            'devPackages' => $devPackages,
        ];
    }

    /**
     * Extract package name from composer.json in the given path.
     *
     * @param string $path The plugin path containing composer.json
     * @return string The package name (e.g., 'cakephp/debug-kit')
     * @throws \Cake\Core\Exception\CakeException When composer.json is missing, unreadable, or invalid
     */
    protected static function getPackageNameFromPath(string $path): string
    {
        $jsonPath = $path . DS . 'composer.json';
        if (!file_exists($jsonPath)) {
            throw new CakeException(sprintf('composer.json does not exist in %s', $jsonPath));
        }
        $jsonString = file_get_contents($jsonPath);
        if ($jsonString === false) {
            throw new CakeException(sprintf('Could not read composer.json: %s', $jsonPath));
        }
        $json = json_decode($jsonString, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new CakeException(sprintf(
                'Error parsing %s: %s',
                $jsonPath,
                json_last_error_msg(),
            ));
        }

        return $json['name'];
    }
}