diff --git a/src/Api/DeployKeys.php b/src/Api/DeployKeys.php index 9259d25c..78843b80 100644 --- a/src/Api/DeployKeys.php +++ b/src/Api/DeployKeys.php @@ -16,6 +16,11 @@ class DeployKeys extends AbstractApi { + /** + * List all deploy keys across all projects of the GitLab instance. + * + * @see https://docs.gitlab.com/api/deploy_keys/#list-all-deploy-keys + */ public function all(array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); diff --git a/src/Api/Deployments.php b/src/Api/Deployments.php index 7e0d514a..0a56cf71 100644 --- a/src/Api/Deployments.php +++ b/src/Api/Deployments.php @@ -20,6 +20,10 @@ class Deployments extends AbstractApi { /** + * List all deployments of a project. + * + * @see https://docs.gitlab.com/api/deployments/#list-all-project-deployments + * * @param array $parameters { * * @var string $order_by Return deployments ordered by id, iid, created_at, updated_at, finished_at, or ref fields (default is id) @@ -74,12 +78,21 @@ public function all(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'deployments'), $resolver->resolve($parameters)); } + /** + * Get a specific deployment of a project. + * + * @see https://docs.gitlab.com/api/deployments/#retrieve-a-deployment + */ public function show(int|string $project_id, int $deployment_id): mixed { return $this->get($this->getProjectPath($project_id, 'deployments/'.$deployment_id)); } /** + * List the merge requests associated with a deployment. + * + * @see https://docs.gitlab.com/api/deployments/#list-all-merge-requests-associated-with-a-deployment + * * @param array $parameters { * * @var string $state return all merge requests or just those that are opened, closed, locked, or merged diff --git a/src/Api/Environments.php b/src/Api/Environments.php index c2825b01..1cf7a1a4 100644 --- a/src/Api/Environments.php +++ b/src/Api/Environments.php @@ -19,6 +19,11 @@ class Environments extends AbstractApi { + /** + * List all environments of a project. + * + * @see https://docs.gitlab.com/api/environments/#list-all-environments + */ public function all(int|string $project_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -34,6 +39,10 @@ public function all(int|string $project_id, array $parameters = []): mixed } /** + * Create a new environment. + * + * @see https://docs.gitlab.com/api/environments/#create-an-environment + * * @param array $parameters { * * @var string $name The name of the environment @@ -55,17 +64,31 @@ public function create(int|string $project_id, array $parameters = []): mixed return $this->post($this->getProjectPath($project_id, 'environments'), $resolver->resolve($parameters)); } + /** + * Delete an environment. + * + * @see https://docs.gitlab.com/api/environments/#delete-an-environment + */ public function remove(int|string $project_id, int $environment_id): mixed { return $this->delete($this->getProjectPath($project_id, 'environments/'.$environment_id)); } + /** + * Stop an environment. + * + * @see https://docs.gitlab.com/api/environments/#stop-an-environment + */ public function stop(int|string $project_id, int $environment_id): mixed { return $this->post($this->getProjectPath($project_id, 'environments/'.self::encodePath($environment_id).'/stop')); } /** + * Stop multiple stale environments. + * + * @see https://docs.gitlab.com/api/environments/#stop-stale-environments + * * @param array $parameters { * * @var \DateTimeInterface $before Stop environments that have been modified or deployed to before the specified date. @@ -86,6 +109,11 @@ public function stopStale(int|string $project_id, array $parameters = []): mixed return $this->post($this->getProjectPath($project_id, 'environments/stop_stale'), $resolver->resolve($parameters)); } + /** + * Get a specific environment. + * + * @see https://docs.gitlab.com/api/environments/#retrieve-an-environment + */ public function show(int|string $project_id, int $environment_id): mixed { return $this->get($this->getProjectPath($project_id, 'environments/'.self::encodePath($environment_id))); diff --git a/src/Api/Events.php b/src/Api/Events.php index 74f3d1cd..a43b1d83 100644 --- a/src/Api/Events.php +++ b/src/Api/Events.php @@ -18,6 +18,10 @@ class Events extends AbstractApi { /** + * List currently authenticated user's events. + * + * @see https://docs.gitlab.com/api/events/#list-all-events + * * @param array $parameters { * * @var string $action include only events of a particular action type diff --git a/src/Api/Groups.php b/src/Api/Groups.php index 1ad1008b..14bc2576 100644 --- a/src/Api/Groups.php +++ b/src/Api/Groups.php @@ -47,6 +47,10 @@ class Groups extends AbstractApi public const STATE_LOCKED = 'locked'; /** + * List all groups visible to the authenticated user. + * + * @see https://docs.gitlab.com/api/groups/#list-all-groups + * * @param array $parameters { * * @var int[] $skip_groups skip the group IDs passes @@ -69,6 +73,10 @@ public function all(array $parameters = []): mixed } /** + * Get a single group. + * + * @see https://docs.gitlab.com/api/groups/#retrieve-a-group + * * @param array $parameters { * * @var bool $with_custom_attributes include custom attributes in response @@ -94,6 +102,11 @@ public function show(int|string $id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($id), $resolver->resolve($parameters)); } + /** + * Create a new group. + * + * @see https://docs.gitlab.com/api/groups/#create-a-group + */ public function create(string $name, string $path, ?string $description = null, string $visibility = 'private', ?bool $lfs_enabled = null, ?bool $request_access_enabled = null, ?int $parent_id = null, ?int $shared_runners_minutes_limit = null): mixed { $params = [ @@ -112,21 +125,41 @@ public function create(string $name, string $path, ?string $description = null, })); } + /** + * Update an existing group. + * + * @see https://docs.gitlab.com/api/groups/#update-group-attributes + */ public function update(int|string $id, array $params): mixed { return $this->put('groups/'.self::encodePath($id), $params); } + /** + * Schedule a group for deletion. + * + * @see https://docs.gitlab.com/api/groups/#schedule-a-group-for-deletion + */ public function remove(int|string $group_id): mixed { return $this->delete('groups/'.self::encodePath($group_id)); } + /** + * Transfer a project to a group. + * + * @see https://docs.gitlab.com/api/groups/#transfer-a-project-to-a-group + */ public function transfer(int|string $group_id, int|string $project_id): mixed { return $this->post('groups/'.self::encodePath($group_id).'/projects/'.self::encodePath($project_id)); } + /** + * List all members of a group, including inherited and invited members. + * + * @see https://docs.gitlab.com/api/members/#list-all-group-members-including-inherited-and-invited-members + */ public function allMembers(int|string $group_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -142,6 +175,10 @@ public function allMembers(int|string $group_id, array $parameters = []): mixed } /** + * List all members of a group. + * + * @see https://docs.gitlab.com/api/members/#list-all-group-members + * * @param array $parameters { * * @var string $query A query string to search for members. @@ -161,16 +198,31 @@ public function members(int|string $group_id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($group_id).'/members', $resolver->resolve($parameters)); } + /** + * Get a single member of a group. + * + * @see https://docs.gitlab.com/api/members/#retrieve-a-group-member + */ public function member(int|string $group_id, int $user_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/members/'.self::encodePath($user_id)); } + /** + * Get a single member of a group, including inherited and invited members. + * + * @see https://docs.gitlab.com/api/members/#retrieve-a-group-member-including-inherited-and-invited-members + */ public function allMember(int|string $group_id, int $user_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/members/all/'.self::encodePath($user_id)); } + /** + * Add a member to a group. + * + * @see https://docs.gitlab.com/api/members/#add-a-group-member + */ public function addMember(int|string $group_id, int $user_id, int $access_level, array $parameters = []): mixed { $dateNormalizer = function (OptionsResolver $optionsResolver, \DateTimeInterface $date): string { @@ -191,6 +243,11 @@ public function addMember(int|string $group_id, int $user_id, int $access_level, return $this->post('groups/'.self::encodePath($group_id).'/members', $parameters); } + /** + * Update a member of a group. + * + * @see https://docs.gitlab.com/api/members/#update-a-group-member + */ public function saveMember(int|string $group_id, int $user_id, int $access_level): mixed { return $this->put('groups/'.self::encodePath($group_id).'/members/'.self::encodePath($user_id), [ @@ -199,6 +256,10 @@ public function saveMember(int|string $group_id, int $user_id, int $access_level } /** + * Share a group with another group (create a group invitation). + * + * @see https://docs.gitlab.com/api/groups/#create-a-group-invitation + * * @param array $parameters { * * @var int $group_access the access level to grant the group @@ -228,12 +289,21 @@ public function addShare(int|string $group_id, array $parameters = []): mixed return $this->post('groups/'.self::encodePath($group_id).'/share', $resolver->resolve($parameters)); } + /** + * Remove a member from a group. + * + * @see https://docs.gitlab.com/api/members/#remove-a-group-member + */ public function removeMember(int|string $group_id, int $user_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/members/'.self::encodePath($user_id)); } /** + * List the projects of a group. + * + * @see https://docs.gitlab.com/api/groups/#list-projects + * * @param array $parameters { * * @var bool $archived limit by archived status @@ -323,6 +393,10 @@ public function projects(int|string $id, array $parameters = []): mixed } /** + * List the subgroups of a group. + * + * @see https://docs.gitlab.com/api/groups/#list-subgroups + * * @param array $parameters { * * @var int[] $skip_groups skip the group IDs passes @@ -342,6 +416,10 @@ public function subgroups(int|string $group_id, array $parameters = []): mixed } /** + * List all issues of a group. + * + * @see https://docs.gitlab.com/api/issues/#list-all-group-issues + * * @param array $parameters { * * @var string $assignee_id Return issues assigned to the given user id. Mutually exclusive with assignee_username. @@ -452,6 +530,10 @@ public function issues(int|string $group_id, array $parameters = []): mixed } /** + * List all labels of a group. + * + * @see https://docs.gitlab.com/api/group_labels/#list-group-labels + * * @param array $parameters { * * @var bool $with_counts Whether or not to include issue and merge request counts. Defaults to false. @@ -483,21 +565,41 @@ public function labels(int|string $group_id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($group_id).'/labels', $resolver->resolve($parameters)); } + /** + * Create a new label for a group. + * + * @see https://docs.gitlab.com/api/group_labels/#create-a-new-group-label + */ public function addLabel(int|string $group_id, array $params): mixed { return $this->post('groups/'.self::encodePath($group_id).'/labels', $params); } + /** + * Update an existing label of a group. + * + * @see https://docs.gitlab.com/api/group_labels/#update-a-group-label + */ public function updateLabel(int|string $group_id, int $label_id, array $params): mixed { return $this->put('groups/'.self::encodePath($group_id).'/labels/'.self::encodePath($label_id), $params); } + /** + * Delete a label of a group. + * + * @see https://docs.gitlab.com/api/group_labels/#delete-a-group-label + */ public function removeLabel(int|string $group_id, int $label_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/labels/'.self::encodePath($label_id)); } + /** + * List all variables of a group. + * + * @see https://docs.gitlab.com/api/group_level_variables/#list-all-group-variables + */ public function variables(int|string $group_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -505,12 +607,21 @@ public function variables(int|string $group_id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($group_id).'/variables', $resolver->resolve($parameters)); } + /** + * Get the details of a single group variable. + * + * @see https://docs.gitlab.com/api/group_level_variables/#retrieve-details-of-a-group-variable + */ public function variable(int|string $group_id, string $key): mixed { return $this->get('groups/'.self::encodePath($group_id).'/variables/'.self::encodePath($key)); } /** + * Create a new variable for a group. + * + * @see https://docs.gitlab.com/api/group_level_variables/#create-a-group-variable + * * @param array $parameters { * * @var string $masked true or false @@ -539,6 +650,11 @@ public function addVariable(int|string $group_id, string $key, string $value, ?b return $this->post('groups/'.self::encodePath($group_id).'/variables', $payload); } + /** + * Update an existing variable of a group. + * + * @see https://docs.gitlab.com/api/group_level_variables/#update-a-group-variable + */ public function updateVariable(int|string $group_id, string $key, string $value, ?bool $protected = null): mixed { $payload = [ @@ -552,12 +668,21 @@ public function updateVariable(int|string $group_id, string $key, string $value, return $this->put('groups/'.self::encodePath($group_id).'/variables/'.self::encodePath($key), $payload); } + /** + * Delete a variable of a group. + * + * @see https://docs.gitlab.com/api/group_level_variables/#delete-a-group-variable + */ public function removeVariable(int|string $group_id, string $key): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/variables/'.self::encodePath($key)); } /** + * List all merge requests of a group. + * + * @see https://docs.gitlab.com/api/merge_requests/#list-group-merge-requests + * * @param array $parameters { * * @var int[] $iids return the request having the given iid @@ -657,6 +782,10 @@ public function mergeRequests(int|string $group_id, array $parameters = []): mix } /** + * List all iterations of a group. + * + * @see https://docs.gitlab.com/api/group_iterations/#list-all-group-iterations + * * @param array $parameters { * * @var string $state Return opened, upcoming, current (previously started), closed, or all iterations. @@ -685,6 +814,10 @@ public function iterations(int|string $group_id, array $parameters = []): mixed } /** + * List all packages of a group. + * + * @see https://docs.gitlab.com/api/packages/#for-a-group + * * @param array $parameters { * * @var bool $exclude_subgroups if the parameter is included as true, packages from projects from subgroups @@ -733,6 +866,11 @@ public function packages(int|string $group_id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($group_id).'/packages', $resolver->resolve($parameters)); } + /** + * List all registry repositories of a group. + * + * @see https://docs.gitlab.com/api/container_registry/#within-a-group + */ public function registryRepositories(int|string $group_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/registry/repositories'); @@ -795,12 +933,21 @@ private function getSubgroupSearchResolver(): OptionsResolver return $resolver; } + /** + * List all deploy tokens of a group. + * + * @see https://docs.gitlab.com/api/deploy_tokens/#list-group-deploy-tokens + */ public function deployTokens(int|string $group_id, ?bool $active = null): mixed { return $this->get('groups/'.self::encodePath($group_id).'/deploy_tokens', (null !== $active) ? ['active' => $active] : []); } /** + * Create a new deploy token for a group. + * + * @see https://docs.gitlab.com/api/deploy_tokens/#create-a-group-deploy-token + * * @param array $parameters { * * @var string $name the name of the deploy token @@ -846,12 +993,21 @@ public function createDeployToken(int|string $group_id, array $parameters = []): return $this->post('groups/'.self::encodePath($group_id).'/deploy_tokens', $resolver->resolve($parameters)); } + /** + * Delete a deploy token of a group. + * + * @see https://docs.gitlab.com/api/deploy_tokens/#delete-a-group-deploy-token + */ public function deleteDeployToken(int|string $group_id, int $token_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/deploy_tokens/'.self::encodePath($token_id)); } /** + * Search within a group. + * + * @see https://docs.gitlab.com/api/search/#search-a-group + * * @param array $parameters { * * @var string $scope The scope to search in diff --git a/src/Api/GroupsBoards.php b/src/Api/GroupsBoards.php index a3fa6742..7e758ab9 100644 --- a/src/Api/GroupsBoards.php +++ b/src/Api/GroupsBoards.php @@ -16,6 +16,11 @@ class GroupsBoards extends AbstractApi { + /** + * List all group issue boards in a group. + * + * @see https://docs.gitlab.com/api/group_boards/#list-all-group-issue-boards-in-a-group + */ public function all(int|string|null $group_id = null, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -25,36 +30,71 @@ public function all(int|string|null $group_id = null, array $parameters = []): m return $this->get($path, $resolver->resolve($parameters)); } + /** + * Get a single group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#retrieve-a-group-issue-board + */ public function show(int|string $group_id, int $board_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id)); } + /** + * Create a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#create-a-group-issue-board + */ public function create(int|string $group_id, array $params): mixed { return $this->post('groups/'.self::encodePath($group_id).'/boards', $params); } + /** + * Update a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#update-a-group-issue-board + */ public function update(int|string $group_id, int $board_id, array $params): mixed { return $this->put('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id), $params); } + /** + * Delete a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#delete-a-group-issue-board + */ public function remove(int|string $group_id, int $board_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id)); } + /** + * List the boards lists of a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#list-group-issue-board-lists + */ public function allLists(int|string $group_id, int $board_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id).'/lists'); } + /** + * Get a single board list of a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#retrieve-a-group-issue-board-list + */ public function showList(int|string $group_id, int $board_id, int $list_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id).'/lists/'.self::encodePath($list_id)); } + /** + * Create a new board list of a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#create-a-group-issue-board-list + */ public function createList(int|string $group_id, int $board_id, int $label_id): mixed { $params = [ @@ -64,6 +104,11 @@ public function createList(int|string $group_id, int $board_id, int $label_id): return $this->post('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id).'/lists', $params); } + /** + * Update the position of a board list of a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#update-a-group-issue-board-list + */ public function updateList(int|string $group_id, int $board_id, int $list_id, int $position): mixed { $params = [ @@ -73,6 +118,11 @@ public function updateList(int|string $group_id, int $board_id, int $list_id, in return $this->put('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id).'/lists/'.self::encodePath($list_id), $params); } + /** + * Delete a board list of a group issue board. + * + * @see https://docs.gitlab.com/api/group_boards/#delete-a-group-issue-board-list + */ public function deleteList(int|string $group_id, int $board_id, int $list_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/boards/'.self::encodePath($board_id).'/lists/'.self::encodePath($list_id)); diff --git a/src/Api/GroupsEpics.php b/src/Api/GroupsEpics.php index 603aef6e..958bb7b4 100644 --- a/src/Api/GroupsEpics.php +++ b/src/Api/GroupsEpics.php @@ -32,6 +32,10 @@ class GroupsEpics extends AbstractApi public const STATE_CLOSED = 'closed'; /** + * List all epics of a group. + * + * @see https://docs.gitlab.com/api/epics/#list-all-group-epics + * * @param array $parameters { * * @var int[] $iids return only the epics having the given iids @@ -56,26 +60,51 @@ public function all(int|string $group_id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($group_id).'/epics', $resolver->resolve($parameters)); } + /** + * Get a single epic of a group. + * + * @see https://docs.gitlab.com/api/epics/#retrieve-an-epic + */ public function show(int|string $group_id, int $epic_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/epics/'.self::encodePath($epic_id)); } + /** + * Create a new epic. + * + * @see https://docs.gitlab.com/api/epics/#create-an-epic + */ public function create(int|string $group_id, array $params): mixed { return $this->post('groups/'.self::encodePath($group_id).'/epics', $params); } + /** + * Update an existing epic. + * + * @see https://docs.gitlab.com/api/epics/#update-an-epic + */ public function update(int|string $group_id, int $epic_id, array $params): mixed { return $this->put('groups/'.self::encodePath($group_id).'/epics/'.self::encodePath($epic_id), $params); } + /** + * Delete an epic. + * + * @see https://docs.gitlab.com/api/epics/#delete-an-epic + */ public function remove(int|string $group_id, int $epic_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/epics/'.self::encodePath($epic_id)); } + /** + * List all issues assigned to an epic. + * + * @see https://docs.gitlab.com/api/epic_issues/#list-all-issues-for-an-epic + */ public function issues(int|string $group_id, int $epic_iid): mixed { return $this->get('groups/'.self::encodePath($group_id).'/epics/'.self::encodePath($epic_iid).'/issues'); diff --git a/src/Api/GroupsHooks.php b/src/Api/GroupsHooks.php index d388bd1e..98efcaa9 100644 --- a/src/Api/GroupsHooks.php +++ b/src/Api/GroupsHooks.php @@ -18,11 +18,21 @@ class GroupsHooks extends AbstractApi { + /** + * List all group hooks. + * + * @see https://docs.gitlab.com/api/group_webhooks/#list-all-group-hooks + */ public function all(int|string $group_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/hooks'); } + /** + * Get a specific group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#retrieve-a-group-hook + */ public function show(int|string $group_id, int $hook_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id)); @@ -58,12 +68,21 @@ public function update(int|string $group_id, int $hook_id, array $parameters): m return $this->put('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id), $parameters); } + /** + * Delete a group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#delete-a-group-hook + */ public function remove(int|string $group_id, int $hook_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id)); } /** + * List all events for a group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#list-all-group-hook-events + * * @param array $parameters { * * @var int|string $status response status code or status category @@ -79,16 +98,31 @@ public function events(int|string $group_id, int $hook_id, array $parameters = [ return $this->get('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/events', $resolver->resolve($parameters)); } + /** + * Resend a group hook event. + * + * @see https://docs.gitlab.com/api/group_webhooks/#resend-group-hook-event + */ public function resendEvent(int|string $group_id, int $hook_id, int $hook_event_id): mixed { return $this->post('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/events/'.self::encodePath($hook_event_id).'/resend'); } + /** + * Trigger a test group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#trigger-a-test-group-hook + */ public function test(int|string $group_id, int $hook_id, string $trigger): mixed { return $this->post('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/test/'.self::encodePath($trigger)); } + /** + * Update a custom header of a group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#update-a-custom-header + */ public function setCustomHeader(int|string $group_id, int $hook_id, string $key, string $value): mixed { return $this->put('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/custom_headers/'.self::encodePath($key), [ @@ -96,11 +130,21 @@ public function setCustomHeader(int|string $group_id, int $hook_id, string $key, ]); } + /** + * Delete a custom header of a group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#delete-a-custom-header + */ public function deleteCustomHeader(int|string $group_id, int $hook_id, string $key): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/custom_headers/'.self::encodePath($key)); } + /** + * Update a URL variable of a group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#update-a-url-variable + */ public function setUrlVariable(int|string $group_id, int $hook_id, string $key, string $value): mixed { return $this->put('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/url_variables/'.self::encodePath($key), [ @@ -108,6 +152,11 @@ public function setUrlVariable(int|string $group_id, int $hook_id, string $key, ]); } + /** + * Delete a URL variable of a group hook. + * + * @see https://docs.gitlab.com/api/group_webhooks/#delete-a-url-variable + */ public function deleteUrlVariable(int|string $group_id, int $hook_id, string $key): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/hooks/'.self::encodePath($hook_id).'/url_variables/'.self::encodePath($key)); diff --git a/src/Api/GroupsMilestones.php b/src/Api/GroupsMilestones.php index 50fac667..617225da 100644 --- a/src/Api/GroupsMilestones.php +++ b/src/Api/GroupsMilestones.php @@ -29,6 +29,10 @@ class GroupsMilestones extends AbstractApi public const STATE_CLOSED = 'closed'; /** + * List all group milestones. + * + * @see https://docs.gitlab.com/api/group_milestones/#list-group-milestones + * * @param array $parameters { * * @var int[] $iids return only the milestones having the given iids @@ -67,31 +71,61 @@ public function all(int|string $group_id, array $parameters = []): mixed return $this->get('groups/'.self::encodePath($group_id).'/milestones', $resolver->resolve($parameters)); } + /** + * Get a single group milestone. + * + * @see https://docs.gitlab.com/api/group_milestones/#get-single-milestone + */ public function show(int|string $group_id, int $milestone_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/milestones/'.self::encodePath($milestone_id)); } + /** + * Create a new group milestone. + * + * @see https://docs.gitlab.com/api/group_milestones/#create-new-milestone + */ public function create(int|string $group_id, array $params): mixed { return $this->post('groups/'.self::encodePath($group_id).'/milestones', $params); } + /** + * Update an existing group milestone. + * + * @see https://docs.gitlab.com/api/group_milestones/#edit-milestone + */ public function update(int|string $group_id, int $milestone_id, array $params): mixed { return $this->put('groups/'.self::encodePath($group_id).'/milestones/'.self::encodePath($milestone_id), $params); } + /** + * Delete a group milestone. + * + * @see https://docs.gitlab.com/api/group_milestones/#delete-group-milestone + */ public function remove(int|string $group_id, int $milestone_id): mixed { return $this->delete('groups/'.self::encodePath($group_id).'/milestones/'.self::encodePath($milestone_id)); } + /** + * Get all issues assigned to a single group milestone. + * + * @see https://docs.gitlab.com/api/group_milestones/#get-all-issues-assigned-to-a-single-milestone + */ public function issues(int|string $group_id, int $milestone_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/milestones/'.self::encodePath($milestone_id).'/issues'); } + /** + * Get all merge requests assigned to a single group milestone. + * + * @see https://docs.gitlab.com/api/group_milestones/#get-all-merge-requests-assigned-to-a-single-milestone + */ public function mergeRequests(int|string $group_id, int $milestone_id): mixed { return $this->get('groups/'.self::encodePath($group_id).'/milestones/'.self::encodePath($milestone_id).'/merge_requests'); diff --git a/src/Api/Integrations.php b/src/Api/Integrations.php index ec3f3d3a..54930903 100644 --- a/src/Api/Integrations.php +++ b/src/Api/Integrations.php @@ -16,11 +16,24 @@ class Integrations extends AbstractApi { + /** + * List all active integrations of a project. + * + * @see https://docs.gitlab.com/api/project_integrations/#list-all-active-integrations + */ public function all(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'integrations')); } + /** + * Get the settings of a project integration by slug. + * + * The response fields vary by integration slug; see the dedicated section for + * that integration (e.g. Asana, Jira, Slack notifications, ...) on the page below. + * + * @see https://docs.gitlab.com/api/project_integrations/ + */ public function show(int|string $project_id, string $integration_slug): mixed { return $this->get($this->getProjectPath($project_id, 'integrations/'.self::encodePath($integration_slug))); @@ -29,7 +42,9 @@ public function show(int|string $project_id, string $integration_slug): mixed /** * Configure a project integration by slug. * - * Integration parameters vary by slug and are passed through to GitLab. + * Integration parameters vary by slug and are passed through to GitLab; see the + * dedicated section for that integration (e.g. Asana, Jira, Slack notifications, ...) + * on the page below. * * @see https://docs.gitlab.com/api/project_integrations/ * @@ -40,6 +55,14 @@ public function set(int|string $project_id, string $integration_slug, array $par return $this->put($this->getProjectPath($project_id, 'integrations/'.self::encodePath($integration_slug)), $parameters); } + /** + * Disable a project integration by slug. + * + * See the dedicated section for that integration (e.g. Asana, Jira, Slack + * notifications, ...) on the page below. + * + * @see https://docs.gitlab.com/api/project_integrations/ + */ public function remove(int|string $project_id, string $integration_slug): mixed { return $this->delete($this->getProjectPath($project_id, 'integrations/'.self::encodePath($integration_slug))); diff --git a/src/Api/IssueBoards.php b/src/Api/IssueBoards.php index 369de96f..448d80cd 100644 --- a/src/Api/IssueBoards.php +++ b/src/Api/IssueBoards.php @@ -16,6 +16,11 @@ class IssueBoards extends AbstractApi { + /** + * List all project issue boards. + * + * @see https://docs.gitlab.com/api/boards/#list-all-project-issue-boards + */ public function all(int|string|null $project_id = null, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -25,36 +30,71 @@ public function all(int|string|null $project_id = null, array $parameters = []): return $this->get($path, $resolver->resolve($parameters)); } + /** + * Get a single project issue board. + * + * @see https://docs.gitlab.com/api/boards/#retrieve-an-issue-board + */ public function show(int|string $project_id, int $board_id): mixed { return $this->get($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id))); } + /** + * Create a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#create-an-issue-board + */ public function create(int|string $project_id, array $params): mixed { return $this->post($this->getProjectPath($project_id, 'boards'), $params); } + /** + * Update a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#update-an-issue-board + */ public function update(int|string $project_id, int $board_id, array $params): mixed { return $this->put($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id)), $params); } + /** + * Delete a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#delete-an-issue-board + */ public function remove(int|string $project_id, int $board_id): mixed { return $this->delete($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id))); } + /** + * List the boards lists of a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#list-all-board-lists-in-an-issue-board + */ public function allLists(int|string $project_id, int $board_id): mixed { return $this->get($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id).'/lists')); } + /** + * Get a single board list of a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#retrieve-a-board-list + */ public function showList(int|string $project_id, int $board_id, int $list_id): mixed { return $this->get($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id).'/lists/'.self::encodePath($list_id))); } + /** + * Create a new board list of a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#create-a-board-list + */ public function createList(int|string $project_id, int $board_id, int $label_id): mixed { $params = [ @@ -64,6 +104,11 @@ public function createList(int|string $project_id, int $board_id, int $label_id) return $this->post($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id).'/lists'), $params); } + /** + * Update the position of a board list of a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#update-a-board-list + */ public function updateList(int|string $project_id, int $board_id, int $list_id, int $position): mixed { $params = [ @@ -73,6 +118,11 @@ public function updateList(int|string $project_id, int $board_id, int $list_id, return $this->put($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id).'/lists/'.self::encodePath($list_id)), $params); } + /** + * Delete a board list of a project issue board. + * + * @see https://docs.gitlab.com/api/boards/#delete-a-board-list-from-a-board + */ public function deleteList(int|string $project_id, int $board_id, int $list_id): mixed { return $this->delete($this->getProjectPath($project_id, 'boards/'.self::encodePath($board_id).'/lists/'.self::encodePath($list_id))); diff --git a/src/Api/IssueLinks.php b/src/Api/IssueLinks.php index d5c8399f..c25015fc 100644 --- a/src/Api/IssueLinks.php +++ b/src/Api/IssueLinks.php @@ -16,12 +16,21 @@ class IssueLinks extends AbstractApi { + /** + * List all issue links of an issue. + * + * @see https://docs.gitlab.com/api/issue_links/#list-all-issue-links + */ public function all(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/links'); } /** + * Create an issue link between two issues. + * + * @see https://docs.gitlab.com/api/issue_links/#create-an-issue-link + * * @param array $parameters { * * @var string $link_type @@ -36,6 +45,10 @@ public function create(int|string $project_id, int $issue_iid, int|string $targe } /** + * Delete an issue link. + * + * @see https://docs.gitlab.com/api/issue_links/#delete-an-issue-link + * * @param array $parameters { * * @var string $link_type diff --git a/src/Api/Issues.php b/src/Api/Issues.php index 10f74f26..540ade15 100644 --- a/src/Api/Issues.php +++ b/src/Api/Issues.php @@ -30,6 +30,12 @@ class Issues extends AbstractApi public const STATE_CLOSED = 'closed'; /** + * List issues, either all issues visible to the authenticated user (when + * $project_id is null) or all issues of a specific project. + * + * @see https://docs.gitlab.com/api/issues/#list-all-issues + * @see https://docs.gitlab.com/api/issues/#list-all-project-issues + * * @param array $parameters { * * @var string $state return all issues or just those that are opened or closed @@ -55,6 +61,11 @@ public function all(int|string|null $project_id = null, array $parameters = []): return $this->get($path, $this->createOptionsResolver()->resolve($parameters)); } + /** + * List all issues of a group. + * + * @see https://docs.gitlab.com/api/issues/#list-all-group-issues + */ public function group(int|string $group_id, array $parameters = []): mixed { return $this->get( @@ -63,26 +74,51 @@ public function group(int|string $group_id, array $parameters = []): mixed ); } + /** + * Get a single project issue. + * + * @see https://docs.gitlab.com/api/issues/#retrieve-a-project-issue + */ public function show(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid))); } + /** + * Create a new project issue. + * + * @see https://docs.gitlab.com/api/issues/#create-an-issue + */ public function create(int|string $project_id, array $params): mixed { return $this->post($this->getProjectPath($project_id, 'issues'), $params); } + /** + * Update an existing project issue. + * + * @see https://docs.gitlab.com/api/issues/#update-an-issue + */ public function update(int|string $project_id, int $issue_iid, array $params): mixed { return $this->put($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)), $params); } + /** + * Reorder an issue. + * + * @see https://docs.gitlab.com/api/issues/#reorder-an-issue + */ public function reorder(int|string $project_id, int $issue_iid, array $params): mixed { return $this->put($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/reorder', $params); } + /** + * Move an issue to a different project. + * + * @see https://docs.gitlab.com/api/issues/#move-an-issue + */ public function move(int|string $project_id, int $issue_iid, int|string $to_project_id): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/move', [ @@ -90,21 +126,41 @@ public function move(int|string $project_id, int $issue_iid, int|string $to_proj ]); } + /** + * Delete a project issue. + * + * @see https://docs.gitlab.com/api/issues/#delete-an-issue + */ public function remove(int|string $project_id, int $issue_iid): mixed { return $this->delete($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid))); } + /** + * List all notes of an issue. + * + * @see https://docs.gitlab.com/api/notes/#list-all-issue-notes + */ public function showNotes(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/notes')); } + /** + * Get a single note of an issue. + * + * @see https://docs.gitlab.com/api/notes/#retrieve-an-issue-note + */ public function showNote(int|string $project_id, int $issue_iid, int $note_id): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/notes/'.self::encodePath($note_id))); } + /** + * Create a new note for an issue. + * + * @see https://docs.gitlab.com/api/notes/#create-an-issue-note + */ public function addNote(int|string $project_id, int $issue_iid, string $body, array $params = []): mixed { $params['body'] = $body; @@ -112,6 +168,11 @@ public function addNote(int|string $project_id, int $issue_iid, string $body, ar return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/notes'), $params); } + /** + * Update an existing note of an issue. + * + * @see https://docs.gitlab.com/api/notes/#update-an-issue-note + */ public function updateNote(int|string $project_id, int $issue_iid, int $note_id, string $body, array $params = []): mixed { $params['body'] = $body; @@ -119,31 +180,61 @@ public function updateNote(int|string $project_id, int $issue_iid, int $note_id, return $this->put($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/notes/'.self::encodePath($note_id)), $params); } + /** + * Delete a note of an issue. + * + * @see https://docs.gitlab.com/api/notes/#delete-an-issue-note + */ public function removeNote(int|string $project_id, int $issue_iid, int $note_id): mixed { return $this->delete($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/notes/'.self::encodePath($note_id))); } + /** + * List all discussion items of an issue. + * + * @see https://docs.gitlab.com/api/discussions/#list-all-issue-discussion-items + */ public function showDiscussions(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/discussions'); } + /** + * Get a single discussion item of an issue. + * + * @see https://docs.gitlab.com/api/discussions/#retrieve-an-issue-discussion-item + */ public function showDiscussion(int|string $project_id, int $issue_iid, string $discussion_id): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/discussions/'.self::encodePath($discussion_id)); } + /** + * Create a new thread on an issue. + * + * @see https://docs.gitlab.com/api/discussions/#create-an-issue-thread + */ public function addDiscussion(int|string $project_id, int $issue_iid, string $body): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/discussions'), ['body' => $body]); } + /** + * Add a note to an existing issue thread. + * + * @see https://docs.gitlab.com/api/discussions/#add-a-note-to-an-issue-thread + */ public function addDiscussionNote(int|string $project_id, int $issue_iid, string $discussion_id, string $body): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/discussions/'.self::encodePath($discussion_id).'/notes'), ['body' => $body]); } + /** + * Update an existing note of an issue thread. + * + * @see https://docs.gitlab.com/api/discussions/#update-an-issue-thread-note + */ public function updateDiscussionNote(int|string $project_id, int $issue_iid, string $discussion_id, int $note_id, string $body): mixed { return $this->put($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/discussions/'.self::encodePath($discussion_id).'/notes/'.self::encodePath($note_id)), [ @@ -151,31 +242,61 @@ public function updateDiscussionNote(int|string $project_id, int $issue_iid, str ]); } + /** + * Delete a note of an issue thread. + * + * @see https://docs.gitlab.com/api/discussions/#delete-an-issue-thread-note + */ public function removeDiscussionNote(int|string $project_id, int $issue_iid, string $discussion_id, int $note_id): mixed { return $this->delete($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/discussions/'.self::encodePath($discussion_id).'/notes/'.self::encodePath($note_id))); } + /** + * Set a time estimate for an issue. + * + * @see https://docs.gitlab.com/api/issues/#set-a-time-estimate-for-an-issue + */ public function setTimeEstimate(int|string $project_id, int $issue_iid, string $duration): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/time_estimate'), ['duration' => $duration]); } + /** + * Reset the time estimate for an issue. + * + * @see https://docs.gitlab.com/api/issues/#reset-the-time-estimate-for-an-issue + */ public function resetTimeEstimate(int|string $project_id, int $issue_iid): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/reset_time_estimate')); } + /** + * Add spent time for an issue. + * + * @see https://docs.gitlab.com/api/issues/#add-spent-time-for-an-issue + */ public function addSpentTime(int|string $project_id, int $issue_iid, string $duration): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/add_spent_time'), ['duration' => $duration]); } + /** + * Reset spent time for an issue. + * + * @see https://docs.gitlab.com/api/issues/#reset-spent-time-for-an-issue + */ public function resetSpentTime(int|string $project_id, int $issue_iid): mixed { return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/reset_spent_time')); } + /** + * Get time tracking stats for an issue. + * + * @see https://docs.gitlab.com/api/issues/#retrieve-time-tracking-stats-for-an-issue + */ public function getTimeStats(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/time_stats')); @@ -185,7 +306,7 @@ public function getTimeStats(int|string $project_id, int $issue_iid): mixed * Subscribes the authenticated user to an issue to receive notifications. * If the user is already subscribed to the issue, the status code 304 is returned. * - * @see https://docs.gitlab.com/ee/api/issues.html#subscribe-to-an-issue + * @see https://docs.gitlab.com/api/issues/#subscribe-to-an-issue * * @param int|string $project_id The ID or URL-encoded path of the project owned by the authenticated user * @param int $issue_iid The internal ID of a project’s issue @@ -199,7 +320,7 @@ public function subscribe(int|string $project_id, int $issue_iid): mixed * Unsubscribes the authenticated user from the issue to not receive notifications from it. * If the user is not subscribed to the issue, the status code 304 is returned. * - * @see https://docs.gitlab.com/ee/api/issues.html#unsubscribe-from-an-issue + * @see https://docs.gitlab.com/api/issues/#unsubscribe-from-an-issue * * @param int|string $project_id The ID or URL-encoded path of the project owned by the authenticated user * @param int $issue_iid The internal ID of a project’s issue @@ -209,36 +330,72 @@ public function unsubscribe(int|string $project_id, int $issue_iid): mixed return $this->post($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/unsubscribe')); } + /** + * List all award emoji of an issue. + * + * @see https://docs.gitlab.com/api/award_emoji/#list-an-awardables-award-emojis + */ public function awardEmoji(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/award_emoji')); } + /** + * Delete an award emoji of an issue. + * + * @see https://docs.gitlab.com/api/award_emoji/#delete-an-award-emoji + */ public function removeAwardEmoji(int|string $project_id, int $issue_iid, int $award_id): mixed { return $this->delete($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/award_emoji/'.self::encodePath($award_id))); } + /** + * List all merge requests that will close an issue when merged. + * + * @see https://docs.gitlab.com/api/issues/#list-all-merge-requests-that-close-an-issue-on-merge + */ public function closedByMergeRequests(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/closed_by'); } + /** + * List all merge requests related to an issue. + * + * @see https://docs.gitlab.com/api/issues/#list-all-merge-requests-related-to-an-issue + */ public function relatedMergeRequests(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid).'/related_merge_requests')); } + /** + * List all participants of an issue. + * + * Not currently documented on the public Issues API reference page; verify + * against a running GitLab instance or the GitLab source before relying on it. + */ public function showParticipants(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/participants'); } + /** + * List all label events of an issue. + * + * @see https://docs.gitlab.com/api/resource_label_events/#list-project-issue-label-events + */ public function showResourceLabelEvents(int|string $project_id, int $issue_iid): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/resource_label_events'); } + /** + * Get a single label event of an issue. + * + * @see https://docs.gitlab.com/api/resource_label_events/#retrieve-a-single-issue-label-event + */ public function showResourceLabelEvent(int|string $project_id, int $issue_iid, int $resource_label_event_id): mixed { return $this->get($this->getProjectPath($project_id, 'issues/'.self::encodePath($issue_iid)).'/resource_label_events/'.self::encodePath($resource_label_event_id)); diff --git a/src/Api/IssuesStatistics.php b/src/Api/IssuesStatistics.php index 33e459ef..b058d7ba 100644 --- a/src/Api/IssuesStatistics.php +++ b/src/Api/IssuesStatistics.php @@ -19,16 +19,25 @@ class IssuesStatistics extends AbstractApi { + /** + * @see https://docs.gitlab.com/api/issues_statistics/#retrieve-issues-statistics-for-a-user + */ public function all(array $parameters): mixed { return $this->get('issues_statistics', $this->createOptionsResolver()->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/issues_statistics/#retrieve-issues-statistics-for-a-project + */ public function project(int|string $project_id, array $parameters): mixed { return $this->get($this->getProjectPath($project_id, 'issues_statistics'), $this->createOptionsResolver()->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/issues_statistics/#retrieve-issues-statistics-for-a-group + */ public function group(int|string $group_id, array $parameters): mixed { return $this->get('groups/'.self::encodePath($group_id).'/issues_statistics', $this->createOptionsResolver()->resolve($parameters)); diff --git a/src/Api/Jobs.php b/src/Api/Jobs.php index ba608620..b5093b42 100644 --- a/src/Api/Jobs.php +++ b/src/Api/Jobs.php @@ -60,6 +60,8 @@ class Jobs extends AbstractApi public const SCOPE_MANUAL = 'manual'; /** + * @see https://docs.gitlab.com/api/jobs/#list-all-jobs-for-a-project + * * @param array $parameters { * * @var string|string[] $scope The scope of jobs to show, one or array of: created, pending, running, failed, @@ -74,6 +76,8 @@ public function all(int|string $project_id, array $parameters = []): mixed } /** + * @see https://docs.gitlab.com/api/jobs/#list-all-jobs-by-pipeline + * * @param array $parameters { * * @var string|string[] $scope The scope of jobs to show, one or array of: created, pending, running, failed, @@ -91,6 +95,8 @@ public function pipelineJobs(int|string $project_id, int $pipeline_id, array $pa } /** + * @see https://docs.gitlab.com/api/jobs/#list-all-trigger-jobs-by-pipeline + * * @param array $parameters { * * @var string|string[] $scope The scope of bridge jobs to show, one or array of: created, pending, running, failed, @@ -108,16 +114,25 @@ public function pipelineBridges(int|string $project_id, int $pipeline_id, array ); } + /** + * @see https://docs.gitlab.com/api/jobs/#retrieve-a-job-by-job-id + */ public function show(int|string $project_id, int $job_id): mixed { return $this->get('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id)); } + /** + * @see https://docs.gitlab.com/api/job_artifacts/#download-job-artifacts-by-job-id + */ public function artifacts(int|string $project_id, int $job_id): StreamInterface { return $this->getAsResponse('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/artifacts')->getBody(); } + /** + * @see https://docs.gitlab.com/api/job_artifacts/#download-job-artifacts-by-reference-name + */ public function artifactsByRefName(int|string $project_id, string $ref_name, string $job_name): StreamInterface { return $this->getAsResponse('projects/'.self::encodePath($project_id).'/jobs/artifacts/'.self::encodePath($ref_name).'/download', [ @@ -125,6 +140,9 @@ public function artifactsByRefName(int|string $project_id, string $ref_name, str ])->getBody(); } + /** + * @see https://docs.gitlab.com/api/job_artifacts/#download-a-single-artifact-file-by-reference-name + */ public function artifactByRefName(int|string $project_id, string $ref_name, string $job_name, string $artifact_path): StreamInterface { return $this->getAsResponse('projects/'.self::encodePath($project_id).'/jobs/artifacts/'.self::encodePath($ref_name).'/raw/'.self::encodePath($artifact_path), [ @@ -132,37 +150,57 @@ public function artifactByRefName(int|string $project_id, string $ref_name, stri ])->getBody(); } + /** + * @see https://docs.gitlab.com/api/job_artifacts/#download-a-single-artifact-file-by-job-id + */ public function artifactByJobId(int|string $project_id, int $job_id, string $artifact_path): StreamInterface { return $this->getAsResponse('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/artifacts/'.self::encodePath($artifact_path))->getBody(); } + /** + * @see https://docs.gitlab.com/api/jobs/#retrieve-a-log-file-for-a-job + */ public function trace(int|string $project_id, int $job_id): mixed { return $this->get('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/trace'); } + /** + * @see https://docs.gitlab.com/api/jobs/#cancel-a-job + */ public function cancel(int|string $project_id, int $job_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/cancel'); } + /** + * @see https://docs.gitlab.com/api/jobs/#retry-a-job + */ public function retry(int|string $project_id, int $job_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/retry'); } + /** + * @see https://docs.gitlab.com/api/jobs/#erase-a-job + */ public function erase(int|string $project_id, int $job_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/erase'); } + /** + * @see https://docs.gitlab.com/api/job_artifacts/#keep-job-artifacts + */ public function keepArtifacts(int|string $project_id, int $job_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/jobs/'.self::encodePath($job_id).'/artifacts/keep'); } /** + * @see https://docs.gitlab.com/api/jobs/#run-a-job + * * @param array $parameters { * * @var array $job_inputs job input values to use when playing the job diff --git a/src/Api/Keys.php b/src/Api/Keys.php index 05f4d4d5..978560f5 100644 --- a/src/Api/Keys.php +++ b/src/Api/Keys.php @@ -16,6 +16,9 @@ class Keys extends AbstractApi { + /** + * @see https://docs.gitlab.com/api/keys/#retrieve-user-by-ssh-key-id + */ public function show(int $id): mixed { return $this->get('keys/'.self::encodePath($id)); diff --git a/src/Api/MergeRequests.php b/src/Api/MergeRequests.php index 92af1a3a..c5bfe677 100644 --- a/src/Api/MergeRequests.php +++ b/src/Api/MergeRequests.php @@ -47,6 +47,9 @@ class MergeRequests extends AbstractApi public const STATE_LOCKED = 'locked'; /** + * @see https://docs.gitlab.com/api/merge_requests/#list-merge-requests + * @see https://docs.gitlab.com/api/merge_requests/#list-project-merge-requests + * * @param array $parameters { * * @var int[] $iids return merge requests having the given IIDs @@ -279,6 +282,8 @@ public function all(int|string|null $project_id = null, array $parameters = []): } /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-a-merge-request + * * @param array $parameters { * * @var bool $include_diverged_commits_count Return the commits behind the target branch @@ -303,6 +308,8 @@ public function show(int|string $project_id, int $mr_iid, array $parameters = [] } /** + * @see https://docs.gitlab.com/api/merge_requests/#create-a-merge-request + * * @param array $parameters { * * @var bool $allow_collaboration allow commits from upstream members @@ -383,6 +390,8 @@ public function create(int|string $project_id, string $source, string $target, s } /** + * @see https://docs.gitlab.com/api/merge_requests/#update-a-merge-request + * * @param array $parameters { * * @var string $add_labels labels to add to the merge request @@ -469,12 +478,17 @@ public function update(int|string $project_id, int $mr_iid, array $parameters): return $this->put($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#delete-a-merge-request + */ public function remove(int|string $project_id, int $mr_iid): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid))); } /** + * @see https://docs.gitlab.com/api/merge_requests/#merge-a-merge-request + * * @param array $parameters { * * @var bool $auto_merge merge when checks pass @@ -515,6 +529,8 @@ public function merge(int|string $project_id, int $mr_iid, array $parameters = [ } /** + * @see https://docs.gitlab.com/api/merge_trains/#add-a-merge-request-to-a-merge-train + * * @param array $parameters { * * @var bool $auto_merge add the merge request to the merge train when checks pass @@ -543,6 +559,8 @@ public function addToMergeTrain(int|string $project_id, int $mr_iid, array $para } /** + * @see https://docs.gitlab.com/api/notes/#list-all-merge-request-notes + * * @param array $parameters { * * @var string $sort return notes sorted in asc or desc order @@ -562,12 +580,17 @@ public function showNotes(int|string $project_id, int $mr_iid, array $parameters return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/notes/#retrieve-a-merge-request-note + */ public function showNote(int|string $project_id, int $mr_iid, int $note_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes/'.self::encodePath($note_id))); } /** + * @see https://docs.gitlab.com/api/notes/#create-a-merge-request-note + * * @param array $params { * * @var string $created_at creation timestamp for admins or project owners @@ -594,6 +617,8 @@ public function addNote(int|string $project_id, int $mr_iid, string $body, array } /** + * @see https://docs.gitlab.com/api/notes/#update-a-merge-request-note + * * @param array $params { * * @var bool $confidential deprecated; use internal instead @@ -611,42 +636,65 @@ public function updateNote(int|string $project_id, int $mr_iid, int $note_id, st ], $resolver->resolve($params))); } + /** + * @see https://docs.gitlab.com/api/notes/#delete-a-merge-request-note + */ public function removeNote(int|string $project_id, int $mr_iid, int $note_id): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes/'.self::encodePath($note_id))); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#list-all-emoji-reactions-for-a-comment + */ public function showNoteAwardEmojis(int|string $project_id, int $mr_iid, int $note_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes/'.self::encodePath($note_id).'/award_emoji')); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#retrieve-an-emoji-reaction-from-a-comment + */ public function showNoteAwardEmoji(int|string $project_id, int $mr_iid, int $note_id, int $award_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes/'.self::encodePath($note_id).'/award_emoji/'.self::encodePath($award_id))); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#add-an-emoji-reaction-to-a-comment + */ public function addNoteAwardEmoji(int|string $project_id, int $mr_iid, int $note_id, string $name): mixed { return $this->post($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes/'.self::encodePath($note_id).'/award_emoji'), ['name' => $name]); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#delete-an-emoji-reaction-from-a-comment + */ public function removeNoteAwardEmoji(int|string $project_id, int $mr_iid, int $note_id, int $award_id): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/notes/'.self::encodePath($note_id).'/award_emoji/'.self::encodePath($award_id))); } + /** + * @see https://docs.gitlab.com/api/discussions/#list-all-merge-request-discussion-items + */ public function showDiscussions(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)).'/discussions'); } + /** + * @see https://docs.gitlab.com/api/discussions/#retrieve-a-merge-request-discussion-item + */ public function showDiscussion(int|string $project_id, int $mr_iid, string $discussion_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)).'/discussions/'.self::encodePath($discussion_id)); } /** + * @see https://docs.gitlab.com/api/discussions/#create-a-merge-request-thread + * * @param array $params { * * @var string $body the note body @@ -674,6 +722,9 @@ public function addDiscussion(int|string $project_id, int $mr_iid, array $params return $this->post($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/discussions'), $resolver->resolve($params)); } + /** + * @see https://docs.gitlab.com/api/discussions/#resolve-a-merge-request-thread + */ public function resolveDiscussion(int|string $project_id, int $mr_iid, string $discussion_id, bool $resolved = true): mixed { return $this->put($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/discussions/'.self::encodePath($discussion_id)), [ @@ -682,6 +733,8 @@ public function resolveDiscussion(int|string $project_id, int $mr_iid, string $d } /** + * @see https://docs.gitlab.com/api/discussions/#add-note-to-a-merge-request-thread + * * @param array $params { * * @var string $created_at creation timestamp for admins or project owners @@ -698,6 +751,8 @@ public function addDiscussionNote(int|string $project_id, int $mr_iid, string $d } /** + * @see https://docs.gitlab.com/api/discussions/#update-a-merge-request-thread-note + * * @param array $params { * * @var string $body the note body @@ -717,27 +772,41 @@ public function updateDiscussionNote(int|string $project_id, int $mr_iid, string return $this->put($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/discussions/'.self::encodePath($discussion_id).'/notes/'.self::encodePath($note_id)), $resolver->resolve($params)); } + /** + * @see https://docs.gitlab.com/api/discussions/#delete-a-merge-request-thread-note + */ public function removeDiscussionNote(int|string $project_id, int $mr_iid, string $discussion_id, int $note_id): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/discussions/'.self::encodePath($discussion_id).'/notes/'.self::encodePath($note_id))); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-merge-request-participants + */ public function showParticipants(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)).'/participants'); } + /** + * @see https://docs.gitlab.com/api/resource_label_events/#list-project-merge-request-label-events + */ public function showResourceLabelEvents(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)).'/resource_label_events'); } + /** + * @see https://docs.gitlab.com/api/resource_label_events/#retrieve-a-single-merge-request-label-event + */ public function showResourceLabelEvent(int|string $project_id, int $mr_iid, int $resource_label_event_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)).'/resource_label_events/'.self::encodePath($resource_label_event_id)); } /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-merge-request-changes + * * @param array $parameters { * * @var bool $access_raw_diffs access raw diffs @@ -757,22 +826,33 @@ public function changes(int|string $project_id, int $mr_iid, array $parameters = return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/changes'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-merge-request-commits + */ public function commits(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/commits')); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#list-issues-that-close-on-merge + */ public function closesIssues(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/closes_issues')); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-state-for-a-merge-request + */ public function approvals(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/approvals')); } /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#approve-merge-request + * * @param array $parameters { * * @var string $approval_password current user's password @@ -792,32 +872,49 @@ public function approve(int|string $project_id, int $mr_iid, array $parameters = return $this->post($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/approve'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#unapprove-a-merge-request + */ public function unapprove(int|string $project_id, int $mr_iid): mixed { return $this->post($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/unapprove')); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#list-all-emoji-reactions-for-a-resource + */ public function awardEmoji(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/award_emoji')); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#retrieve-an-emoji-reaction-from-a-resource + */ public function showAwardEmoji(int|string $project_id, int $mr_iid, int $award_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/award_emoji/'.self::encodePath($award_id))); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#add-an-emoji-reaction-to-a-resource + */ public function addAwardEmoji(int|string $project_id, int $mr_iid, string $name): mixed { return $this->post($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/award_emoji'), ['name' => $name]); } + /** + * @see https://docs.gitlab.com/api/emoji_reactions/#delete-an-emoji-reaction-from-a-resource + */ public function removeAwardEmoji(int|string $project_id, int $mr_iid, int $award_id): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/award_emoji/'.self::encodePath($award_id))); } /** + * @see https://docs.gitlab.com/api/merge_requests/#rebase-a-merge-request + * * @param array $params { * * @var bool $skip_ci skip the CI pipeline @@ -832,11 +929,17 @@ public function rebase(int|string $project_id, int $mr_iid, array $params = []): return $this->put($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid)).'/rebase', $resolver->resolve($params)); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-details-for-a-merge-request + */ public function approvalState(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/approval_state')); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-merge-request + */ public function levelRules(int|string $project_id, int $mr_iid, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -845,6 +948,8 @@ public function levelRules(int|string $project_id, int $mr_iid, array $parameter } /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-merge-request + * * @param array $parameters { * * @var int $approval_project_rule_id approval project rule id @@ -890,6 +995,8 @@ public function createLevelRule(int|string $project_id, int $mr_iid, string $nam } /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-merge-request + * * @param array $parameters { * * @var int[] $group_ids group ids @@ -934,22 +1041,33 @@ public function updateLevelRule(int|string $project_id, int $mr_iid, int $approv ); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#delete-an-approval-rule-for-a-merge-request + */ public function deleteLevelRule(int|string $project_id, int $mr_iid, int $approval_rule_id): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/approval_rules/'.self::encodePath($approval_rule_id))); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-merge-request-dependencies + */ public function dependencies(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/blocks')); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-merge-request-dependencies + */ public function showDependency(int|string $project_id, int $mr_iid, int $block_id): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/blocks/'.self::encodePath($block_id))); } /** + * @see https://docs.gitlab.com/api/merge_requests/#create-a-merge-request-dependency + * * @param array $parameters { * * @var int $blocking_merge_request_id global ID of the blocking merge request @@ -981,11 +1099,17 @@ public function createDependency(int|string $project_id, int $mr_iid, array $par return $this->post($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/blocks'), $parameters); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#delete-a-merge-request-dependency + */ public function deleteDependency(int|string $project_id, int $mr_iid, int $block_id): mixed { return $this->delete($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/blocks/'.self::encodePath($block_id))); } + /** + * @see https://docs.gitlab.com/api/merge_requests/#retrieve-blocked-merge-requests + */ public function blockedMergeRequests(int|string $project_id, int $mr_iid): mixed { return $this->get($this->getProjectPath($project_id, 'merge_requests/'.self::encodePath($mr_iid).'/blockees')); diff --git a/src/Api/Milestones.php b/src/Api/Milestones.php index ee076150..e8a39e6e 100644 --- a/src/Api/Milestones.php +++ b/src/Api/Milestones.php @@ -27,6 +27,8 @@ class Milestones extends AbstractApi public const STATE_CLOSED = 'closed'; /** + * @see https://docs.gitlab.com/api/milestones/#list-all-project-milestones + * * @param array $parameters { * * @var int[] $iids return only the milestones having the given iids @@ -51,31 +53,49 @@ public function all(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'milestones'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/milestones/#retrieve-a-milestone + */ public function show(int|string $project_id, int $milestone_id): mixed { return $this->get($this->getProjectPath($project_id, 'milestones/'.self::encodePath($milestone_id))); } + /** + * @see https://docs.gitlab.com/api/milestones/#create-a-milestone + */ public function create(int|string $project_id, array $params): mixed { return $this->post($this->getProjectPath($project_id, 'milestones'), $params); } + /** + * @see https://docs.gitlab.com/api/milestones/#update-a-milestone + */ public function update(int|string $project_id, int $milestone_id, array $params): mixed { return $this->put($this->getProjectPath($project_id, 'milestones/'.self::encodePath($milestone_id)), $params); } + /** + * @see https://docs.gitlab.com/api/milestones/#delete-a-milestone + */ public function remove(int|string $project_id, int $milestone_id): mixed { return $this->delete($this->getProjectPath($project_id, 'milestones/'.self::encodePath($milestone_id))); } + /** + * @see https://docs.gitlab.com/api/milestones/#list-all-issues-for-a-milestone + */ public function issues(int|string $project_id, int $milestone_id): mixed { return $this->get($this->getProjectPath($project_id, 'milestones/'.self::encodePath($milestone_id).'/issues')); } + /** + * @see https://docs.gitlab.com/api/milestones/#list-all-merge-requests-for-a-milestone + */ public function mergeRequests(int|string $project_id, int $milestone_id): mixed { return $this->get($this->getProjectPath($project_id, 'milestones/'.self::encodePath($milestone_id).'/merge_requests')); diff --git a/src/Api/Packages.php b/src/Api/Packages.php index 4698905f..69d74374 100644 --- a/src/Api/Packages.php +++ b/src/Api/Packages.php @@ -19,6 +19,8 @@ class Packages extends AbstractApi { /** + * @see https://docs.gitlab.com/api/packages/#for-a-project + * * @param array $parameters { * * @var string $order_by the field to use as order. one of created_at (default), name, @@ -60,21 +62,33 @@ public function all(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'packages'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/packages/#retrieve-a-project-package + */ public function show(int|string $project_id, int $package_id): mixed { return $this->get($this->getPackagePath($project_id, $package_id)); } + /** + * @see https://docs.gitlab.com/api/packages/#list-package-files + */ public function allFiles(int|string $project_id, int $package_id): mixed { return $this->get($this->getPackagePath($project_id, $package_id).'/package_files'); } + /** + * @see https://docs.gitlab.com/api/packages/#delete-a-project-package + */ public function remove(int|string $project_id, int $package_id): mixed { return $this->delete($this->getPackagePath($project_id, $package_id)); } + /** + * @see https://docs.gitlab.com/api/packages/#delete-a-package-file + */ public function removeFile(int|string $project_id, int $package_id, int $package_file_id): mixed { return $this->delete( @@ -82,6 +96,9 @@ public function removeFile(int|string $project_id, int $package_id, int $package ); } + /** + * @see https://docs.gitlab.com/user/packages/generic_packages/#publish-a-single-file + */ public function addGenericFile(int|string $project_id, string $package_name, string $package_version, string $file, string $status = 'default'): mixed { return $this->putFile( diff --git a/src/Api/PersonalAccessTokens.php b/src/Api/PersonalAccessTokens.php index 81736c9e..67ce1666 100644 --- a/src/Api/PersonalAccessTokens.php +++ b/src/Api/PersonalAccessTokens.php @@ -20,6 +20,8 @@ class PersonalAccessTokens extends AbstractApi { /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#list-all-personal-access-tokens + * * @param array $parameters { * * @var string $search search text @@ -95,17 +97,25 @@ public function all(array $parameters = []): mixed return $this->get('personal_access_tokens', $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#retrieve-a-personal-access-token + */ public function show(int|string $id): mixed { return $this->get('personal_access_tokens/'.self::encodePath($id)); } + /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#self-inform + */ public function current(): mixed { return $this->get('personal_access_tokens/self'); } /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#rotate-a-personal-access-token + * * @param array $parameters { * * @var \DateTimeInterface $expires_at expiration date of the access token @@ -126,6 +136,8 @@ public function rotate(int|string $id, array $parameters = []): mixed } /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#self-rotate + * * @param array $parameters { * * @var \DateTimeInterface $expires_at expiration date of the access token @@ -145,11 +157,17 @@ public function rotateCurrent(array $parameters = []): mixed return $this->post('personal_access_tokens/self/rotate', $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#revoke-a-personal-access-token + */ public function remove(int|string $id): mixed { return $this->delete('personal_access_tokens/'.self::encodePath($id)); } + /** + * @see https://docs.gitlab.com/api/personal_access_tokens/#self-revoke + */ public function removeCurrent(): mixed { return $this->delete('personal_access_tokens/self'); diff --git a/src/Api/ProjectNamespaces.php b/src/Api/ProjectNamespaces.php index d35228ba..2b26ee25 100644 --- a/src/Api/ProjectNamespaces.php +++ b/src/Api/ProjectNamespaces.php @@ -17,6 +17,8 @@ class ProjectNamespaces extends AbstractApi { /** + * @see https://docs.gitlab.com/api/namespaces/#list-all-namespaces + * * @param array $parameters { * * @var string $search Returns a list of namespaces the user is authorized to see based on the search criteria. @@ -30,6 +32,9 @@ public function all(array $parameters = []): mixed return $this->get('namespaces', $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/namespaces/#retrieve-namespace-details + */ public function show(int|string $namespace_id): mixed { return $this->get('namespaces/'.self::encodePath($namespace_id)); diff --git a/src/Api/Projects.php b/src/Api/Projects.php index 080d7278..3d82c205 100644 --- a/src/Api/Projects.php +++ b/src/Api/Projects.php @@ -22,6 +22,8 @@ class Projects extends AbstractApi { /** + * @see https://docs.gitlab.com/api/projects/#list-all-projects + * * @param array $parameters { * * @var bool $archived limit by archived status @@ -151,6 +153,8 @@ public function all(array $parameters = []): mixed } /** + * @see https://docs.gitlab.com/api/projects/#retrieve-a-project + * * @param array $parameters { * * @var bool $statistics include project statistics @@ -175,6 +179,9 @@ public function show(int|string $project_id, array $parameters = []): mixed return $this->get('projects/'.self::encodePath($project_id), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/projects/#create-a-project + */ public function create(string $name, array $parameters = []): mixed { $parameters['name'] = $name; @@ -182,6 +189,9 @@ public function create(string $name, array $parameters = []): mixed return $this->post('projects', $parameters); } + /** + * @see https://docs.gitlab.com/api/projects/#create-a-project-for-a-user + */ public function createForUser(int $user_id, string $name, array $parameters = []): mixed { $parameters['name'] = $name; @@ -189,12 +199,17 @@ public function createForUser(int $user_id, string $name, array $parameters = [] return $this->post('projects/user/'.self::encodePath($user_id), $parameters); } + /** + * @see https://docs.gitlab.com/api/projects/#update-a-project + */ public function update(int|string $project_id, array $parameters): mixed { return $this->put('projects/'.self::encodePath($project_id), $parameters); } /** + * @see https://docs.gitlab.com/api/projects/#delete-a-project + * * @param array $parameters { * * @var string $full_path full path of project to use with permanently_remove @@ -214,31 +229,49 @@ public function remove(int|string $project_id, array $parameters = []): mixed return $this->delete('projects/'.self::encodePath($project_id), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/projects/#restore-a-project-marked-for-deletion + */ public function restore(int|string $project_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/restore'); } + /** + * @see https://docs.gitlab.com/api/projects/#archive-a-project + */ public function archive(int|string $project_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/archive'); } + /** + * @see https://docs.gitlab.com/api/projects/#unarchive-a-project + */ public function unarchive(int|string $project_id): mixed { return $this->post('projects/'.self::encodePath($project_id).'/unarchive'); } + /** + * @see https://docs.gitlab.com/api/pipeline_triggers/#list-project-trigger-tokens + */ public function triggers(int|string $project_id): mixed { return $this->get('projects/'.self::encodePath($project_id).'/triggers'); } + /** + * @see https://docs.gitlab.com/api/pipeline_triggers/#retrieve-trigger-token-details + */ public function trigger(int|string $project_id, int $trigger_id): mixed { return $this->get($this->getProjectPath($project_id, 'triggers/'.self::encodePath($trigger_id))); } + /** + * @see https://docs.gitlab.com/api/pipeline_triggers/#create-a-trigger-token + */ public function createTrigger(int|string $project_id, string $description): mixed { return $this->post($this->getProjectPath($project_id, 'triggers'), [ @@ -246,11 +279,17 @@ public function createTrigger(int|string $project_id, string $description): mixe ]); } + /** + * @see https://docs.gitlab.com/api/pipeline_triggers/#delete-a-pipeline-trigger-token + */ public function removeTrigger(int|string $project_id, int $trigger_id): mixed { return $this->delete($this->getProjectPath($project_id, 'triggers/'.self::encodePath($trigger_id))); } + /** + * @see https://docs.gitlab.com/api/pipeline_triggers/#trigger-a-pipeline-with-a-token + */ public function triggerPipeline(int|string $project_id, string $ref, #[\SensitiveParameter] string $token, array $variables = []): mixed { return $this->post($this->getProjectPath($project_id, 'trigger/pipeline'), [ @@ -260,11 +299,17 @@ public function triggerPipeline(int|string $project_id, string $ref, #[\Sensitiv ]); } + /** + * @see https://docs.gitlab.com/api/runners/#unassign-a-runner-from-project + */ public function disableRunner(int $project_id, int $runner_id): mixed { return $this->delete('projects/'.self::encodePath($project_id).'/runners/'.self::encodePath($runner_id)); } + /** + * @see https://docs.gitlab.com/api/runners/#assign-a-runner-to-project + */ public function enableRunner(int $project_id, int $runner_id): mixed { $parameters = [ @@ -275,6 +320,8 @@ public function enableRunner(int $project_id, int $runner_id): mixed } /** + * @see https://docs.gitlab.com/api/pipelines/#list-project-pipelines + * * @param array $parameters { * * @var string $scope the scope of pipelines, one of: running, pending, finished, branches, tags @@ -336,12 +383,17 @@ public function pipelines(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'pipelines'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/pipelines/#retrieve-a-single-pipeline + */ public function pipeline(int|string $project_id, int $pipeline_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id))); } /** + * @see https://docs.gitlab.com/api/pipelines/#retrieve-the-latest-pipeline + * * @param array $parameters { * * @var string $ref branch or tag to check for the latest pipeline @@ -357,27 +409,41 @@ public function latestPipeline(int|string $project_id, array $parameters = []): return $this->get($this->getProjectPath($project_id, 'pipelines/latest'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/jobs/#list-all-jobs-by-pipeline + */ public function pipelineJobs(int|string $project_id, int $pipeline_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id).'/jobs')); } + /** + * @see https://docs.gitlab.com/api/pipelines/#retrieve-pipeline-variables + */ public function pipelineVariables(int|string $project_id, int $pipeline_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id).'/variables')); } + /** + * @see https://docs.gitlab.com/api/pipelines/#retrieve-a-test-report-for-a-pipeline + */ public function pipelineTestReport(int|string $project_id, int $pipeline_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id).'/test_report')); } + /** + * @see https://docs.gitlab.com/api/pipelines/#retrieve-a-test-report-summary-for-a-pipeline + */ public function pipelineTestReportSummary(int|string $project_id, int $pipeline_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id).'/test_report_summary')); } /** + * @see https://docs.gitlab.com/api/pipelines/#create-a-new-pipeline + * * @param array|null $variables { * * @var string $key The name of the variable @@ -408,21 +474,33 @@ public function createPipeline(int|string $project_id, string $commit_ref, ?arra ]); } + /** + * @see https://docs.gitlab.com/api/pipelines/#retry-jobs-in-a-pipeline + */ public function retryPipeline(int|string $project_id, int $pipeline_id): mixed { return $this->post($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id)).'/retry'); } + /** + * @see https://docs.gitlab.com/api/pipelines/#cancel-all-jobs-for-a-pipeline + */ public function cancelPipeline(int|string $project_id, int $pipeline_id): mixed { return $this->post($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id)).'/cancel'); } + /** + * @see https://docs.gitlab.com/api/pipelines/#delete-a-pipeline + */ public function deletePipeline(int|string $project_id, int $pipeline_id): mixed { return $this->delete($this->getProjectPath($project_id, 'pipelines/'.self::encodePath($pipeline_id))); } + /** + * @see https://docs.gitlab.com/api/project_members/#list-all-members-of-a-project + */ public function allMembers(int|string $project_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -438,6 +516,8 @@ public function allMembers(int|string $project_id, array $parameters = []): mixe } /** + * @see https://docs.gitlab.com/api/project_members/#list-all-direct-members-of-a-project + * * @param array $parameters { * * @var string $query The query you want to search members for. @@ -460,16 +540,25 @@ public function members(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'members'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_members/#retrieve-a-direct-member-of-a-project + */ public function member(int|string $project_id, int $user_id): mixed { return $this->get($this->getProjectPath($project_id, 'members/'.self::encodePath($user_id))); } + /** + * @see https://docs.gitlab.com/api/project_members/#retrieve-a-member-of-a-project + */ public function allMember(int|string $project_id, int $user_id): mixed { return $this->get($this->getProjectPath($project_id, 'members/all/'.self::encodePath($user_id))); } + /** + * @see https://docs.gitlab.com/api/project_members/#add-a-member-to-a-project + */ public function addMember(int|string $project_id, int $user_id, int $access_level, ?string $expires_at = null): mixed { $params = [ @@ -483,6 +572,9 @@ public function addMember(int|string $project_id, int $user_id, int $access_leve return $this->post($this->getProjectPath($project_id, 'members'), $params); } + /** + * @see https://docs.gitlab.com/api/project_members/#update-a-member-of-a-project + */ public function saveMember(int|string $project_id, int $user_id, int $access_level, ?string $expires_at = null): mixed { $params = [ @@ -495,11 +587,17 @@ public function saveMember(int|string $project_id, int $user_id, int $access_lev return $this->put($this->getProjectPath($project_id, 'members/'.self::encodePath($user_id)), $params); } + /** + * @see https://docs.gitlab.com/api/project_members/#remove-a-direct-member-of-a-project + */ public function removeMember(int|string $project_id, int $user_id): mixed { return $this->delete($this->getProjectPath($project_id, 'members/'.self::encodePath($user_id))); } + /** + * @see https://docs.gitlab.com/api/project_webhooks/#list-webhooks-for-a-project + */ public function hooks(int|string $project_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -507,6 +605,9 @@ public function hooks(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'hooks'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_webhooks/#retrieve-a-project-webhook + */ public function hook(int|string $project_id, int $hook_id): mixed { return $this->get($this->getProjectPath($project_id, 'hooks/'.self::encodePath($hook_id))); @@ -515,7 +616,7 @@ public function hook(int|string $project_id, int $hook_id): mixed /** * Get project users. * - * See https://docs.gitlab.com/ee/api/projects.html#get-project-users for more info. + * @see https://docs.gitlab.com/api/projects/#list-all-members-of-a-project */ public function users(int|string $project_id, array $parameters = []): mixed { @@ -525,7 +626,7 @@ public function users(int|string $project_id, array $parameters = []): mixed /** * Get project issues. * - * See https://docs.gitlab.com/ee/api/issues.html#list-project-issues for more info. + * @see https://docs.gitlab.com/api/issues/#list-all-project-issues */ public function issues(int|string $project_id, array $parameters = []): mixed { @@ -535,7 +636,7 @@ public function issues(int|string $project_id, array $parameters = []): mixed /** * Get projects board list. * - * See https://docs.gitlab.com/ee/api/boards.html for more info. + * @see https://docs.gitlab.com/api/boards/#list-all-project-issue-boards */ public function boards(int|string $project_id): mixed { @@ -543,6 +644,8 @@ public function boards(int|string $project_id): mixed } /** + * @see https://docs.gitlab.com/api/iterations/#list-all-project-iterations + * * @param array $parameters { * * @var string $state Return opened, upcoming, current (previously started), closed, or all iterations. @@ -577,13 +680,16 @@ public function iterations(int|string $project_id, array $parameters = []): mixe * - https://gitlab.com/gitlab-org/gitlab/-/commit/695c29abcf7dc2eabde8d59869abcea0923ce8fa#note_334686748 * - https://gitlab.com/api/v4/projects/gitlab-org%2Fgitlab/repository/commits/695c29abcf7dc2eabde8d59869abcea0923ce8fa/discussions * - * @see https://docs.gitlab.com/ee/api/discussions.html#list-project-commit-discussion-items + * @see https://docs.gitlab.com/api/discussions/#list-all-commit-discussion-items */ public function getRepositoryCommitDiscussions(int|string $project_id, string $commit_id): mixed { return $this->get($this->getProjectPath($project_id, 'repository/commits/'.self::encodePath($commit_id)).'/discussions'); } + /** + * @see https://docs.gitlab.com/api/project_webhooks/#add-a-webhook-to-a-project + */ public function addHook(int|string $project_id, string $url, array $parameters = []): mixed { if (0 === \count($parameters)) { @@ -595,31 +701,49 @@ public function addHook(int|string $project_id, string $url, array $parameters = return $this->post($this->getProjectPath($project_id, 'hooks'), $parameters); } + /** + * @see https://docs.gitlab.com/api/project_webhooks/#update-a-project-webhook + */ public function updateHook(int|string $project_id, int $hook_id, array $parameters): mixed { return $this->put($this->getProjectPath($project_id, 'hooks/'.self::encodePath($hook_id)), $parameters); } + /** + * @see https://docs.gitlab.com/api/project_webhooks/#delete-project-webhook + */ public function removeHook(int|string $project_id, int $hook_id): mixed { return $this->delete($this->getProjectPath($project_id, 'hooks/'.self::encodePath($hook_id))); } + /** + * @see https://docs.gitlab.com/api/projects/#transfer-a-project-to-a-new-namespace + */ public function transfer(int|string $project_id, mixed $namespace): mixed { return $this->put($this->getProjectPath($project_id, 'transfer'), ['namespace' => $namespace]); } + /** + * @see https://docs.gitlab.com/api/deploy_keys/#list-deploy-keys-for-project + */ public function deployKeys(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'deploy_keys')); } + /** + * @see https://docs.gitlab.com/api/deploy_keys/#retrieve-a-deploy-key + */ public function deployKey(int|string $project_id, int $key_id): mixed { return $this->get($this->getProjectPath($project_id, 'deploy_keys/'.self::encodePath($key_id))); } + /** + * @see https://docs.gitlab.com/api/deploy_keys/#add-a-deploy-key-for-a-project + */ public function addDeployKey(int|string $project_id, string $title, string $key, bool $canPush = false): mixed { return $this->post($this->getProjectPath($project_id, 'deploy_keys'), [ @@ -630,6 +754,8 @@ public function addDeployKey(int|string $project_id, string $title, string $key, } /** + * @see https://docs.gitlab.com/api/deploy_keys/#update-a-deploy-key + * * @param array $parameters { * * @var bool $can_push can deploy key push to the project's repository @@ -649,22 +775,33 @@ public function updateDeployKey(int|string $project_id, int $key_id, array $para return $this->put($this->getProjectPath($project_id, 'deploy_keys/'.self::encodePath($key_id)), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/deploy_keys/#delete-a-deploy-key + */ public function deleteDeployKey(int|string $project_id, int $key_id): mixed { return $this->delete($this->getProjectPath($project_id, 'deploy_keys/'.self::encodePath($key_id))); } + /** + * @see https://docs.gitlab.com/api/deploy_keys/#enable-a-deploy-key + */ public function enableDeployKey(int|string $project_id, int $key_id): mixed { return $this->post($this->getProjectPath($project_id, 'deploy_keys/'.self::encodePath($key_id).'/enable')); } + /** + * @see https://docs.gitlab.com/api/deploy_tokens/#list-project-deploy-tokens + */ public function deployTokens(int|string $project_id, ?bool $active = null): mixed { return $this->get($this->getProjectPath($project_id, 'deploy_tokens'), (null !== $active) ? ['active' => $active] : []); } /** + * @see https://docs.gitlab.com/api/deploy_tokens/#create-a-project-deploy-token + * * @param array $parameters { * * @var string $name the name of the deploy token @@ -710,17 +847,25 @@ public function createDeployToken(int|string $project_id, array $parameters = [] return $this->post($this->getProjectPath($project_id, 'deploy_tokens'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/deploy_tokens/#delete-a-project-deploy-token + */ public function deleteDeployToken(int|string $project_id, int $token_id): mixed { return $this->delete($this->getProjectPath($project_id, 'deploy_tokens/'.self::encodePath($token_id))); } + /** + * @see https://docs.gitlab.com/api/project_push_rules/#retrieve-the-push-rules-of-a-project + */ public function pushRule(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'push_rule')); } /** + * @see https://docs.gitlab.com/api/project_push_rules/#add-push-rules-to-a-project + * * @param array $parameters { * * @var string $author_email_regex all commit author emails must match this regular expression @@ -747,6 +892,8 @@ public function createPushRule(int|string $project_id, array $parameters = []): } /** + * @see https://docs.gitlab.com/api/project_push_rules/#update-push-rules-of-a-project + * * @param array $parameters { * * @var string $author_email_regex all commit author emails must match this regular expression @@ -772,12 +919,17 @@ public function updatePushRule(int|string $project_id, array $parameters = []): return $this->put($this->getProjectPath($project_id, 'push_rule'), self::createPushRuleOptionsResolver()->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_push_rules/#delete-the-push-rules-of-a-project + */ public function deletePushRule(int|string $project_id): mixed { return $this->delete($this->getProjectPath($project_id, 'push_rule')); } /** + * @see https://docs.gitlab.com/api/events/#list-all-visible-events-for-a-project + * * @param array $parameters { * * @var string $action include only events of a particular action type @@ -815,6 +967,8 @@ public function events(int|string $project_id, array $parameters = []): mixed } /** + * @see https://docs.gitlab.com/api/labels/#list-all-project-labels + * * @param array $parameters { * * @var bool $with_counts Whether or not to include issue and merge request counts. Defaults to false. @@ -838,16 +992,25 @@ public function labels(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'labels'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/labels/#create-a-project-label + */ public function addLabel(int|string $project_id, array $parameters): mixed { return $this->post($this->getProjectPath($project_id, 'labels'), $parameters); } + /** + * @see https://docs.gitlab.com/api/labels/#update-a-project-label + */ public function updateLabel(int|string $project_id, int $label_id, array $parameters): mixed { return $this->put($this->getProjectPath($project_id, 'labels/'.self::encodePath($label_id)), $parameters); } + /** + * @see https://docs.gitlab.com/api/labels/#delete-a-project-label + */ public function removeLabel(int|string $project_id, int $label_id): mixed { return $this->delete($this->getProjectPath($project_id, 'labels/'.self::encodePath($label_id))); @@ -855,6 +1018,8 @@ public function removeLabel(int|string $project_id, int $label_id): mixed /** * Get languages used in a project with percentage value. + * + * @see https://docs.gitlab.com/api/projects/#retrieve-programming-language-usage-information */ public function languages(int|string $project_id): mixed { @@ -862,6 +1027,8 @@ public function languages(int|string $project_id): mixed } /** + * @see https://docs.gitlab.com/api/project_forks/#list-all-forks-of-a-project + * * @param array $parameters { * * @var bool $archived Limit by archived status @@ -959,6 +1126,8 @@ public function forks(int|string $project_id, array $parameters = []): mixed } /** + * @see https://docs.gitlab.com/api/project_forks/#create-a-fork-of-a-project + * * @param array $parameters { * * @var string $branches Branches to fork (empty for all branches) @@ -1009,26 +1178,41 @@ public function fork(int|string $project_id, array $parameters = []): mixed return $this->post($this->getProjectPath($project_id, 'fork'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_forks/#create-a-fork-relationship + */ public function createForkRelation(int|string $project_id, int|string $forked_project_id): mixed { return $this->post($this->getProjectPath($project_id, 'fork/'.self::encodePath($forked_project_id))); } + /** + * @see https://docs.gitlab.com/api/project_forks/#delete-a-fork-relationship + */ public function removeForkRelation(int|string $project_id): mixed { return $this->delete($this->getProjectPath($project_id, 'fork')); } + /** + * @see https://docs.gitlab.com/api/project_integrations/ + */ public function setService(int|string $project_id, string $service_name, array $parameters = []): mixed { return $this->put($this->getProjectPath($project_id, 'services/'.self::encodePath($service_name)), $parameters); } + /** + * @see https://docs.gitlab.com/api/project_integrations/ + */ public function removeService(int|string $project_id, string $service_name): mixed { return $this->delete($this->getProjectPath($project_id, 'services/'.self::encodePath($service_name))); } + /** + * @see https://docs.gitlab.com/api/project_level_variables/#list-project-variables + */ public function variables(int|string $project_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -1036,6 +1220,9 @@ public function variables(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'variables'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_level_variables/#retrieve-a-single-variable + */ public function variable(int|string $project_id, string $key, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -1046,6 +1233,8 @@ public function variable(int|string $project_id, string $key, array $parameters } /** + * @see https://docs.gitlab.com/api/project_level_variables/#create-a-variable + * * @param array $parameters { * * @var string $variable_type env_var (default) or file @@ -1072,6 +1261,8 @@ public function addVariable(int|string $project_id, string $key, string $value, } /** + * @see https://docs.gitlab.com/api/project_level_variables/#update-a-variable + * * @param array $parameters { * * @var string $variable_type env_var (default) or file @@ -1097,6 +1288,8 @@ public function updateVariable(int|string $project_id, string $key, string $valu } /** + * @see https://docs.gitlab.com/api/project_level_variables/#delete-a-variable + * * @param array $parameters { * * @var array $filter { @@ -1113,18 +1306,24 @@ public function removeVariable(int|string $project_id, string $key, array $param return $this->delete($this->getProjectPath($project_id, 'variables/'.self::encodePath($key)), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_markdown_uploads/#create-an-upload + */ public function uploadFile(int|string $project_id, string $file): mixed { return $this->post($this->getProjectPath($project_id, 'uploads'), [], [], ['file' => $file]); } + /** + * @see https://docs.gitlab.com/api/projects/#upload-a-project-avatar + */ public function uploadAvatar(int|string $project_id, string $file): mixed { return $this->put('projects/'.self::encodePath($project_id), [], [], ['avatar' => $file]); } /** - * @see https://docs.gitlab.com/ee/api/deployments.html#list-project-deployments + * @see https://docs.gitlab.com/api/deployments/#list-all-project-deployments */ public function deployments(int|string $project_id, array $parameters = []): mixed { @@ -1176,11 +1375,17 @@ public function deployments(int|string $project_id, array $parameters = []): mix return $this->get($this->getProjectPath($project_id, 'deployments'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/deployments/#retrieve-a-deployment + */ public function deployment(int|string $project_id, int $deployment_id): mixed { return $this->get($this->getProjectPath($project_id, 'deployments/'.self::encodePath($deployment_id))); } + /** + * @see https://docs.gitlab.com/api/projects/#share-a-project-with-a-group + */ public function addShare(int|string $project_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -1204,92 +1409,145 @@ public function addShare(int|string $project_id, array $parameters = []): mixed return $this->post($this->getProjectPath($project_id, 'share'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/projects/#delete-a-shared-project-link-in-a-group + */ public function removeShare(int|string $project_id, int|string $group_id): mixed { return $this->delete($this->getProjectPath($project_id, 'share/'.$group_id)); } + /** + * @see https://docs.gitlab.com/api/project_badges/#list-all-badges-of-a-project + */ public function badges(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'badges')); } + /** + * @see https://docs.gitlab.com/api/project_badges/#retrieve-a-badge-of-a-project + */ public function badge(int|string $project_id, int $badge_id): mixed { return $this->get($this->getProjectPath($project_id, 'badges/'.self::encodePath($badge_id))); } + /** + * @see https://docs.gitlab.com/api/project_badges/#create-a-badge-for-a-project + */ public function addBadge(int|string $project_id, array $parameters = []): mixed { return $this->post($this->getProjectPath($project_id, 'badges'), $parameters); } + /** + * @see https://docs.gitlab.com/api/project_badges/#delete-a-badge-from-a-project + */ public function removeBadge(int|string $project_id, int $badge_id): mixed { return $this->delete($this->getProjectPath($project_id, 'badges/'.self::encodePath($badge_id))); } + /** + * @see https://docs.gitlab.com/api/project_badges/#update-a-badge-of-a-project + */ public function updateBadge(int|string $project_id, int $badge_id, array $parameters = []): mixed { return $this->put($this->getProjectPath($project_id, 'badges/'.self::encodePath($badge_id)), $parameters); } + /** + * @see https://docs.gitlab.com/api/protected_branches/#list-protected-branches + */ public function protectedBranches(int|string $project_id, array $parameters = []): mixed { return $this->get('projects/'.self::encodePath($project_id).'/protected_branches'); } + /** + * @see https://docs.gitlab.com/api/protected_branches/#protect-repository-branches + */ public function addProtectedBranch(int|string $project_id, array $parameters = []): mixed { return $this->post($this->getProjectPath($project_id, 'protected_branches'), $parameters); } + /** + * @see https://docs.gitlab.com/api/protected_branches/#unprotect-repository-branches + */ public function deleteProtectedBranch(int|string $project_id, string $branch_name): mixed { return $this->delete($this->getProjectPath($project_id, 'protected_branches/'.self::encodePath($branch_name))); } + /** + * @see https://docs.gitlab.com/api/protected_branches/#update-a-protected-branch + */ public function updateProtectedBranch(int|string $project_id, string $branch_name, array $parameters = []): mixed { return $this->patch($this->getProjectPath($project_id, 'protected_branches/'.self::encodePath($branch_name)), $parameters); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#retrieve-approval-configuration-for-a-project + */ public function approvalsConfiguration(int|string $project_id): mixed { return $this->get('projects/'.self::encodePath($project_id).'/approvals'); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#update-approval-configuration-for-a-project + */ public function updateApprovalsConfiguration(int|string $project_id, array $parameters = []): mixed { return $this->post('projects/'.self::encodePath($project_id).'/approvals', $parameters); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#list-all-approval-rules-for-a-project + */ public function approvalsRules(int|string $project_id): mixed { return $this->get('projects/'.self::encodePath($project_id).'/approval_rules'); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#create-an-approval-rule-for-a-project + */ public function createApprovalsRule(int|string $project_id, array $parameters = []): mixed { return $this->post('projects/'.self::encodePath($project_id).'/approval_rules/', $parameters); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#update-an-approval-rule-for-a-project + */ public function updateApprovalsRule(int|string $project_id, int $approval_rule_id, array $parameters = []): mixed { return $this->put('projects/'.self::encodePath($project_id).'/approval_rules/'.self::encodePath($approval_rule_id), $parameters); } + /** + * @see https://docs.gitlab.com/api/merge_request_approvals/#delete-an-approval-rule-for-a-project + */ public function deleteApprovalsRule(int|string $project_id, int $approval_rule_id): mixed { return $this->delete('projects/'.self::encodePath($project_id).'/approval_rules/'.self::encodePath($approval_rule_id)); } + /** + * @see https://docs.gitlab.com/api/branches/#delete-all-merged-branches + */ public function deleteAllMergedBranches(int|string $project_id): mixed { return $this->delete($this->getProjectPath($project_id, 'repository/merged_branches')); } /** + * @see https://docs.gitlab.com/api/project_access_tokens/#list-all-project-access-tokens + * * @param array $parameters { * * @var string $search search text @@ -1358,12 +1616,17 @@ public function projectAccessTokens(int|string $project_id, array $parameters = return $this->get($this->getProjectPath($project_id, 'access_tokens'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_access_tokens/#retrieve-details-on-a-project-access-token + */ public function projectAccessToken(int|string $project_id, int|string $token_id): mixed { return $this->get($this->getProjectPath($project_id, 'access_tokens/'.self::encodePath($token_id))); } /** + * @see https://docs.gitlab.com/api/project_access_tokens/#create-a-project-access-token + * * @param array $parameters { * * @var string $name the name of the project access token @@ -1412,6 +1675,8 @@ public function createProjectAccessToken(int|string $project_id, array $paramete } /** + * @see https://docs.gitlab.com/api/project_access_tokens/#rotate-a-project-access-token + * * @param array $parameters { * * @var \DateTimeInterface $expires_at expiration date of the access token @@ -1431,26 +1696,41 @@ public function rotateProjectAccessToken(int|string $project_id, int|string $tok return $this->post($this->getProjectPath($project_id, 'access_tokens/'.self::encodePath($token_id).'/rotate'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/project_access_tokens/#revoke-a-project-access-token + */ public function deleteProjectAccessToken(int|string $project_id, int|string $token_id): mixed { return $this->delete($this->getProjectPath($project_id, 'access_tokens/'.$token_id)); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#retrieve-the-cicd-job-token-access-settings-for-a-project + */ public function jobTokenScope(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'job_token_scope')); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#update-the-cicd-job-token-access-settings-for-a-project + */ public function updateJobTokenScope(int|string $project_id, bool $enabled): mixed { return $this->patch($this->getProjectPath($project_id, 'job_token_scope'), ['enabled' => $enabled]); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#list-all-projects-in-a-cicd-job-token-allowlist + */ public function jobTokenScopeAllowlistProjects(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'job_token_scope/allowlist')); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#add-a-project-to-a-cicd-job-token-allowlist + */ public function addJobTokenScopeAllowlistProject(int|string $project_id, int $target_project_id): mixed { return $this->post( @@ -1459,16 +1739,25 @@ public function addJobTokenScopeAllowlistProject(int|string $project_id, int $ta ); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#delete-a-project-from-a-cicd-job-token-allowlist + */ public function removeJobTokenScopeAllowlistProject(int|string $project_id, int $target_project_id): mixed { return $this->delete($this->getProjectPath($project_id, 'job_token_scope/allowlist/'.self::encodePath($target_project_id))); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#list-all-groups-in-a-cicd-job-token-allowlist + */ public function jobTokenScopeAllowlistGroups(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'job_token_scope/groups_allowlist')); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#add-a-group-to-a-cicd-job-token-allowlist + */ public function addJobTokenScopeAllowlistGroup(int|string $project_id, int $target_group_id): mixed { return $this->post( @@ -1477,12 +1766,17 @@ public function addJobTokenScopeAllowlistGroup(int|string $project_id, int $targ ); } + /** + * @see https://docs.gitlab.com/api/project_job_token_scopes/#delete-a-group-from-a-cicd-job-token-allowlist + */ public function removeJobTokenScopeAllowlistGroup(int|string $project_id, int $target_group_id): mixed { return $this->delete($this->getProjectPath($project_id, 'job_token_scope/groups_allowlist/'.self::encodePath($target_group_id))); } /** + * @see https://docs.gitlab.com/api/container_registry/#within-a-project + * * @param array $parameters { * * @var bool $tags include an array of tags in each repository @@ -1508,16 +1802,25 @@ public function registryRepositories(int|string $project_id, array $parameters = return $this->get($this->getProjectPath($project_id, 'registry/repositories'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/protected_tags/#list-protected-tags + */ public function protectedTags(int|string $project_id): mixed { return $this->get('projects/'.self::encodePath($project_id).'/protected_tags'); } + /** + * @see https://docs.gitlab.com/api/protected_tags/#get-a-protected-tag-or-wildcard-protected-tag + */ public function protectedTag(int|string $project_id, string $tag_name): mixed { return $this->get('projects/'.self::encodePath($project_id).'/protected_tags/'.self::encodePath($tag_name)); } + /** + * @see https://docs.gitlab.com/api/protected_tags/#protect-a-repository-tag + */ public function addProtectedTag(int|string $project_id, array $parameters = []): mixed { $resolver = new OptionsResolver(); @@ -1546,27 +1849,41 @@ public function addProtectedTag(int|string $project_id, array $parameters = []): return $this->post($this->getProjectPath($project_id, 'protected_tags'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/protected_tags/#unprotect-repository-tags + */ public function deleteProtectedTag(int|string $project_id, string $tag_name): mixed { return $this->delete($this->getProjectPath($project_id, 'protected_tags/'.self::encodePath($tag_name))); } + /** + * @see https://docs.gitlab.com/api/remote_mirrors/#list-all-remote-mirrors-for-a-project + */ public function remoteMirrors(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'remote_mirrors')); } + /** + * @see https://docs.gitlab.com/api/remote_mirrors/#retrieve-a-remote-mirror-for-a-project + */ public function remoteMirror(int|string $project_id, int $mirror_id): mixed { return $this->get($this->getProjectPath($project_id, 'remote_mirrors/'.self::encodePath($mirror_id))); } + /** + * @see https://docs.gitlab.com/api/remote_mirrors/#retrieve-a-public-key-for-a-remote-mirror + */ public function remoteMirrorPublicKey(int|string $project_id, int $mirror_id): mixed { return $this->get($this->getProjectPath($project_id, 'remote_mirrors/'.self::encodePath($mirror_id).'/public_key')); } /** + * @see https://docs.gitlab.com/api/search/#search-a-project + * * @param array $parameters { * * @var string $scope The scope to search in diff --git a/src/Api/Registry.php b/src/Api/Registry.php index 89232330..b5a54b63 100644 --- a/src/Api/Registry.php +++ b/src/Api/Registry.php @@ -20,6 +20,8 @@ class Registry extends AbstractApi { /** + * @see https://docs.gitlab.com/api/container_registry/#retrieve-details-of-a-single-repository + * * @param array $parameters { * * @var bool $tags include an array of tags in the response @@ -34,16 +36,25 @@ public function repository(int|string $repository_id, array $parameters = []): m return $this->get('registry/repositories/'.self::encodePath($repository_id), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/container_registry/#delete-registry-repository + */ public function removeRepository(int|string $project_id, int $repository_id): mixed { return $this->delete($this->getProjectPath($project_id, 'registry/repositories/'.self::encodePath($repository_id))); } + /** + * @see https://docs.gitlab.com/api/container_registry/#list-all-registry-repository-tags + */ public function repositoryTags(int|string $project_id, int $repository_id): mixed { return $this->get($this->getProjectPath($project_id, 'registry/repositories/'.self::encodePath($repository_id).'/tags')); } + /** + * @see https://docs.gitlab.com/api/container_registry/#retrieve-details-of-a-registry-repository-tag + */ public function repositoryTag(int|string $project_id, int $repository_id, string $tag_name): mixed { return $this->get($this->getProjectPath( @@ -52,6 +63,9 @@ public function repositoryTag(int|string $project_id, int $repository_id, string )); } + /** + * @see https://docs.gitlab.com/api/container_registry/#delete-a-registry-repository-tag + */ public function removeRepositoryTag(int|string $project_id, int $repository_id, string $tag_name): mixed { return $this->delete($this->getProjectPath( @@ -61,6 +75,8 @@ public function removeRepositoryTag(int|string $project_id, int $repository_id, } /** + * @see https://docs.gitlab.com/api/container_registry/#delete-registry-repository-tags-in-bulk + * * @param array $parameters { * * @var string $name_regex_delete regex of tag names to delete diff --git a/src/Api/Repositories.php b/src/Api/Repositories.php index fe5ddefd..0cdf4c68 100644 --- a/src/Api/Repositories.php +++ b/src/Api/Repositories.php @@ -30,6 +30,8 @@ class Repositories extends AbstractApi public const TYPE_TAG = 'tag'; /** + * @see https://docs.gitlab.com/api/branches/#list-all-repository-branches + * * @param array $parameters { * * @var string $search return branches matching the search string @@ -54,11 +56,17 @@ public function branches(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'repository/branches'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/branches/#retrieve-a-repository-branch + */ public function branch(int|string $project_id, string $branch): mixed { return $this->get($this->getProjectPath($project_id, 'repository/branches/'.self::encodePath($branch))); } + /** + * @see https://docs.gitlab.com/api/branches/#create-repository-branch + */ public function createBranch(int|string $project_id, string $branch, string $ref): mixed { return $this->post($this->getProjectPath($project_id, 'repository/branches'), [ @@ -67,11 +75,17 @@ public function createBranch(int|string $project_id, string $branch, string $ref ]); } + /** + * @see https://docs.gitlab.com/api/branches/#delete-repository-branch + */ public function deleteBranch(int|string $project_id, string $branch): mixed { return $this->delete($this->getProjectPath($project_id, 'repository/branches/'.self::encodePath($branch))); } + /** + * @see https://docs.gitlab.com/api/branches/#protect-repository-branch + */ public function protectBranch(int|string $project_id, string $branch, bool $devPush = false, bool $devMerge = false): mixed { return $this->put($this->getProjectPath($project_id, 'repository/branches/'.self::encodePath($branch).'/protect'), [ @@ -80,11 +94,17 @@ public function protectBranch(int|string $project_id, string $branch, bool $devP ]); } + /** + * @see https://docs.gitlab.com/api/branches/#unprotect-repository-branch + */ public function unprotectBranch(int|string $project_id, string $branch): mixed { return $this->put($this->getProjectPath($project_id, 'repository/branches/'.self::encodePath($branch).'/unprotect')); } + /** + * @see https://docs.gitlab.com/api/tags/#list-all-project-repository-tags + */ public function tags(int|string $project_id, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -94,6 +114,9 @@ public function tags(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'repository/tags'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/tags/#create-a-new-tag + */ public function createTag(int|string $project_id, string $name, string $ref, ?string $message = null): mixed { return $this->post($this->getProjectPath($project_id, 'repository/tags'), [ @@ -103,6 +126,9 @@ public function createTag(int|string $project_id, string $name, string $ref, ?st ]); } + /** + * @see https://docs.gitlab.com/api/releases/#create-a-release + */ public function createRelease(int|string $project_id, string $tag_name, string $description, ?string $name = null): mixed { return $this->post($this->getProjectPath($project_id, 'releases'), \array_filter([ @@ -113,6 +139,9 @@ public function createRelease(int|string $project_id, string $tag_name, string $ ], fn ($v) => null !== $v)); } + /** + * @see https://docs.gitlab.com/api/releases/#update-a-release + */ public function updateRelease(int|string $project_id, string $tag_name, string $description, ?string $name = null): mixed { return $this->put($this->getProjectPath($project_id, 'releases/'.self::encodePath($tag_name)), \array_filter([ @@ -123,6 +152,9 @@ public function updateRelease(int|string $project_id, string $tag_name, string $ ], fn ($v) => null !== $v)); } + /** + * @see https://docs.gitlab.com/api/releases/#list-releases + */ public function releases(int|string $project_id): mixed { $resolver = $this->createOptionsResolver(); @@ -131,7 +163,7 @@ public function releases(int|string $project_id): mixed } /** - * @see https://docs.gitlab.com/ee/api/commits.html#list-repository-commits + * @see https://docs.gitlab.com/api/commits/#list-repository-commits * * @param array $parameters { * @@ -180,11 +212,17 @@ public function commits(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'repository/commits'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/commits/#retrieve-a-commit + */ public function commit(int|string $project_id, string $sha): mixed { return $this->get($this->getProjectPath($project_id, 'repository/commits/'.self::encodePath($sha))); } + /** + * @see https://docs.gitlab.com/api/commits/#list-all-references-a-commit-is-pushed-to + */ public function commitRefs(int|string $project_id, string $sha, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -196,6 +234,8 @@ public function commitRefs(int|string $project_id, string $sha, array $parameter } /** + * @see https://docs.gitlab.com/api/commits/#list-merge-requests-associated-with-a-commit + * * @param array $parameters { * * @var string $state Returns merge requests with the specified state: opened, closed, locked, or merged. @@ -215,6 +255,8 @@ public function commitMergeRequests(int|string $project_id, string $sha, array $ } /** + * @see https://docs.gitlab.com/api/commits/#create-a-commit + * * @param array $parameters { * * @var string $branch Name of the branch to commit into. To create a new branch, also provide start_branch. @@ -279,6 +321,9 @@ public function createCommit(int|string $project_id, array $parameters = []): mi return $this->post($this->getProjectPath($project_id, 'repository/commits'), $resolver->resolve($parameters)); } + /** + * @see https://docs.gitlab.com/api/commits/#revert-a-commit + */ public function revertCommit(int|string $project_id, string $branch, string $sha): mixed { return $this->post($this->getProjectPath($project_id, 'repository/commits/'.self::encodePath($sha).'/revert'), [ @@ -286,6 +331,9 @@ public function revertCommit(int|string $project_id, string $branch, string $sha ]); } + /** + * @see https://docs.gitlab.com/api/commits/#list-all-commit-comments + */ public function commitComments(int|string $project_id, string $sha, array $parameters = []): mixed { $resolver = $this->createOptionsResolver(); @@ -296,6 +344,9 @@ public function commitComments(int|string $project_id, string $sha, array $param ); } + /** + * @see https://docs.gitlab.com/api/commits/#post-comment-to-commit + */ public function createCommitComment(int|string $project_id, string $sha, string $note, array $params = []): mixed { $params['note'] = $note; @@ -303,11 +354,17 @@ public function createCommitComment(int|string $project_id, string $sha, string return $this->post($this->getProjectPath($project_id, 'repository/commits/'.self::encodePath($sha).'/comments'), $params); } + /** + * @see https://docs.gitlab.com/api/commits/#list-commit-statuses + */ public function getCommitBuildStatus(int|string $project_id, string $sha, array $params = []): mixed { return $this->get($this->getProjectPath($project_id, 'repository/commits/'.self::encodePath($sha).'/statuses'), $params); } + /** + * @see https://docs.gitlab.com/api/commits/#set-commit-pipeline-status + */ public function postCommitBuildStatus(int|string $project_id, string $sha, string $state, array $params = []): mixed { $params['state'] = $state; @@ -315,6 +372,9 @@ public function postCommitBuildStatus(int|string $project_id, string $sha, strin return $this->post($this->getProjectPath($project_id, 'statuses/'.self::encodePath($sha)), $params); } + /** + * @see https://docs.gitlab.com/api/repositories/#compare-branches-tags-or-commits + */ public function compare(int|string $project_id, string $fromShaOrMaster, string $toShaOrMaster, bool $straight = false, ?string $fromProjectId = null): mixed { $params = [ @@ -330,22 +390,33 @@ public function compare(int|string $project_id, string $fromShaOrMaster, string return $this->get($this->getProjectPath($project_id, 'repository/compare'), $params); } + /** + * @see https://docs.gitlab.com/api/commits/#retrieve-commit-diff + */ public function diff(int|string $project_id, string $sha): mixed { return $this->get($this->getProjectPath($project_id, 'repository/commits/'.self::encodePath($sha).'/diff')); } + /** + * @see https://docs.gitlab.com/api/repositories/#list-all-repository-trees-in-a-project + */ public function tree(int|string $project_id, array $params = []): mixed { return $this->get($this->getProjectPath($project_id, 'repository/tree'), $params); } + /** + * @see https://docs.gitlab.com/api/repositories/#get-contributor-list + */ public function contributors(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'repository/contributors')); } /** + * @see https://docs.gitlab.com/api/repositories/#retrieve-file-archive-from-a-repository + * * @param string $format Options: "tar.gz", "zip", "tar.bz2" and "tar" */ public function archive(int|string $project_id, array $params = [], string $format = 'tar.gz'): mixed @@ -353,11 +424,17 @@ public function archive(int|string $project_id, array $params = [], string $form return $this->get($this->getProjectPath($project_id, 'repository/archive.'.$format), $params); } + /** + * @see https://docs.gitlab.com/api/repositories/#get-merge-base + */ public function mergeBase(int|string $project_id, array $refs): mixed { return $this->get($this->getProjectPath($project_id, 'repository/merge_base'), ['refs' => $refs]); } + /** + * @see https://docs.gitlab.com/api/commits/#cherry-pick-a-commit + */ public function cherryPick(int|string $project_id, string $sha, array $params = []): mixed { $resolver = $this->createOptionsResolver(); diff --git a/src/Api/RepositoryFiles.php b/src/Api/RepositoryFiles.php index 80f303ad..ed158dd8 100644 --- a/src/Api/RepositoryFiles.php +++ b/src/Api/RepositoryFiles.php @@ -18,6 +18,9 @@ class RepositoryFiles extends AbstractApi { + /** + * @see https://docs.gitlab.com/api/repository_files/#retrieve-a-file-from-a-repository + */ public function getFile(int|string $project_id, string $file_path, string $ref): mixed { return $this->get($this->getProjectPath($project_id, 'repository/files/'.self::encodePath($file_path)), [ @@ -25,6 +28,9 @@ public function getFile(int|string $project_id, string $file_path, string $ref): ]); } + /** + * @see https://docs.gitlab.com/api/repository_files/#retrieve-a-raw-file-from-a-repository + */ public function getRawFile(int|string $project_id, string $file_path, string $ref): mixed { return $this->get($this->getProjectPath($project_id, 'repository/files/'.self::encodePath($file_path).'/raw'), [ @@ -33,6 +39,8 @@ public function getRawFile(int|string $project_id, string $file_path, string $re } /** + * @see https://docs.gitlab.com/api/repository_files/#create-a-file-in-a-repository + * * @param array $parameters { * * @var string $file_path Url encoded full path to new file. Ex. lib%2Fclass%2Erb. @@ -65,6 +73,8 @@ public function createFile(int|string $project_id, array $parameters = []): mixe } /** + * @see https://docs.gitlab.com/api/repository_files/#update-a-file-in-a-repository + * * @param array $parameters { * * @var string $file_path Url encoded full path to new file. Ex. lib%2Fclass%2Erb. @@ -99,6 +109,8 @@ public function updateFile(int|string $project_id, array $parameters = []): mixe } /** + * @see https://docs.gitlab.com/api/repository_files/#delete-a-file-in-a-repository + * * @param array $parameters { * * @var string $file_path Url encoded full path to new file. Ex. lib%2Fclass%2Erb. diff --git a/src/Api/ResourceIterationEvents.php b/src/Api/ResourceIterationEvents.php index f18edb75..2e90f05b 100644 --- a/src/Api/ResourceIterationEvents.php +++ b/src/Api/ResourceIterationEvents.php @@ -16,6 +16,11 @@ class ResourceIterationEvents extends AbstractApi { + /** + * List project issue iteration events. + * + * @see https://docs.gitlab.com/api/resource_iteration_events/#list-project-issue-iteration-events + */ public function all(int|string $project_id, int $issue_iid): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_iteration_events'; @@ -23,6 +28,11 @@ public function all(int|string $project_id, int $issue_iid): mixed return $this->get($this->getProjectPath($project_id, $path)); } + /** + * Retrieve a single issue iteration event. + * + * @see https://docs.gitlab.com/api/resource_iteration_events/#retrieve-an-issue-iteration-event + */ public function show(int|string $project_id, int $issue_iid, int $resource_iteration_event_id): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_iteration_events/'; diff --git a/src/Api/ResourceLabelEvents.php b/src/Api/ResourceLabelEvents.php index 9ccf6567..72fcc90e 100644 --- a/src/Api/ResourceLabelEvents.php +++ b/src/Api/ResourceLabelEvents.php @@ -16,6 +16,11 @@ class ResourceLabelEvents extends AbstractApi { + /** + * List project issue label events. + * + * @see https://docs.gitlab.com/api/resource_label_events/#list-project-issue-label-events + */ public function all(int|string $project_id, int $issue_iid): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_label_events'; @@ -23,6 +28,11 @@ public function all(int|string $project_id, int $issue_iid): mixed return $this->get($this->getProjectPath($project_id, $path)); } + /** + * Retrieve a single issue label event. + * + * @see https://docs.gitlab.com/api/resource_label_events/#retrieve-a-single-issue-label-event + */ public function show(int|string $project_id, int $issue_iid, int $resource_label_event_id): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_label_events/'; diff --git a/src/Api/ResourceMilestoneEvents.php b/src/Api/ResourceMilestoneEvents.php index be4adb47..f251831f 100644 --- a/src/Api/ResourceMilestoneEvents.php +++ b/src/Api/ResourceMilestoneEvents.php @@ -16,6 +16,11 @@ class ResourceMilestoneEvents extends AbstractApi { + /** + * List project issue milestone events. + * + * @see https://docs.gitlab.com/api/resource_milestone_events/#list-project-issue-milestone-events + */ public function all(int|string $project_id, int $issue_iid): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_milestone_events'; @@ -23,6 +28,11 @@ public function all(int|string $project_id, int $issue_iid): mixed return $this->get($this->getProjectPath($project_id, $path)); } + /** + * Retrieve a single issue milestone event. + * + * @see https://docs.gitlab.com/api/resource_milestone_events/#retrieve-a-single-issue-milestone-event + */ public function show(int|string $project_id, int $issue_iid, int $resource_milestone_event_id): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_milestone_events/'; diff --git a/src/Api/ResourceStateEvents.php b/src/Api/ResourceStateEvents.php index be03a6d5..e4b76ad7 100644 --- a/src/Api/ResourceStateEvents.php +++ b/src/Api/ResourceStateEvents.php @@ -16,6 +16,11 @@ class ResourceStateEvents extends AbstractApi { + /** + * List project issue state events. + * + * @see https://docs.gitlab.com/api/resource_state_events/#list-project-issue-state-events + */ public function all(int|string $project_id, int $issue_iid): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_state_events'; @@ -23,6 +28,11 @@ public function all(int|string $project_id, int $issue_iid): mixed return $this->get($this->getProjectPath($project_id, $path)); } + /** + * Retrieve a single issue state event. + * + * @see https://docs.gitlab.com/api/resource_state_events/#retrieve-a-single-issue-state-event + */ public function show(int|string $project_id, int $issue_iid, int $resource_label_event_id): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_state_events/'; diff --git a/src/Api/ResourceWeightEvents.php b/src/Api/ResourceWeightEvents.php index 53a7b162..7c05baba 100644 --- a/src/Api/ResourceWeightEvents.php +++ b/src/Api/ResourceWeightEvents.php @@ -16,6 +16,11 @@ class ResourceWeightEvents extends AbstractApi { + /** + * List all project issue weight events. + * + * @see https://docs.gitlab.com/api/resource_weight_events/#list-all-project-issue-weight-events + */ public function all(int|string $project_id, int $issue_iid): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_weight_events'; @@ -23,6 +28,11 @@ public function all(int|string $project_id, int $issue_iid): mixed return $this->get($this->getProjectPath($project_id, $path)); } + /** + * Retrieve single issue weight event. + * + * @see https://docs.gitlab.com/api/resource_weight_events/#retrieve-single-issue-weight-event + */ public function show(int|string $project_id, int $issue_iid, int $resource_label_event_id): mixed { $path = 'issues/'.self::encodePath($issue_iid).'/resource_weight_events/'; diff --git a/src/Api/Schedules.php b/src/Api/Schedules.php index 44b61964..bcac9ce9 100644 --- a/src/Api/Schedules.php +++ b/src/Api/Schedules.php @@ -16,31 +16,61 @@ class Schedules extends AbstractApi { + /** + * Create a new pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#create-a-new-pipeline-schedule + */ public function create(int|string $project_id, array $params): mixed { return $this->post($this->getProjectPath($project_id, 'pipeline_schedules'), $params); } + /** + * Retrieve a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#retrieve-a-pipeline-schedule + */ public function show(int|string $project_id, int $schedule_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipeline_schedules/'.self::encodePath($schedule_id))); } + /** + * List all pipeline schedules. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#list-all-pipeline-schedules + */ public function showAll(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'pipeline_schedules')); } + /** + * Update a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#update-a-pipeline-schedule + */ public function update(int|string $project_id, int $schedule_id, array $params): mixed { return $this->put($this->getProjectPath($project_id, 'pipeline_schedules/'.self::encodePath($schedule_id)), $params); } + /** + * Delete a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#delete-a-pipeline-schedule + */ public function remove(int|string $project_id, int $schedule_id): mixed { return $this->delete($this->getProjectPath($project_id, 'pipeline_schedules/'.self::encodePath($schedule_id))); } + /** + * Create a variable for a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#create-a-variable-for-a-pipeline-schedule + */ public function addVariable(int|string $project_id, int $schedule_id, array $params): mixed { $path = 'pipeline_schedules/'.self::encodePath($schedule_id).'/variables'; @@ -48,6 +78,11 @@ public function addVariable(int|string $project_id, int $schedule_id, array $par return $this->post($this->getProjectPath($project_id, $path), $params); } + /** + * Update a variable for a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#update-a-variable-for-a-pipeline-schedule + */ public function updateVariable(int|string $project_id, int $schedule_id, string $variable_key, array $params): mixed { $path = 'pipeline_schedules/'.self::encodePath($schedule_id).'/variables/'.self::encodePath($variable_key); @@ -55,6 +90,11 @@ public function updateVariable(int|string $project_id, int $schedule_id, string return $this->put($this->getProjectPath($project_id, $path), $params); } + /** + * Delete a variable for a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#delete-a-variable-for-a-pipeline-schedule + */ public function removeVariable(int|string $project_id, int $schedule_id, string $variable_key): mixed { $path = 'pipeline_schedules/'.self::encodePath($schedule_id).'/variables/'.self::encodePath($variable_key); @@ -62,11 +102,21 @@ public function removeVariable(int|string $project_id, int $schedule_id, string return $this->delete($this->getProjectPath($project_id, $path)); } + /** + * Update ownership of a pipeline schedule. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#update-ownership-of-a-pipeline-schedule + */ public function takeOwnership(int|string $project_id, int $schedule_id): mixed { return $this->post($this->getProjectPath($project_id, 'pipeline_schedules/'.self::encodePath($schedule_id)).'/take_ownership'); } + /** + * Run a pipeline schedule immediately. + * + * @see https://docs.gitlab.com/api/pipeline_schedules/#run-a-pipeline-schedule-immediately + */ public function play(int|string $project_id, int $schedule_id): mixed { return $this->post($this->getProjectPath($project_id, 'pipeline_schedules/'.self::encodePath($schedule_id)).'/play'); diff --git a/src/Api/Search.php b/src/Api/Search.php index a7685bd6..913c6fe0 100644 --- a/src/Api/Search.php +++ b/src/Api/Search.php @@ -21,6 +21,10 @@ class Search extends AbstractApi { /** + * Search an instance. + * + * @see https://docs.gitlab.com/api/search/#search-an-instance + * * @param array $parameters { * * @var string $scope The scope to search in diff --git a/src/Api/Snippets.php b/src/Api/Snippets.php index d62e174e..1a90dd71 100644 --- a/src/Api/Snippets.php +++ b/src/Api/Snippets.php @@ -16,16 +16,31 @@ class Snippets extends AbstractApi { + /** + * List all snippets for a project. + * + * @see https://docs.gitlab.com/api/project_snippets/#list-all-snippets-for-a-project + */ public function all(int|string $project_id): mixed { return $this->get($this->getProjectPath($project_id, 'snippets')); } + /** + * Retrieve a snippet. + * + * @see https://docs.gitlab.com/api/project_snippets/#retrieve-a-snippet + */ public function show(int|string $project_id, int $snippet_id): mixed { return $this->get($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id))); } + /** + * Create a snippet. + * + * @see https://docs.gitlab.com/api/project_snippets/#create-a-snippet + */ public function create(int|string $project_id, string $title, string $filename, string $code, string $visibility): mixed { return $this->post($this->getProjectPath($project_id, 'snippets'), [ @@ -36,31 +51,61 @@ public function create(int|string $project_id, string $title, string $filename, ]); } + /** + * Update a snippet. + * + * @see https://docs.gitlab.com/api/project_snippets/#update-a-snippet + */ public function update(int|string $project_id, int $snippet_id, array $params): mixed { return $this->put($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id)), $params); } + /** + * Retrieve snippet content. + * + * @see https://docs.gitlab.com/api/project_snippets/#retrieve-snippet-content + */ public function content(int|string $project_id, int $snippet_id): mixed { return $this->get($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/raw')); } + /** + * Delete a snippet. + * + * @see https://docs.gitlab.com/api/project_snippets/#delete-a-snippet + */ public function remove(int|string $project_id, int $snippet_id): mixed { return $this->delete($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id))); } + /** + * List all snippet notes. + * + * @see https://docs.gitlab.com/api/notes/#list-all-snippet-notes + */ public function showNotes(int|string $project_id, int $snippet_id): mixed { return $this->get($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/notes')); } + /** + * Retrieve a snippet note. + * + * @see https://docs.gitlab.com/api/notes/#retrieve-a-snippet-note + */ public function showNote(int|string $project_id, int $snippet_id, int $note_id): mixed { return $this->get($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/notes/'.self::encodePath($note_id))); } + /** + * Create a snippet note. + * + * @see https://docs.gitlab.com/api/notes/#create-a-snippet-note + */ public function addNote(int|string $project_id, int $snippet_id, string $body, array $params = []): mixed { $params['body'] = $body; @@ -68,6 +113,11 @@ public function addNote(int|string $project_id, int $snippet_id, string $body, a return $this->post($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/notes'), $params); } + /** + * Update a snippet note. + * + * @see https://docs.gitlab.com/api/notes/#update-a-snippet-note + */ public function updateNote(int|string $project_id, int $snippet_id, int $note_id, string $body): mixed { return $this->put($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/notes/'.self::encodePath($note_id)), [ @@ -75,16 +125,31 @@ public function updateNote(int|string $project_id, int $snippet_id, int $note_id ]); } + /** + * Delete a snippet note. + * + * @see https://docs.gitlab.com/api/notes/#delete-a-snippet-note + */ public function removeNote(int|string $project_id, int $snippet_id, int $note_id): mixed { return $this->delete($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/notes/'.self::encodePath($note_id))); } + /** + * List all emoji reactions for a snippet. + * + * @see https://docs.gitlab.com/api/emoji_reactions/#list-all-emoji-reactions-for-a-resource + */ public function awardEmoji(int|string $project_id, int $snippet_id): mixed { return $this->get($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/award_emoji')); } + /** + * Delete an emoji reaction from a snippet. + * + * @see https://docs.gitlab.com/api/emoji_reactions/#delete-an-emoji-reaction-from-a-resource + */ public function removeAwardEmoji(int|string $project_id, int $snippet_id, int $award_id): mixed { return $this->delete($this->getProjectPath($project_id, 'snippets/'.self::encodePath($snippet_id).'/award_emoji/'.self::encodePath($award_id))); diff --git a/src/Api/SystemHooks.php b/src/Api/SystemHooks.php index f068429d..bd604c47 100644 --- a/src/Api/SystemHooks.php +++ b/src/Api/SystemHooks.php @@ -19,12 +19,21 @@ class SystemHooks extends AbstractApi { + /** + * List all system hooks. + * + * @see https://docs.gitlab.com/api/system_hooks/#list-all-system-hooks + */ public function all(): mixed { return $this->get('hooks'); } /** + * Add new system hook. + * + * @see https://docs.gitlab.com/api/system_hooks/#add-new-system-hook + * * @param array $parameters { * * @var string $token secret token to validate received payloads @@ -44,11 +53,24 @@ public function create(string $url, array $parameters = []): mixed return $this->post('hooks', $parameters); } + /** + * Retrieve system hook. + * + * Note: despite its name, this performs a GET request, which the current GitLab + * docs document as retrieving the hook configuration (not firing a test event). + * + * @see https://docs.gitlab.com/api/system_hooks/#retrieve-system-hook + */ public function test(int $id): mixed { return $this->get('hooks/'.self::encodePath($id)); } + /** + * Delete system hook. + * + * @see https://docs.gitlab.com/api/system_hooks/#delete-system-hook + */ public function remove(int $id): mixed { return $this->delete('hooks/'.self::encodePath($id)); diff --git a/src/Api/Tags.php b/src/Api/Tags.php index 8085d763..b9d38002 100644 --- a/src/Api/Tags.php +++ b/src/Api/Tags.php @@ -17,6 +17,10 @@ class Tags extends AbstractApi { /** + * List project repository tags. + * + * @see https://docs.gitlab.com/api/tags/#list-all-project-repository-tags + * * @param array $parameters { * * @var string $order_by Return tags ordered by `name`, `updated` or `version` fields. Default is `updated`. @@ -37,26 +41,59 @@ public function all(int|string $project_id, array $parameters = []): mixed return $this->get($this->getProjectPath($project_id, 'repository/tags'), $resolver->resolve($parameters)); } + /** + * Retrieve a single repository tag. + * + * @see https://docs.gitlab.com/api/tags/#retrieve-a-single-repository-tag + */ public function show(int|string $project_id, string $tag_name): mixed { return $this->get($this->getProjectPath($project_id, 'repository/tags/'.self::encodePath($tag_name))); } + /** + * Create a new tag. + * + * @see https://docs.gitlab.com/api/tags/#create-a-new-tag + */ public function create(int|string $project_id, array $params = []): mixed { return $this->post($this->getProjectPath($project_id, 'repository/tags'), $params); } + /** + * Delete a tag. + * + * @see https://docs.gitlab.com/api/tags/#delete-a-tag + */ public function remove(int|string $project_id, string $tag_name): mixed { return $this->delete($this->getProjectPath($project_id, 'repository/tags/'.self::encodePath($tag_name))); } + /** + * Create a release for a tag. + * + * Note: the `POST .../repository/tags/:tag_name/release` endpoint this method calls + * is no longer documented on the current Tags API page; it has been superseded by + * the Releases API. Linked here as the closest current equivalent. + * + * @see https://docs.gitlab.com/api/releases/#create-a-release + */ public function createRelease(int|string $project_id, string $tag_name, array $params = []): mixed { return $this->post($this->getProjectPath($project_id, 'repository/tags/'.self::encodePath($tag_name).'/release'), $params); } + /** + * Update a release for a tag. + * + * Note: the `PUT .../repository/tags/:tag_name/release` endpoint this method calls + * is no longer documented on the current Tags API page; it has been superseded by + * the Releases API. Linked here as the closest current equivalent. + * + * @see https://docs.gitlab.com/api/releases/#update-a-release + */ public function updateRelease(int|string $project_id, string $tag_name, array $params = []): mixed { return $this->put($this->getProjectPath($project_id, 'repository/tags/'.self::encodePath($tag_name).'/release'), $params); diff --git a/src/Api/Users.php b/src/Api/Users.php index e8091361..8630a337 100644 --- a/src/Api/Users.php +++ b/src/Api/Users.php @@ -20,6 +20,10 @@ class Users extends AbstractApi { /** + * List all users. + * + * @see https://docs.gitlab.com/api/users/#list-all-users + * * @param array $parameters { * * @var string $search search for user by email or username @@ -72,12 +76,21 @@ public function all(array $parameters = []): mixed return $this->get('users', $resolver->resolve($parameters)); } + /** + * Retrieve a single user. + * + * @see https://docs.gitlab.com/api/users/#retrieve-a-single-user + */ public function show(int $id): mixed { return $this->get('users/'.self::encodePath($id)); } /** + * List projects and groups that a user is a member of. + * + * @see https://docs.gitlab.com/api/users/#list-projects-and-groups-that-a-user-is-a-member-of + * * @param array $parameters { * * @var string $type Filter memberships by type. Can be either Project or Namespace @@ -94,6 +107,10 @@ public function usersMemberships(int $id, array $parameters = []): mixed } /** + * List all personal projects for a user. + * + * @see https://docs.gitlab.com/api/projects/#list-all-personal-projects-for-a-user + * * @param array $parameters { * * @var bool $archived limit by archived status @@ -168,6 +185,10 @@ public function usersProjects(int $id, array $parameters = []): mixed } /** + * List all projects contributions for a user. + * + * @see https://docs.gitlab.com/api/projects/#list-all-projects-contributions-for-a-user + * * @param array $parameters { * * @var string $order_by return projects ordered by id, name, path, created_at, updated_at, @@ -198,6 +219,10 @@ public function usersContributedProjects(int|string $id, array $parameters = []) } /** + * List projects starred by a user. + * + * @see https://docs.gitlab.com/api/project_starring/#list-projects-starred-by-a-user + * * @param array $parameters { * * @var bool $archived limit by archived status @@ -276,11 +301,21 @@ public function usersStarredProjects(int $id, array $parameters = []): mixed return $this->get('users/'.self::encodePath($id).'/starred_projects', $resolver->resolve($parameters)); } + /** + * Retrieve the current user. + * + * @see https://docs.gitlab.com/api/users/#retrieve-the-current-user + */ public function user(): mixed { return $this->get('user'); } + /** + * Create a user. + * + * @see https://docs.gitlab.com/api/users/#create-a-user + */ public function create(string $email, #[\SensitiveParameter] string $password, array $params = []): mixed { $params['email'] = $email; @@ -289,12 +324,21 @@ public function create(string $email, #[\SensitiveParameter] string $password, a return $this->post('users', $params); } + /** + * Modify a user. + * + * @see https://docs.gitlab.com/api/users/#modify-a-user + */ public function update(int $id, array $params, array $files = []): mixed { return $this->put('users/'.self::encodePath($id), $params, [], $files); } /** + * Delete a user. + * + * @see https://docs.gitlab.com/api/users/#delete-a-user + * * @param array $params { * * @var bool $hard_delete If true, contributions that would usually be moved to the ghost user are @@ -306,41 +350,81 @@ public function remove(int $id, array $params = []): mixed return $this->delete('users/'.self::encodePath($id), $params); } + /** + * Block access to a user. + * + * @see https://docs.gitlab.com/api/user_moderation/#block-access-to-a-user + */ public function block(int $id): mixed { return $this->post('users/'.self::encodePath($id).'/block'); } + /** + * Unblock access to a user. + * + * @see https://docs.gitlab.com/api/user_moderation/#unblock-access-to-a-user + */ public function unblock(int $id): mixed { return $this->post('users/'.self::encodePath($id).'/unblock'); } + /** + * Reactivate a user. + * + * @see https://docs.gitlab.com/api/user_moderation/#reactivate-a-user + */ public function activate(int $id): mixed { return $this->post('users/'.self::encodePath($id).'/activate'); } + /** + * Deactivate a user. + * + * @see https://docs.gitlab.com/api/user_moderation/#deactivate-a-user + */ public function deactivate(int $id): mixed { return $this->post('users/'.self::encodePath($id).'/deactivate'); } + /** + * Retrieve the current user. + * + * @see https://docs.gitlab.com/api/users/#retrieve-the-current-user + */ public function me(): mixed { return $this->get('user'); } + /** + * List all SSH keys. + * + * @see https://docs.gitlab.com/api/user_keys/#list-all-ssh-keys + */ public function keys(): mixed { return $this->get('user/keys'); } + /** + * Retrieve an SSH key. + * + * @see https://docs.gitlab.com/api/user_keys/#retrieve-an-ssh-key + */ public function key(int $id): mixed { return $this->get('user/keys/'.self::encodePath($id)); } + /** + * Add an SSH key. + * + * @see https://docs.gitlab.com/api/user_keys/#add-an-ssh-key + */ public function createKey(string $title, string $key): mixed { return $this->post('user/keys', [ @@ -349,21 +433,41 @@ public function createKey(string $title, string $key): mixed ]); } + /** + * Delete an SSH key. + * + * @see https://docs.gitlab.com/api/user_keys/#delete-an-ssh-key + */ public function removeKey(int $id): mixed { return $this->delete('user/keys/'.self::encodePath($id)); } + /** + * List all SSH keys for a user. + * + * @see https://docs.gitlab.com/api/user_keys/#list-all-ssh-keys-for-a-user + */ public function userKeys(int $user_id): mixed { return $this->get('users/'.self::encodePath($user_id).'/keys'); } + /** + * Retrieve an SSH key for a user. + * + * @see https://docs.gitlab.com/api/user_keys/#retrieve-an-ssh-key-for-a-user + */ public function userKey(int $user_id, int $key_id): mixed { return $this->get('users/'.self::encodePath($user_id).'/keys/'.self::encodePath($key_id)); } + /** + * Add an SSH key for a user. + * + * @see https://docs.gitlab.com/api/user_keys/#add-an-ssh-key-for-a-user + */ public function createKeyForUser(int $user_id, string $title, string $key): mixed { return $this->post('users/'.self::encodePath($user_id).'/keys', [ @@ -372,26 +476,51 @@ public function createKeyForUser(int $user_id, string $title, string $key): mixe ]); } + /** + * Delete an SSH key for a user. + * + * @see https://docs.gitlab.com/api/user_keys/#delete-an-ssh-key-for-a-user + */ public function removeUserKey(int $user_id, int $key_id): mixed { return $this->delete('users/'.self::encodePath($user_id).'/keys/'.self::encodePath($key_id)); } + /** + * List all email addresses. + * + * @see https://docs.gitlab.com/api/user_email_addresses/#list-all-email-addresses + */ public function emails(): mixed { return $this->get('user/emails'); } + /** + * Retrieve details on an email address. + * + * @see https://docs.gitlab.com/api/user_email_addresses/#retrieve-details-on-an-email-address + */ public function email(int $id): mixed { return $this->get('user/emails/'.self::encodePath($id)); } + /** + * List all email addresses for a user. + * + * @see https://docs.gitlab.com/api/user_email_addresses/#list-all-email-addresses-for-a-user + */ public function userEmails(int $user_id): mixed { return $this->get('users/'.self::encodePath($user_id).'/emails'); } + /** + * Add an email address for a user. + * + * @see https://docs.gitlab.com/api/user_email_addresses/#add-an-email-address-for-a-user + */ public function createEmailForUser(int $user_id, string $email, bool $skip_confirmation = false): mixed { return $this->post('users/'.self::encodePath($user_id).'/emails', [ @@ -400,11 +529,21 @@ public function createEmailForUser(int $user_id, string $email, bool $skip_confi ]); } + /** + * Delete an email address for a user. + * + * @see https://docs.gitlab.com/api/user_email_addresses/#delete-an-email-address-for-a-user + */ public function removeUserEmail(int $user_id, int $email_id): mixed { return $this->delete('users/'.self::encodePath($user_id).'/emails/'.self::encodePath($email_id)); } + /** + * List all impersonation tokens for a user. + * + * @see https://docs.gitlab.com/api/user_tokens/#list-all-impersonation-tokens-for-a-user + */ public function userImpersonationTokens(int $user_id, array $params = []): mixed { $resolver = $this->createOptionsResolver(); @@ -416,11 +555,21 @@ public function userImpersonationTokens(int $user_id, array $params = []): mixed return $this->get('users/'.self::encodePath($user_id).'/impersonation_tokens', $resolver->resolve($params)); } + /** + * Retrieve an impersonation token for a user. + * + * @see https://docs.gitlab.com/api/user_tokens/#retrieve-an-impersonation-token-for-a-user + */ public function userImpersonationToken(int $user_id, int $impersonation_token_id): mixed { return $this->get('users/'.self::encodePath($user_id).'/impersonation_tokens/'.self::encodePath($impersonation_token_id)); } + /** + * Create an impersonation token. + * + * @see https://docs.gitlab.com/api/user_tokens/#create-an-impersonation-token + */ public function createImpersonationToken(int $user_id, string $name, array $scopes, ?string $expires_at = null): mixed { return $this->post('users/'.self::encodePath($user_id).'/impersonation_tokens', [ @@ -430,12 +579,21 @@ public function createImpersonationToken(int $user_id, string $name, array $scop ]); } + /** + * Revoke an impersonation token. + * + * @see https://docs.gitlab.com/api/user_tokens/#revoke-an-impersonation-token + */ public function removeImpersonationToken(int $user_id, int $impersonation_token_id): mixed { return $this->delete('users/'.self::encodePath($user_id).'/impersonation_tokens/'.self::encodePath($impersonation_token_id)); } /** + * Retrieve contribution events for a user. + * + * @see https://docs.gitlab.com/api/events/#retrieve-contribution-events-for-a-user + * * @param array $parameters { * * @var string $action include only events of a particular action type @@ -474,6 +632,8 @@ public function events(int $user_id, array $parameters = []): mixed /** * Deletes a user’s authentication identity using the provider name associated with that identity. + * + * @see https://docs.gitlab.com/api/users/#delete-authentication-identity-from-a-user */ public function removeUserIdentity(int $user_id, string $provider): mixed { diff --git a/src/Api/Version.php b/src/Api/Version.php index 8976a320..c21ff8c1 100644 --- a/src/Api/Version.php +++ b/src/Api/Version.php @@ -16,6 +16,14 @@ class Version extends AbstractApi { + /** + * Retrieve version information for the GitLab instance. + * + * Note: `GET /version` is documented together with `GET /metadata` on the + * Metadata API page, which has no dedicated per-endpoint anchor. + * + * @see https://docs.gitlab.com/api/metadata/ + */ public function show(): mixed { return $this->get('version'); diff --git a/src/Api/Wiki.php b/src/Api/Wiki.php index fbb05551..d3dd187e 100644 --- a/src/Api/Wiki.php +++ b/src/Api/Wiki.php @@ -17,6 +17,10 @@ class Wiki extends AbstractApi { /** + * Create a wiki page. + * + * @see https://docs.gitlab.com/api/wikis/#create-a-wiki-page + * * @param array $params */ public function create(int|string $project_id, array $params): mixed @@ -24,12 +28,21 @@ public function create(int|string $project_id, array $params): mixed return $this->post($this->getProjectPath($project_id, 'wikis'), $params); } + /** + * Retrieve a wiki page. + * + * @see https://docs.gitlab.com/api/wikis/#retrieve-a-wiki-page + */ public function show(int|string $project_id, string $wiki_slug): mixed { return $this->get($this->getProjectPath($project_id, 'wikis/'.self::encodePath($wiki_slug))); } /** + * List all wiki pages. + * + * @see https://docs.gitlab.com/api/wikis/#list-all-wiki-pages + * * @param array $params { * * @var bool $with_content Include pages' content @@ -45,6 +58,10 @@ public function showAll(int|string $project_id, array $params): mixed } /** + * Update a wiki page. + * + * @see https://docs.gitlab.com/api/wikis/#update-a-wiki-page + * * @param array $params */ public function update(int|string $project_id, string $wiki_slug, array $params): mixed @@ -52,6 +69,11 @@ public function update(int|string $project_id, string $wiki_slug, array $params) return $this->put($this->getProjectPath($project_id, 'wikis/'.self::encodePath($wiki_slug)), $params); } + /** + * Delete a wiki page. + * + * @see https://docs.gitlab.com/api/wikis/#delete-a-wiki-page + */ public function remove(int|string $project_id, string $wiki_slug): mixed { return $this->delete($this->getProjectPath($project_id, 'wikis/'.self::encodePath($wiki_slug)));