Merge branch 'master' of github.com:Codegyre/Robo

# Conflicts: # robo.phar
elmpp · Aug 4, 2016 · 443ba7e · 443ba7e
2 parents 6f29ed9 + 16ad208
commit 443ba7e
Show file tree

Hide file tree

Showing 35 changed files with 389 additions and 438 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,15 +3,16 @@
 #### 1.0.0
 
 * [Collection] Add tasks to a collection, and implement them as a group with rollback
-   * Use `$task->addToCollection($collection);` instead of `$task->run();` during chained configuration to ad a task to a collection.
-   * Tasks may also be added to a collection via `$collection->add($task);`
+   * Tasks may be added to a collection via `$collection->add($task);`
    * `$collection->run();` runs all tasks in the collection
    * `$collection->addCode(function () { ... } );` to add arbitrary code to a collection
    * `$collection->progressMessage(...);` will log a message
    * `$collection->rollback($task);` and `$collection->rollbackCode($callable);` add a rollback function to clean up after a failed task
    * `$collection->completion($task);` and `$collection->completionCode($callable);` add a function that is called once the collection completes or rolls back.
    * `$collection->before();` and `$collection->after();` can be used to add a task or function that runs before or after (respectively) the specified named task. To use this feature, tasks must be given names via an optional `$taskName` parameter when they are added.
    * Collections may be added to collections, if desired. 
+* [CollectionBuilder] Create tasks and add them to a collection in a single operation.
+   * `$this->collectionBuilder()->taskExec('pwd')->taskExec('ls')->run()`
 * Add output formatters
    * If a Robo command returns a string, or a `Result` object with a `$message`, then it will be printed
    * Commands may be annotated to describe output formats that may be used
@@ -22,10 +23,10 @@
    * *Breaking* Tasks that use other tasks must also use `$this->task('taskName');` instead of `new TaskClass();` when creating task objects to call.
 * [Extract] task added
 * [Pack] task added
-* [TmpFile] task added
+* [TmpDir], [WorkDir] and [TmpFile] tasks added
 * Support standalone Robo scripts that allows scripts starting with `#!/usr/bin/env robo` to define multiple robo commands.  Use `#!/usr/bin/env robo run` to define a single robo command implemented by the `run()` method.
 * Provide ProgresIndicatorAwareInterface and ProgressIndicatorAwareTrait that make it easy to add progress indicators to tasks
-* Add --simulate mode that causes tasks to print what they would have done, but make no changed
+* Add --simulate mode that causes tasks to print what they would have done, but make no changes
 * Add `robo generate:task` code-generator to make new stack-based task wrappers around existing classes
 * Add `robo sniff` by @dustinleblanc. Runs the PHP code sniffer followed by the code beautifier, if needed.
 * Implement ArrayInterface for Result class, so result data may be accessed like an array 

diff --git a/RoboFile.php b/RoboFile.php
@@ -147,7 +147,7 @@ public function versionBump($version = '')
      */
     public function docs()
     {
-        $collection = $this->collection();
+        $collection = $this->collectionBuilder();
         $collection->progressMessage('Generate documentation from source code.');
         $files = Finder::create()->files()->name('*.php')->in('src/Task');
         $docs = [];
@@ -169,7 +169,7 @@ class_exists($class = "Robo\\Task\\$ns\\$class");
         ksort($docs);
 
         foreach ($docs as $ns => $tasks) {
-            $taskGenerator = $this->taskGenDoc("docs/tasks/$ns.md");
+            $taskGenerator = $collection->taskGenDoc("docs/tasks/$ns.md");
             $taskGenerator->filterClasses(function (\ReflectionClass $r) {
                 return !($r->isAbstract() || $r->isTrait()) && $r->implementsInterface('Robo\Contract\TaskInterface');
             })->prepend("# $ns Tasks");
@@ -220,7 +220,7 @@ function (\ReflectionMethod $m, $text) {
 
                     return $text ? ' ' . trim(strtok($text, "\n"), "\n") : '';
                 }
-            )->addToCollection($collection);
+            );
         }
         $collection->progressMessage('Documentation generation complete.');
         return $collection->run();
@@ -252,16 +252,23 @@ public function publish()
      */
     public function pharBuild()
     {
-        $collection = $this->collection();
-
         // Make sure to remove dev files before finding the files to pack into
-        // the phar.
+        // the phar.  This must therefore be done outside the collection,
+        // as the files to pack are found when the collection is built.
         $this->taskComposerInstall()
             ->noDev()
             ->printed(false)
             ->run();
 
-        $packer = $this->taskPackPhar('robo.phar');
+        $collection = $this->collectionBuilder();
+
+        // revert back phar dependencies on completion
+        $collection->completion($this
+            ->taskComposerInstall()
+            ->printed(false)
+        );
+
+        $packer = $collection->taskPackPhar('robo.phar');
         $files = Finder::create()->ignoreVCS(true)
             ->files()
             ->name('*.php')
@@ -280,8 +287,9 @@ public function pharBuild()
             $packer->addFile($file->getRelativePathname(), $file->getRealPath());
         }
         $packer->addFile('robo', 'robo')
-            ->executable('robo')
-            ->addToCollection($collection);
+            ->executable('robo');
+
+        $collection->addTask($packer);
 
         return $collection->run();
     }
@@ -306,7 +314,7 @@ public function pharInstall()
      */
     public function pharPublish()
     {
-        $this->pharBuild()->run();
+        $this->pharBuild();
 
         $this->_rename('robo.phar', 'robo-release.phar');
         return $this->collectionBuilder()

diff --git a/docs/collections.md b/docs/collections.md
@@ -30,7 +30,7 @@ Examples of adding different kinds of tasks to a collection are provided below.
 ```php
 <?php
   $collection->add(
-    $this->taskOther($work)
+    $this->taskExec('ls')
   );
 ?>
 ```
@@ -77,8 +77,8 @@ class RoboFile extends \Robo\Tasks
     {
         $current_branch = exec('git rev-parse --abbrev-ref HEAD');
 
-        $builder = $this->builder();
-        $builder->taskGitStack()
+        $collection = $this->collectionBuilder();
+        $collection->taskGitStack()
             ->checkout('site')
             ->merge('master')
         ->completion($this->taskGitStack()->checkout($current_branch))
@@ -87,7 +87,7 @@ class RoboFile extends \Robo\Tasks
         ->completion($this->taskFilesystemStack()->remove('docs/changelog.md'))
         ->taskExec('mkdocs gh-deploy');
 
-        return $builder;
+        return $collection;
     }
 }
 ?>
@@ -119,38 +119,63 @@ Since the concept of temporary objects that are cleaned up  on failure is a comm
 
 ### Temporary Directories
 
-It is recommended that operations that perform multiple filesystem operations should, whenever possible, do most of their work in a temporary directory. Temporary directories are created by `$this->taskTmpDir()`, and are automatically be removed when the collection completes or rolls back. Move the temporary directory to another location to prevent its deletion.
+It is recommended that operations that perform multiple filesystem operations should, whenever possible, do most of their work in a temporary directory. Temporary directories are created by `$this->taskTmpDir()`, and are automatically be removed when the collection completes or rolls back. As an added convenience, the CollectionBuilder class has a `tmpDir()` method that creates a temporary directory via `taskTmpDir()`, and then returns the path to the temporary directory.
 
 ``` php
 <?php
 class RoboFile extends \Robo\Tasks
 {
     function myOperation()
     {
-        $collection = $this->collection();
+        $collection = $this->collectionBuilder();
 
         // Create a temporary directory, and fetch its path.
-        $work = $this->taskTmpDir()
-          ->addToCollection($collection)
-          ->getPath();
+        $work = $collection->tmpDir();
 
-        $this->taskOther($work)
-          ->addToCollection($collection);
+        $collection
+          ->taskWriteToFile("$work/README.md")
+            ->line('-----')
+            ->line(date('Y-m-d').' Generated file: do not edit.')
+            ->line('----');
+
+        // If all of the preceding tasks succeed, then rename the temporary 
+        // directory to its final name.
+        $collection->taskFilesystemStack()
+          ->rename($work, 'destination');
+
+        return $collection->run();
+    }
+}
+?>
+```
+
+In the previous example, the path to the temporary directory is stored in the variable `$work`, and is passed as needed to the parameters of the other tasks as they are added to the collection. After the task collection is run, the temporary directory will be automatically deleted. In the example above, the temporary directory is renamed by the last task in the collection. This allows the working directory to persist; the collection will still attempt to remove the working directory, but no errors will be thrown if it no longer exists in its original location. Following this pattern allows Robo scripts to easily and safely do work that cleans up after itself on failure, without introducing a lot of branching or additional error recovery code.  This paradigm is common enough to warrant a shortcut method of accomplishing the same thing.  The example below is identical to the one above, save for the fact that it uses the `workDir()` method instead of `tmpDir()`.  `workDir()` renames the temporary directory to its final name if the collection completes; any directory that exists in the same location will be overwritten at that time, but will persist if the collection roles back.
 
+``` php
+<?php
+class RoboFile extends \Robo\Tasks
+{
+    function myOperation()
+    {
+        $collection = $this->collectionBuilder();
+
+        // Create a temporary directory, and fetch its path.
         // If all of the tasks succeed, then rename the temporary directory
         // to its final name.
-        $this->taskFilesystemStack()
-          ->rename($work, 'destination')
-          ->addToCollection($collection);
+        $work = $collection->workDir('destination');
+
+        $collection
+          ->taskWriteToFile("$work/README.md")
+            ->line('-----')
+            ->line(date('Y-m-d').' Generated file: do not edit.')
+            ->line('----');
 
-        $result = $collection->run();
+        return $collection->run();
     }
 }
 ?>
 ```
 
-In the previous example, the path to the temporary directory is stored in the variable `$work`, and is passed as needed to the parameters of the other tasks as they are added to the collection. After the task collection is run, the temporary directory will be automatically deleted. In the example above, the temporary directory is renamed by the last task in the collection. This allows the working directory to persist; the collection will still attempt to remove the working directory, but no errors will be thrown if it no longer exists in its original location. Following this pattern allows Robo scripts to easily and safely do work that cleans up after itself on failure, without introducing a lot of branching or additional error recovery code.
-
 Temporary directories may also be created via the shortcut `$this->_tmpDir();`. Temporary directories created in this way are deleted when the script terminates.
 
 ### Temporary Files

diff --git a/docs/tasks/ApiGen.md b/docs/tasks/ApiGen.md
@@ -51,11 +51,9 @@ $this->taskApiGen('./apigen.neon')
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 * `dir($dir)`  changes working directory of command
 * `printed($arg)`  Should command output be printed
 * `arg($arg)`  Pass argument to executable

diff --git a/docs/tasks/Archive.md b/docs/tasks/Archive.md
@@ -33,11 +33,9 @@ $this->taskExtract($archivePath)
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
 ## Pack
 
@@ -64,9 +62,7 @@ $this->taskPack(
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
diff --git a/docs/tasks/Assets.md b/docs/tasks/Assets.md
@@ -65,11 +65,9 @@ This will execute as:
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
 ## Less
 
@@ -119,11 +117,9 @@ inject the name there.
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
 ## Minify
 
@@ -154,11 +150,9 @@ Please install additional dependencies to use:
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
 ## Scss
 
@@ -195,9 +189,7 @@ inject the name there.
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
diff --git a/docs/tasks/Base.md b/docs/tasks/Base.md
@@ -29,11 +29,9 @@ if ($this->taskExec('phpunit .')->run()->wasSuccessful()) {
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 * `dir($dir)`  changes working directory of command
 * `printed($arg)`  Should command output be printed
 * `arg($arg)`  Pass argument to executable
@@ -69,11 +67,9 @@ $this->taskExecStack()
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 * `dir($dir)`  changes working directory of command
 * `printed($arg)`  Should command output be printed
 
@@ -105,11 +101,9 @@ $this->taskParallelExec()
 * `logger()` 
 * `setLogger($logger)`  Sets a logger.
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
 ## SymfonyCommand
 
@@ -138,11 +132,9 @@ $this->taskSymfonyCommand(new ModelGeneratorCommand())
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)` 
 
 ## Watch
 
@@ -167,9 +159,7 @@ $this->taskWatch()
 * `setLogger($logger)`  Sets a logger.
 * `progressIndicatorSteps()` 
 * `setProgressIndicator($progressIndicator)` 
+* `setConfig($config)`  Set the config management object.
+* `getConfig()`  Get the config management object.
 * `inflect($parent)`  Ask the provided parent class to inject all of the dependencies
-* `addToCollection($collection, $taskName = null, $rollbackTask = null)` 
-* `addAsRollback($collection)` 
-* `addAsCompletion($collection)` 
-* `addToCollectionAndIgnoreErrors($collection, $taskName = null)`