michaelschiemer/src/Framework/Console/Terminal/PhpStormDetector.php

<?php

declare(strict_types=1);

namespace App\Framework\Console\Terminal;

/**
 * Detects PhpStorm/JetBrains terminal environment
 *
 * Provides utilities for PhpStorm-specific terminal features like
 * clickable file links and project root detection.
 */
final readonly class PhpStormDetector
{
    /**
     * Check if running in PhpStorm/JetBrains terminal
     */
    public static function isPhpStorm(): bool
    {
        // Check TERMINAL_EMULATOR environment variable
        $terminalEmulator = getenv('TERMINAL_EMULATOR');
        if ($terminalEmulator !== false && $terminalEmulator === 'JetBrains-JediTerm') {
            return true;
        }

        // Check IDE_PROJECT_ROOTS (set by PhpStorm/IntelliJ)
        $ideProjectRoots = getenv('IDE_PROJECT_ROOTS');
        if ($ideProjectRoots !== false && $ideProjectRoots !== '') {
            return true;
        }

        // Check TERM for jetbrains-related values
        $term = getenv('TERM');
        if ($term !== false && str_contains(strtolower($term), 'jetbrains')) {
            return true;
        }

        return false;
    }

    /**
     * Get project root paths from IDE_PROJECT_ROOTS
     *
     * @return array<string> Array of project root paths, or empty array if not available
     */
    public static function getProjectRoots(): array
    {
        $ideProjectRoots = getenv('IDE_PROJECT_ROOTS');
        if ($ideProjectRoots === false || $ideProjectRoots === '') {
            return [];
        }

        // IDE_PROJECT_ROOTS is typically a colon-separated list (Unix) or semicolon-separated (Windows)
        $separator = str_contains($ideProjectRoots, ';') ? ';' : ':';
        $roots = explode($separator, $ideProjectRoots);

        // Filter out empty values and normalize paths
        return array_filter(
            array_map('trim', $roots),
            fn(string $root) => $root !== '' && is_dir($root)
        );
    }

    /**
     * Convert absolute file path to relative path based on project roots
     *
     * If PhpStorm is detected and project roots are available, returns the shortest
     * relative path. Otherwise returns the absolute path.
     *
     * @param string $filePath Absolute file path
     * @return string Relative path if project root found, otherwise absolute path
     */
    public static function getRelativePath(string $filePath): string
    {
        if (!self::isPhpStorm()) {
            return $filePath;
        }

        $projectRoots = self::getProjectRoots();
        if (empty($projectRoots)) {
            return $filePath;
        }

        $filePath = realpath($filePath);
        if ($filePath === false) {
            return $filePath;
        }

        $shortestPath = $filePath;
        $shortestLength = strlen($filePath);

        foreach ($projectRoots as $root) {
            $root = realpath($root);
            if ($root === false) {
                continue;
            }

            // Check if file is within this project root
            if (str_starts_with($filePath, $root . DIRECTORY_SEPARATOR) || $filePath === $root) {
                $relative = substr($filePath, strlen($root) + 1);
                if (strlen($relative) < $shortestLength) {
                    $shortestPath = $relative;
                    $shortestLength = strlen($relative);
                }
            }
        }

        return $shortestPath;
    }
}