mborne/remote-git

A lightweight PHP client providing a consistent way to find hosted and self-hosted git repositories (github, gitlab,...)

v0.7.0 2024-03-23 10:09 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ~7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: 3.17.*
• pdepend/pdepend: 2.15.*
• php-coveralls/php-coveralls: ^2.5
• phpmd/phpmd: ^2.8
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9

MIT

• Mickaël BORNE

README

Description

A lightweight PHP client providing a consistent access to hosted and self-hosted git repositories (github, gitlab, gogs and gitea).

Use cases

Note that a small set of features is prefered here to a rich API integration to allow homogenous access to remote hosting services.

The original development has been realized in mborne/satis-gitlab repository to generate a config file referencing git repositories.

This module is also used by mborne/git-manager to backup and analyse git repositories (for example that following files are present : README.md, LICENSE,...)

Features

• List repositories from multiple GIT hosting services filtering by
  • usernames
  • organizations/groups
• Get raw files from repositories
• Apply custom filter
  • Project contains a given file (RequiredFileFilter)
  • Project is a composer project (ComposerProjectFilter)
  • Project name doesn't match a given regexp (IgnoreRegexpFilter)

Requirements

• PHP >= 8.1

Supported GIT hosting services

Type	Description
gitlab-v4	gitlab.com and self hosted gitlab instances
github	github.com
gogs-v1	Gogs or Gitea

Usage

Create a client

// configure client
$clientOptions = new ClientOptions();
$clientOptions
    ->setUrl('https://github.com')
    ->setToken($token)
;

// create client
$client = ClientFactory::createClient(
    $clientOptions,
    new NullLogger()
);

Filter by usernames or orgs/groups

$options = new FindOptions();
// Use '_me_' on github to include private repositories
$options->setUsers(array('mborne'));
$options->setOrganizations(array('symfony','FriendsOfSymfony'));
$projects = $client->find($options);

Filter according to composer.json

$options = new FindOptions();
$options->setUsers(array('mborne'));
$filter = new ComposerProjectFilter($client);
$filter->setType('library');
$options->setFilter($filter);
$projects = $client->find($options);

Compose filters

$options = new FindOptions();
$options->setUsers(array('mborne'));

$filterCollection = new FilterCollection();

// filter according to composer.json
$composerFilter = new ComposerProjectFilter($client);
$composerFilter->setType('library');
$filterCollection->addFilter($composerFilter);

// filter according to README.md
$filterCollection->addFilter(new RequiredFileFilter(
    $client,
    'README.md'
));

$options->setFilter($filterCollection);
$projects = $client->find($options);

Dependencies

• guzzlehttp/guzzle - 7.x
• psr/log

License

MIT

Testing

• Configure access token for github.com and gitlab.com APIs (optional) :

# see https://github.com/settings/tokens
export GITHUB_TOKEN=AnyGithubToken
# see https://gitlab.com/-/profile/personal_access_tokens
export GITLAB_TOKEN=AnyGitlabToken

• Install dependencies and run tests :

make test
# Alternative :
# composer install
# vendor/bin/phpunit -c phpunit.xml.dist

Note that an HTML coverage report is generated to output/coverage/index.html