feature #1108 Deployment branch policies (Froxz)

This PR was squashed before being merged into the 3.10.x-dev branch.

Discussion
----------

* added Deployment branch policies
* Moved environments under deployment

Commits
-------

9734d23 Deployment branch policies
c72fdae removed params validation
a61fe84 StyleCI fixes
c30050c styleCI fixes
5d7048f Merge branch 'master' into feature/deployment-branch-policies
f657c3f StyleCi fixes
d9f0195 Changes to docs

doc/README.md

@@ -62,9 +62,10 @@ v3 APIs:
   * [Check Suites](repo/check_suites.md)
   * [Contents](repo/contents.md)
   * [Deployments](repo/deployments.md)
-    * [Secrets](environment/secrets.md)
-    * [Variables](environment/variables.md)
-  * [Environments](repo/environments.md)
+    * [Policies](repo/deployments/policies.md)
+    * [Environments](repo/deployments/environments.md)
+        * [Secrets](repo/deployments/environment/secrets.md)
+        * [Variables](repo/deployments/environment/variables.md)
   * [Labels](repo/labels.md)
   * [Protection](repo/protection.md)
   * [Releases](repo/releases.md)

doc/environment/secrets.md → doc/repo/deployments/environment/secrets.md

@@ -1,5 +1,5 @@
 ## Environment / Secrets API
-[Back to the "Environments API"](../repo/environments.md) | [Back to the navigation](../README.md)
+[Back to the "Environments API"](../environments.md) | [Back to the navigation](../README.md)
 
 ### List environment secrets
 

doc/environment/variables.md → doc/repo/deployments/environment/variables.md

@@ -1,5 +1,5 @@
 ## Environment / Variables API
-[Back to the "Environments API"](../repo/environments.md) | [Back to the navigation](../README.md)
+[Back to the "Environments API"](../environments.md) | [Back to the navigation](../README.md)
 
 ### List environment variables
 

doc/repo/deployments/environments.md

@@ -0,0 +1,32 @@
+## Deployment / Environments API
+[Back to the "Deployment API"](../deployments.md) | [Back to the navigation](../index.md)
+
+Provides information about environments for a repository. Wraps [GitHub Environments API](https://docs.github.com/en/rest/deployments/environments?apiVersion=2022-11-28).
+
+Additional APIs:
+* [Secrets API](environment/secrets.md)
+* [Variables API](environment/variables.md)
+
+#### List all environments.
+
+```php
+$environments = $client->deployment()->environment()->all('KnpLabs', 'php-github-api');
+```
+
+### Get one environment.
+
+```php
+$environment = $client->deployment()->environment()->show('KnpLabs', 'php-github-api', $name);
+```
+
+#### Create or update environment.
+
+```php
+$data = $client->deployment()->environment()->createOrUpdate('KnpLabs', 'php-github-api', $name);
+```
+
+#### Delete a existing environment.
+
+```php
+$environment = $client->deployment()->environment()->remove('KnpLabs', 'php-github-api', $name);
+```

doc/repo/deployments/policies.md

@@ -0,0 +1,38 @@
+## Deployment / Branch policies API
+[Back to the "Deployment API"](../deployments.md) | [Back to the navigation](../index.md)
+
+Provides information about deployment branch policies. Wraps [GitHub Deployment branch policies API](https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#about-deployment-branch-policies).
+
+#### List deployment branch policies.
+
+```php
+$policies = $client->deployment()->policies()->all('KnpLabs', 'php-github-api', 'production');
+```
+
+### Get one environment.
+
+```php
+$policy = $client->deployment()->policies()->show('KnpLabs', 'php-github-api', 'production', $branchPolicyId);
+```
+
+#### Create policy.
+
+```php
+$data = $client->deployment()->policies()->create('KnpLabs', 'php-github-api', 'production', [
+    'name' => 'name'
+]);
+```
+
+#### Update policy.
+
+```php
+$data = $client->deployment()->policies()->update('KnpLabs', 'php-github-api', 'production', $branchPolicyId, [
+    'name' => 'name'
+]);
+```
+
+#### Delete a existing policy.
+
+```php
+$policy = $client->deployment()->policies()->remove('KnpLabs', 'php-github-api', 'production', $branchPolicyId);
+```

lib/Github/Api/Deployment.php

@@ -2,6 +2,8 @@
 
 namespace Github\Api;
 
+use Github\Api\Deployment\Environments;
+use Github\Api\Deployment\Policies;
 use Github\Exception\MissingArgumentException;
 
 /**
@@ -130,4 +132,20 @@ public function getStatuses($username, $repository, $id)
     {
         return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments/'.$id.'/statuses');
     }
+
+    /**
+     * @return Environments
+     */
+    public function environments()
+    {
+        return new Environments($this->getClient());
+    }
+
+    /**
+     * @return Policies
+     */
+    public function policies()
+    {
+        return new Policies($this->getClient());
+    }
 }

lib/Github/Api/Environment.php → lib/Github/Api/Deployment/Environments.php

@@ -1,7 +1,8 @@
 <?php
 
-namespace Github\Api;
+namespace Github\Api\Deployment;
 
+use Github\Api\AbstractApi;
 use Github\Api\Environment\Secrets;
 use Github\Api\Environment\Variables;
 
@@ -10,7 +11,7 @@
  *
  * @link https://docs.github.com/en/rest/deployments/environments?apiVersion=2022-11-28#
  */
-class Environment extends AbstractApi
+class Environments extends AbstractApi
 {
     /**
      * List environments for a particular repository.

lib/Github/Api/Deployment/Policies.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Github\Api\Deployment;
+
+use Github\Api\AbstractApi;
+
+/**
+ * Listing, creating and updating deployments.
+ *
+ * @link https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#list-deployment-branch-policies
+ */
+class Policies extends AbstractApi
+{
+    /**
+     * List deployment branch policies.
+     *
+     * @link https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#list-deployment-branch-policies
+     *
+     * @param string $username    the username of the user who owns the repository
+     * @param string $repository  the name of the repository
+     * @param string $environment the name of the environment.
+     * @param array  $params      query parameters to filter deployments by (see link)
+     *
+     * @return array the branch policies requested
+     */
+    public function all(string $username, string $repository, string $environment, array $params = [])
+    {
+        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/environments/'.rawurlencode($environment).'/deployment-branch-policies', $params);
+    }
+
+    /**
+     * Get a deployment branch policy.
+     *
+     * @link https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#get-a-deployment-branch-policy
+     *
+     * @param string $username    the username of the user who owns the repository
+     * @param string $repository  the name of the repository
+     * @param string $environment the name of the environment.
+     * @param int    $id          the unique identifier of the branch policy.
+     *
+     * @return array
+     */
+    public function show(string $username, string $repository, string $environment, int $id)
+    {
+        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/environments/'.rawurlencode($environment).'/deployment-branch-policies/'.$id);
+    }
+
+    /**
+     * Creates a deployment branch policy for an environment.
+     *
+     * @link https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#create-a-deployment-branch-policy
+     *
+     * @param string $username    the username of the user who owns the repository
+     * @param string $repository  the name of the repository
+     * @param string $environment the name of the environment.
+     *
+     * @return array information about the deployment branch policy
+     */
+    public function create(string $username, string $repository, string $environment, array $params)
+    {
+        return $this->post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/environments/'.rawurlencode($environment).'/deployment-branch-policies', $params);
+    }
+
+    /**
+     * Updates a deployment branch policy for an environment.
+     *
+     * @link https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#update-a-deployment-branch-policy
+     *
+     * @param string $username    the username of the user who owns the repository
+     * @param string $repository  the name of the repository
+     * @param string $environment the name of the environment.
+     * @param int    $id          the unique identifier of the branch policy.
+     *
+     * @return array information about the deployment branch policy
+     */
+    public function update(string $username, string $repository, string $environment, int $id, array $params)
+    {
+        return $this->put('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/environments/'.rawurlencode($environment).'/deployment-branch-policies/'.$id, $params);
+    }
+
+    /**
+     * Delete a deployment branch policy.
+     *
+     * @link https://docs.github.com/en/rest/deployments/branch-policies?apiVersion=2022-11-28#delete-a-deployment-branch-policy
+     *
+     * @param string $username    the username of the user who owns the repository
+     * @param string $repository  the name of the repository
+     * @param string $environment the name of the environment.
+     * @param int    $id          the unique identifier of the branch policy.
+     *
+     * @return mixed null on success, array on error with 'message'
+     */
+    public function remove(string $username, string $repository, string $environment, int $id)
+    {
+        return $this->delete('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/environments/'.rawurlencode($environment).'/deployment-branch-policies/'.$id);
+    }
+}

lib/Github/Client.php

@@ -181,11 +181,6 @@ public function api($name): AbstractApi
                 $api = new Api\Deployment($this);
                 break;
 
-            case 'environment':
-            case 'environments':
-                $api = new Api\Environment($this);
-                break;
-
             case 'ent':
             case 'enterprise':
                 $api = new Api\Enterprise($this);

test/Github/Tests/Api/EnvironmentTest.php → test/Github/Tests/Api/Deployment/EnvironmentsTest.php

@@ -1,6 +1,8 @@
 <?php
 
-namespace Github\Tests\Api;
+namespace Github\Tests\Api\Deployment;
+
+use Github\Tests\Api\TestCase;
 
 class EnvironmentTest extends TestCase
 {
@@ -66,6 +68,6 @@ public function shouldDeleteEnvironment()
      */
     protected function getApiClass()
     {
-        return \Github\Api\Environment::class;
+        return \Github\Api\Deployment\Environments::class;
     }
 }