Added registerTask method and added names and descriptions to media tasks

Signed-off-by: Bastian Schwarz <bastian@codename-php.de>

Author: bastianschwarz

src/functions/All.php

@@ -19,6 +19,8 @@
 
 use Closure;
 use de\codenamephp\deployer\base\MissingConfigurationException;
+use de\codenamephp\deployer\base\task\iTaskWithDescription;
+use de\codenamephp\deployer\base\task\iTaskWithName;
 use Deployer\Deployer;
 use Deployer\Host\Host;
 use Deployer\Host\Localhost;
@@ -153,6 +155,11 @@ public function task(string $name, callable|array|\de\codenamephp\deployer\base\
     return \Deployer\task($name, $body);
   }
 
+  public function registerTask(iTaskWithName $task) : void {
+    $registeredTask = $this->task($task->getName(), $task);
+    if($task instanceof iTaskWithDescription) $registeredTask->desc($task->getDescription());
+  }
+
   public function upload(string $source, string $destination, array $config = []) : void {
     upload($source, $destination, $config);
   }

src/functions/iTask.php

@@ -17,6 +17,7 @@
 
 namespace de\codenamephp\deployer\base\functions;
 
+use de\codenamephp\deployer\base\task\iTaskWithName;
 use Deployer\Task\Task;
 
 /**
@@ -33,4 +34,13 @@ interface iTask {
    * @param \de\codenamephp\deployer\base\task\iTask|callable|array|null $body Callable task, array of other tasks names or nothing to get a defined tasks
    */
   public function task(string $name, \de\codenamephp\deployer\base\task\iTask|callable|array|null $body = null) : Task;
+
+  /**
+   * Registers a task with deployer. The task itself is used as body and the name is the identifier that the task is registered with. Implementations should
+   * support the iTaskWithDescription interface and add the description as well if the task has the interface.
+   *
+   * @param iTaskWithName $task The task to register with deployer
+   * @return void
+   */
+  public function registerTask(iTaskWithName $task) : void;
 }

src/task/iTaskWithDescription.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+/*
+ *   Copyright 2022 Bastian Schwarz <bastian@codename-php.de>.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+namespace de\codenamephp\deployer\base\task;
+
+/**
+ * Interface to automatically add a description for the task when used with our custom registerTask() method. This is what you would add with the desc() method
+ */
+interface iTaskWithDescription extends iTask {
+
+  /**
+   * Gets the description of the task that will be shown in the task list. This is what you would pass to the desc() function.
+   *
+   * @return string
+   */
+  public function getDescription() : string;
+}

src/task/iTaskWithName.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+/*
+ *   Copyright 2022 Bastian Schwarz <bastian@codename-php.de>.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+namespace de\codenamephp\deployer\base\task;
+
+/**
+ * Interface that is needed when our custom registerTask() method is used. This is the name the task is registered with to deployer.
+ */
+interface iTaskWithName extends iTask {
+
+  /**
+   * The name the task is registered with. This is what you would pass as the first parameter to task()
+   *
+   * @return string
+   */
+  public function getName() : string;
+}

src/task/media/Copy.php

@@ -26,7 +26,8 @@
 use de\codenamephp\deployer\base\MissingConfigurationException;
 use de\codenamephp\deployer\base\ssh\client\iClient;
 use de\codenamephp\deployer\base\ssh\client\StaticProxy;
-use de\codenamephp\deployer\base\task\iTask;
+use de\codenamephp\deployer\base\task\iTaskWithDescription;
+use de\codenamephp\deployer\base\task\iTaskWithName;
 use de\codenamephp\deployer\base\transferable\iTransferable;
 use de\codenamephp\deployer\base\UnsafeOperationException;
 use Deployer\Exception\RunException;
@@ -37,9 +38,10 @@
  *
  * @psalm-suppress PropertyNotSetInConstructor see https://github.com/vimeo/psalm/issues/4393
  */
-final class Copy implements iTask {
+final class Copy implements iTaskWithName, iTaskWithDescription {
 
   public const OPTION_SOURCE_HOST = 'cpd:media:copy:sourceHost';
+  public const NAME = 'media:copy';
 
   /**
    * @var array<iTransferable>
@@ -65,16 +67,8 @@ public function __construct(array             $transferables,
     );
   }
 
-  /**
-   * @return iTransferable[]
-   */
-  public function getTransferables() : array {
-    return $this->transferables;
-  }
-
-  public function setTransferables(iTransferable ...$transferables) : Copy {
-    $this->transferables = $transferables;
-    return $this;
+  public function getDescription() : string {
+    return 'Copies the media from one remote to another. The copy is done using rsync directly between the hosts.';
   }
 
   /**
@@ -109,4 +103,20 @@ public function __invoke() : void {
       $this->deployerFunctions->runLocally(sprintf('%s "%s"', $sshCommand, sprintf($rsyncCommand, implode(' ', $transferable->getConfig()['options'] ?? []), $sourcePath, $targetPath)));
     }
   }
+
+  public function getName() : string {
+    return self::NAME;
+  }
+
+  /**
+   * @return iTransferable[]
+   */
+  public function getTransferables() : array {
+    return $this->transferables;
+  }
+
+  public function setTransferables(iTransferable ...$transferables) : Copy {
+    $this->transferables = $transferables;
+    return $this;
+  }
 }

src/task/media/Pull.php

@@ -19,7 +19,8 @@
 
 use de\codenamephp\deployer\base\functions\All;
 use de\codenamephp\deployer\base\functions\iDownload;
-use de\codenamephp\deployer\base\task\iTask;
+use de\codenamephp\deployer\base\task\iTaskWithDescription;
+use de\codenamephp\deployer\base\task\iTaskWithName;
 use de\codenamephp\deployer\base\transferable\iTransferable;
 use Deployer\Exception\RunException;
 
@@ -28,7 +29,9 @@
  *
  * @psalm-suppress PropertyNotSetInConstructor see https://github.com/vimeo/psalm/issues/4393
  */
-final class Pull implements iTask {
+final class Pull implements iTaskWithName, iTaskWithDescription {
+
+  public const NAME = 'media:pull';
 
   /**
    * @var array<iTransferable>
@@ -43,16 +46,8 @@ public function __construct(array $transferables, public iDownload $deployerFunc
     $this->setTransferables(...$transferables);
   }
 
-  /**
-   * @return iTransferable[]
-   */
-  public function getTransferables() : array {
-    return $this->transferables;
-  }
-
-  public function setTransferables(iTransferable ...$transferables) : Pull {
-    $this->transferables = $transferables;
-    return $this;
+  public function getDescription() : string {
+    return 'Pull the media from remote to local.';
   }
 
   /**
@@ -66,4 +61,20 @@ public function __invoke() : void {
       $this->deployerFunctions->download($transferable->getRemotePath(), $transferable->getLocalPath(), $transferable->getConfig());
     }
   }
+
+  public function getName() : string {
+    return self::NAME;
+  }
+
+  /**
+   * @return iTransferable[]
+   */
+  public function getTransferables() : array {
+    return $this->transferables;
+  }
+
+  public function setTransferables(iTransferable ...$transferables) : Pull {
+    $this->transferables = $transferables;
+    return $this;
+  }
 }

src/task/media/Push.php

@@ -22,7 +22,8 @@
 use de\codenamephp\deployer\base\hostCheck\DoNotRunOnProduction;
 use de\codenamephp\deployer\base\hostCheck\iHostCheck;
 use de\codenamephp\deployer\base\hostCheck\SkippableByOption;
-use de\codenamephp\deployer\base\task\iTask;
+use de\codenamephp\deployer\base\task\iTaskWithDescription;
+use de\codenamephp\deployer\base\task\iTaskWithName;
 use de\codenamephp\deployer\base\transferable\iTransferable;
 use de\codenamephp\deployer\base\UnsafeOperationException;
 use Deployer\Exception\RunException;
@@ -32,7 +33,9 @@
  *
  * @psalm-suppress PropertyNotSetInConstructor see https://github.com/vimeo/psalm/issues/4393
  */
-final class Push implements iTask {
+final class Push implements iTaskWithName, iTaskWithDescription {
+
+  public const NAME = 'media:push';
 
   /**
    * @var array<iTransferable>
@@ -62,6 +65,14 @@ public function setTransferables(iTransferable ...$transferables) : Push {
     return $this;
   }
 
+  public function getDescription() : string {
+    return 'Pushes media from local to remote.';
+  }
+
+  public function getName() : string {
+    return self::NAME;
+  }
+
   /**
    * Iterates over all transferables and passes the localPath, the remotePath and the config to the upload function. If the stage is production an
    * UnsafeOperationException is thrown since we don't want to push to production.

test/task/media/CopyTest.php

@@ -116,4 +116,12 @@ public function test__invoke() : void {
 
     $this->sut->__invoke();
   }
+
+  public function testGetName() : void {
+    self::assertEquals(Copy::NAME, $this->sut->getName());
+  }
+
+  public function testGetDescription() : void {
+    self::assertEquals('Copies the media from one remote to another. The copy is done using rsync directly between the hosts.', $this->sut->getDescription());
+  }
 }

test/task/media/PullTest.php

@@ -72,4 +72,12 @@ public function test__invoke() : void {
 
     $this->sut->__invoke();
   }
+
+  public function testGetName() : void {
+    self::assertEquals(Pull::NAME, $this->sut->getName());
+  }
+
+  public function testGetDescription() : void {
+    self::assertEquals('Pull the media from remote to local.', $this->sut->getDescription());
+  }
 }

test/task/media/PushTest.php

@@ -71,4 +71,12 @@ public function test__invoke() : void {
 
     $this->sut->__invoke();
   }
+
+  public function testGetName() : void {
+    self::assertEquals(Push::NAME, $this->sut->getName());
+  }
+
+  public function testGetDescription() : void {
+    self::assertEquals('Pushes media from local to remote.', $this->sut->getDescription());
+  }
 }