From db1e299c65a82789434d922911e9f37337a6b818 Mon Sep 17 00:00:00 2001 From: Fulvio Sicurezza Date: Wed, 13 Jul 2016 09:57:50 +0200 Subject: [PATCH 1/3] Package rebase --- README.md | 2 +- composer.json | 9 +++++++-- lib/Gitlab/Client.php | 2 +- lib/Gitlab/HttpClient/HttpClient.php | 2 +- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 157474446..ac6d75493 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ $ sudo mv composer.phar /usr/local/bin/composer Add the following to your require block in composer.json config. Note: be careful when using the `dev-master` tag as this may have unexpected results depending on your version of Gitlab. See the Versioning section below for more information. ``` -"m4tthumphrey/php-gitlab-api": "dev-master" +"fsicurezza/php-gitlab-api": "dev-master" ``` Include Composer's autoloader: diff --git a/composer.json b/composer.json index 5b67a9626..a4170c5b4 100644 --- a/composer.json +++ b/composer.json @@ -1,8 +1,8 @@ { - "name": "m4tthumphrey/php-gitlab-api", + "name": "fsicurezza/php-gitlab-api", "type": "library", "description": "GitLab API client", - "homepage": "https://github.com/m4tthumphrey/php-gitlab-api", + "homepage": "https://github.com/fsicurezza/php-gitlab-api", "keywords": ["gitlab", "api"], "license": "MIT", "authors": [ @@ -18,6 +18,11 @@ "name": "Thibault Duplessis", "email": "thibault.duplessis@gmail.com", "homepage": "http://ornicar.github.com/" + }, + { + "name": "Fulvio Sicurezza", + "email": "f.sicurezza@generalservice.na.it", + "homepage": "http://www.generalservice.na.it/" } ], "require": { diff --git a/lib/Gitlab/Client.php b/lib/Gitlab/Client.php index af6a69417..1cb7c2927 100644 --- a/lib/Gitlab/Client.php +++ b/lib/Gitlab/Client.php @@ -54,7 +54,7 @@ class Client * @var array */ private $options = array( - 'user_agent' => 'php-gitlab-api (http://github.com/m4tthumphrey/php-gitlab-api)', + 'user_agent' => 'php-gitlab-api (http://github.com/fsicurezza/php-gitlab-api)', 'timeout' => 60 ); diff --git a/lib/Gitlab/HttpClient/HttpClient.php b/lib/Gitlab/HttpClient/HttpClient.php index 974b57ad8..b27045bb5 100644 --- a/lib/Gitlab/HttpClient/HttpClient.php +++ b/lib/Gitlab/HttpClient/HttpClient.php @@ -21,7 +21,7 @@ class HttpClient implements HttpClientInterface * @var array */ protected $options = array( - 'user_agent' => 'php-gitlab-api (http://github.com/m4tthumphrey/php-gitlab-api)', + 'user_agent' => 'php-gitlab-api (http://github.com/fsicurezza/php-gitlab-api)', 'timeout' => 10, ); From d394c614452fce03416bc7ecd15f4bc1b568279b Mon Sep 17 00:00:00 2001 From: Fulvio Sicurezza Date: Wed, 13 Jul 2016 14:35:14 +0200 Subject: [PATCH 2/3] Added support for: GET /projects/starred GET /projects/:id/repository/commits/:sha/statuses POST /projects/:id/statuses/:sha --- lib/Gitlab/Api/Projects.php | 41 +++++++++++++++++++++++++ lib/Gitlab/Api/Repositories.php | 54 ++++++++++++++++++++++++--------- 2 files changed, 81 insertions(+), 14 deletions(-) diff --git a/lib/Gitlab/Api/Projects.php b/lib/Gitlab/Api/Projects.php index b2aaec615..d40ed7659 100644 --- a/lib/Gitlab/Api/Projects.php +++ b/lib/Gitlab/Api/Projects.php @@ -56,6 +56,31 @@ public function owned($page = 1, $per_page = self::PER_PAGE, $order_by = self::O )); } + /** + * Get a list of projects which are starred by the authenticated user. + * + * @param int $page Page number + * @param int $per_page Number of starred projects per page + * @param null $archived if passed, limit by archived status + * @param null $visibility if passed, limit by visibility public, internal, private + * @param string $order_by Return requests ordered by id, name, path, created_at, updated_at or last_activity_at fields. Default is created_at + * @param string $sort Return requests sorted in asc or desc order. Default is desc + * @param null $search Return list of authorized projects according to a search criteria + * @return mixed + */ + public function starred($page = 1, $per_page = self::PER_PAGE, $archived = null, $visibility = null, $order_by = self::ORDER_BY, $sort = self::SORT, $search = null) + { + return $this->get('projects/starred', array( + 'page' => $page, + 'per_page' => $per_page, + 'archived' => $archived, + 'visibility' => $visibility, + 'order_by' => $order_by, + 'sort' => $sort, + 'search' => $search + )); + } + /** * @param string $query * @param int $page @@ -417,4 +442,20 @@ public function removeService($project_id, $service_name) { return $this->delete($this->getProjectPath($project_id, 'services/'.$this->encodePath($service_name))); } + + /** + * @param $project_id + * @param $sha + * @param $state The state of the status. Can be one of the following: pending, running, success, failed, canceled + * @param array $params name or context (string) = The label to differentiate this status from the status of other systems. Default value is default + * target_url (string) = The target URL to associate with this status + * description (string) = The short description of the status + * @return mixed + */ + public function createStatus($project_id, $sha, $state, array $params = array()) + { + $params['state'] = $state; + return $this->post($this->getProjectPath($project_id, 'statuses/'.$this->encodePath($sha)), $params); + } + } diff --git a/lib/Gitlab/Api/Repositories.php b/lib/Gitlab/Api/Repositories.php index d69b4d73b..f3cd30151 100644 --- a/lib/Gitlab/Api/Repositories.php +++ b/lib/Gitlab/Api/Repositories.php @@ -134,20 +134,46 @@ public function commit($project_id, $sha) return $this->get($this->getProjectPath($project_id, 'repository/commits/'.$this->encodePath($sha))); } - /** - * @param int $project_id - * @param string $sha - * @param int $page - * @param int $per_page - * @return mixed - */ - public function commitComments($project_id, $sha, $page = 0, $per_page = self::PER_PAGE) - { - return $this->get($this->getProjectPath($project_id, 'repository/commits/'.$this->encodePath($sha).'/comments'), array( - 'page' => $page, - 'per_page' => $per_page - )); - } + /** + * Get the statuses of a commit in a project. + * + * @since GitLab 8.1 + * + * @param $project_id + * @param $sha + * @param int $page + * @param int $per_page + * @param null $ref_name The name of a repository branch or tag or, if not given, the default branch + * @param null $stage Filter by build stage, e.g., test + * @param null $name Filter by job name, e.g., bundler:audit + * @param bool $all Return all statuses, not only the latest ones + * @return mixed + */ + public function commitStatuses( $project_id, $sha, $page = 0, $per_page = self::PER_PAGE, $ref_name = null, $stage = null, $name = null, $all = false ) { + return $this->get( $this->getProjectPath( $project_id, 'repository/commits/' . $this->encodePath( $sha ) . '/statuses' ), array( + 'page' => $page, + 'per_page' => $per_page, + 'ref_name' => $ref_name, + 'stage' => $stage, + 'name' => $name, + 'all' => $all + ) ); + } + + /** + * @param int $project_id + * @param string $sha + * @param int $page + * @param int $per_page + * @return mixed + */ + public function commitComments($project_id, $sha, $page = 0, $per_page = self::PER_PAGE) + { + return $this->get($this->getProjectPath($project_id, 'repository/commits/'.$this->encodePath($sha).'/comments'), array( + 'page' => $page, + 'per_page' => $per_page + )); + } /** * @param int $project_id From 4056353c475e454fa695cf05686a3f0c98c48561 Mon Sep 17 00:00:00 2001 From: Fulvio Sicurezza Date: Wed, 13 Jul 2016 16:12:03 +0200 Subject: [PATCH 3/3] Projects API methods update Added support for: POST /projects/fork/:id POST /projects/:id/star DELETE /projects/:id/star POST /projects/:id/archive POST /projects/:id/unarchive POST /projects/:id/uploads POST /projects/:id/share --- lib/Gitlab/Api/Projects.php | 444 ++++++++++++++++++++++++++++-------- 1 file changed, 344 insertions(+), 100 deletions(-) diff --git a/lib/Gitlab/Api/Projects.php b/lib/Gitlab/Api/Projects.php index d40ed7659..6f9d03b86 100644 --- a/lib/Gitlab/Api/Projects.php +++ b/lib/Gitlab/Api/Projects.php @@ -6,87 +6,106 @@ class Projects extends AbstractApi const SORT = 'asc'; /** + * Get a list of all GitLab projects (admin only). + * * @param int $page * @param int $per_page - * @param string $order_by - * @param string $sort + * @param string $order_by Return requests ordered by id, name, path, created_at, updated_at or last_activity_at fields. Default is created_at + * @param string $sort Return requests sorted in asc or desc order. Default is desc + * @param array $params archived (optional) - if passed, limit by archived status + * visibility (optional) - if passed, limit by visibility public, internal, private + * search (optional) - Return list of authorized projects according to a search criteria * @return mixed */ - public function all($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT) + public function all($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT, $params = array()) { - return $this->get('projects/all', array( + $params = array_merge($params, array( 'page' => $page, 'per_page' => $per_page, 'order_by' => $order_by, 'sort' => $sort )); + return $this->get('projects/all', $params); } /** + * Get a list of projects accessible by the authenticated user. + * * @param int $page * @param int $per_page - * @param string $order_by - * @param string $sort + * @param string $order_by Return requests ordered by id, name, path, created_at, updated_at or last_activity_at fields. Default is created_at + * @param string $sort Return requests sorted in asc or desc order. Default is desc + * @param array $params archived (optional) - if passed, limit by archived status + * visibility (optional) - if passed, limit by visibility public, internal, private + * search (optional) - Return list of authorized projects according to a search criteria * @return mixed */ - public function accessible($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT) + public function accessible($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT, $params = array()) { - return $this->get('projects', array( + $params = array_merge($params, array( 'page' => $page, 'per_page' => $per_page, 'order_by' => $order_by, 'sort' => $sort )); + return $this->get('projects', $params); } /** + * Get a list of projects which are owned by the authenticated user. + * * @param int $page * @param int $per_page - * @param string $order_by - * @param string $sort + * @param string $order_by order_by (optional) - Return requests ordered by id, name, path, created_at, updated_at or last_activity_at fields. Default is created_at + * @param string $sort sort (optional) - Return requests sorted in asc or desc order. Default is desc + * @param array $params archived (optional) - if passed, limit by archived status + * visibility (optional) - if passed, limit by visibility public, internal, private + * search (optional) - Return list of authorized projects according to a search criteria * @return mixed */ - public function owned($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT) + public function owned($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT, $params = array()) { - return $this->get('projects/owned', array( + $params = array_merge($params, array( 'page' => $page, 'per_page' => $per_page, 'order_by' => $order_by, 'sort' => $sort )); + return $this->get('projects/owned', $params); } /** * Get a list of projects which are starred by the authenticated user. * - * @param int $page Page number - * @param int $per_page Number of starred projects per page - * @param null $archived if passed, limit by archived status - * @param null $visibility if passed, limit by visibility public, internal, private + * @param int $page + * @param int $per_page * @param string $order_by Return requests ordered by id, name, path, created_at, updated_at or last_activity_at fields. Default is created_at * @param string $sort Return requests sorted in asc or desc order. Default is desc - * @param null $search Return list of authorized projects according to a search criteria + * @param array $params archived (optional) - if passed, limit by archived status + * visibility (optional) - if passed, limit by visibility public, internal, private + * search (optional) - Return list of authorized projects according to a search criteria + * @param null $search * @return mixed */ - public function starred($page = 1, $per_page = self::PER_PAGE, $archived = null, $visibility = null, $order_by = self::ORDER_BY, $sort = self::SORT, $search = null) + public function starred($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT, $params = array()) { - return $this->get('projects/starred', array( + $params = array_merge($params, array( 'page' => $page, 'per_page' => $per_page, - 'archived' => $archived, - 'visibility' => $visibility, 'order_by' => $order_by, - 'sort' => $sort, - 'search' => $search + 'sort' => $sort )); + return $this->get('projects/starred', $params); } /** - * @param string $query - * @param int $page - * @param int $per_page - * @param string $order_by - * @param string $sort + * Search for projects by name which are accessible to the authenticated user. + * + * @param string $query A string contained in the project name + * @param int $page the page to retrieve + * @param int $per_page number of projects to return per page + * @param string $order_by Return requests ordered by id, name, created_at or last_activity_at fields + * @param string $sort Return requests sorted in asc or desc order * @return mixed */ public function search($query, $page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT) @@ -100,7 +119,9 @@ public function search($query, $page = 1, $per_page = self::PER_PAGE, $order_by } /** - * @param int $project_id + * Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME, which is owned by the authenticated user. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project * @return mixed */ public function show($project_id) @@ -109,8 +130,23 @@ public function show($project_id) } /** - * @param string $name - * @param array $params + * Creates a new project owned by the authenticated user. + * + * @param string $name new project name + * @param array $params path (optional) - custom repository name for new project. By default generated based on name + * namespace_id (optional) - namespace for the new project (defaults to user) + * description (optional) - short project description + * issues_enabled (optional) + * merge_requests_enabled (optional) + * builds_enabled (optional) + * wiki_enabled (optional) + * snippets_enabled (optional) + * container_registry_enabled (optional) + * shared_runners_enabled (optional) + * public (optional) - if true same as setting visibility_level = 20 + * visibility_level (optional) + * import_url (optional) + * public_builds (optional) * @return mixed */ public function create($name, array $params = array()) @@ -121,9 +157,22 @@ public function create($name, array $params = array()) } /** - * @param int $user_id - * @param string $name - * @param array $params + * Creates a new project owned by the specified user. Available only for admins. + * + * @param int $user_id user_id of owner + * @param string $name new project name + * @param array $params description (optional) - short project description + * issues_enabled (optional) + * merge_requests_enabled (optional) + * builds_enabled (optional) + * wiki_enabled (optional) + * snippets_enabled (optional) + * container_registry_enabled (optional) + * shared_runners_enabled (optional) + * public (optional) - if true same as setting visibility_level = 20 + * visibility_level (optional) + * import_url (optional) + * public_builds (optional) * @return mixed */ public function createForUser($user_id, $name, array $params = array()) @@ -134,8 +183,23 @@ public function createForUser($user_id, $name, array $params = array()) } /** - * @param int $project_id - * @param array $params + * Updates an existing project + * + * @param int $project_id The ID of a project + * @param array $params name (optional) - project name + * path (optional) - repository name for project + * description (optional) - short project description + * default_branch (optional) + * issues_enabled (optional) + * merge_requests_enabled (optional) + * builds_enabled (optional) + * wiki_enabled (optional) + * snippets_enabled (optional) + * container_registry_enabled (optional) + * shared_runners_enabled (optional) + * public (optional) - if true same as setting visibility_level = 20 + * visibility_level (optional) + * public_builds (optional) * @return mixed */ public function update($project_id, array $params) @@ -144,7 +208,9 @@ public function update($project_id, array $params) } /** - * @param int $project_id + * Removes a project including all associated resources (issues, merge requests etc.) + * + * @param int $project_id The ID of a project * @return mixed */ public function remove($project_id) @@ -153,8 +219,10 @@ public function remove($project_id) } /** - * @param int $project_id - * @param array $scope + * Get a list of builds in a project (http://docs.gitlab.com/ce/api/builds.html#list-project-builds) + * + * @param int $project_id The ID of a project + * @param array $scope The scope of builds to show, one or array of: pending, running, failed, success, canceled; showing all builds if none provided * @return mixed */ public function builds($project_id, $scope = null) @@ -165,8 +233,10 @@ public function builds($project_id, $scope = null) } /** - * @param $project_id - * @param $build_id + * Get a single build of a project (http://docs.gitlab.com/ce/api/builds.html#get-a-single-build) + * + * @param $project_id The ID of a project + * @param $build_id The ID of a build * @return mixed */ public function build($project_id, $build_id) @@ -175,8 +245,10 @@ public function build($project_id, $build_id) } /** - * @param $project_id - * @param $build_id + * Get a trace of a specific build of a project (http://docs.gitlab.com/ce/api/builds.html#get-a-trace-file) + * + * @param $project_id The ID of a project + * @param $build_id The ID of a build * @return mixed */ public function trace($project_id, $build_id) @@ -185,8 +257,10 @@ public function trace($project_id, $build_id) } /** - * @param int $project_id - * @param string $username_query + * Get a list of a project's team members. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param string $username_query Query string to search for members * @return mixed */ public function members($project_id, $username_query = null) @@ -197,8 +271,10 @@ public function members($project_id, $username_query = null) } /** - * @param int $project_id - * @param int $user_id + * Gets a project team member. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $user_id The ID of a user * @return mixed */ public function member($project_id, $user_id) @@ -207,9 +283,12 @@ public function member($project_id, $user_id) } /** - * @param int $project_id - * @param int $user_id - * @param int $access_level + * Adds a user to a project team. This is an idempotent method and can be called multiple times with the same parameters. + * Adding team membership to a user that is already a member does not affect the existing membership. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $user_id The ID of a user to add + * @param int $access_level Project access level * @return mixed */ public function addMember($project_id, $user_id, $access_level) @@ -221,9 +300,11 @@ public function addMember($project_id, $user_id, $access_level) } /** - * @param int $project_id - * @param int $user_id - * @param int $access_level + * Updates a project team member to a specified access level. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $user_id The ID of a team member + * @param int $access_level Project access level * @return mixed */ public function saveMember($project_id, $user_id, $access_level) @@ -234,9 +315,13 @@ public function saveMember($project_id, $user_id, $access_level) } /** - * @param int $project_id - * @param int $user_id - * @return mixed + * Removes a user from a project team. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $user_id The ID of a team member + * @return mixed It returns a status code 403 if the member does not have the proper rights to perform this action. + * In all other cases this method is idempotent and revoking team membership for a user who is not currently a team member is considered success. + * Please note that the returned JSON currently differs slightly. Thus you should not rely on the returned JSON structure. */ public function removeMember($project_id, $user_id) { @@ -244,7 +329,9 @@ public function removeMember($project_id, $user_id) } /** - * @param int $project_id + * Get a list of project hooks. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project * @param int $page * @param int $per_page * @return mixed @@ -258,8 +345,10 @@ public function hooks($project_id, $page = 1, $per_page = self::PER_PAGE) } /** - * @param int $project_id - * @param int $hook_id + * Get a specific hook for a project. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $hook_id The ID of a project hook * @return mixed */ public function hook($project_id, $hook_id) @@ -268,9 +357,16 @@ public function hook($project_id, $hook_id) } /** - * @param int $project_id - * @param string $url - * @param array $params + * Adds a hook to a specified project. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param string $url The hook URL + * @param array $params push_events - Trigger hook on push events + * issues_events - Trigger hook on issues events + * merge_requests_events - Trigger hook on merge_requests events + * tag_push_events - Trigger hook on push_tag events + * note_events - Trigger hook on note events + * enable_ssl_verification - Do SSL verification when triggering the hook * @return mixed */ public function addHook($project_id, $url, array $params = array()) @@ -285,9 +381,17 @@ public function addHook($project_id, $url, array $params = array()) } /** - * @param int $project_id - * @param int $hook_id - * @param array $params + * Edits a hook for a specified project. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $hook_id The ID of a project hook + * @param array $params url (required) - The hook URL + * push_events - Trigger hook on push events + * issues_events - Trigger hook on issues events + * merge_requests_events - Trigger hook on merge_requests events + * tag_push_events - Trigger hook on push_tag events + * note_events - Trigger hook on note events + * enable_ssl_verification - Do SSL verification when triggering the hook * @return mixed */ public function updateHook($project_id, $hook_id, array $params) @@ -296,9 +400,12 @@ public function updateHook($project_id, $hook_id, array $params) } /** - * @param int $project_id - * @param int $hook_id - * @return mixed + * Removes a hook from a project. This is an idempotent method and can be called multiple times. Either the hook is available or not. + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project + * @param int $hook_id The ID of hook to delete + * @return mixed Note the JSON response differs if the hook is available or not. + * If the project hook is available before it is returned in the JSON response or an empty response is returned. */ public function removeHook($project_id, $hook_id) { @@ -306,7 +413,9 @@ public function removeHook($project_id, $hook_id) } /** - * @param int $project_id + * Get a list of a project's deploy keys (http://docs.gitlab.com/ce/api/deploy_keys.html#list-deploy-keys) + * + * @param int $project_id The ID of the project * @return mixed */ public function keys($project_id) @@ -315,8 +424,10 @@ public function keys($project_id) } /** - * @param int $project_id - * @param int $key_id + * Get a single key (http://docs.gitlab.com/ce/api/deploy_keys.html#single-deploy-key) + * + * @param int $project_id The ID of the project + * @param int $key_id The ID of the deploy key * @return mixed */ public function key($project_id, $key_id) @@ -325,9 +436,12 @@ public function key($project_id, $key_id) } /** - * @param int $project_id - * @param string $title - * @param string $key + * Creates a new deploy key for a project (http://docs.gitlab.com/ce/api/deploy_keys.html#add-deploy-key) + * If the deploy key already exists in another project, it will be joined to current project only if original one was is accessible by the same user. + * + * @param int $project_id The ID of the project + * @param string $title New deploy key's title + * @param string $key New deploy key * @return mixed */ public function addKey($project_id, $title, $key) @@ -339,8 +453,10 @@ public function addKey($project_id, $title, $key) } /** - * @param int $project_id - * @param int $key_id + * Delete a deploy key from a project (http://docs.gitlab.com/ce/api/deploy_keys.html#delete-deploy-key) + * + * @param int $project_id The ID of the project + * @param int $key_id The ID of the deploy key * @return mixed */ public function removeKey($project_id, $key_id) @@ -349,7 +465,9 @@ public function removeKey($project_id, $key_id) } /** - * @param int $project_id + * Get the events for the specified project. Sorted from newest to latest + * + * @param int $project_id The ID or NAMESPACE/PROJECT_NAME of a project * @param int $page * @param int $per_page * @return mixed @@ -363,7 +481,9 @@ public function events($project_id, $page = 1, $per_page = self::PER_PAGE) } /** - * @param int $project_id + * Get all labels for a given project (http://docs.gitlab.com/ce/api/labels.html#list-labels) + * + * @param int $project_id The ID of the project * @return mixed */ public function labels($project_id) @@ -372,9 +492,13 @@ public function labels($project_id) } /** - * @param int $project_id - * @param array $params - * @return mixed + * Creates a new label for the given repository with the given name and color (http://docs.gitlab.com/ce/api/labels.html#create-a-new-label) + * + * @param int $project_id The ID of the project + * @param array $params name (string, required) - The name of the label + * color (string, required) - The color of the label in 6-digit hex notation with leading # sign + * description (string, optional) - The description of the label + * @return mixed It returns 200 if the label was successfully created, 400 for wrong parameters and 409 if the label already exists. */ public function addLabel($project_id, array $params) { @@ -382,9 +506,16 @@ public function addLabel($project_id, array $params) } /** - * @param int $project_id - * @param array $params - * @return mixed + * Updates an existing label with new name or new color (http://docs.gitlab.com/ce/api/labels.html#edit-an-existing-label) + * At least one parameter is required, to update the label. + * + * @param int $project_id The ID of the project + * @param array $params name (string, required) - The name of the existing label + * new_name (string, required if color if not provided) - The new name of the label + * color (string, required if new_name is not provided) - The new color of the label in 6-digit hex notation with leading # sign + * description (string, optional) - The new description of the label + * @return mixed It returns 200 if the label was successfully deleted, 400 for wrong parameters and 404 if the label does not exist. + * In case of an error, an additional error message is returned. */ public function updateLabel($project_id, array $params) { @@ -392,9 +523,12 @@ public function updateLabel($project_id, array $params) } /** - * @param int $project_id - * @param string $name - * @return mixed + * Deletes a label with a given name (http://docs.gitlab.com/ce/api/labels.html#delete-a-label) + * + * @param int $project_id The ID of the project + * @param string $name The name of the label + * @return mixed It returns 200 if the label was successfully deleted, 400 for wrong parameters and 404 if the label does not exist. + * In case of an error, an additional error message is returned. */ public function removeLabel($project_id, $name) { @@ -404,8 +538,11 @@ public function removeLabel($project_id, $name) } /** - * @param int $project_id - * @param int $forked_project_id + * Allows modification of the forked relationship between existing projects. Available only for admins. + * Create a forked from/to relation between existing projects. + * + * @param int $project_id The ID of the project + * @param int $forked_project_id The ID of the project that was forked from * @return mixed */ public function createForkRelation($project_id, $forked_project_id) @@ -414,7 +551,10 @@ public function createForkRelation($project_id, $forked_project_id) } /** - * @param int $project_id + * Allows modification of the forked relationship between existing projects. Available only for admins. + * Delete an existing forked from relationship. + * + * @param int $project_id The ID of the project * @return mixed */ public function removeForkRelation($project_id) @@ -423,9 +563,11 @@ public function removeForkRelation($project_id) } /** - * @param int $project_id - * @param string $service_name - * @param array $params + * Sets a service for the project (http://docs.gitlab.com/ce/api/services.html) + * + * @param int $project_id The ID of the project + * @param string $service_name The name of the service (Asana, JIRA, Redmine, etc...) + * @param array $params Service specific parameters (api_key, token, subdomain, etc...) * @return mixed */ public function setService($project_id, $service_name, array $params = array()) @@ -434,8 +576,10 @@ public function setService($project_id, $service_name, array $params = array()) } /** - * @param int $project_id - * @param string $service_name + * Deletes a service for the project (http://docs.gitlab.com/ce/api/services.html) + * + * @param int $project_id The ID of the project + * @param string $service_name The name of the service (Asana, JIRA, Redmine, etc...) * @return mixed */ public function removeService($project_id, $service_name) @@ -444,12 +588,14 @@ public function removeService($project_id, $service_name) } /** - * @param $project_id - * @param $sha + * Adds or updates a build status of a commit (http://docs.gitlab.com/ce/api/commits.html#post-the-build-status-to-a-commit) + * + * @param $project_id The ID of a project + * @param $sha The commit SHA * @param $state The state of the status. Can be one of the following: pending, running, success, failed, canceled - * @param array $params name or context (string) = The label to differentiate this status from the status of other systems. Default value is default - * target_url (string) = The target URL to associate with this status - * description (string) = The short description of the status + * @param array $params name or context (string, optional) - The label to differentiate this status from the status of other systems. Default value is default + * target_url (string, optional) - The target URL to associate with this status + * description (string, optional) - The short description of the status * @return mixed */ public function createStatus($project_id, $sha, $state, array $params = array()) @@ -458,4 +604,102 @@ public function createStatus($project_id, $sha, $state, array $params = array()) return $this->post($this->getProjectPath($project_id, 'statuses/'.$this->encodePath($sha)), $params); } + /** + * Forks a project into the user namespace of the authenticated user. + * + * @param $project_id The ID of the project to be forked + * @return mixed + */ + public function fork($project_id) + { + return $this->post('projects/fork/'.$this->encodePath($project_id)); + } + + /** + * Stars a given project. + * + * @param $project_id The ID of the project + * @return mixed Returns status code 201 and the project on success and 304 if the project is already starred. + */ + public function star($project_id) + { + return $this->post($this->getProjectPath($project_id, 'star')); + } + + /** + * Unstars a given project. + * + * @param $project_id The ID of the project + * @return mixed Returns status code 200 and the project on success and 304 if the project is not starred. + */ + public function unstar($project_id) + { + return $this->delete($this->getProjectPath($project_id, 'star')); + } + + /** + * Archives the project if the user is either admin or the project owner of this project. + * This action is idempotent, thus archiving an already archived project will not change the project. + * + * @param $project_id The ID of the project + * @return mixed Status code 201 with the project as body is given when successful, in case the user doesn't have the proper access rights, code 403 is returned. + * Status 404 is returned if the project doesn't exist, or is hidden to the user. + */ + public function archive($project_id) + { + return $this->post($this->getProjectPath($project_id, 'archive')); + } + + /** + * Unarchives the project if the user is either admin or the project owner of this project. + * This action is idempotent, thus unarchiving an non-archived project will not change the project. + * + * @param $project_id The ID of the project + * @return mixed Status code 201 with the project as body is given when successful, in case the user doesn't have the proper access rights, code 403 is returned. + * Status 404 is returned if the project doesn't exist, or is hidden to the user. + */ + public function unarchive($project_id) + { + return $this->post($this->getProjectPath($project_id, 'unarchive')); + } + + /** + * Uploads a file to the specified project to be used in an issue or merge request description, or a comment. + * + * @param $project_id The ID of the project + * @param $file The file to be uploaded + * { + * "alt": "dk", + * "url": "/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png", + * "is_image": true, + * "markdown": "![dk](/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png)" + * } + * + * @return mixed The returned url is relative to the project path. In Markdown contexts, the link is automatically expanded when the format in markdown is used. + */ + public function upload($project_id, $file) + { + return $this->post($this->getProjectPath($project_id, 'uploads'), array( + 'file' => $file + )); + } + + /** + * Allow to share project with group. + * + * @param $project_id The ID of a project + * @param $group_id The ID of a group + * @param $group_access Level of permissions for sharing + * + * @return mixed + */ + public function share($project_id, $group_id, $group_access) + { + return $this->post($this->getProjectPath($project_id, 'share'), array( + 'group_id' => $group_id, + 'group_access' => $group_access + )); + } + + }