GitLab PHP API Client

If you are not using gitlab.com, use the setUrl method to point the client to your specific GitLab domain.

$client = new Gitlab\Client();
$client->setUrl('https://git.yourdomain.com');
$client->authenticate('your_access_token', Gitlab\Client::AUTH_HTTP_TOKEN);

For framework-specific integrations, use the following packages:

Laravel: Use graham-campbell/gitlab.

Symfony: Use zeichen32/gitlabapibundle.

# Laravel
$ composer require "graham-campbell/gitlab:^8.1"

# Symfony
$ composer require "zeichen32/gitlabapibundle:^7.0"

To install the GitLab PHP API Client, use Composer. This version supports PHP 8.1-8.5. You must also ensure you have packages installed that provide psr/http-client-implementation and psr/http-factory-implementation (such as Guzzle).

$ composer require "m4tthumphrey/php-gitlab-api:^12.1" "guzzlehttp/guzzle:^7.9.2"

The Gitlab\Client is the primary entry point for interacting with the GitLab API. You can initialize it in two ways:

1. Default Initialization: Using the constructor, which sets up a default HTTP client builder configured for https://gitlab.com with standard plugins (ExceptionThrower, History, Redirect, and User-Agent).
2. Custom HTTP Client: Using createWithHttpClient() if you want to provide your own PSR-18 compliant ClientInterface implementation.

To target a self-hosted GitLab instance, use the setUrl() method after instantiation.

use Gitlab\Client;

// Option 1: Default (gitlab.com)
$client = new Client();

// Option 2: Custom HTTP Client
$client = Client::createWithHttpClient($myPsr18Client);

// For self-hosted instances
$client->setUrl('https://gitlab.example.com');

To handle paginated API responses and retrieve all items in a collection, use the Gitlab\ResultPager. The fetchAll method takes the API resource, a pagination type (e.g., 'all'), and an optional array of filters.

$pager = new Gitlab\ResultPager($client);
$issues = $pager->fetchAll($client->issues(), 'all', [null, ['state' => 'closed']]);

Initialize a Gitlab\Client and use the authenticate method to provide credentials. The client supports multiple authentication methods via constants:

• Gitlab\Client::AUTH_HTTP_TOKEN: For Personal Access Tokens.
• Gitlab\Client::AUTH_OAUTH_TOKEN: For OAuth2 tokens.

$client = new Gitlab\Client();

// Personal access token authentication
$client->authenticate('your_access_token', Gitlab\Client::AUTH_HTTP_TOKEN);

// OAuth2 authentication
// $client->authenticate('your_oauth_token', Gitlab\Client::AUTH_OAUTH_TOKEN);

You can customize the underlying HTTP behavior (like adding custom headers or User-Agents) by passing a Gitlab\HttpClient\Builder to the Gitlab\Client constructor. This allows you to use HTTPlug plugins to modify requests.

$plugin = new Http\Client\Common\Plugin\HeaderSetPlugin([
    'User-Agent' => 'Foobar',
]);

$builder = new Gitlab\HttpClient\Builder();
$builder->addPlugin($plugin);

$client = new Gitlab\Client($builder);

Use the projects(int|string $id, array $parameters) method to retrieve projects belonging to a specific group.

Available Parameters:

• search: Search for projects matching criteria.
• visibility: public, internal, or private.
• order_by: id, name, path, created_at, updated_at, or last_activity_at (default created_at).
• sort: asc or desc (default desc).
• include_subgroups: Include projects in subgroups (default false).
• simple: If true, returns only id, url, name, and path.
• archived: Filter by archived status.
• last_activity_after / last_activity_before: Filter by activity time using \DateTimeInterface objects.

// Get all public projects in a group, including subgroups
$projects = $groups->projects($groupId, [
    'visibility' => 'public',
    'include_subgroups' => true
]);

Use the all() method to retrieve a list of merge requests. You can optionally provide a project_id to scope the request to a specific project. The method accepts a parameters array for filtering and sorting.

Available State Constants:

• MergeRequests::STATE_ALL ('all')
• MergeRequests::STATE_MERGED ('merged')
• MergeRequests::STATE_OPENED ('opened')
• MergeRequests::STATE_CLOSED ('closed')
• MergeRequests::STATE_LOCKED ('locked')

// List all merge requests for a specific project with filters
$mergeRequests = $api->mergeRequests()->all($project_id, [
    'state' => 'opened',
    'assignee_id' => 123,
    'labels' => 'feature,bug',
    'order_by' => 'created_at',
    'sort' => 'desc'
]);

You can manage emoji reactions on GitLab merge requests using the following methods. Note that $project_id can be an integer or a string (e.g., a URL-encoded path), and $mr_iid is the internal ID of the merge request.

// Add an emoji
$client->mergeRequests()->addAwardEmoji($project_id, $mr_iid, 'thumbsup');

// Show details of a specific award
$emoji = $client->mergeRequests()->showAwardEmoji($project_id, $mr_iid, $award_id);

// Remove an emoji
$client->mergeRequests()->removeAwardEmoji($project_id, $mr_iid, $award_id);