README

adachsoft/git-platform is a small PHP library that provides a thin, test-friendly abstraction over Git hosting providers.

The first implementation in this repository targets GitLab (REST API v4) and focuses on repository management and offset-based pagination for listing repositories.

The only layer you need to use as a consumer is the PublicApi layer, in particular AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface and AdachSoft\GitPlatform\PublicApi\GitRepository\Builder\GitRepositoryFacadeBuilder.

This package is intended to be used as a library in other applications (not as a standalone service).

Requirements

• PHP ^8.1
• ext-json
• A PSR-18 HTTP client implementation
• PSR-17 request & stream factories

This library is tested with:

• guzzlehttp/guzzle as PSR-18 client
• guzzlehttp/psr7 as PSR-7 implementation and factories

Installation

Install the library via Composer:

composer require adachsoft/git-platform

The package itself only requires PSR interfaces:

• psr/http-client
• psr/http-factory

In a typical setup you will also install a concrete implementation, e.g.:

composer require guzzlehttp/guzzle
composer require guzzlehttp/psr7

If you already have a PSR-18 client and PSR-17 factories in your project, you can reuse them – the library will use them under the hood when you build the facade.

Quick Start (GitLab)

The recommended entry point is the GitRepositoryFacadeBuilder, which creates a ready-to-use GitRepositoryFacadeInterface instance for GitLab.

<?php

use AdachSoft\GitPlatform\Infrastructure\GitLab\GitLabConfigDto;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Builder\GitRepositoryFacadeBuilder;
use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;

$baseUrl = 'https://gitlab.com';
$accessToken = 'your-gitlab-personal-access-token';

$gitLabConfig = new GitLabConfigDto($baseUrl, $accessToken);

$builder = new GitRepositoryFacadeBuilder();

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$gitRepositoryFacade = $builder->build($gitLabConfig);

From now on you only interact with the GitRepositoryFacadeInterface and PublicApi DTOs.

Listing Repositories (Pagination)

The GitRepositoryFacade::listRepositories() method exposes offset-based pagination on top of GitLab projects API.

Default pagination

Calling listRepositories() without arguments uses the default pagination:

• page = 1
• perPage = 20

use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\ListRepositoriesQueryDto;
use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\PaginatedRepositoryCollectionDto;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Collection\RepositoryCollection;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\RepositoryDto;

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$paginated = $gitRepositoryFacade->listRepositories();

// $paginated is an instance of PaginatedRepositoryCollectionDto

$items = $paginated->items; // RepositoryCollection

foreach ($items as $repository) {
    /** @var RepositoryDto $repository */
    echo $repository->id . ' ' . $repository->fullName . PHP_EOL;
}

// Pagination metadata
$page = $paginated->page;        // int
$perPage = $paginated->perPage;  // int
$totalItems = $paginated->totalItems; // ?int (may be null when GitLab does not return it)
$totalPages = $paginated->totalPages; // ?int

Custom pagination

To request a specific page and page size, construct ListRepositoriesQueryDto and pass it to listRepositories():

use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\ListRepositoriesQueryDto;
use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$query = new ListRepositoriesQueryDto(page: 2, perPage: 50);

$paginated = $gitRepositoryFacade->listRepositories($query);

// You can now assert or use pagination metadata
assert($paginated->page === 2);
assert($paginated->perPage === 50);

Creating a Repository

Use CreateRepositoryDto to create a new repository:

use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\CreateRepositoryDto;
use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\RepositoryDto;

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$dto = new CreateRepositoryDto(
    name: 'my-new-repository',
    description: 'Example project managed via git-platform',
    private: null,           // optional, let GitLab defaults decide
    visibility: 'private',   // or 'public', 'internal' depending on your GitLab setup
);

/** @var RepositoryDto $repository */
$repository = $gitRepositoryFacade->createRepository($dto);

echo $repository->id;       // string
echo $repository->fullName; // string

Updating a Repository

Use UpdateRepositoryDto to update an existing repository. You only need to provide the fields you want to change:

use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\RepositoryDto;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\UpdateRepositoryDto;

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$dto = new UpdateRepositoryDto(
    repositoryId: '123456',
    name: 'renamed-repository',
    description: 'Updated description',
    private: null,             // keep previous value
    visibility: 'private',     // change visibility
    hasIssues: true,
    hasWiki: false,
);

/** @var RepositoryDto $repository */
$repository = $gitRepositoryFacade->updateRepository($dto);

echo $repository->name; // "renamed-repository"

Getting a Single Repository

use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;
use AdachSoft\GitPlatform\PublicApi\GitRepository\Dto\RepositoryDto;

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$repositoryId = '123456';

/** @var RepositoryDto $repository */
$repository = $gitRepositoryFacade->getRepository($repositoryId);

echo $repository->fullName;

Deleting a Repository

use AdachSoft\GitPlatform\PublicApi\GitRepository\GitRepositoryFacadeInterface;

/** @var GitRepositoryFacadeInterface $gitRepositoryFacade */
$repositoryId = '123456';

$gitRepositoryFacade->deleteRepository($repositoryId);

Versioning

This library follows semantic versioning (SemVer).

• Current stable version: 0.1.0 (initial release)
• See CHANGELOG.md for a human-readable list of changes between versions.

Error Handling

The facade methods may throw domain-specific exceptions when underlying operations fail, for example when:

• the repository cannot be found,
• there is a connection problem with the GitLab API,
• the GitLab API returns an unexpected response.

Make sure to wrap calls in your own error handling or translate these exceptions to your application-level errors.

License

This library is released under the MIT License.