### Install and Test Project

Source: https://github.com/gitlabphp/client/blob/12.1/README.md

Commands to install project dependencies and run tests using make targets. Ensure you have the necessary build tools installed.

```bash
$ make install
$ make test
```

--------------------------------

### Complete Usage Example with HTTP Client Customization

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/01-client.md

Shows a full example including client initialization with a custom HTTP client, URL configuration for self-hosted GitLab, authentication, API usage, and accessing response metadata.

```php
<?php

use Gitlab\Client;
use GuzzleHttp\Client as GuzzleClient;

// Initialize with Guzzle HTTP client
$guzzle = new GuzzleClient();
$client = Client::createWithHttpClient($guzzle);

// Configure for self-hosted GitLab
$client->setUrl('https://gitlab.example.com');

// Authenticate
$client->authenticate('glpat-xxxxxxxxxxxxx', Client::AUTH_HTTP_TOKEN);

// Use the API
$projects = $client->projects()->all(['archived' => false]);
foreach ($projects as $project) {
    echo "Project: " . $project['name'] . "\n";
}

// Access last response metadata
$response = $client->getLastResponse();
echo "Status: " . $response->getStatusCode() . "\n";
```

--------------------------------

### Standard Composer Installation

Source: https://github.com/gitlabphp/client/blob/12.1/README.md

Install the GitLab PHP API Client and Guzzle HTTP client using Composer. This is the standard method for integrating the library into your PHP project.

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

--------------------------------

### Complete GitLab Groups API Usage Example

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

A comprehensive PHP example demonstrating various GitLab Groups API operations, including authentication, listing, showing, creating, and managing groups, members, and webhooks.

```php
<?php

use Gitlab\Client;

$client = new Client();
$client->authenticate('token', Client::AUTH_HTTP_TOKEN);
$groupsApi = $client->groups();

// List groups
$groups = $groupsApi->all(['owned' => true]);

// Get single group
$group = $groupsApi->show(1);
echo "Group: " . $group['name'] . "\n";

// Create group
$newGroup = $groupsApi->create(
    'My Team',
    'my-team',
    'Team workspace',
    'private'
);

// Add members
$groupsApi->addMember($newGroup['id'], 5, 30);   // user 5 as developer
$groupsApi->addMember($newGroup['id'], 10, 40);  // user 10 as maintainer

// Get members
$members = $groupsApi->members($newGroup['id']);
foreach ($members as $member) {
    echo $member['username'] . " - Level " . $member['access_level'] . "\n";
}

// Create subgroup
$subgroup = $groupsApi->create(
    'Backend',
    'backend',
    'Backend team',
    'private',
    parent_id: $newGroup['id']
);

// Get subgroups
$subs = $groupsApi->subgroups($newGroup['id']);

// Get group projects
$projects = $groupsApi->projects($newGroup['id']);

// Create webhook
$webhook = $groupsApi->createHook($newGroup['id'], [
    'url' => 'https://example.com/webhook',
    'push_events' => true,
    'issues_events' => true
]);

// Update group
$groupsApi->update($newGroup['id'], [
    'visibility' => 'public'
]);

// Remove group
$groupsApi->remove($newGroup['id']);

```

--------------------------------

### Get All Tags

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieve all tags for a project. Supports searching, ordering, and pagination.

```php
$tags = $client->repositories()->tags(1);
```

--------------------------------

### Get All Projects

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Retrieves a list of all projects with optional filtering and sorting parameters.

```php
public function all(array $parameters = []): mixed
```

```php
$projects = $client->projects()->all([
    'visibility' => 'public',
    'order_by' => 'name',
    'sort' => 'asc'
]);

foreach ($projects as $project) {
    echo $project['name'] . " (" . $project['id'] . ")\n";
}
```

--------------------------------

### Example Usage of API Resource Accessors

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/01-client.md

Demonstrates how to instantiate the client, authenticate, and use accessor methods to retrieve projects and issues.

```php
$client = new Gitlab\Client();
$client->authenticate('token', Gitlab\Client::AUTH_HTTP_TOKEN);

// Get projects API
$projectsApi = $client->projects();
$projects = $projectsApi->all();

// Get issues API
$issuesApi = $client->issues();
$issues = $issuesApi->all($project_id);
```

--------------------------------

### Get Single Project by ID or Path

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Fetches a specific project using its unique ID or its URL-encoded path.

```php
public function show(int|string $id): mixed
```

```php
$project = $client->projects()->show(1);
echo $project['name'];

// Also works with path
$project = $client->projects()->show('namespace/project-name');
```

--------------------------------

### Create Stream from Resource

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/04-http-client.md

Get the PSR-17 stream factory and use it to create a stream from a resource.

```php
$factory = $builder->getStreamFactory();
$stream = $factory->createStreamFromResource($resource);
```

--------------------------------

### Get Repository Tree (Root)

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieve the file and directory listing for the root of a project's repository.

```php
$root = $client->repositories()->tree(1);
```

--------------------------------

### Authenticate

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/13-quick-reference.md

Provides examples for authenticating the client using various methods like Personal Access Tokens, OAuth2, and CI Job Tokens.

```APIDOC
## Authenticate

### Description

Illustrates different authentication methods for the GitLab client, including Personal Access Tokens, OAuth2 tokens, CI Job Tokens, and impersonation.

### Usage

```php
// Personal Access Token (default)
$client->authenticate('glpat-xxxxx', Client::AUTH_HTTP_TOKEN);

// OAuth2
$client->authenticate('oauth_token', Client::AUTH_OAUTH_TOKEN);

// CI Job Token
$client->authenticate('job_token', Client::AUTH_HTTP_JOB_TOKEN);

// With impersonation
$client->authenticate('token', Client::AUTH_HTTP_TOKEN, 'user_id');
```
```

--------------------------------

### showNote()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/03-issues-api.md

Get a single note for a specific issue. Requires project ID, issue IID, and the note's ID.

```APIDOC
## showNote()

### Description
Get a single note.

### Method
GET

### Endpoint
`/projects/:project_id/issues/:issue_iid/notes/:note_id`

### Parameters
#### Path Parameters
- **project_id** (int|string) - Required - Project ID or path
- **issue_iid** (int) - Required - Issue IID
- **note_id** (int) - Required - Note ID

### Response
#### Success Response (200)
- **Note object** (mixed) - The response contains a single note object.
```

--------------------------------

### showNotes()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/03-issues-api.md

Get all notes for a specific issue. Requires the project ID or path and the issue's internal ID (IID).

```APIDOC
## showNotes()

### Description
Get all notes for an issue.

### Method
GET

### Endpoint
`/projects/:project_id/issues/:issue_iid/notes`

### Parameters
#### Path Parameters
- **project_id** (int|string) - Required - Project ID or path
- **issue_iid** (int) - Required - Issue IID

### Response
#### Success Response (200)
- **Array of note objects** (mixed) - The response contains an array of note objects.
```

--------------------------------

### Get Single User by ID

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/07-users-api.md

Retrieves a specific user's details using their unique ID. This is the most direct way to get information about a known user.

```php
$user = $client->users()->show(5);
echo "User: " . $user['username'];
```

--------------------------------

### Create and Update Projects

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Demonstrates how to create a new project with specified details and then update an existing project's description.

```php
// Create
$project = $client->projects()->create('My Project', [
    'visibility' => 'private',
    'description' => 'Project description'
]);

// Update
$client->projects()->update($project['id'], [
    'description' => 'Updated description'
]);
```

--------------------------------

### Complete HTTP Client Usage Example

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/04-http-client.md

Demonstrates creating a GitLab client with a customized HTTP client builder, including adding custom headers and authentication.

```php
<?php

use Gitlab\Client;
use Gitlab\HttpClient\Builder;
use Http\Client\Common\Plugin\HeaderSetPlugin;
use GuzzleHttp\Client as GuzzleClient;

// Create builder with Guzzle
$guzzle = new GuzzleClient([
    'timeout' => 30
]);
$builder = new Builder($guzzle);

// Add custom headers
$headerPlugin = new HeaderSetPlugin([
    'X-Application' => 'MyApp',
    'X-Version' => '1.0'
]);
$builder->addPlugin($headerPlugin);

// Add caching (requires PSR-6 cache implementation)
// $builder->addCache($cachePool);

// Create client with customized builder
$client = new Client($builder);
$client->authenticate('token', Client::AUTH_HTTP_TOKEN);

// Use the client
$projects = $client->projects()->all();
```

--------------------------------

### Initialize Client

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/13-quick-reference.md

Demonstrates how to initialize the GitLab client, including options for self-hosted instances and custom HTTP clients.

```APIDOC
## Initialize Client

### Description

Shows how to create a new instance of the GitLab client. Supports default configuration for gitlab.com, custom URLs for self-hosted instances, and integration with custom HTTP clients.

### Usage

```php
use Gitlab\Client;

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

// Self-hosted
$client = new Client();
$client->setUrl('https://gitlab.company.com');

// With custom HTTP client
$client = Client::createWithHttpClient($httpClient);
```
```

--------------------------------

### commit()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Get a single commit by its SHA.

```APIDOC
## commit()

### Description
Get a single commit by its SHA.

### Method
GET

### Endpoint
/projects/:id/repository/commits/:sha

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **sha** (string) - Required - Commit SHA (full or short)

### Response
#### Success Response (200)
- **id** (string) - The SHA of the commit
- **message** (string) - The commit message
- **author_name** (string) - The author's name
- **authored_date** (string) - The author date

### Request Example
```php
$commit = $client->repositories()->commit(1, 'abc123');
echo "Author: " . $commit['author_name'];
echo "Message: " . $commit['message'];
```
```

--------------------------------

### Work with Repository Branches and Commits

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Provides examples for retrieving a list of branches, fetching commits for a specific branch, and creating a new commit with file updates.

```php
// Get branches
$branches = $client->repositories()->branches(1);

// Get commits
$commits = $client->repositories()->commits(1, [
    'ref_name' => 'main',
    'per_page' => 20
]);

// Create commit
$commit = $client->repositories()->createCommit(1, [
    'branch' => 'main',
    'commit_message' => 'Update README',
    'actions' => [
        [
            'action' => 'update',
            'file_path' => 'README.md',
            'content' => '# My Project'
        ]
    ]
]);
```

--------------------------------

### branch()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Get a single branch by its name.

```APIDOC
## branch()

### Description
Get a single branch by its name.

### Method
GET

### Endpoint
/projects/:id/repository/branches/:branch

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **branch** (string) - Required - Branch name

### Response
#### Success Response (200)
- **name** (string) - The name of the branch
- **commit** (object) - Information about the commit the branch points to

### Request Example
```php
$branch = $client->repositories()->branch(1, 'main');
echo "Branch: " . $branch['name'];
echo "Commit: " . $branch['commit']['id'];
```
```

--------------------------------

### Add HeaderSetPlugin to Builder

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/04-http-client.md

Add an HTTPlug plugin to the end of the plugin chain. This example adds a HeaderSetPlugin to set custom headers.

```php
use Http\Client\Common\Plugin\HeaderSetPlugin;

$plugin = new HeaderSetPlugin([
    'X-Custom-Header' => 'value'
]);

$builder->addPlugin($plugin);
```

--------------------------------

### Complete Projects API Usage Example

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Demonstrates a comprehensive workflow for interacting with the Projects API, including authentication, listing, showing, creating, updating, archiving, adding members, listing members, and deleting projects.

```php
<?php

use Gitlab\Client;

$client = new Client();
$client->authenticate('token', Client::AUTH_HTTP_TOKEN);
$projectsApi = $client->projects();

// List projects
$allProjects = $projectsApi->all([
    'visibility' => 'public',
    'starred' => true,
    'per_page' => 10
]);

// Get single project
$project = $projectsApi->show(123);
echo "Project: " . $project['name'] . "\n";

// Create project
$newProject = $projectsApi->create('New Project', [
    'visibility' => 'private',
    'description' => 'A new project'
]);
echo "Created: " . $newProject['id'] . "\n";

// Update project
$projectsApi->update(123, ['description' => 'Updated']);

// Archive project
$projectsApi->archive(123);

// Add member
$projectsApi->addMember(123, 10, 30);

// List members
$members = $projectsApi->members(123);

// Delete project
$projectsApi->remove(123);
```

--------------------------------

### Get user status

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/07-users-api.md

Retrieves the current status of a user.

```APIDOC
## GET /users/{id}/status

### Description
Get user status.

### Method
GET

### Endpoint
/users/{id}/status

### Parameters
#### Path Parameters
- **id** (int) - Required - User ID

### Response
#### Success Response (200)
- **mixed** - Status object

### Request Example
```php
$status = $client->users()->status(5);
```
```

--------------------------------

### Get User Memberships

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/07-users-api.md

Fetches all project and group memberships for a given user ID. Use the 'type' parameter to filter by 'Project' or 'Namespace'.

```php
// Get all memberships
$memberships = $client->users()->usersMemberships(5);

// Get only project memberships
$projects = $client->users()->usersMemberships(5, [
    'type' => 'Project'
]);
```

--------------------------------

### Complete GitLab Repository Files Usage Example

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/12-repository-files-api.md

Demonstrates a comprehensive set of file operations including reading, creating, updating, obtaining blame information, and deleting files using the GitLab client.

```php
<?php

use Gitlab\Client;

$client = new Client();
$client->authenticate('token', Client::AUTH_HTTP_TOKEN);
$filesApi = $client->repositoryFiles();

// Read file
$file = $filesApi->show(1, 'README.md', 'main');
$content = base64_decode($file['content']);
echo "README:\n" . $content . "\n";

// Read as raw string
$rawContent = $filesApi->getRawFile(1, '.env.example', 'main');

// Create new file
$newFile = $filesApi->create(
    1,
    'config/app.php',
    '<?php\nreturn [\'app\' => \'config\'];',
    'main',
    'Add app config'
);

// Update existing file
$filesApi->update(
    1,
    'README.md',
    '# Updated Project\n\nNew content',
    'main',
    'Update README'
);

// Get blame info
$blame = $filesApi->blame(1, 'src/Api.php', ['ref' => 'main']);
foreach ($blame as $range) {
    $lines = $range['lines'];
    $commit = $range['commit'];
    echo "Lines by " . $commit['author_name'] . ":\n";
    foreach ($lines as $line) {
        echo "  " . $line . "\n";
    }
}

// Delete file
$filesApi->delete(
    1,
    'temp.txt',
    'main',
    'Remove temporary file'
);
```

--------------------------------

### Get Group Webhooks

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

Retrieves all webhooks configured for a specific group.

```php
public function hooks(int|string $group_id, array $parameters = []): mixed
```

--------------------------------

### Create and Update Project

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Demonstrates how to create a new project with specified details and how to update an existing project's description.

```APIDOC
## Create Project

### Description
Creates a new project with a given name and optional details.

### Method
POST

### Endpoint
`/projects`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project.
- **visibility** (string) - Optional - The visibility level of the project (e.g., 'private', 'public', 'internal').
- **description** (string) - Optional - A description for the project.

### Request Example
```php
$client->projects()->create('My Project', [
    'visibility' => 'private',
    'description' => 'Project description'
]);
```

## Update Project

### Description
Updates an existing project, allowing modification of its details.

### Method
PUT

### Endpoint
`/projects/:id`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the project to update.
#### Request Body
- **description** (string) - Optional - The updated description for the project.

### Request Example
```php
$client->projects()->update($project['id'], [
    'description' => 'Updated description'
]);
```
```

--------------------------------

### Get Group Milestones

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

Retrieves a list of all milestones associated with a group.

```php
public function milestones(int|string $group_id, array $parameters = []): mixed
```

--------------------------------

### Symfony Framework Integration

Source: https://github.com/gitlabphp/client/blob/12.1/README.md

Install the GitLab API bundle for Symfony using Composer. This provides integration for the GitLab API within a Symfony application.

```bash
$ composer require "zeichen32/gitlabapibundle:^7.0"
```

--------------------------------

### Get Blame Information

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieve blame information for a specific file in a project. Optionally specify a reference (branch, tag, or commit).

```php
public function blame(int|string $project_id, string $file, array $parameters = []): mixed
```

--------------------------------

### Get Shared Projects

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

Retrieves all projects that are shared with the specified group.

```php
public function sharedProjects(int|string $group_id, array $parameters = []): mixed
```

--------------------------------

### Complete Users API Usage Example

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/07-users-api.md

Demonstrates comprehensive usage of the Users API, including authentication, fetching current user, listing all users, retrieving a specific user, creating, updating, adding SSH keys, blocking, activating, and removing users.

```php
<?php

use Gitlab\Client;

$client = new Client();
$client->authenticate('token', Client::AUTH_HTTP_TOKEN);
$usersApi = $client->users();

// Get current user
$me = $usersApi->me();
echo "Logged in as: " . $me['username'] . "\n";

// List all users
$users = $usersApi->all(['per_page' => 10]);
foreach ($users as $user) {
    echo $user['username'] . " (" . $user['name'] . ")\n";
}

// Get specific user
$user = $usersApi->show(5);
echo "User: " . $user['name'] . "\n";

// Create new user
$newUser = $usersApi->create([
    'username' => 'john_doe',
    'email' => 'john@example.com',
    'password' => 'secure_pass',
    'name' => 'John Doe'
]);

// Update user
$usersApi->update($newUser['id'], [
    'organization' => 'My Company'
]);

// Add SSH key
$usersApi->createKey($newUser['id'], [
    'title' => 'Work SSH Key',
    'key' => 'ssh-rsa AAAA...'
]);

// Block user
$usersApi->block($newUser['id']);

// Activate user
$usersApi->activate($newUser['id']);

// Remove user
$usersApi->remove($newUser['id']);

```

--------------------------------

### Start a New Discussion

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/03-issues-api.md

Initiates a new discussion thread on an issue. Requires project ID, issue IID, and the initial message body.

```php
public function addDiscussion(int|string $project_id, int $issue_iid, string $body): mixed
```

--------------------------------

### Manage Users

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Demonstrates fetching all users, retrieving the current user's details, creating a new user, and adding an SSH key to a user account.

```php
// Get all users
$users = $client->users()->all(['active' => true]);

// Get current user
$me = $client->users()->me();

// Create user
$user = $client->users()->create([
    'username' => 'john_doe',
    'email' => 'john@example.com',
    'password' => 'password',
    'name' => 'John Doe'
]);

// Add SSH key
$client->users()->createKey($user['id'], [
    'title' => 'SSH Key',
    'key' => 'ssh-rsa AAAA...'
]);
```

--------------------------------

### Get Projects in Group

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

Retrieves all projects that belong to a specific group.

```php
public function projects(int|string $group_id, array $parameters = []): mixed
```

--------------------------------

### Configure HTTP Client with Plugins

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Shows how to customize the HTTP client by adding plugins, such as setting custom headers.

```php
use Gitlab\HttpClient\Builder;
use Http\Client\Common\Plugin\HeaderSetPlugin;

$builder = new Builder();

// Add custom header
$plugin = new HeaderSetPlugin([
    'X-Custom-Header' => 'value'
]);
$builder->addPlugin($plugin);

$client = new Client($builder);
```

--------------------------------

### Get Merge Request Discussions

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Retrieves all discussions on a merge request.

```APIDOC
## `showDiscussions()`

### Description
Get all discussions on MR.

### Method
GET

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/discussions`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

### Response
#### Success Response (200)
- **discussions** (array) - Array of discussion objects
```

--------------------------------

### Basic Usage of GitLab Client

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Instantiate the client, authenticate with an access token, and fetch all projects.

```php
<?php

use Gitlab\Client;

// Create client
$client = new Client();

// Authenticate
$client->authenticate('your_access_token', Client::AUTH_HTTP_TOKEN);

// Use API
$projects = $client->projects()->all();

foreach ($projects as $project) {
    echo $project['name'] . "\n";
}
```

--------------------------------

### Get Single Tag

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieve a specific tag by its name from a project.

```php
$tag = $client->repositories()->tag(1, 'v1.0.0');
echo "Commit: " . $tag['commit']['id'];
```

--------------------------------

### Get user by username

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/07-users-api.md

Retrieves user information using their username.

```APIDOC
## GET /users?username={username}

### Description
Get user by username.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **username** (string) - Required - User username

### Response
#### Success Response (200)
- **mixed** - User object
```

--------------------------------

### Configuration and Customization

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Shows how to customize the HTTP client with plugins and enable response caching.

```APIDOC
## HTTP Client with Plugins

### Description
Configures the HTTP client to include custom headers using plugins.

### Method
Client initialization

### Endpoint
`/` (Client initialization)

### Parameters
N/A

### Request Example
```php
use Gitlab\HttpClient\Builder;
use Http\Client\Common\Plugin\HeaderSetPlugin;

$builder = new Builder();

// Add custom header
$plugin = new HeaderSetPlugin([
    'X-Custom-Header' => 'value'
]);
$builder->addPlugin($plugin);

$client = new Client($builder);
```

## Response Caching

### Description
Enables response caching for API calls using a specified cache adapter.

### Method
Client initialization

### Endpoint
`/` (Client initialization)

### Parameters
N/A

### Request Example
```php
use Gitlab\HttpClient\Builder;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$cache = new FilesystemAdapter();
$builder = new Builder();
$builder->addCache($cache);

$client = new Client($builder);
```
```

--------------------------------

### Complete Repositories API Usage Example

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

This snippet shows how to authenticate, retrieve branches, commits, tags, and file trees, as well as create branches and tags using the GitLab PHP client. Ensure you have a valid authentication token.

```php
<?php

use Gitlab\Client;
use Gitlab\ResultPager;

$client = new Client();
$client->authenticate('token', Client::AUTH_HTTP_TOKEN);
$repoApi = $client->repositories();

// Get all branches
$branches = $repoApi->branches(1);
echo "Branches:\n";
foreach ($branches as $branch) {
    echo "  - " . $branch['name'];
    if ($branch['default']) echo " (default)";
    echo "\n";
}

// Get single branch
$main = $repoApi->branch(1, 'main');
echo "Main branch latest commit: " . $main['commit']['short_id'] . "\n";

// Create a new branch
$feature = $repoApi->createBranch(1, 'feature/new-api', 'main');

// Get commits
$commits = $repoApi->commits(1, [
    'ref_name' => 'main',
    'per_page' => 10
]);
echo "\nLatest commits:\n";
foreach ($commits as $commit) {
    echo "  - " . $commit['short_id'] . ": " . $commit['title'] . "\n";
}

// Get single commit
$commit = $repoApi->commit(1, 'abc123');

// Create commit with changes
$newCommit = $repoApi->createCommit(1, [
    'branch' => 'feature/new-api',
    'commit_message' => 'Add API endpoint',
    'actions' => [
        [
            'action' => 'create',
            'file_path' => 'src/api.php',
            'content' => '<?php\n// API code'
        ]
    ]
]);

// Get tags
$tags = $repoApi->tags(1);
echo "\nTags:\n";
foreach ($tags as $tag) {
    echo "  - " . $tag['name'] . "\n";
}

// Create tag
$tag = $repoApi->createTag(1, [
    'tag_name' => 'v1.0.0',
    'ref' => 'main',
    'message' => 'Release v1.0.0'
]);

// Get file tree
$tree = $repoApi->tree(1, ['path' => 'src']);
foreach ($tree as $item) {
    echo $item['type'] . ": " . $item['name'] . "\n";
}

```

--------------------------------

### Get Group Issues

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/03-issues-api.md

Retrieves a list of issues for a specific group.

```APIDOC
## GET /groups/:group_id/issues

### Description
Retrieves a list of issues for a specific group.

### Method
GET

### Endpoint
/groups/:group_id/issues

### Parameters
#### Path Parameters
- **group_id** (int|string) - Required - Group ID or path

#### Query Parameters
- **parameters** (array) - Optional - Query parameters

### Response
#### Success Response (200)
- **mixed** — Array of issue objects from group projects
```

--------------------------------

### branches()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Get all branches in a project. Supports searching by name and pagination.

```APIDOC
## branches()

### Description
Get all branches in a project. Supports searching by name and pagination.

### Method
GET

### Endpoint
/projects/:id/repository/branches

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path

#### Query Parameters
- **search** (string) - Optional - Search branches by name
- **page** (int) - Optional - Page number for pagination
- **per_page** (int) - Optional - Number of results per page

### Response
#### Success Response (200)
- **name** (string) - The name of the branch
- **commit** (object) - Information about the commit the branch points to

### Request Example
```php
$branches = $client->repositories()->branches(1);

foreach ($branches as $branch) {
    echo $branch['name'] . "\n";
}

// Search for branch
$main = $client->repositories()->branches(1, ['search' => 'main']);
```
```

--------------------------------

### Get Single Group Webhook

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

Retrieves a specific webhook for a group by its ID.

```php
public function hook(int|string $group_id, int $hook_id): mixed
```

--------------------------------

### General API Usage with Authentication

Source: https://github.com/gitlabphp/client/blob/12.1/README.md

Instantiate the GitLab client and authenticate using a personal access token. This example shows how to set up the client for API calls.

```php
$client = new Gitlab\Client();

// Choose one authentication method.

// 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);

// An example API call
$project = $client->projects()->create('My Project', [
    'description' => 'This is a project',
    'issues_access_level' => 'disabled',
]);
```

--------------------------------

### Manage Groups

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Shows how to create a new group, add members with specific roles, and list the members of a group.

```php
// Create group
$group = $client->groups()->create(
    'Engineering',
    'engineering',
    'Engineering team'
);

// Add members
$client->groups()->addMember($group['id'], 5, 30);   // developer
$client->groups()->addMember($group['id'], 10, 40);  // maintainer

// List members
$members = $client->groups()->members($group['id']);
```

--------------------------------

### Initialize Gitlab Client

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/01-client.md

Basic initialization of the Gitlab client. Optionally, a custom HTTP client builder can be provided for advanced configuration.

```php
// Basic initialization
$client = new Gitlab
ew Gitlab
ew Client();

// With custom HTTP client builder
$builder = new Gitlab
ew Gitlab
ew HttpClient
ew Builder();
$client = new Gitlab
ew Gitlab
ew Client($builder);
```

--------------------------------

### Get Diff Between Commits

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieve the differences between two specified commits in a project.

```php
public function diff(int|string $project_id, string $from, string $to): mixed
```

--------------------------------

### Handle Rate Limits with Pagination

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/13-quick-reference.md

Demonstrates fetching multiple projects using a pager to avoid hitting rate limits, contrasting with a naive loop.

```php
// Wrong - no retry logic
for ($i = 0; $i < 1000; $i++) {
    $client->projects()->show($i);  // Will hit rate limit
}

// Better - with pagination
$pager = new ResultPager($client);
$projects = $pager->fetchAll($client->projects(), 'all', []);
```

--------------------------------

### Get a Single Commit

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieves details for a specific commit using its SHA.

```php
$commit = $client->repositories()->commit(1, 'abc123');
echo "Author: " . $commit['author_name'];
echo "Message: " . $commit['message'];
```

--------------------------------

### Get a Single Branch

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Retrieves details for a specific branch within a project.

```php
$branch = $client->repositories()->branch(1, 'main');
echo "Branch: " . $branch['name'];
echo "Commit: " . $branch['commit']['id'];
```

--------------------------------

### Configure Response Caching

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/00-index.md

Demonstrates how to enable response caching for the HTTP client using a filesystem adapter.

```php
use Gitlab\HttpClient\Builder;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$cache = new FilesystemAdapter();
$builder = new Builder();
$builder->addCache($cache);

$client = new Client($builder);
```

--------------------------------

### Client Constructor

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/01-client.md

Initializes a new Gitlab client. You can provide a custom HTTP client builder or let it create a default one. It sets up default plugins and headers.

```APIDOC
## Constructor Gitlab\Client

### Description
Initializes a new Gitlab client with optional HTTP client builder configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
`public function __construct(?Gitlab\HttpClient\Builder $httpClientBuilder = null)`

### Parameters
- `$httpClientBuilder` (Gitlab\HttpClient\Builder) - Optional - Custom HTTP client builder; if null, creates new Builder instance

### Behavior:
- Sets up default plugins: ExceptionThrower, HistoryPlugin, HeaderDefaults, RedirectPlugin
- Sets default User-Agent header to "gitlab-php-api-client/12.1"
- Sets default base URL to "https://gitlab.com"

### Example:
```php
// Basic initialization
$client = new Gitlab\Client();

// With custom HTTP client builder
$builder = new Gitlab\HttpClient\Builder();
$client = new Gitlab\Client($builder);
```
```

--------------------------------

### Get Single Group Milestone

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/08-groups-api.md

Retrieves a specific milestone within a group by its ID.

```php
public function milestone(int|string $group_id, int|string $milestone_id): mixed
```

--------------------------------

### Get Merge Request Commits

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Retrieves the list of commits included in a merge request.

```APIDOC
## `commits()`

### Description
Get commits in the MR.

### Method
GET

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/commits`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

### Response
#### Success Response (200)
- **commits** (array) - Array of commit objects
```

--------------------------------

### create()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Creates a new GitLab project with specified name and additional parameters.

```APIDOC
## create()

### Description
Create a new project.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **name** (string) - Required - Project name
- **path** (string) - Optional - Project path
- **description** (string) - Optional - Project description
- **visibility** (string) - Optional - Visibility level: `public`, `internal`, or `private`
- **issues_enabled** (bool) - Optional
- **merge_requests_enabled** (bool) - Optional
- **wiki_enabled** (bool) - Optional
- **snippets_enabled** (bool) - Optional
- **container_registry_enabled** (bool) - Optional
- **namespace_id** (int) - Optional - Group ID to create project in

### Response
#### Success Response (200)
- **project** (object) - Created project object

### Response Example
```json
{
  "id": 1,
  "name": "My New Project",
  "path": "my-new-project"
}
```
```

--------------------------------

### Get Merge Request Head Pipeline

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Retrieves the head pipeline for a merge request.

```APIDOC
## `pipeline()`

### Description
Get the head pipeline.

### Method
GET

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/head_pipeline`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

### Response
#### Success Response (200)
- **pipeline** (object) - Pipeline object
```

--------------------------------

### Get Merge Request Pipelines

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Retrieves CI/CD pipelines associated with a merge request.

```APIDOC
## `pipelines()`

### Description
Get CI/CD pipelines for the MR.

### Method
GET

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/pipelines`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

#### Query Parameters
- **parameters** (array) - Optional - Query parameters for filtering pipelines

### Response
#### Success Response (200)
- **pipelines** (array) - Array of pipeline objects
```

--------------------------------

### Create New Project

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Creates a new GitLab project with a specified name and optional parameters like description and visibility.

```php
public function create(
    string $name,
    array $params = []
): mixed
```

```php
$newProject = $client->projects()->create('My Project', [
    'description' => 'A new project',
    'visibility' => 'private'
]);
```

--------------------------------

### List Projects Parameters

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/13-quick-reference.md

Parameters for filtering and sorting project listings.

```php
[
    'archived' => false,
    'visibility' => 'public',
    'order_by' => 'name',
    'sort' => 'asc',
    'search' => 'query',
    'owned' => true,
    'starred' => true,
    'per_page' => 20
]
```

--------------------------------

### Get Merge Request Notes

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Retrieves all notes (comments) associated with a merge request.

```APIDOC
## `showNotes()`

### Description
Get all notes/comments on MR.

### Method
GET

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/notes`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

### Response
#### Success Response (200)
- **notes** (array) - Array of note objects
```

--------------------------------

### Get Commits in a Merge Request

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Fetches all commits that are part of a specific merge request.

```php
$client->mergeRequests()->commits(1, 123);
```

--------------------------------

### Compare Commits

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/10-repositories-api.md

Compare two commits within a project to get a comparison object.

```php
public function compare(int|string $project_id, array $params): mixed
```

--------------------------------

### show()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Retrieves a single project's details using its ID or URL-encoded path.

```APIDOC
## show()

### Description
Get a single project by ID or path.

### Method
GET

### Endpoint
/projects/{id}

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or URL-encoded path

### Response
#### Success Response (200)
- **project** (object) - Project object

### Response Example
```json
{
  "id": 1,
  "name": "My Project",
  "description": "A sample project"
}
```
```

--------------------------------

### Add Discussion to Merge Request

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Starts a new discussion thread on a merge request.

```APIDOC
## `addDiscussion()`

### Description
Start a discussion thread on MR.

### Method
POST

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/discussions`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

#### Request Body
- **body** (string) - Required - The content of the discussion

### Response
#### Success Response (200)
- **discussion** (object) - Created discussion object
```

--------------------------------

### all()

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/02-projects-api.md

Retrieves a list of all projects, with extensive filtering and sorting capabilities.

```APIDOC
## all()

### Description
Get a list of all projects.

### Method
GET

### Endpoint
/projects

### Parameters
#### Query Parameters
- **archived** (bool) - Optional - Limit by archived status
- **visibility** (string) - Optional - Visibility level: `public`, `internal`, or `private`
- **order_by** (string) - Optional - Field to order by: `id`, `name`, `path`, `created_at`, `updated_at`, `last_activity_at`, `repository_size`, `storage_size`, `packages_size`, or `wiki_size`
- **sort** (string) - Optional - Sort order: `asc` or `desc`
- **search** (string) - Optional - Search query for project name or path
- **search_namespaces** (bool) - Optional - Include ancestor namespaces in search
- **simple** (bool) - Optional - Return only ID, URL, name, and path
- **owned** (bool) - Optional - Limit to projects owned by current user
- **membership** (bool) - Optional - Limit to projects current user is a member of
- **starred** (bool) - Optional - Limit to projects starred by current user
- **statistics** (bool) - Optional - Include project statistics
- **with_issues_enabled** (bool) - Optional - Limit to projects with issues enabled
- **with_merge_requests_enabled** (bool) - Optional - Limit to projects with merge requests enabled
- **min_access_level** (int) - Optional - Minimum access level: 10, 20, 30, 40, or 50
- **id_after** (int) - Optional - Return projects with ID greater than this
- **id_before** (int) - Optional - Return projects with ID less than this
- **last_activity_after** (DateTimeInterface) - Optional - Last activity after date
- **last_activity_before** (DateTimeInterface) - Optional - Last activity before date
- **repository_checksum_failed** (bool) - Optional - Repository checksum failed
- **repository_storage** (string) - Optional - Repository storage type
- **wiki_checksum_failed** (bool) - Optional - Wiki checksum failed
- **with_custom_attributes** (bool) - Optional - Include custom attributes
- **with_programming_language** (string) - Optional - Filter by programming language
- **topic** (string) - Optional - Filter by topic
- **page** (int) - Optional - Page number (>0)
- **per_page** (int) - Optional - Items per page (1-100)

### Response
#### Success Response (200)
- **projects** (array) - Array of project objects

### Response Example
```json
[
  {
    "id": 1,
    "name": "My Project",
    "path": "my-project"
  }
]
```
```

--------------------------------

### Get Merge Request Approvals

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Retrieves the approval status and rules for a specific merge request.

```APIDOC
## `approvals()`

### Description
Get MR approval status and rules.

### Method
GET

### Endpoint
`/projects/:id/merge_requests/:merge_request_iid/approvals`

### Parameters
#### Path Parameters
- **id** (int|string) - Required - Project ID or path
- **merge_request_iid** (int) - Required - MR internal ID

### Response
#### Success Response (200)
- **object** (mixed) - Approval object
```

--------------------------------

### Create user

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/07-users-api.md

Creates a new user account with specified details.

```APIDOC
## POST /users

### Description
Create a new user.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **username** (string) - Required - User username
- **email** (string) - Required - User email
- **password** (string) - Required - User password
- **name** (string) - Optional - User full name
- **skype** (string) - Optional - Skype username
- **linkedin** (string) - Optional - LinkedIn profile
- **twitter** (string) - Optional - Twitter handle
- **website_url** (string) - Optional - Personal website
- **organization** (string) - Optional - Organization name
- **projects_limit** (int) - Optional - Max projects user can create
- **external** (bool) - Optional - Whether user is external
- **provider** (string) - Optional - External authentication provider
- **extern_uid** (string) - Optional - External user identifier
- **reset_password** (bool) - Optional - Send password reset email
- **can_create_group** (bool) - Optional - Allow group creation
- **admin** (bool) - Optional - Make user admin

### Response
#### Success Response (200)
- **mixed** - Created user object

### Request Example
```php
$newUser = $client->users()->create([
    'username' => 'newuser',
    'email' => 'user@example.com',
    'password' => 'secure_password',
    'name' => 'New User'
]);
```
```

--------------------------------

### Get All Notes on a Merge Request

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/11-merge-requests-api.md

Fetches all comments and notes associated with a specific merge request.

```php
$client->mergeRequests()->showNotes(1, 123);
```

--------------------------------

### Instantiate HTTP Client Builder

Source: https://github.com/gitlabphp/client/blob/12.1/_autodocs/04-http-client.md

Create a new HTTP client builder. It can auto-discover factories or accept custom PSR-18 and PSR-17 factories.

```php
use Gitlab\HttpClient\Builder;

// Auto-discover all factories
$builder = new Builder();

// With custom HTTP client
use GuzzleHttp\Client;
$guzzle = new Client();
$builder = new Builder($guzzle);

// With all custom factories
$builder = new Builder(
    $httpClient,
    $requestFactory,
    $streamFactory,
    $uriFactory
);
```