Exploiter l'API GitHub avec Voozanoo4

Voozanoo4 permet, via la classe Core_Library_Github, d’exploiter l’API de GitHub

Edit me

Prérequis

Pour pouvoir utiliser Core_Library_Github, il est nécessaire de générer un token .

Ce token devra être renseigné dans la directive github.access.token du fichier application.ini

Tip: Il est aussi possible de stocker ce token dans une variable d’environnement nommée GITHUB_ACCESS_TOKEN

Comment ça fonctionne

L’API GitHub nous donne accès à trois points d’entrées principaux :

- orgs

https://api.github.com/orgs/{org}

- repos

https://api.github.com/repos/{org}/{repo}

- users

https://api.github.com/users/{user}

Instantiation

Pour interroger ces trois points d’entrées avec le manager Voozanoo4, il faudra procéder de la façon suivante :

$oGithub = new Core_Library_Github();

// Instanciation de l'objet Core_Library_Github_Orgs pour l'organisation "Epiconcept-Paris"
$oOrg = $oGithub->org( 'Epiconcept-Paris' );

// Instanciation de l'objet Core_Library_Github_Repos pour le repo "mon-appli"
// En réalité, le nom exacte du repo est "Epiconcept-Paris/mon-appli"
$oInternalRepo = $oGithub->repo( 'mon-appli' );

// Instanciation de l'objet Core_Library_Github_Repos pour le repo "node" de l'organisation "nodejs"
$oExternalRepo = $oGithub->repo( 'node', 'nodejs' );

// Instanciation de l'objet Core_Library_Github_Users pour l'utilisateur "epikgr"
$oUser = $oGithub->user( 'epikgr' );

La méthode GetUrl() retourne l’URL construite :

echo $oOrg->GetURL();
// "https://api.github.com/orgs/Epiconcept-Paris"

echo $oInternalRepo->GetURL();
// "https://api.github.com/repos/Epiconcept-Paris/mon-appli"

echo $oExternalRepo->GetURL();
// "https://api.github.com/repos/nodejs/node"

echo $oUser->GetURL();
// "https://api.github.com/users/epikgr"

Pour construire le reste de l’URL, il faudra procéder de la façon suivante :

$oContents = $oInternalRepo->contents( 'configs/APPINFOS' );
echo $oContents->GetURL();
// "https://api.github.com/repos/Epiconcept-Paris/mon-appli/contents/configs/APPINFOS"

Si nous voulons lister les commentaires d’une issue, nous devons interroger l’API GitHub avec le lien /repos/:owner/:repo/issues/:issue_number/comments

$oGithub = new Core_Library_Github();
$oComments = $oGithub->repo( 'Voozanoo4' )->issues( 1854 )->comments();

echo $oComments->GetURL();
// "https://api.github.com/repos/Epiconcept-Paris/Voozanoo4/issues/1854/comments"

Utilisation

HEAD

Core_Library_Github::head()

Peut être émis sur n’importe quelle URL pour obtenir uniquement les informations d’en-tête HTTP.

$oGithub = new Core_Library_Github();

$aHeaders = $oGithub->repo( 'aides' )->issues()->head();

echo( sprintf(
    'Cette URL a été utilisée %s/%s fois. Le reset se fera le %s',
    $aHeaders[ 'x-ratelimit-limit' ] - $aHeaders[ 'x-ratelimit-remaining' ],
    $aHeaders[ 'x-ratelimit-limit' ],
    date( 'd/m/Y à H:i:s', (int) $aHeaders[ 'x-ratelimit-reset' ] )
) );
// Cette URL a été utilisée 26/5000 fois. Le reset se fera le 09/09/2019 à 12:42:25

GET

Core_Library_Github::get( $aParams = array() )

Utilisé pour récupérer une ou plusieurs ressources.

$oGithub = new Core_Library_Github();

$aContributors = $oGithub->repo( 'aides' )->contributors()->get();

$sContributors = implode( ', ', array_map( function ( $aContributor ) { return $aContributor[ 'login' ]; }, $aContributors ) );

echo sprintf( 'Les contributeurs du repo "aides" sont : %s', $sContributors );
// Les contributeurs du repo "aides" sont : epikgr, rodriguehee, atouraut, Norelles, gylv, EpiMVE, epi-rlt, nkhaji

GET ALL

Core_Library_Github::getAll( $aParams = array(), $iMaxCall = 20 )

La méthode getAll permet de boucler sur les résultats paginés. En effet, l’API GitHub ne renvoie que 30 ressources, par défaut. Documentation

Pour des raisons de performance, getAll bouclera 20 fois par défaut. Pour changer cette valeur, il faudra passer un entier au deuxième argument de la méthode getAll

$oGithub = new Core_Library_Github();

$aIssues = $oGithub->repo( 'Voozanoo4' )->issues()->getAll( array( 'state' => 'all' ) );

echo sprintf( 'Le repo "Voozanoo4" possède %s issues', sizeof( $aIssues ) );
// Le repo "Voozanoo4" possède 1968 issues (pull request compris) 

$aIssues = $oGithub->repo( 'Voozanoo4' )->issues()->getAll( array( 'state' => 'all' ), 2 );

echo sprintf( 'Le repo "Voozanoo4" possède %s issues', sizeof( $aIssues ) );
// Le repo "Voozanoo4" possède 200 issues (pull request compris) 

POST

Core_Library_Github::post( $aParams = array() )

Utilisé pour créer des ressources.

$oGithub = new Core_Library_Github();

$aResponses = $oGithub->repo( 'Voozanoo4' )->issues( 1854 )->comments()->post( array( 
    'body' => 'Et voici mon super commentaire en **Markdown**' 
) );

echo $aResponses[ 'html_url' ];
// https://github.com/Epiconcept-Paris/Voozanoo4/issues/1854#issuecomment-529457961

PATCH

Core_Library_Github::patch( $aParams = array() )

Utilisé pour la mise à jour d’une ressource avec des données partielles.

$oGithub = new Core_Library_Github();

$aResponses = $oGithub->repo( 'mon-appli' )->patch( array(
    'description' => 'Un repo privé pour tester le manager de l\'API GitHub de Voozanoo4',
    'private' => true
) );

echo $aResponses[ 'description' ];
// Un repo privé pour tester le manager de l'API GitHub de Voozanoo4

PUT

Core_Library_Github::put( $aParams = array() )

Utilisé pour remplacer une ressource ou une collection de ressources.

$oGithub = new Core_Library_Github();

$aResponses = $oGithub->repo( 'mon-appli' )->contents( 'README.md' )->put( array(
    'message' => 'First commit via api',
    'content' => 'This is a README.md file'
) );

echo $aResponses[ 'content' ][ 'html_url' ];
// https://github.com/Epiconcept-Paris/mon-appli/blob/master/README.md

UPSERT

Core_Library_Github_Repos_Contents::upsert( $aParams = array() )

La méthode upsert permet de créer ou de mettre à jour un fichier. Cette mêthode est un raccourci de Core_Library_Github_Repos_Contents::get() puis Core_Library_Github_Repos_Contents::put()

Warning: La méthode upsert n’existe que dans la classe Core_Library_Github_Repos_Contents

$oGithub = new Core_Library_Github();

// Création du fichier README.md
$oGithub->repo( 'mon-appli' )->contents( 'README.md' )->upsert( array(
    'message' => 'First commit via api',
    'content' => 'This is a README.md file'
) );

// Mise à jour du fichier README.md
$oGithub->repo( 'mon-appli' )->contents( 'README.md' )->upsert( array(
    'message' => 'Second commit via api',
    'content' => 'This is a README.md file updated'
) );


echo $aResponses[ 'content' ][ 'html_url' ];
// https://github.com/Epiconcept-Paris/mon-appli/blob/master/README.md

DELETE

Core_Library_Github::delete()

Utilisé pour supprimer des ressources.

$oGithub = new Core_Library_Github();

$oGithub->repo( 'Voozanoo4' )->issues()->comments( 529457961 )->delete();

Exemple complet

$oGithub = new Core_Library_Github();

try {        
    // Instanciation de l'objet Core_Library_Github_Orgs pour l'organisation "Epiconcept-Paris"
    $oOrg = $oGithub->org( 'Epiconcept-Paris' );

    // Instanciation de l'objet Core_Library_Github_Repos pour le repo "mon-appli"
    $oRepo = $oGithub->repo( 'mon-appli' );

    // Création du repo "mon-appli"
    $oOrg->repos()->post(
        array(
            'name' => 'mon-appli'
        )
    );

    // Instanciation de l'objet Core_Library_Github_Repos_Contents pour le path "README.md"
    $oContents = $oRepo->contents( 'README.md' );

    // Premier commit vers le fichier "README.md"
    $oContents->upsert(
        array(
            'message' => 'first commit via api',
            'content' => 'my new file contents'
        )
    );

    // Deuxième commit vers le fichier "README.md"
    $oContents->upsert(
        array(
            'message' => 'second commit via api',
            'content' => 'my file contents updated'
        )
    );

    // Création d'une release "1.01.01"
    $aReleases = $oRepo->releases()->post(
        array(
            'tag_name' => '1.01.01'
        )
    );

    echo sprintf( 'Le tag "%s" a bien été créé !', $aReleases[ 'tag_name' ] );
} catch ( Exception $e ) {
    echo $e->getMessage();
}