add abort step and refactored execute definition to be the same for all flow steps

classes/exportable.php

@@ -40,7 +40,7 @@ trait exportable {
     /**
      * Mime type for the downloaded file.
      *
-     * @var string $mimetype
+     * @var string
      */
     private $mimetype = 'application/x-yaml';
 

classes/helper.php

@@ -51,7 +51,7 @@ class helper {
         'wwwroot',
     ];
 
-    /** @var null|bool Is this Windows?  */
+    /** @var null|bool Is this Windows? */
     protected static $iswindows = null;
 
     /**
@@ -260,5 +260,4 @@ public static function obj_empty(\stdClass $obj): bool {
         }
         return true;
     }
-
 }

classes/local/execution/connector_engine_step.php

@@ -44,9 +44,9 @@ public function go(): int {
         switch ($this->proceed_status()) {
             case self::PROCEED_GO:
                 try {
-                    $result = $this->steptype->execute($this);
+                    $result = $this->steptype->execute(new \stdClass);
                     $this->steptype->prepare_vars();
-                    if ($result === true) {
+                    if ($result !== false) {
                         $this->set_status(engine::STATUS_FINISHED);
                     } else {
                         $this->set_status(engine::STATUS_CANCELLED);

classes/local/execution/engine.php

@@ -82,10 +82,10 @@ class engine {
     const STATUS_TERMINATORS = [
         self::STATUS_ABORTED,
         self::STATUS_FINALISED,
-        self::STATUS_CANCELLED
+        self::STATUS_CANCELLED,
     ];
 
-    /** @var  array The queue of steps to be given a run. */
+    /** @var array The queue of steps to be given a run. */
     public $queue;
 
     /** @var dataflow The dataflow defined by the user. */
@@ -121,7 +121,7 @@ class engine {
     /** @var \core\lock\lock|false Lock for the dataflow. Sometimes, only one dataflow of each def should be running at a time. */
     protected $lock = false;
 
-    /** @var \core\lock\lock_factory Factory to produce locks.  */
+    /** @var \core\lock\lock_factory Factory to produce locks. */
     protected static $lockfactory = null;
 
     /** @var bool Has this engine been blocked by a lock. */
@@ -405,6 +405,10 @@ public function execute() {
             }
 
             if ($this->status == self::STATUS_ABORTED) {
+                if (isset($this->run)) {
+                    $this->dataflow->save_config_version();
+                    $this->run->finalise($this->status, $this->export());
+                }
                 return;
             }
         }
@@ -631,7 +635,7 @@ public function set_status(int $status) {
 
         if ($status === self::STATUS_INITIALISED) {
             $this->log('status: ' . self::STATUS_LABELS[$status] . ', config: ' . json_encode(['isdryrun' => $this->isdryrun]));
-        } else if ($status === self::STATUS_FINALISED) {
+        } else if (in_array($status, self::STATUS_TERMINATORS, true)) {
             $this->log('status: ' . self::STATUS_LABELS[$status]);
             $this->log("dumping state..\n" . $this->export());
         } else {

classes/local/execution/engine_step.php

@@ -38,7 +38,7 @@ abstract class engine_step {
     /** @var int Can go forward. Perform execution. */
     const PROCEED_GO = 2;
 
-    /** @var engine Dataflow_execution engine  */
+    /** @var engine Dataflow_execution engine */
     protected $engine;
 
     /** @var int ID as supplied by the step definition */
@@ -50,16 +50,16 @@ abstract class engine_step {
     /** @var base_step The step type definition. */
     protected $steptype;
 
-    /** @var array  The upstream steps. */
+    /** @var array The upstream steps. */
     public $upstreams = [];
 
-    /** @var array  The downstream steps. */
+    /** @var array The downstream steps. */
     public $downstreams = [];
 
     /** @var int The step's current status */
     protected $status;
 
-    /** @var \moodle_exception  Any exception that was thrown by this step. */
+    /** @var \moodle_exception Any exception that was thrown by this step. */
     protected $exception = null;
 
     /**

classes/local/execution/iterators/dataflow_iterator.php

@@ -30,22 +30,22 @@
  */
 class dataflow_iterator implements iterator {
 
-    /** @var steptype $steptype */
+    /** @var steptype */
     protected $steptype;
 
-    /** @var bool $finished */
+    /** @var bool */
     protected $finished = false;
 
-    /** @var mixed $input */
+    /** @var mixed */
     protected $input;
 
-    /** @var flow_engine_step $step */
+    /** @var flow_engine_step */
     protected $step;
 
-    /** @var mixed $value */
+    /** @var mixed */
     protected $value = null;
 
-    /** @var int $iterationcount */
+    /** @var int */
     protected $iterationcount = 0;
 
     /**

classes/local/execution/logging_context.php

@@ -28,10 +28,10 @@
  */
 class logging_context {
 
-    /** @var engine $engine The engine. */
+    /** @var engine The engine. */
     protected $engine = null;
 
-    /** @var engine_step $enginestep The engine step. */
+    /** @var engine_step The engine step. */
     protected $enginestep = null;
 
     /**

classes/local/step/abort_trait.php

@@ -0,0 +1,80 @@
+<?php
+// This file is part of Moodle - https://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Abort Step ..Trait
+ *
+ * This trait allows both flow/connector implementations to share core
+ * functionality. This should be moved to the "main" step type in an ideal
+ * world, and live there directly instead, but will need to be done as such
+ * until support for dual steps are fully supported.
+ *
+ * @package    tool_dataflows
+ * @author     Kevin Pham <[email protected]>
+ * @copyright  Catalyst IT, 2022
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace tool_dataflows\local\step;
+
+trait abort_trait {
+
+    /**
+     * Executes the step, aborting the whole dataflow.
+     *
+     * @param mixed|null $input
+     * @return mixed
+     */
+    public function execute($input = null) {
+        $config = $this->get_config();
+
+        // If a condition was set, it should not abort if the result is false. be evaluated and abort if 'true'.
+        if ($config->condition === false) {
+            return $input;
+        }
+
+        // If the condition was set, print out the results of the expression so it's obvious what it had evaluated to.
+        if ($config->condition !== '') {
+            $rawconfig = $this->get_raw_config();
+            $strresult = var_export($config->condition, true);
+            $this->log("Aborting dataflow due to the expression returning '{$strresult}': {$rawconfig->condition}");
+        }
+
+        // By default, it should abort the step.
+        $this->enginestep->engine->abort();
+        return false;
+    }
+
+    /**
+     * Return the definition of the fields available in this form.
+     *
+     * @return array
+     */
+    public static function form_define_fields(): array {
+        return [
+            'condition' => ['type' => PARAM_TEXT, 'required' => false],
+        ];
+    }
+
+    /**
+     * Custom form inputs
+     *
+     * @param \MoodleQuickForm $mform
+     */
+    public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
+        $mform->addElement('text', 'config_condition', get_string('connector_abort:condition', 'tool_dataflows'));
+    }
+}

classes/local/step/base_step.php

@@ -36,7 +36,7 @@ abstract class base_step {
     /** @var engine_step Engine step made by this class for an execution. */
     protected $enginestep = null;
 
-    /** @var step The step definition use to create the engine step.  */
+    /** @var step The step definition use to create the engine step. */
     protected $stepdef = null;
 
     /** @var array of variables exposed for use from this step. */
@@ -45,7 +45,7 @@ abstract class base_step {
     /**
      * This is autopopulated by the dataflows manager.
      *
-     * @var string $component - The component / plugin this step belongs to.
+     * @var string - The component / plugin this step belongs to.
      */
     protected $component = 'tool_dataflows';
 
@@ -662,6 +662,17 @@ protected function get_config(): \stdClass {
         return $this->stepdef->config;
     }
 
+    /**
+     * Get the step's (definition) raw config
+     *
+     * Helper method to reduce the complexity when authoring step types.
+     *
+     * @return  \stdClass configuration object
+     */
+    protected function get_raw_config(): \stdClass {
+        return $this->stepdef->get_raw_config();
+    }
+
     /**
      * Returns whether the engine's run is dry
      *

classes/local/step/connector_abort.php

@@ -0,0 +1,35 @@
+<?php
+// This file is part of Moodle - https://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace tool_dataflows\local\step;
+
+/**
+ * 'Abort if' step
+ *
+ * @package    tool_dataflows
+ * @author     Kevin Pham <[email protected]>
+ * @copyright  Catalyst IT, 2022
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class connector_abort extends connector_step {
+    use abort_trait;
+
+    /** @var int[] number of output flows (min, max). */
+    protected $outputflows = [0, 1];
+
+    /** @var int[] number of output connectors (min, max) */
+    protected $outputconnectors = [0, 1];
+}

classes/local/step/connector_curl.php

@@ -203,9 +203,10 @@ public function validate_for_run() {
      *
      * Performs a curl call according to given parameters.
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
         // Get variables.
         $config = $this->get_config();
         $method = $config->method;

classes/local/step/connector_debug_file_display.php

@@ -33,9 +33,10 @@ class connector_debug_file_display extends connector_step {
      *
      * This will take the contents of the given stream name, and dump its contents via mtrace.
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
         $config = $this->enginestep->stepdef->config;
 
         $streamname = $this->enginestep->engine->resolve_path($config->streamname);

classes/local/step/connector_debugging.php

@@ -32,9 +32,10 @@ class connector_debugging extends connector_step {
      *
      * This will logs the input via debugging and passes the input value as-is to the output.
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
         // TODO: Reach in and output the result of an expression via a debugging call.
         return true;
     }

classes/local/step/connector_email.php

@@ -59,9 +59,10 @@ public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
     /**
      * Sends the email.
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
 
         // Do not execute operations during a dry run.
         if ($this->enginestep->engine->isdryrun) {

classes/local/step/connector_file_exists.php

@@ -54,9 +54,10 @@ public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
     /**
      * Executes the step
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
         $config = $this->get_config();
 
         $path = $this->enginestep->engine->resolve_path($config->path);

classes/local/step/connector_s3.php

@@ -94,9 +94,10 @@ public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
      *
      * This will take the input and perform S3 interaction functions.
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
         global $CFG;
         // Engine step contains the execution context, configuration, variables etc.
 

classes/local/step/connector_sns_notify.php

@@ -69,9 +69,10 @@ public function form_add_custom_inputs(\MoodleQuickForm &$mform) {
      *
      * This will take the input and perform S3 interaction functions.
      *
-     * @return bool Returns true if successful, false otherwise.
+     * @param  mixed|null $input
+     * @return mixed
      */
-    public function execute(): bool {
+    public function execute($input = null) {
         global $CFG;
 
         try {