The rex_gitapi AddOn provides the RexGitApi class for easy access to the GitHub API. In the backend, access to the GitHub API can be tested with the API tester and the associated PHP code can be generated for copying.

The GitHub API documentation can be found here: https://docs.github.com/rest

All API accesses are made using the URL https://api.github.com/.

Notice: REDAXO-AddOns can use the class to update e.g. themes, styles or other data directly from GitHub.

The GitHub API returns all results in JSON format. By default, the class RexGitApi returns the result as a PHP array get(). However, the original JSON result of the GitHub API can also be queried get(true).

In general, all URLs of the GitHub API can be processed directly via the class (public or authorized URL's).

Notice: Without authentication, only 60 accesses per hour to the GitHub Api are possible. One token can access the API 5,000 times per hour. See Authentication (token)

The following URL provides e.g. how many accesses can be carried out at most, how many have already been carried out and how many accesses to the API still remain.

https://api.github.com/rate_limit

Either the full URL https://api.github.com/rate_limit or just rate_limit can be passed as the URL parameter of the class. Protocol and domain (https://api.github.com/) can be omitted.

The token can be passed when instantiating with new, with the factory() method or with setToken(). If no token is passed and there is a token in the AddOn settings, this will be used.

GitHub results are cached by default. The cache lifetime can be changed in the AddOn settings. The caching can be switched off with the method setCache(false). With the AddOn setting Never create a cache no cache will be created!

Example:

// Determine GitHub rate limit
$gitapi = \FriendsOfRedaxo\RexGitApi\RexGitApi::factory();
// or $gitapi = new \FriendsOfRedaxo\RexGitApi\RexGitApi();
$gitapi->setDebug(false);
$gitapi->setCache(false);
$gitapi->setUrl('https://api.github.com/rate_limit');
$gitapi->execute();
$gitresult = $gitapi->get();
dump($gitresult);

// Result PHP array
$gitresult = \FriendsOfRedaxo\RexGitApi\RexGitApi::factory()->execute('https://api.github.com/rate_limit')->get();
dump($gitresult);

// Result JSON Format
$jsonresult = \FriendsOfRedaxo\RexGitApi\RexGitApi::factory()->execute('rate_limit')->get(true);
dump($jsonresult);

// special method
$gitresult = \FriendsOfRedaxo\RexGitApi\RexGitApi::factory()->getLimits();
dump($gitresult);

$jsonresult = \FriendsOfRedaxo\RexGitApi\RexGitApi::factory()->getLimits(true);
dump($jsonresult);

The preferred way to use RexGitApi is to create a new instance (due to error handling)

is optional. If no token is specified, the token from the addon settings is used.

To catch errors when accessing GitHub, an instance of RexGitAPI should be created with new.

$gitapi = new \FriendsOfRedaxo\RexGitApi\RexGitApi();

With the method hasError() a possibly occurring error can be queried. The error message can be output using the getMessage() method.

Example:

$gitapi = new \FriendsOfRedaxo\RexGitApi\RexGitApi();
$gitapi->setDebug(false);
$gitresult = $gitapi->execute('orgs/friendsofredaxo/repos?page=99');
if ($gitapi->hasError()) {
     echo rex_view::error(
        $gitapi->getMessage()
        . '<br>Requested URL: ' . $gitapi->getUrl()
        . '<br>GitHub-Token: ' . $gitapi->getToken()
    );
} else {
    $gitresult = $gitapi->get();
    dump($gitresult);
}

The debug output of the class can be requested via setDebug(true). That can sometimes be quite helpful. 2 blocks are dumped with the REDAXO dump() instruction. Arrays can be expanded here by clicking on the arrow.

Block 1: Parameters

Description

0. Info Debug output of RexGitApi class
1. Requested GitHub Api URL
2. CURLOPT_USERAGENT
3. CURLOPT_HTTPHEADER (including the token)

Block 2: Results

Description

0. Info Debug output of RexGitApi class
1. JSON result of the API call
2. PHP array result of the API call

... TODO

Without authentication, only 60 accesses per hour to the GitHub API are possible. With token you can access the API 5,000 times per hour.

To create an access token (personal access token), you should log into GitHub and then go to the following URL:

https://github.com/settings/apps

Then click Personal access tokens (1) on the page and then Tokens (classic) (2) (see screenshot).

On the next page, click on the button Generate new token (1) and then select Generate new token (classic) (2) (see screenshot).

Notice: Then the Github password must be entered again for confirmation!

On the next page, enter a label (1), select the token expiration (2), and select repo (3) from the options.

For access to user data, additionally select the option user (4).

The generated token is then output on the following screen, which should definitely be copied and saved.

Notice: Be sure to copy and save the token! The token can no longer be displayed!

Ideally the token is stored in the settings for rex_gitapi.

Notice: Tokens can be deleted and re-created at any time. A new token in the settings of the AddOn rex_gitapi is taken into account immediately.

Then it goes on here ...

• On GitHub: https://github.com/FriendsOfREDAXO/rex_gitapi

• In the Slack channel: https://friendsofredaxo.slack.com/

• GitHub API https://docs.github.com/rest
• Friends Of REDAXO Gemeinsame REDAXO-Entwicklung!
• Andreas Eberhard @aeberhard, http://aesoft.de

Photo by Christina Morillo from Pexels: https://www.pexels.com/photo/eyeglasses-in-front-of-laptop-computer-1181253/