MDL-67789 xapi: Add support to save content state

lib/xapi/classes/handler.php

@@ -14,34 +14,28 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+namespace core_xapi;
+
+use core_xapi\local\state;
+use core_xapi\local\statement;
+use core_xapi\xapi_exception;
+
 /**
- * The core_xapi statement validation and tansformation.
+ * Class handler handles basic xAPI statements and states.
  *
  * @package    core_xapi
  * @since      Moodle 3.9
  * @copyright  2020 Ferran Recio
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
-namespace core_xapi;
-
-use core_xapi\local\statement;
-use core_xapi\xapi_exception;
-use stdClass;
-
-defined('MOODLE_INTERNAL') || die();
-
-/**
- * Class handler handles basic xapi statements.
- *
- * @package core_xapi
- * @copyright  2020 Ferran Recio
- */
 abstract class handler {
 
     /** @var string component name in frankenstyle. */
     protected $component;
 
+    /** @var state_store the state_store instance. */
+    protected $statestore;
+
     /**
      * Constructor for a xAPI handler base class.
      *
@@ -49,6 +43,7 @@ abstract class handler {
      */
     final protected function __construct(string $component) {
         $this->component = $component;
+        $this->statestore = $this->get_state_store();
     }
 
     /**
@@ -59,13 +54,24 @@ abstract class handler {
      * @throws xapi_exception
      */
     final public static function create(string $component): self {
-        $classname = "\\$component\\xapi\\handler";
-        if (class_exists($classname)) {
+        if (self::supports_xapi($component)) {
+            $classname = "\\$component\\xapi\\handler";
             return new $classname($component);
         }
         throw new xapi_exception('Unknown handler');
     }
 
+    /**
+     * Whether a component supports (and implements) xAPI.
+     *
+     * @param string $component the component name in frankenstyle.
+     * @return bool true if the given component implements xAPI handler; false otherwise.
+     */
+    final public static function supports_xapi(string $component): bool {
+        $classname = "\\$component\\xapi\\handler";
+        return class_exists($classname);
+    }
+
     /**
      * Convert a statement object into a Moodle xAPI Event.
      *
@@ -115,4 +121,104 @@ abstract class handler {
         }
         return $result;
     }
+
+    /**
+     * Validate a xAPI state.
+     *
+     * Check if the state is valid for this handler.
+     *
+     * This method is used also for the state get requests so the validation
+     * cannot rely on having state data.
+     *
+     * Note: this method must be overridden by the plugins which want to use xAPI states.
+     *
+     * @param state $state
+     * @return bool if the state is valid or not
+     */
+    abstract protected function validate_state(state $state): bool;
+
+    /**
+     * Process a state save request.
+     *
+     * @param state $state the state object
+     * @return bool if the state can be saved
+     */
+    public function save_state(state $state): bool {
+        if (!$this->validate_state($state)) {
+            throw new xapi_exception('The state is not accepted, so it cannot be saved');
+        }
+        return $this->statestore->put($state);
+    }
+
+    /**
+     * Process a state save request.
+     *
+     * @param state $state the state object
+     * @return state|null the resulting loaded state
+     */
+    public function load_state(state $state): ?state {
+        if (!$this->validate_state($state)) {
+            throw new xapi_exception('The state is not accepted, so it cannot be loaded');
+        }
+        $state = $this->statestore->get($state);
+        return $state;
+    }
+
+    /**
+     * Process a state delete request.
+     *
+     * @param state $state the state object
+     * @return bool if the deletion is successful
+     */
+    public function delete_state(state $state): bool {
+        if (!$this->validate_state($state)) {
+            throw new xapi_exception('The state is not accepted, so it cannot be deleted');
+        }
+        return $this->statestore->delete($state);
+    }
+
+    /**
+     * Delete all states from this component.
+     *
+     * @param string|null $itemid
+     * @param int|null $userid
+     * @param string|null $stateid
+     * @param string|null $registration
+     */
+    public function wipe_states(
+        ?string $itemid = null,
+        ?int $userid = null,
+        ?string $stateid = null,
+        ?string $registration = null
+    ): void {
+        $this->statestore->wipe($itemid, $userid, $stateid, $registration);
+    }
+
+    /**
+     * Reset all states from this component.
+     *
+     * @param string|null $itemid
+     * @param int|null $userid
+     * @param string|null $stateid
+     * @param string|null $registration
+     */
+    public function reset_states(
+        ?string $itemid = null,
+        ?int $userid = null,
+        ?string $stateid = null,
+        ?string $registration = null
+    ): void {
+        $this->statestore->reset($itemid, $userid, $stateid, $registration);
+    }
+
+    /**
+     * Return a valor state store for this component.
+     *
+     * Plugins may override this method is they want to use a different
+     * state store class.
+     * @return state_store the store to use to get/put/delete states.
+     */
+    public function get_state_store(): state_store {
+        return new state_store($this->component);
+    }
 }