Gitter Laravel Package

Getting Started

klaussilveira/gitter is a small, read-oriented object wrapper around the git CLI. You give it a path to a repository on disk, and it returns commit, branch, tag, tree, blob, diff, and statistics objects. There is no framework integration, no service provider, and no database — just Composer autoloading and a git binary.

Prerequisites to verify before writing any code:

• PHP version compatible with the release you install (check composer.json; the codebase is pre-PHP-8 style and may not be fully typed)
• git installed and on PATH for the web process user (often www-data, not your shell user)
• Read permission on the repository directory and its .git folder for that same user

Install:

composer require klaussilveira/gitter

Smallest useful example — list recent commits:

use Gitter\Client;

$client = new Client();
$repository = $client->getRepository(base_path('repos/my-app'));

foreach ($repository->getCommits() as $commit) {
    printf("%s  %s  %s\n",
        substr($commit->getHash(), 0, 8),
        $commit->getAuthor(),
        $commit->getMessage()
    );
}

Where to look first:

1. src/Gitter/Client.php — how git commands are executed and how the binary path is configured.
2. src/Gitter/Repository.php — the primary API surface: getCommits(), getCommit(), getBranches(), getTags(), getTree(), getBlob(), getDiff(), getStatistics(), getCurrentBranch().
3. src/Gitter/Model/ — the plain value objects (Commit, Branch, Tag, Tree, Blob, Diff, Statistics). Skim their getters so you know what you actually get back.

First use case to validate the package against: "show the last N commits on branch X with insertions/deletions per commit." That single flow exercises listing, pagination, ref handling, and diff/stat parsing, and will quickly expose whether the shell-out model and parsing quality are acceptable for your app.

Implementation Patterns

Repository as a scoped service. In Laravel, bind a single Client as a singleton, and resolve a Repository per request from a configured base path. Keep the raw gitter objects out of controllers; wrap them in your own RepoReader/ChangelogService so tests can swap in fakes and so you control caching and error handling in one place.

$this->app->singleton(Client::class, fn () => new Client());

// In a service:
public function commits(string $branch, int $page = 1, int $perPage = 20): array
{
    return $this->client
        ->getRepository($this->repoPath)
        ->getCommits($branch, ($page - 1) * $perPage, $perPage);
}

Commit browsing / changelog pages. The dominant pattern is paginate → iterate → render. Always pass explicit offset and limit; the default limit is small and will silently truncate lists. Resolve the branch or ref yourself (getCurrentBranch() or a route parameter) and pass it consistently.

Tree and blob traversal. getTree() returns entries that are either blobs or subtrees. Check each entry's type/mode before recursing, and pass hash values — not paths — to getBlob() and getTree(). Recursive file browsers should be built with a depth cap and a cancellation/size guard.

Diff and stat views. getDiff($commit) and getStatistics($commit) are the two calls behind a "files changed" tab. Render diff lines by their type (added / removed / unchanged) rather than diffing strings yourself, and use statistics for summary badges. Resolve the parent commit first if you want first-parent diffs on merges.

Caching aggressively. Every call shells out to git. Cache commit lists per (repo, ref, offset, limit), commit objects per hash, and tree listings per tree hash with a short TTL. Invalidate by comparing getCurrentBranch()/HEAD or simply use a 1–5 minute TTL for dashboards.

Testing pattern. Don't point unit tests at your real repository. Create a temp directory per test, run git init and a few commits through Symfony\Component\Process\Process, then exercise gitter against it. This also documents exactly which git version behavior you depend on.

Read-only by design. This library is for inspection. Deploy tooling, commit creation, branch checkout, merges, and pushes are not part of the API — use symfony/process or git directly for those and keep gitter for the read side.

Gotchas and Tips

• It shells out to git. Expect process-spawn overhead and PATH issues. If PHP-FPM cannot find git, configure the binary explicitly on the client (setGitBinary('/usr/bin/git')) instead of debugging exec.
• Empty repositories throw. A freshly git init-ed repo with no commits will fail on getCommits(). Guard for this before rendering a UI.
• The default page size is small. If your list looks cut off, it is almost certainly the implicit limit. Pass offset/limit on every listing call and assert the count in tests.
• Refs, not strings, please. The first argument to commit listing is a git ref (branch, tag, or hash). Passing a display name with spaces or shell-hostile characters is a bug waiting to happen — validate ref names against a whitelist.
• Date types vary by model/version. Check whether getDate() / getAuthorDate() return a DateTime or a formatted string before calling ->format(). Normalize to DateTimeImmutable at your boundary either way.
• Diff parsing is the weakest link. Rename detection, binary files, and merge commits can produce output the model flattens or mislabels. Verify a handful of real commits (especially merges and renames) before trusting the diff tab.
• Binary blobs. getBlob()->getContent() will happily return binary bytes. Size-check and MIME-sniff before sending content to a browser.
• Escape everything. Commit messages, author names, tag messages, and file paths can contain HTML, control characters, and non-UTF-8 bytes. Escape at render time.
• Path security. Never pass a user-supplied path to getRepository(). Resolve with realpath() and assert it starts with a known repository root; otherwise you have an arbitrary-read primitive over the filesystem.
• Errors surface as generic runtime exceptions from failed git commands. Catch them at the service boundary and convert to a 404/500 with a useful message; don't let a missing repo bubble up through a Blade template.
• Debug by replaying the command. When a result looks wrong, run the equivalent git log/git show/git diff manually in the same directory as the same OS user. That distinguishes a gitter parsing bug from a permissions or git-version issue.
• Extension points are thin. There is no plugin system. Prefer decorating/adapting Repository and the model objects over subclassing; Client and Repository have few seams, and the model classes are simple value objects.
• Pin the version and test on your PHP runtime. The last release is from January 2022; it is stable but not actively evolving. Lock a specific version, run your test suite on the exact PHP and git versions you deploy, and budget a small amount of time for compatibility fixes rather than expecting upstream changes.