Php Gitlab Api Laravel Package

Getting Started

Start by installing the package with Composer and a PSR-18 HTTP client (e.g., Guzzle):

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

Authenticate using a personal access token (PAT) or OAuth token:

use Gitlab\Client;
use Gitlab\HttpClient\AccessToken;

$client = new Client();
$client->authenticate('your-personal-access-token', Client::AUTH_HTTP_TOKEN);

For self-hosted GitLab instances, set the base URL before authenticating:

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

The first use case is typically fetching projects or creating a new one:

// List projects
$projects = $client->projects()->all();

// Create a project
$project = $client->projects()->create('MyProject', [
    'description' => 'My first project',
    'visibility' => 'private',
]);

Check the official API docs reference for full method coverage.

Implementation Patterns

Encapsulate in Services

Wrap the client in domain-specific services for reuse and testability:

class GitLabProjectService
{
    private Client $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function createProtectedProject(string $name): array
    {
        return $this->client->projects()->create($name, [
            'visibility' => 'private',
            'issues_enabled' => true,
            'merge_requests_enabled' => true,
        ]);
    }
}

Use Pager for Large Datasets

Leverage the ResultPager class to iterate over paginated endpoints efficiently:

use Gitlab\ResultPager;

$pager = new ResultPager($client);
$members = $pager->fetchAll($client->projects()->members(), 'all', [12345]);

Build Custom HTTP Clients

Configure middleware and headers using the HttpClient\Builder:

use Http\Client\Common\Plugin\RetryPlugin;
use Gitlab\HttpClient\Builder;

$builder = new Builder();
$builder->addPlugin(new RetryPlugin());

$client = new Client($builder);

Laravel Integration

Use the official Laravel package for DI and config management:

composer require graham-campbell/gitlab

Then inject Gitlab\Client or use the Gitlab facade in controllers.

Gotchas and Tips

PSR-7/17/18 Compatibility

Ensure you install both a PSR-18 client (e.g., Guzzle) and a PSR-17 factory implementation (e.g., nyholm/psr7 or php-http/discovery handles this automatically in most cases). Use php-http/discovery for framework integrations to avoid tight coupling.

Authentication Mode Must Be Explicit

The client throws exceptions if authentication mode is omitted. Always pass Client::AUTH_HTTP_TOKEN or Client::AUTH_OAUTH_TOKEN.

Self-Hosted Instances Require Trailing Slash Removal

GitLab URLs with trailing slashes can cause malformed paths. Trim or validate URLs:

$url = rtrim($config['url'], '/');
$client->setUrl($url);

Page-Based vs. Full Fetch

Using all() fetches all pages automatically but can time out on very large lists. Prefer streaming or filtered queries for production:

// Filter first to reduce payload size
$issues = $client->issues()->all($projectId, [
    'state' => 'opened',
    'per_page' => 20,
]);

Type Safety in v12+

The package enforces strict return types (e.g., array, ?array, bool, void). Be wary of relying on vague docblocks—consult src/Api methods directly for signatures.

Caching Responses

Enable caching via HTTPlug plugins (e.g., symfony/http-cache) or PSR-6/16 cache adapters if using symfony/cache. Example in HttpClient\Builder:

$builder->addPlugin(new CachePlugin($pool, $requestMatcher));

Debugging Requests

Enable request logging using a logger plugin or inspect HTTP history:

$history = $client->getResponseHistory();
// Or use Laravel Telescope for full request introspection via the Laravel wrapper.