Deprecate Environment actions returning a single activity

Author: pjcdawkins

src/Model/ApiResourceBase.php

@@ -393,6 +393,7 @@ public function runOperation($op, $method = 'POST', array $body = [])
      */
     protected function runLongOperation($op, $method = 'post', array $body = [])
     {
+        @trigger_error('This method is deprecated as actions may return multiple activities. Use runOperation() if possible.', E_USER_DEPRECATED);
         $result = $this->runOperation($op, $method, $body);
         $activities = $result->getActivities();
         if (count($activities) !== 1) {

src/Model/Environment.php

@@ -301,6 +301,9 @@ public function getPublicUrl()
      *                            Leave this empty to use the default type for new
      *                            environments ('development' at the time of writing).
      *
+     * @deprecated use instead: runOperation('branch', 'POST', ['name' => 'git-branch-name', 'title' => 'Untitled', 'clone_parent' => true, 'type' => 'development'])
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function branch($title, $id = null, $cloneParent = true, $type = null)
@@ -380,6 +383,9 @@ public function isActive()
      *
      * @throws EnvironmentStateException
      *
+     * @deprecated use instead: runOperation('activate')
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function activate()
@@ -394,7 +400,7 @@ public function activate()
     /**
      * Deactivate the environment.
      *
-     * @deprecated use runOperation('deactivate') instead
+     * @deprecated use instead: runOperation('deactivate')
      * @see Environment::runOperation()
      *
      * @return Activity
@@ -409,6 +415,9 @@ public function deactivate()
      *
      * @throws OperationUnavailableException
      *
+     * @deprecated use instead: runOperation('merge')
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function merge()
@@ -429,6 +438,9 @@ public function merge()
      *
      * @throws \InvalidArgumentException
      *
+     * @deprecated use instead: runOperation('synchronize', 'POST', ['synchronize_data' => false, 'synchronize_code' => false, 'rebase' => false])
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function synchronize($data = false, $code = false, $rebase = false)
@@ -472,6 +484,9 @@ public static function wrapCollection(array $data, $baseUrl, ClientInterface $cl
      *   during the backup. So it reduces downtime, at the risk of backing up
      *   data in an inconsistent state.
      *
+     * @deprecated use instead: runOperation('backup', 'POST', ['safe' => true])
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function backup($unsafeAllowInconsistent = false)
@@ -587,6 +602,9 @@ public function getRouteUrls()
      *   An array of files that may be used in conjunction or in place of the
      *   repository parameter info.
      *
+     * @deprecated use instead: runOperation('initialize', 'POST', ['profile' => '', 'repository' => ''])
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function initialize($profile, $repository, $files=[])
@@ -650,6 +668,9 @@ public function addUser($user, $role, $byUuid = true)
     /**
      * Redeploy the environment.
      *
+     * @deprecated use instead: runOperation('redeploy')
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function redeploy()
@@ -755,6 +776,9 @@ public function runSourceOperation(string $name, array $variables = []): Result
      * @see Environment::redeploy()
      * @see Environment::status
      *
+     * @deprecated use instead: runOperation('pause')
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function pause()
@@ -767,6 +791,9 @@ public function pause()
      *
      * @see Environment::status
      *
+     * @deprecated use instead: runOperation('resume')
+     * @see Environment::runOperation()
+     *
      * @return Activity
      */
     public function resume()