Provideri a prihlásenie

Providera získate cez fasádu Git. S tokenom v konfigurácii nemusíte odovzdávať žiadne prihlasovacie údaje; explicitne odovzdané údaje majú vždy prednosť pred konfiguráciou:

use RoundlyConsulting\Git\Dto\Credentials\Token;
use RoundlyConsulting\Git\Enums\ProviderName;
use RoundlyConsulting\Git\Facades\Git;
use RoundlyConsulting\Git\Providers\Gitlab;

$github = Git::github();                       // uses config('git.providers.github.token')
$github = Git::github(Token::from('ghp_...')); // explicit override
$gitlab = Git::gitlab();
$bitbucket = Git::bitbucket();

$gitlab = Git::provider('gitlab');             // by string,
$gitlab = Git::provider(ProviderName::Gitlab); // by ProviderName enum,
$gitlab = Git::provider(Gitlab::class);        // or by class-string

Ako sa vyberajú predvolené údaje

• Ak sú nastavené git.providers.github.app.id, installation_id aj private_key, vytvorí sa z nich samoobnovujúci sa GithubAppToken.
• Ak niektorá z troch hodnôt chýba, token providera (GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN) sa použije ako statický Token. Aplikácia nastavená len pre Git::githubApp() — id a kľúč, pričom id inštalácií prichádzajú pre každého zákazníka zvlášť — je bežné nastavenie, nie chyba.
• Bez oboch je provider neprihlásený a verejné repozitáre číta anonymne — neposiela sa žiadna hlavička Authorization a platí anonymná kvóta platformy (na GitHube 60 požiadaviek za hodinu). Zápisy vyhodia InvalidCredentialsException.

Typy prihlasovacích údajov

Získaného providera môžete prihlásiť aj sami a zistiť, čo akceptuje:

$provider = Git::provider('github');          // unauthenticated when nothing is configured
$provider->isAuthenticated();                   // false

$provider->authenticate(Token::from($user->github_token));
$provider->isAuthenticated();                   // true

$provider->authenticationMethods();             // [Token::class, GithubAppToken::class, GithubApp::class, OauthToken::class]
$provider->name();                              // "GitHub"
$provider->providerName();                      // ProviderName::Github

Ak odovzdáte údaje, ktoré provider neakceptuje, vyhodí sa InvalidCredentialsException so zoznamom podporovaných metód. Každý typ údajov v toArray() a toJson() tajomstvá maskuje (••••), takže sa nikdy nedostanú do logov.

Chyby prihlásenia

Odpoveď 401 — platforma odmietla samotné prihlasovacie údaje — vyhodí InvalidCredentialsException: „requires authentication“, ak žiadne údaje nie sú nastavené, a „rejected the credential“, ak je token neplatný, zrušený alebo expirovaný (odpoveď platformy nájdete v getPrevious()). Každé iné odmietnutie zostáva výnimkou RequestException z Laravelu, takže z nej prečítate stav: repozitár, ktorý nevidíte, je 404 (GitHub pred volajúcimi bez prístupu súkromné repozitáre skrýva), a obmedzené 403 či 429 zostáva opakovateľné, nezamení sa s pokazenými údajmi. To isté platí pre 401 pri vydávaní inštalačného tokenu GitHub App (zrušený alebo nesprávny kľúč aplikácie) či pri obnove OAuth tokenu.

use Illuminate\Http\Client\RequestException;
use RoundlyConsulting\Git\Exceptions\InvalidCredentialsException;

try {
    $repository = Git::github()->repo('acme/api')->get();
} catch (InvalidCredentialsException $e) {
    // 401: "requires authentication" (none configured) or "rejected the credential"
    report($e->getPrevious());   // the forge's own response
} catch (RequestException $e) {
    $e->response->status();      // 404 = missing or not visible, 403/429 = throttled
}

Rozšírenie manažéra

Balík hovorí s GitHubom, GitLabom a Bitbucketom — provider() rozpozná len tieto tri, podľa kľúča v konfigurácii, triedy drivera alebo ProviderName. Rozšíriť ho môžete na dvoch miestach. GitManager podporuje makrá, takže si nad drivermi zaregistrujete vlastné skratky a voláte ich cez fasádu:

use RoundlyConsulting\Git\Dto\Credentials\Token;
use RoundlyConsulting\Git\Facades\Git;
use RoundlyConsulting\Git\Handles\RepositoryHandle;

Git::macro('app', fn (): RepositoryHandle => $this->github()->repo('acme/app'));
Git::macro('forUser', fn (User $user) => $this->github(Token::from($user->github_token)));

Git::app()->pullRequests();          // same as Git::github()->repo('acme/app')->pullRequests()
Git::forUser($user)->repositories();

Drivery sa získavajú z kontajnera a nie sú final, takže vstavaný driver môžete nahradiť podtriedou — napríklad kvôli ďalšiemu endpointu. Git::github(), Git::capabilities() aj matica funkcií vo fake podtriedu prevezmú:

use RoundlyConsulting\Git\Providers\Github;

$this->app->bind(Github::class, AcmeGithub::class); // class AcmeGithub extends Github { … }