Gitlabapibundle Laravel Package

Getting Started

This is a Symfony bundle wrapping the php-gitlab-api client — not a first-class Laravel package. Before installing, decide whether you actually need the bundle or just the underlying client (m4tthumphrey/php-gitlab-api). In most Laravel apps you want the client only; the bundle's value (DI wiring, config tree, service definitions) is Symfony-specific and doesn't map cleanly onto Laravel's container.

If you still want it:

1. composer require zeichen32/gitlab-api-bundle
2. Publish/merge config — the bundle expects a Symfony-style gitlab_api config block. In Laravel you have no config tree, so create config/gitlab.php with the same keys (url, token, auth_method, per_page, pagination) and bind a service yourself.
3. Register a singleton in a service provider:

   $this->app->singleton(\GitLab\Client::class, function ($app) {
       $client = new \GitLab\Client();
       $client->setUrl($app['config']['gitlab.url']);
       $client->authenticate($app['config']['gitlab.token'], \GitLab\Client::AUTH_HTTP_TOKEN);
       return $client;
   });
   

4. First use case: list projects or open MRs for a repo —

   $client->projects()->all(['membership' => true, 'per_page' => 100]);
   $client->mergeRequests()->all($projectId, ['state' => 'opened']);
   

Look first at the php-gitlab-api docs for the API surface; the bundle is essentially configuration + service aliases on top of it.

Implementation Patterns

Prefer the client directly. Since the bundle is a thin Symfony layer, treat it as a config source rather than a runtime dependency. Most Laravel teams end up requiring m4tthumphrey/php-gitlab-api alone and skipping the bundle entirely — fewer moving parts, no Symfony DI baggage.

Facade wrapping. Bind the client as a singleton and expose a GitLab facade for terse calls in controllers and jobs:

GitLab::projects()->all();

Keep the facade thin — one method per resource accessor, not per endpoint.

Pagination as a first-class concern. GitLab returns X-Next-Page headers. Wrap iteration in a generator so jobs don't blow memory:

foreach ($client->projects()->all(['per_page' => 100]) as $page) { ... }

The bundle's per_page/pagination config keys only set defaults; they don't give you a lazy iterator — implement that yourself.

Auth strategy per-environment. Support both AUTH_HTTP_TOKEN (PAT) and OAuth refresh tokens. Store tokens in config/services.php or encrypted env, never in the published config file. For CI jobs, use project access tokens scoped to api.

Queued jobs for write operations. Wrap create/update MRs, comments, pipeline triggers in jobs with RateLimiter::for('gitlab', ...). GitLab enforces per-token rate limits and you'll want retries with backoff on 429s.

Test doubles. Inject the GitLab\Client via constructor and mock it in tests; or point url at a stub server (WireMock/HttpFake) to exercise real HTTP paths.

Symfony 8 support (v7.2.0). Relevant only if you're also running a Symfony app alongside the Laravel one, or if you're using the bundle in a Symfony microservice. For a pure Laravel app this release changes nothing you'll touch.

Gotchas and Tips

• No Laravel service provider ships with the bundle. You must wire the container yourself. Don't expect php artisan vendor:publish to give you a working config.
• Config key names are Symfony-flavored. gitlab_api in Symfony becomes a plain array in Laravel. Watch for nested keys (auth_method vs auth, url vs base_url) — the bundle's aliases don't match older client versions.
• Version drift between bundle and client. The bundle pins a php-gitlab-api version; if you also require the client directly, Composer will resolve to the intersection. Lock both explicitly and check composer why php-gitlab-api when auth breaks.
• Symfony 8 support doesn't imply PHP 8.4 readiness — verify the transitive symfony/* components against your PHP version, especially if you're pulling the bundle into an app that otherwise has no Symfony dependencies.
• Self-hosted GitLab: set url with the sub-path (https://git.example.com/api/v4 vs. base host — the client appends /api/v4 in some versions, not others). Test a simple projects()->all() before wiring anything else; misconfiguration here produces confusing 404s.
• Token scopes: read_api is enough for most read paths; api is required for MR creation, pipeline triggers, and approvals. A 403 on write with a working read is almost always scope, not code.
• Rate limits and pagination interact. A per_page=100 loop against a large group can exhaust your limit inside one request. Queue it, add jitter, and honour Retry-After.
• Extension points are thin. The bundle offers little beyond service definitions — for custom behaviour (caching, logging, metrics) decorate the client in your provider rather than looking for bundle hooks.
• Debugging: enable the client's HTTP logging ($client->getHttpClient()->addListener(...) or Guzzle middleware) to see raw requests. The bundle swallows exceptions inconsistently across versions, so log at the job boundary.

If your goal is simply "talk to GitLab from Laravel," the honest recommendation is to skip this package and use php-gitlab-api directly with a small service provider — you'll get the same capabilities with far less Symfony surface area.