README

A modern, strictly typed PHP client for the GitLab REST API built on PSR standards.

Why this library?

Most existing GitLab clients rely heavily on loosely structured arrays and mirror the API 1:1. This project takes a different approach:

Typed DTOs instead of raw arrays
Resource-based API for better developer experience
PSR-18 compatible HTTP layer
Explicit authentication strategies
Focused on maintainability and testability

Key Concept: Resource-Based API

Instead of working with raw arrays or deeply nested API calls, this client introduces resource objects.

You can start with a project and continue working within its context:

$project = $client->projects()->get('nusphere/nuclub');

$branches = $project->branches()->list();
$commits = $project->commits()->list();
$file = $project->files()->getRaw('composer.json', 'main');

This allows a more natural and expressive workflow compared to traditional API clients.

Features

Supports multiple authentication strategies:
- Private Token
- Bearer Token
- Job Token
- Sudo (as decorator)
Clean separation of concerns:
- HTTP layer
- API modules
- DTOs
- Resource objects
Strong typing:
- ProjectResource, ProjectDetails, etc.
- No raw array handling required
Strong error handling via domain-specific exceptions
Designed for testing:
- Mockable HTTP client (PSR-18)
- Fixture-based testing

Installation

composer require nutoolbox/php-gitlab-client

Usage

Basic Example

use NuToolbox\Gitlab\Client;
use NuToolbox\Gitlab\Auth\GitlabAuthentication;
use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\Psr18Client;

$client = new Client(
    psrHttpClient: new Psr18Client(),
    requestFactory: new Psr17Factory(),
    authentication: GitlabAuthentication::privateToken('glpat-xxxxxxxx'),
    baseUrl: 'https://gitlab.example.com',
);

$projects = $client->projects()->list();

foreach ($projects as $project) {
    echo $project->details()->pathWithNamespace . PHP_EOL;
}

Working with Project Resources

$project = $client->projects()->get('nusphere/nuclub');

// Access project details
echo $project->details()->name;

// Work with related resources
$branches = $project->branches()->list();
$commits = $project->commits()->list();

// Access repository files
$content = $project->files()->getRaw('composer.json', 'main');

Direct API Access (Alternative)

You can still use the flat API if preferred:

$branches = $client->branches()->list('nusphere/nuclub');
$file = $client->repositoryFiles()->getRaw('nusphere/nuclub', 'composer.json', 'main');

Authentication

GitlabAuthentication::privateToken('glpat-...');
GitlabAuthentication::bearer('token');
GitlabAuthentication::jobToken('token');

GitlabAuthentication::sudo(
    GitlabAuthentication::privateToken('admin-token'),
    'root'
);

Testing

This library is designed to be testable.

HTTP layer is fully mockable (PSR-18)
Supports fixture-based testing
No real API calls required for unit tests

Example:

$mockHttpClient = new MockHttpClient($response);

Integration tests can use environment variables:

GITLAB_BASE_URL=https://gitlab.example.com
GITLAB_TOKEN=glpat-xxxxxxxx

Example integration test usage:

Requirements

PHP 8.1+
PSR-18 compatible HTTP client

Philosophy

This library focuses on:

strict typing over loosely structured data
explicit behavior over magic
resource-oriented design over endpoint mirroring
small, composable building blocks
long-term maintainability over quick wrappers

License

Apache License 2.0

nutoolbox / php-gitlab-client

Maintainers

Package info

Statistics

Security