Implement more options for the branch() method

src/Model/Environment.php

@@ -12,6 +12,7 @@
 use Platformsh\Client\Model\Backups\Policy;
 use Platformsh\Client\Model\Deployment\EnvironmentDeployment;
 use Platformsh\Client\Model\Deployment\Worker;
+use Platformsh\Client\Model\Environment\BranchOptions;
 use Platformsh\Client\Model\Git\Commit;
 use Platformsh\Client\Model\Type\Duration;
 
@@ -24,6 +25,8 @@
  *   The primary ID of the environment. This is the same as the 'name' property.
  * @property-read string      $status
  *   The status of the environment: active, inactive, or dirty.
+ * @property-read string      $type
+ *   The type of the environment, for example: production, staging, or development.
  * @property-read string      $head_commit
  *   The SHA-1 hash identifying the Git commit at the branch's HEAD.
  * @property-read string      $name
@@ -234,21 +237,28 @@ public function getPublicUrl()
     /**
      * Branch (create a new environment).
      *
-     * @param string $title       The title of the new environment.
-     * @param string $id          The ID of the new environment. This will be the Git
-     *                            branch name. Leave blank to generate automatically
-     *                            from the title.
-     * @param bool   $cloneParent Whether to clone data from the parent
-     *                            environment while branching.
+     * @param BranchOptions|string $options
+     *   If a BranchOptions object is provided (recommended), this is the only argument and the others will be ignored.
+     *   If a string is provided, this is the title of the new environment (deprecated).
+     * @param string|null $id   Deprecated: use BranchOptions.
+     * @param bool $cloneParent Deprecated: use BranchOptions
      *
      * @return Activity
      */
-    public function branch($title, $id = null, $cloneParent = true)
-    {
-        $id = $id ?: $this->sanitizeId($title);
-        $body = ['name' => $id, 'title' => $title];
-        if (!$cloneParent) {
-            $body['clone_parent'] = false;
+    public function branch($options, $id = null, $cloneParent = true)
+    {
+        if ($options instanceof BranchOptions) {
+            $body = $options->toArray();
+        } elseif (is_string($options)) {
+            \trigger_error('The previous arguments list has been replaced by a single BranchOptions argument', E_USER_DEPRECATED);
+            $title = $options;
+            $id = $id ?: $this->sanitizeId($title);
+            $body = ['name' => $id, 'title' => $title];
+            if (!$cloneParent) {
+                $body['clone_parent'] = false;
+            }
+        } else {
+            throw new \InvalidArgumentException('The first argument must be a BranchOptions object or a string');
         }
 
         return $this->runLongOperation('branch', 'post', $body);

src/Model/Environment/BranchOptions.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Platformsh\Client\Model\Environment;
+
+final class BranchOptions {
+    /** @var string */
+    private $id;
+    /** @var string|null */
+    private $title;
+    /** @var bool|null */
+    private $clone_parent;
+    /** @var string|null */
+    private $type;
+
+    public function __construct($id, $title = null, $cloneParent = null, $type = null)
+    {
+        $this->id = $id;
+        $this->title = $title;
+        $this->clone_parent = $cloneParent;
+        $this->type = $type;
+    }
+
+    public function toArray() {
+        $arr = [];
+        foreach ($this as $key => $value) {
+            if ($value !== null) {
+                $arr[$key] = $value;
+            }
+        }
+        return $arr;
+    }
+}