Zum Inhalt springen

Einführung

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu bfe242f

Pitmaster ist eine reine PHP-Bibliothek, die Git-Repositorys nativ liest und schreibt. Grundlegende Repository-Operationen rufen weder das git-Binary als externen Prozess auf noch verwenden sie FFI. Das Git-Objektmodell, das Pack-Dateiformat, das Indexformat und der Smart-HTTP-Transport sind in PHP implementiert.

Warum es Pitmaster gibt

PHP-Anwendungen, die mit Git-Repositorys arbeiten, rufen normalerweise das git-Binary als externen Prozess auf. Das funktioniert, setzt aber voraus, dass git installiert ist, birgt Sicherheitsrisiken durch exec() und proc_open() und erschwert die Bereitstellung in eingeschränkten Umgebungen (Containern ohne git, Shared Hosting, serverlosen Funktionen).

Pitmaster macht das git für grundlegende Repository-Arbeiten überflüssig. Deine PHP-Anwendung kann Commit-Historien lesen, Commits erstellen, Diffs berechnen, den Status prüfen und über Smart-HTTP auf Remotes pushen – nur mit den integrierten Funktionen von PHP. Hooks und SSH-Transport sind Ausnahmen: Beide starten Prozesse und lassen sich pro Repository-Handle deaktivieren (siehe Hooks).

Funktionen

  • Liest und schreibt lose Objekte (Blob, Tree, Commit, Tag)
  • Liest Packdateien und löst Delta-Ketten auf (OFS_DELTA und REF_DELTA)
  • Schreibt Packdateien für Netzwerkoperationen
  • Liest und schreibt den Index/Staging-Bereich (Formate v2, v3, v4)
  • Liest und schreibt Refs (Branches, Tags, HEAD, Packed-Refs, Reftable)
  • Berechnet Diffs (Myers-, Patience-, Histogram- und Minimal-Algorithmen) im einheitlichen Format von git
  • Führt Three-Way-Merges mit Konflikterkennung aus
  • Durchläuft Commit-Graphen (Log, Abstammung, Merge-Basis)
  • Unterstützt das Smart-HTTP-Protokoll Git (Clone, Fetch, Push)
  • Unterstützt Arbeitsbäume, Submodule, Stash, Hooks und Git LFS

Voraussetzungen

  • PHP 8.2 oder höher
  • Erweiterung zlib (in praktisch allen PHP-Installationen integriert)
  • Erweiterung json
  • Erweiterung mbstring (in composer.json deklariert, daher von Composer bei der Installation verlangt)
  • Erweiterung ctype (zur Validierung von Objekt-Hashes; in den meisten PHP-Builds aktiviert, aber nicht in composer.json deklariert)

Für grundlegende Repository-Operationen ist das git-Binary nicht erforderlich. Optionale Funktionen benötigen möglicherweise zusätzliche Laufzeitfunktionen: Hooks werden mit proc_open() ausgeführt, und der SSH-Transport verwendet ext-ssh2, wenn es geladen ist, andernfalls startet er das System-ssh-Binary über proc_open().

Schnellstart-Beispiel

PHP
use Pitmaster\Pitmaster;

$repo = Pitmaster::open('/path/to/project');

// Read the current HEAD commit
$head = $repo->head();
echo $head->message;

// List branches
foreach ($repo->branches() as $branch) {
    echo $branch . "\n";
}

// Check status
foreach ($repo->status() as $entry) {
    echo "{$entry->path}: {$entry->index->value}{$entry->worktree->value}\n";
}

// Create a commit
$repo->add('src/Feature.php');
$commitId = $repo->commit('Add new feature');

Beginne mit Erste Schritte und nutze dann API, CLI und Vorgänge für den restlichen Funktionsumfang. Unter Tests erfährst du, wie Pitmaster anhand von git geprüft wird.