Fasáda Git

Všetko začína pri fasáde Git. Git::github() (alebo gitlab(), bitbucket(), provider()) vám dá prihláseného drivera; ->repo('owner/name') ho obmedzí na jeden repozitár a ->pullRequest($number) na jeden jeho pull request. S tokenom v konfigurácii nemusíte odovzdávať žiadne prihlasovacie údaje; explicitne odovzdané majú vždy prednosť pred konfiguráciou:

use RoundlyConsulting\Git\Enums\MergeMethod;
use RoundlyConsulting\Git\Facades\Git;

$github = Git::github();                       // a driver: account-wide reads and writes
$github->repositories();                       // Page<Repository>
$github->createRepository($newRepository);     // Repository

$repo = $github->repo('acme/app');             // a handle on one repository
$repo->pullRequests('open');                   // Page<PullRequest>
$repo->commits()->branch('main')->lazy();      // LazyCollection<int, Commit>
$repo->contents('README.md');                  // FileContent (decoded)
$repo->compare('main', 'feature/ci');          // Comparison
$repo->webhooks()->register();                 // Webhook

$pr = $repo->pullRequest(12);                  // a handle on one pull request
$pr->approve('LGTM');
$pr->merge(MergeMethod::Squash, sha: $pr->get()->raw()['head']['sha'] ?? null);

Git::githubApp()->installations()->find($id);  // app-JWT lookups
Git::capabilities('bitbucket');                // no authentication needed
Git::credentials('github');                    // ?Credentials — what github() would use
Git::verifyWebhook('github', $request);        // bool

API v skratke

Git::credentials() vráti prihlasovacie údaje, ktoré driver dostane, keď žiadne neodovzdáte — najprv nastavenú inštaláciu GitHub App, potom statický token, inak null — takže tie isté údaje môžete odovzdať aj niečomu mimo balíka, napríklad URL na klonovanie. Git::verifyWebhook() spustí kontrolu podpisu balíka pre routu, ktorú spravujete sami (pozrite sekciu Webhooky).

Handly neopustia svoj rozsah

Každá cesta, ktorú handle prijme, skončí v URL platformy, preto ju handly najprv skontrolujú a namiesto oslovenia iného zdroja vyhodia OutOfScopeException (InvalidArgumentException):

use RoundlyConsulting\Git\Exceptions\OutOfScopeException;

Git::github()->repo('acme/app/../billing');          // OutOfScopeException
Git::github()->repo($gitlabRepository);              // OutOfScopeException: belongs to GitLab
Git::github()->repo('acme/app')->contents('../.env'); // OutOfScopeException
Git::github()->repo('acme/app')->contents('%2e%2e/%2e%2e/x');   // OutOfScopeException — decoded first
Git::github()->repo('acme/app')->webhooks()->delete('1/../..'); // OutOfScopeException
Git::github()->repo('acme/app')->pullRequest(0);     // OutOfScopeException

• repo() odmietne prázdnu cestu, prázdny segment, segment . či .., znaky ?, #, \, bajt NUL aj medzery — a tiež objekt Repository, ktorý patrí inému providerovi (repozitár z GitLabu na Git::github()).
• contents(), createFile() a updateFile() odmietnu cesty k súborom so segmentmi ., .. či prázdnymi a so znakmi ?, #, \ alebo bajtom NUL; commit(), release() a compare() odmietnu takéto refy, rovnako ako každý iný ref, ktorý skončí v ceste URL (základný ref pri createBranch() a ref pri createTag() na GitHube).
• Každá hodnota sa kontroluje tak, ako prišla, aj po každom percentovom dekódovaní, pretože HTTP vrstva pred odoslaním dekóduje %2e a zlúči bodkové segmenty: %2e%2e/victim, %252e%252e/victim aj ..%2Fvictim sa odmietnu presne ako ../victim. Čo prejde, sa percentovo zakóduje po segmentoch, takže platforma dostane presne ten názov, ktorý ste zadali (docs/a b.md → docs/a%20b.md, 100%.md → 100%25.md).
• pullRequest() odmietne číslo menšie ako 1, installations()->find() nečíselné id a forOrganization() / forUser() čokoľvek iné než jeden segment.
• webhooks()->delete($id) — aj git:webhook --delete= — prijme len tvar id, aký vydáva platforma: číselné na GitHube a GitLabe, {uuid} v zložených zátvorkách na Bitbuckete, pretože id skončí v URL požiadavky DELETE.

Ploché metódy drivera (Git::github()->contents('acme/app', …)) aj batch() zostavujú URL cez rovnaké kontroly, takže odmietnu tie isté hodnoty.