QueryEngine interface (#8215)

This defines the QueryEngine interface for querying module data from PHP.

A QueryEngine is an entity which represents a set of data and
the ability to query against them.

Queries are divided into 2 phases, filtering the data down to
a set of CandIDs, and retrieving the data for a known set of
CandID/SessionIDs.

There is usually one query engine per module that deals with
candidate data.

CHANGELOG.md

@@ -11,7 +11,7 @@ changes in the following format: PR #1234***
 ## LORIS 25.0 (Release Date: ????-??-??)
 ### Core
 #### Features
-- placeholder 
+- Added new interface intended to be used for querying module data from PHP (PR #8215) 
 
 #### Updates and Improvements
 - Rename subproject to Cohort (PR #7817)
@@ -77,7 +77,6 @@ changes in the following format: PR #1234***
 #### API
 - Ability to use PSCID instead of the CandID in the candidates API (PR #8138)
 
-
 ## LORIS 24.0 (Release Date: 2022-03-24)
 ### Core
 #### Features

src/Data/Query/Criteria.php

@@ -0,0 +1,17 @@
+<?php
+namespace LORIS\Data\Query;
+
+/**
+ * A Criteria represents a comparison to compare a data dictionary
+ * against for the purposes of querying.
+ *
+ * Generally, the operator is defined by the class type and the
+ * the value by getValue().
+ */
+interface Criteria
+{
+    /**
+     * Get the value of the comparison.
+     */
+    public function getValue();
+}

src/Data/Query/Criteria/EndsWith.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * An EndsWith criteria represents a search for values that
+ * the string representation of ends with a certain value.
+ */
+class EndsWith implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Construct an EndsWith criteria
+     *
+     * @param mixed $suffix The suffix that values must end with
+     */
+    public function __construct(private $suffix)
+    {
+    }
+
+    public function getValue()
+    {
+        return $this->suffix;
+    }
+}

src/Data/Query/Criteria/Equal.php

@@ -0,0 +1,28 @@
+<?php
+namespace LORIS\Data\Query\Criteria;
+
+use LORIS\Data\Query\Criteria;
+
+/**
+ * An Equal criteria matches data which equals a given
+ * value.
+ */
+class Equal implements Criteria
+{
+    /**
+     * Construct an Equal criteria.
+     *
+     * @param mixed $value The value that must be equal
+     */
+    public function __construct(private $value)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+}

src/Data/Query/Criteria/GreaterThan.php

@@ -0,0 +1,26 @@
+<?php
+namespace LORIS\Data\Query\Criteria;
+
+use LORIS\Data\Query\Criteria;
+
+/**
+ * A GreaterThan Criteria specifies that an item must be strictly
+ * > a given value.
+ */
+class GreaterThan implements Criteria
+{
+    /**
+     * Construct a GreaterThan comparison
+     */
+    public function __construct(protected $value)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+}

src/Data/Query/Criteria/GreaterThanOrEqual.php

@@ -0,0 +1,26 @@
+<?php
+namespace LORIS\Data\Query\Criteria;
+
+use LORIS\Data\Query\Criteria;
+
+/**
+ * A GreaterThanOrEqual criteria denotes a criteria that must
+ * be >= a given value.
+ */
+class GreaterThanOrEqual implements Criteria
+{
+    /**
+     * Constructor
+     */
+    public function __construct(protected $value)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+}

src/Data/Query/Criteria/In.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * In represents a criteria specifying that the value must be
+ * in a given set of choices.
+ */
+class In implements \LORIS\Data\Query\Criteria
+{
+    protected array $val;
+
+    /**
+     * Construct an In criteria.
+     *
+     * @param $val The set that the value must be in.
+     */
+    public function __construct(...$val)
+    {
+        $this->val = $val;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->val;
+    }
+}

src/Data/Query/Criteria/IsNull.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * Criteria to compare if a value is null
+ */
+class IsNull implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Constructor
+     */
+    public function __construct()
+    {
+    }
+
+    /**
+     * Stub to implement Criteria interface
+     */
+    public function getValue()
+    {
+        return null;
+    }
+}

src/Data/Query/Criteria/LessThan.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * Criteria to specify that a given item must be strictly <
+ * a comparison value.
+ */
+class LessThan implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Constructor
+     */
+    public function __construct(protected $value)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+}

src/Data/Query/Criteria/LessThanOrEqual.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * A Criteria to determine that a DictionaryItem must be <= a
+ * given value
+ */
+class LessThanOrEqual implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Constructor
+     *
+     * @param mixed $value The comparison value
+     */
+    public function __construct(protected $value)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+}

src/Data/Query/Criteria/NotEqual.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+use LORIS\Data\Query\Criteria;
+
+/**
+ * A NotEqual Criteria specifies that the value should be compared
+ * against not being a given value.
+ */
+class NotEqual implements Criteria
+{
+    /**
+     * Construct a NotEqual criteria
+     */
+    public function __construct(protected $value)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+}

src/Data/Query/Criteria/NotNull.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * A Criteria to specify querying for items that must not be
+ * null
+ */
+class NotNull implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Constructor
+     */
+    public function __construct()
+    {
+    }
+
+    /**
+     * Stub to implement Criteria interface
+     */
+    public function getValue()
+    {
+        return null;
+    }
+}

src/Data/Query/Criteria/StartsWith.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * A Criteria to specify that the string serialization must
+ * start with a given prefix.
+ */
+class StartsWith implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Construct a StartsWith
+     */
+    public function __construct(protected $prefix)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->prefix;
+    }
+}

src/Data/Query/Criteria/Substring.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace LORIS\Data\Query\Criteria;
+
+/**
+ * Criteria to specify that the string serialization of a
+ * value must contain a substring.
+ */
+class Substring implements \LORIS\Data\Query\Criteria
+{
+    /**
+     * Construct a Substring criteria
+     *
+     * @param string $substr The substring that must be contained in
+     *                       the value
+     */
+    public function __construct(protected $substr)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getValue()
+    {
+        return $this->substr;
+    }
+}