biurad / php-git-scm

src/Repository.php

<?php declare(strict_types=1);

/*
 * This file is part of Biurad opensource projects.
 *
 * @copyright 2022 Biurad Group (https://biurad.com/)
 * @license   https://opensource.org/licenses/BSD-3-Clause License
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Biurad\Git;

use Psr\Log\LoggerInterface;
use Symfony\Component\Process\Exception\ExceptionInterface;
use Symfony\Component\Process\Exception\ProcessFailedException;
use Symfony\Component\Process\Process;

/**
 * The Git Repository.
 *
 * @author Divine Niiquaye Ibok <divineibok@gmail.com>
 */
class Repository
{
    private float $timeout = 600.0;
    private string $command = 'git';
    private int $exitCode = 0;
    private int $concurrency = 0;
    private string $gitDir;
    private array $cache = [];

    public function __construct(
        private string $path,
        private array $envVars = [],
        private bool $debug = true,
        private ?LoggerInterface $logger = null,
    ) {
        $this->gitDir = $this->path.'/.git';

        if (\defined('PHP_WINDOWS_VERSION_BUILD') && isset($_SERVER['PATH']) && !isset($envVars['PATH'])) {
            $this->envVars['PATH'] = $_SERVER['PATH'];
        }
    }

    /**
     * Create a local clone of a remote repository.
     *
     * @param string            $path    The path to clone the repository to
     * @param array<int,string> $envVars
     * @param array<int,string> $args    Additional arguments to pass to the clone command
     */
    public static function fromRemote(
        string $remoteRepo,
        string $path,
        array $envVars = [],
        array $args = [],
        bool $debug = true,
        LoggerInterface $logger = null,
    ): self {
        if (!\file_exists($path)) {
            \mkdir($path, 0777, true);
        }

        $repo = new self($path, $envVars, $debug, $logger);
        $repo->run('clone', [$remoteRepo, '.', ...$args], null, $path);

        return $repo;
    }

    /**
     * Set how long to wait for a command to finish.
     */
    public function setTimeOut(float $timeout): void
    {
        $this->timeout = $timeout;
    }

    /**
     * Set the git command to use (e.g. 'git' or '/usr/bin/git').
     */
    public function setCommand(string $command): void
    {
        $this->command = $command;
    }

    /**
     * Set the git environment variables.
     */
    public function setEnvVars(array $envVars): void
    {
        $this->envVars = $envVars;
    }

    /**
     * Remove the git environment variable(s).
     */
    public function removeEnvVars(string ...$envVars): void
    {
        foreach ($envVars as $envVar) {
            unset($this->envVars[$envVar]);
        }
    }

    /**
     * Get the git environment variables.
     *
     * @return array<string,string>
     */
    public function getEnvVars(): array
    {
        return $this->envVars;
    }

    /**
     * Returns the url or path to the repository.
     */
    public function getPath(): string
    {
        return $this->path;
    }

    /**
     * Returns the path to the .git directory.
     */
    public function getGitPath(): string
    {
        return $this->isBare() ? $this->path : $this->gitDir;
    }

    /**
     * Returns true if the repository is bare.
     */
    public function isBare(): bool
    {
        if (!\file_exists($this->path)) {
            return false;
        }

        return 'true' === \trim($this->run('rev-parse', ['--is-bare-repository']));

It seems like $this->run('rev-parse', array('--is-bare-repository')) can also be of type null; however, parameter $string of trim() does only seem to accept string, maybe add an additional type check?

    }

    /**
     * @return int the size of repository in kilobytes, -1 if command failed
     */
    public function getSize(bool $real = false): int
    {
        if ($real) {
            if (0 === ($totalBytes = &$this->cache['size'] ?? 0)) {
                $iterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($this->getGitPath(), \FilesystemIterator::SKIP_DOTS));

                foreach ($iterator as $object) {
                    $totalBytes += $object->getSize();
                }
            }

            return (int) ($totalBytes / 1000 + 0.5);
        }

        if (empty($o = $this->run('count-objects')) || 0 !== $this->exitCode) {
            return -1;
        }

        return (int) \substr($o, \strpos($o, ',') + 2, -10);
    }

    /**
     * Get the git repository configuration(s).
     */
    public function getConfig(string $key = null, string|int|float|bool $default = null): mixed
    {
        $resolve = fn (string $v) => 'true' === $v ? true : ('false' === $v ? false : (\is_numeric($v) ? (int) $v : $v));

        if (null === $key) {
            $o = $this->run('config', ['--list']);

            if (empty($o) || 0 !== $this->exitCode) {
                return null;
            }

            if (!isset($this->cache[$i = \md5($o)])) {
                foreach (\explode("\n", $o) as $line) {
                    if (!empty($line)) {
                        [$k, $v] = \explode('=', $line, 2);
                        $this->cache[$i][$k] = $resolve($v);
                    }
                }
            }

            return $this->cache[$i];
        }

        try {
            $o = $this->run('config', ['--get', $key]);
        } catch (ExceptionInterface) {

Consider adding a comment why this CATCH block is empty.

        }

        return (empty($o) || 0 !== $this->exitCode) ? $default : $resolve(\trim($o));
    }

    /**
     * Returns all remotes.
     *
     * @return array<string,Remote>
     */
    public function getRemotes(): array
    {
        $o = $this->run('remote', ['--verbose']);

        if (empty($o) || 0 !== $this->exitCode) {
            return [];
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\array_filter(\explode(" (push)\n", $o)) as $line) {
                [$a, $b] = \explode("\n", $line, 2);
                [$remote, $url] = \explode("\t", $b, 2);
                $this->cache[$i][$remote] = new Remote($remote, \substr($a, \strlen($remote) + 1, -8), $url);
            }
        }

        return $this->cache[$i];
    }

    /**
     * Returns untracked files in the repository.
     *
     * @return array<int,array<string,string>> array of [status => '??', file => 'file.txt']
     */
    public function getUntrackedFiles(bool $staged = false): array
    {
        $o = $this->run('status', ['--porcelain', '-uall', $staged ? '-s' : '--untracked-files=all']);

        if (empty($o) || 0 !== $this->exitCode) {
            return [];
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\explode("\n", $o) as $line) {
                if (!empty($line)) {
                    [$status, $file] = \explode(' ', $line, 2);
                    $this->cache[$i][] = \compact('status', 'file');
                }
            }
        }

        return $this->cache[$i];
    }

    /**
     * Get the git repository's references.
     *
     * @return array<int,Revision>
     */
    public function getReferences(): array
    {
        $o = $this->run('show-ref');

        if (empty($o) || 0 !== $this->exitCode) {
            return [];
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\explode("\n", $o) as $line) {
                if (!empty($line)) {
                    [$hash, $ref] = \explode(' ', $line, 2);

                    if (\str_starts_with($ref, 'refs/heads/') || \str_starts_with($ref, 'refs/remotes/')) {
                        $this->cache[$i][] = new Branch($this, $ref, $hash);
                    } elseif (\str_starts_with($ref, 'refs/tags/')) {
                        $this->cache[$i][] = new Tag($this, $ref, $hash);
                    } else {
                        $this->cache[$i][] = new Revision($this, $ref, $hash);
                    }
                }
            }
        }

        return $this->cache[$i];
    }

    /**
     * Returns an array of all branches.
     *
     * @return array<int,Branch>
     */
    public function getBranches(): array
    {
        $o = $this->run('branch', ['-a', '--format=%(refname:short) %(objectname)']);

        if (empty($o) || 0 !== $this->exitCode) {
            return [];
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\explode("\n", $o) as $line) {
                if (!empty($line)) {
                    [$branch, $hash] = \explode(' ', $line, 2);

                    if (\in_array($branch, ['refs/heads/HEAD', 'origin/HEAD'], true)) {
                        continue;
                    }

                    $ref = \str_starts_with($branch, 'origin/') ? 'remotes/' : 'heads/';
                    $this->cache[$i][] = new Branch($this, 'refs/'.$ref.$branch, $hash);
                }
            }
        }

        return $this->cache[$i];
    }

    /**
     * Returns branch(es) belonging to a revision, if count is 1, the first branch is returned.
     * Head is detached if the revision value is HEAD and null is returned.
     *
     * @param string $revision The branch ref name or short name, tag, or a commit hash
     *
     * @return array<int,Branch>|Branch|null
     */
    public function getBranch(string $revision = 'HEAD'): Branch|array|null
    {
        $o = $this->run('branch', ['--points-at', $revision, '--format=%(refname:short) %(objectname)']);

        if (empty($o) || 0 !== $this->exitCode) {
            return null;
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\explode("\n", $o) as $line) {
                if (!empty($line)) {
                    [$branch, $hash] = \explode(' ', $line, 2);

                    if (\in_array($branch, ['refs/heads/HEAD', 'origin/HEAD'], true)) {
                        continue;
                    }

                    if (\str_starts_with($revision, 'refs/')) {
                        $branch = (\str_starts_with($revision, 'refs/heads/') ? 'refs/heads/' : 'refs/remotes/').$branch;
                    } elseif (\str_starts_with($revision, 'heads/')) {
                        $branch = 'refs/heads/'.$branch;
                    } elseif (\str_starts_with($revision, 'origin/') || \str_starts_with($revision, 'remotes/')) {
                        $branch = 'refs/remotes/origin/'.$branch;
                    }

                    $this->cache[$i][] = new Branch($this, $branch, $hash);
                }
            }
        }

        return 1 === \count($this->cache[$i]) ? $this->cache[$i][0] : $this->cache[$i] ?? null;
    }

    /**
     * Returns an indexed array of all tags.
     *
     * @return array<int,Tag>
     */
    public function getTags(): array
    {
        $o = $this->run('tag', ['--sort=-creatordate', '--format=%(refname:short) %(objectname)']);

        if (empty($o) || 0 !== $this->exitCode) {
            return [];
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\explode("\n", $o) as $line) {
                if (!empty($line)) {
                    [$tag, $hash] = \explode(' ', $line, 2);
                    $this->cache[$i][] = new Tag($this, 'refs/tags/'.$tag, $hash);
                }
            }
        }

        return $this->cache[$i];
    }

    /**
     * Returns tag(s) belonging to a revision, if count is 1, the first tag is returned.
     *
     * @param string $revision The tag ref name or short name, tag, or a commit hash
     *
     * @return array<int,Tag>|Tag|null
     */
    public function getTag(string $revision = 'HEAD'): Tag|array|null
    {
        $o = $this->run('tag', ['--points-at', $revision, '--format=%(refname:short) %(objectname)']);

        if (empty($o) || 0 !== $this->exitCode) {
            return null;
        }

        if (!isset($this->cache[$i = \md5($o)])) {
            foreach (\explode("\n", $o) as $line) {
                if (!empty($line)) {
                    [$tag, $hash] = \explode(' ', $line, 2);
                    $this->cache[$i][] = new Tag($this, 'refs/tags/'.$tag, $hash);
                }
            }
        }

        return 1 === \count($this->cache[$i]) ? $this->cache[$i][0] : $this->cache[$i] ?? null;
    }

    /**
     * Returns a commit object from it given hash.
     */
    public function getCommit(string $commitHash): Commit
    {
        return $this->cache[$commitHash] ??= new Commit($this, $commitHash);
    }

    /**
     * Returns the current commit.
     */
    public function getLastCommit(): ?Commit
    {
        $o = $this->run('log', ['--pretty=format:%H', '-n', 1]);

        if (empty($o) || 0 !== $this->exitCode) {
            return null;
        }

        return $this->getCommit(\trim($o));
    }

    /**
     * @param array<int,string>|string|null $revisions a list of revisions or null if you want all history
     * @param array<int,string>|string|null $paths     paths to filter on
     * @param int|null                      $offset    start list from a given position
     * @param int|null                      $limit     limit number of fetched elements
     */
    public function getLog(array|string $revisions = null, array|string $paths = null, int $offset = null, int $limit = null): Log
    {
        return new Log($this, $revisions, $paths, $offset, $limit);
    }

    /**
     * Returns the global default git user.
     */
    public function getAuthor(bool $local = false): ?Commit\Identity
    {
        if (!isset($this->cache['author'])) {
            $data = $this->runConcurrent([
                ['config', '--get', $local ? '--local' : '--global', 'user.name'],
                ['config', '--get', $local ? '--local' : '--global', 'user.email'],
            ], null, false);

            if (empty($data) || 0 !== $this->exitCode) {
                return null;
            }

            $this->cache['author'] = new Commit\Identity($data[0], $data[1]);
        }

        return $this->cache['author'];
    }

    /**
     * Returns the last exit code.
     */
    public function getExitCode(): int
    {
        return $this->exitCode;
    }

    /**
     * Returns the number of concurrent git commands.
     */
    public function getConcurrentRuns(): int
    {
        return $this->concurrency;
    }

    /**
     * Resets the repository object reference object, cache
     * and discard all local changes in your working directory.
     *
     * @param bool $keep preserve uncommitted local changes if true
     */
    public function reset(string $commitHash = null, bool $keep = false): void
    {
        $this->cache = [];
        $this->run('reset', [$keep ? '--keep' : '--hard', $commitHash ?? 'HEAD']);
    }

    /**
     * Cleans up the repository completely without leaving a single file.
     */
    public function clean(): void
    {
        $this->runConcurrent([
            ['clean', '-f', '-d', '-x'],
            ['rm', '-rfq', '--ignore-unmatch', '.'], // Extra to ensure everything is removed
            ['reset'],
        ]);
    }

    /**
     * Initializes the repository as a Git repository.
     */
    public function initialize(int|string ...$args): self
    {
        if (!\file_exists($p = $this->path)) {
            \mkdir($p, 0777, true);
        }

        $this->run('init', $args);

        return $this;
    }

    /**
     * Adds a new commit to repository.
     *
     * @param array<int,string> $args arguments to pass to git commit
     */
    public function commit(CommitNew|Commit\Message $commit, array $args = [], string $cwd = null): self
    {
        if ($commit instanceof Commit\Message) {
            $msg = $commit->__toString();
            $msg = !empty($msg) ? ['-m', $msg] : ['--allow-empty-message'];
            $this->runConcurrent([['add', '--all'], ['commit', '--allow-empty', ...$msg, ...$args]], cwd: $cwd);

            return $this;
        }

        $commands = [];
        $msg = ($data = $commit->getData())[0]->__toString();
        $commands[] = !empty($paths = $data[1] ?? []) ? ['add', ...$paths] : ['add', '--all'];
        $oldEnv = $this->envVars;

        if (isset($data[2])) {
            $this->envVars['GIT_AUTHOR_NAME'] = $data[2]->getName();
            $this->envVars['GIT_AUTHOR_EMAIL'] = $data[2]->getEmail();

            if (null !== $d = $data[2]->getDate()) {
                $this->envVars['GIT_AUTHOR_DATE'] = $d->format('D, d M Y H:i:s');
            }

            if (!isset($data[3])) {
                $data[3] = $data[2];
            }
        }

        if (isset($data[3])) {
            $this->envVars['GIT_COMMITTER_NAME'] = $data[3]->getName();
            $this->envVars['GIT_COMMITTER_EMAIL'] = $data[3]->getEmail();

            if (null !== $d = $data[3]->getDate()) {
                $this->envVars['GIT_COMMITTER_DATE'] = $d->format('D, d M Y H:i:s');
            }
        }

        if (!empty($coAuthors = $data[4] ?? [])) {
            $coAuthors = \array_map(fn (Commit\Identity $i) => $i->getName().' <'.$i->getEmail().'>', $coAuthors);
            $msg .= "\n".($c = "\n".'Co-Authored-By: ').\implode($c, $coAuthors);
        }

        $msg = !empty($msg) ? ['-m', $msg] : ['--allow-empty-message'];
        $commands[] = ['commit', '--allow-empty', ...$msg, ...$args];
        $this->runConcurrent($commands, cwd: $cwd);
        $this->envVars = $oldEnv;

        return $this;
    }

    /**
     * Amend a previous commit message from it hash.
     */
    public function amend(string $commitHash, Commit\Message $message, string $cwd = null): bool
    {
        $msg = $message->__toString();
        $msg = !empty($msg) ? ['-m', $msg] : ['--allow-empty-message'];

        return $this->check('commit', ['-C', $commitHash, ...$msg, '--amend'], null, $cwd);
    }

    /**
     * Pushes changes to a remote or git repository.
     *
     * @param array<int,string> $args arguments to pass to git push
     * @param string|null       $cwd  The working directory command should run from
     */
    public function push(string $remote = null, array $args = [], string $cwd = null): self
    {
        if (false === $this->getConfig('push.autoSetupRemote', false)) {
            if (0 === $this->getExitCode()) {
                $this->run('config', ['push.autoSetupRemote', 'true']);
            } elseif (!\in_array('--all', $args, true)) {
                \array_unshift($args, '--set-upstream', $remote ?? 'origin', $this->getBranch()[1]);
                $remote = null; // looks like git version is older than 2.35
            }
        }

        if (null !== $remote) {
            \array_unshift($args, $remote);
        }

        $this->run('push', $args, cwd: $cwd);

        return $this;
    }

    /**
     * Checks if command status is true or false.
     *
     * @param string                $command  Run git command eg. (checkout, branch, tag)
     * @param array<int,int|string> $args     Arguments of the git command
     * @param callable|string|null  $expected The string or callable to check command output
     * @param string|null           $cwd      The working directory command should run from
     */
    public function check(string $command, array $args = [], string|callable $expected = null, string $cwd = null): bool
    {
        try {
            $o = $this->run($command, $args, null, $cwd);
        } catch (ProcessFailedException) {

Consider adding a comment why this CATCH block is empty.

        }

        if (0 !== $this->exitCode) {
            return false;
        }

        return isset($o) ? ($expected === $o || (\is_callable($expected) ? $expected($o) : true)) : false;
    }

    /**
     * @param string                $command  Run git command eg. (checkout, branch, tag)
     * @param array<int,int|string> $args     Arguments of the git command
     * @param callable|null         $callback Reads buffer, param of (string $type, string $buffer)
     * @param string|null           $cwd      The working directory command should run from
     *
     * @return string output of a successful process or null if execution failed and debug-mode is disabled
     *
     * @throws \RuntimeException while executing git command (debug-mode only)
     */
    public function run(string $command, array $args = [], callable $callback = null, string $cwd = null): ?string
    {
        $process = new Process([$this->command, $command, ...$args], $cwd ?? $this->path, $this->envVars, null, $this->timeout);

        if (0 !== $this->concurrency) {
            $this->concurrency = 0;
        }

        try {
            $this->exitCode = $process->mustRun($callback)->getExitCode();

            return $process->getOutput();
        } catch (ExceptionInterface $e) {
            $this->logger?->error($e->getMessage());

            return $this->debug ? throw $e : null;
        } finally {
            if (null !== $this->logger) {
                $message = \sprintf(' at "%.2fms".', (\microtime(true) - $process->getStartTime()) * 1000);
                $this->logger->debug(\sprintf('Command "%s" finished successfully'.$message, $process->getCommandLine()));
            }
        }
    }

    /**
     * Concurrently run multiple git commands.
     *
     * @param array<int,array<int,string>|string> $commands An array list of commands eg. [['log', 'master'], ['git', '-v']]
     * @param callable|null                       $callback Reads buffer, param of (array $command, string $type, string $buffer)
     * @param string|null                         $cwd      The working directory command should run from
     *
     * @return array<int,string>
     */
    public function runConcurrent(array $commands, callable $callback = null, bool $exitOnFailure = true, string $cwd = null): array
    {
        $outputs = [];
        $this->concurrency = 0;

        if (null !== $this->logger) {
            $message = 'Concurrent command(s) [%s] finished successfully';
            $lines = [];
            $start = 0;
        }

        if ($hasCallback = null !== $callback) {
            $callback = fn (array $command): callable => fn (string $type, string $buffer) => $callback($type, $buffer, $command);
        }

        foreach ($commands as $k => $command) {
            $command = \is_array($command) ? $command : [$command];
            $process = new Process([$this->command, ...$command], $cwd ?? $this->path, $this->envVars, null, $this->timeout);

            try {
                $process->start($hasCallback ? $callback($command) : null);

                foreach ($process->getIterator() as $buffer) {
                    if (!isset($outputs[$k])) {
                        $outputs[$k] = $buffer;
                        continue;
                    }
                    $outputs[$k] .= "\n" === $buffer[0] ? $buffer : "\n".$buffer;
                }

                $this->exitCode = $process->wait();
                ++$this->concurrency;
            } catch (ExceptionInterface $e) {
                $this->exitCode = 1;
            }

            if (0 !== $this->exitCode) {
                $this->logger?->error(
                    \sprintf('Concurrent executed "%s/%s" successfully, but failed on "%s".', $this->concurrency, \count($commands), $process->getCommandLine()),
                    ['error' => null]
                );

                if ($exitOnFailure) {
                    return $this->debug ? throw ($e ?? new ProcessFailedException($process)) : [];
                }
            }

            if (isset($lines)) {
                $lines[] = $process->getCommandLine();

                if (isset($start)) {
                    $start += \microtime(true) - $process->getStartTime();
                }
            }
        }

        if (isset($message, $start)) {
            $this->logger->debug(\sprintf($message.' at "%.2fms".', \implode(', ', $lines ?? []), $start * 1000));

The method debug() does not exist on null.

        }

        return $outputs;
    }

    /**
     * Executes a shell command on the repository, using PHP pipes.
     *
     * @param string $command The command to execute
     */
    public function shell(string $command, array $env = []): void
    {
        $argument = \sprintf('%s \'%s\'', $command, $this->getGitPath());
        $prefix = '';

        foreach ($env as $name => $value) {
            $prefix .= \sprintf('export %s=%s;', \escapeshellarg($name), \escapeshellarg($value));
        }

        \proc_open($prefix.'git shell -c '.\escapeshellarg($argument), [\STDIN, \STDOUT, \STDERR], $pipes);
    }
}