From 0767621e0afe35f7cc06aaa9606dc3e231b65f7f Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Thu, 26 May 2022 20:15:51 +0300
Subject: [PATCH 01/11] feature: legacy TR-1499 html5+figure/figcaption support

---
 qtism/common/utils/Format.php                 |  13 ++
 qtism/data/content/xhtml/html5/Figcaption.php |  36 +++++
 qtism/data/content/xhtml/html5/Figure.php     |  37 +++++
 .../data/content/xhtml/html5/Html5Element.php | 129 ++++++++++++++++++
 .../xhtml/html5/Html5LayoutElement.php        |  82 +++++++++++
 qtism/data/storage/xml/QtiNamespaced.php      |   8 ++
 .../xml/marshalling/ContentMarshaller.php     |   8 ++
 .../marshalling/Html5ElementMarshaller.php    |  84 ++++++++++++
 .../xml/marshalling/Html5LayoutMarshaller.php | 103 ++++++++++++++
 .../xml/marshalling/MarshallerFactory.php     |   4 +
 .../data/storage/xml/versions/QtiVersion.php  |   5 +
 .../storage/xml/versions/QtiVersion220.php    |  13 ++
 .../content/xhtml/html5/FigcaptionTest.php    |  61 +++++++++
 .../data/content/xhtml/html5/FigureTest.php   |  61 +++++++++
 .../xhtml/html5/Html5LayoutElementTest.php    |  68 +++++++++
 .../marshalling/Html5LayoutMarshallerTest.php |  86 ++++++++++++
 16 files changed, 798 insertions(+)
 create mode 100644 qtism/data/content/xhtml/html5/Figcaption.php
 create mode 100644 qtism/data/content/xhtml/html5/Figure.php
 create mode 100644 qtism/data/content/xhtml/html5/Html5Element.php
 create mode 100644 qtism/data/content/xhtml/html5/Html5LayoutElement.php
 create mode 100644 qtism/data/storage/xml/QtiNamespaced.php
 create mode 100644 qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
 create mode 100644 qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
 create mode 100644 test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
 create mode 100644 test/qtismtest/data/content/xhtml/html5/FigureTest.php
 create mode 100644 test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
 create mode 100644 test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php

diff --git a/qtism/common/utils/Format.php b/qtism/common/utils/Format.php
index 3a1cdff37..81ffc5fe0 100644
--- a/qtism/common/utils/Format.php
+++ b/qtism/common/utils/Format.php
@@ -689,4 +689,17 @@ public static function isAriaIdRefs($ariaIdRefs)
 
         return true;
     }
+
+    /**
+     * Is the given string a normalized string (no line break nor tabulation)?
+     *
+     * @param string $string
+     * @return bool
+     */
+    public static function isNormalizedString(string $string): bool
+    {
+        return strpos($string, "\n") === false
+            && strpos($string, "\r") === false
+            && strpos($string, "\t") === false;
+    }
 }
diff --git a/qtism/data/content/xhtml/html5/Figcaption.php b/qtism/data/content/xhtml/html5/Figcaption.php
new file mode 100644
index 000000000..a00290b8a
--- /dev/null
+++ b/qtism/data/content/xhtml/html5/Figcaption.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace qtism\data\content\xhtml\html5;
+
+use qtism\data\content\BlockStatic;
+use qtism\data\content\FlowStatic;
+
+class Figcaption extends Html5LayoutElement implements BlockStatic, FlowStatic
+{
+    public const QTI_CLASS_NAME = 'figcaption';
+
+    public function getQtiClassName(): string
+    {
+        return self::QTI_CLASS_NAME;
+    }
+}
\ No newline at end of file
diff --git a/qtism/data/content/xhtml/html5/Figure.php b/qtism/data/content/xhtml/html5/Figure.php
new file mode 100644
index 000000000..f74c8e192
--- /dev/null
+++ b/qtism/data/content/xhtml/html5/Figure.php
@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
+ *
+ * @author Julien Sébire <julien@taotesting.com>
+ * @license GPLv2
+ */
+
+namespace qtism\data\content\xhtml\html5;
+
+/**
+ * The XHTML figure class.
+ */
+class Figure extends Html5LayoutElement
+{
+    public const QTI_CLASS_NAME = 'figure';
+
+    public function getQtiClassName(): string
+    {
+        return self::QTI_CLASS_NAME;
+    }
+}
\ No newline at end of file
diff --git a/qtism/data/content/xhtml/html5/Html5Element.php b/qtism/data/content/xhtml/html5/Html5Element.php
new file mode 100644
index 000000000..43b488d60
--- /dev/null
+++ b/qtism/data/content/xhtml/html5/Html5Element.php
@@ -0,0 +1,129 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Copyright (c) 2020 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
+ *
+ * @author Julien Sébire <julien@taotesting.com>
+ * @license GPLv2
+ */
+
+namespace qtism\data\content\xhtml\html5;
+
+use InvalidArgumentException;
+use qtism\common\utils\Format;
+use qtism\data\content\BodyElement;
+use qtism\data\storage\xml\QtiNamespaced;
+
+/**
+ * The base Html 5 element.
+ */
+abstract class Html5Element extends BodyElement implements QtiNamespaced
+{
+    private const HTML5_NAMESPACE = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
+
+    /**
+     * The title characteristic represents advisory information for the tag,
+     * such as would be appropriate for a tooltip. On a link, this could be the
+     * title or a description of the target resource; on an image, it could be
+     * the image credit or a description of the image; on a paragraph, it could
+     * be a footnote or commentary on the text; on a citation, it could be
+     * further information about the source; on interactive content, it could
+     * be a label for, or instructions for, use of the element; and so forth.
+     * The value is text.
+     *
+     * @var string
+     */
+    private $title = '';
+
+    /**
+     * Create a new Html5 element.
+     *
+     * For the reason why using null instead of default values, see:
+     *
+     * @see https://stackoverflow.com/questions/45320353/php-7-1-nullable-default-function-parameter#45320694
+     *
+     * @param mixed $title A title in the sense of Html title attribute
+     * @param mixed $id A QTI identifier.
+     * @param mixed $class One or more class names separated by spaces.
+     * @param mixed $lang An RFC3066 language.
+     * @param mixed $label A label that does not exceed 256 characters.
+     */
+    public function __construct(
+        $title = null,
+        $id = null,
+        $class = null,
+        $lang = null,
+        $label = null
+    ) {
+        parent::__construct($id ?? '', $class ?? '', $lang ?? '', $label ?? '');
+
+        $this->setTitle($title);
+    }
+
+    /**
+     * @param mixed $title
+     *
+     * @throws InvalidArgumentException when $title cannot be converted to a string.
+     */
+    public function setTitle($title): void
+    {
+        $this->title = $this->acceptNormalizedStringOrNull($title, 'title', '');
+    }
+
+    public function getTitle(): string
+    {
+        return $this->title;
+    }
+
+    public function hasTitle(): bool
+    {
+        return $this->title !== '';
+    }
+
+    protected function acceptNormalizedStringOrNull($value, string $argumentName, string $default = null): string
+    {
+        if ($value === null) {
+            return $default;
+        }
+
+        if (!Format::isNormalizedString($value)) {
+            $given = is_string($value)
+                ? $value
+                : gettype($value);
+
+            throw new InvalidArgumentException(
+                sprintf(
+                    'The "%s" argument must be a non-empty, normalized string (no line break nor tabulation), "%s" given.',
+                    $argumentName,
+                    $given
+                )
+            );
+        }
+
+        return $value ?? $default;
+    }
+
+    public function getTargetNamespace(): string
+    {
+        return self::HTML5_NAMESPACE;
+    }
+
+    public function getTargetNamespacePrefix(): string
+    {
+        return 'qh5';
+    }
+}
\ No newline at end of file
diff --git a/qtism/data/content/xhtml/html5/Html5LayoutElement.php b/qtism/data/content/xhtml/html5/Html5LayoutElement.php
new file mode 100644
index 000000000..cb2aa35d5
--- /dev/null
+++ b/qtism/data/content/xhtml/html5/Html5LayoutElement.php
@@ -0,0 +1,82 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
+ *
+ * @author Julien Sébire <julien@taotesting.com>
+ * @license GPLv2
+ */
+
+namespace qtism\data\content\xhtml\html5;
+
+use InvalidArgumentException;
+use qtism\data\content\FlowCollection;
+use qtism\data\content\FlowStatic;
+use qtism\data\content\FlowTrait;
+
+/**
+ * Generic Html5 layout element.
+ * Holds content management common to:
+ * * figcaption
+ * * figure
+ */
+abstract class Html5LayoutElement extends Html5Element implements FlowStatic
+{
+    use FlowTrait;
+
+    /**
+     * The Flow objects composing the FigCaption.
+     *
+     * @var FlowCollection A collection of Flow objects.
+     * @qtism-bean-property
+     */
+    protected $content;
+
+    /**
+     * @param string|null $title A title in the sense of Html title attribute
+     * @param string|null $id The id of the bodyElement.
+     * @param string|null $class The class of the bodyElement.
+     * @param string|null $lang The language of the bodyElement.
+     * @param string|null $label The label of the bodyElement.
+     * @throws InvalidArgumentException If one of the arguments is invalid.
+     */
+    public function __construct(
+        $title = null,
+        $id = null,
+        $class = null,
+        $lang = null,
+        $label = null
+    ) {
+        parent::__construct($title, $id, $class, $lang, $label);
+        $this->setContent(new FlowCollection());
+    }
+
+    public function getComponents(): FlowCollection
+    {
+        return $this->getContent();
+    }
+
+    public function setContent(FlowCollection $content)
+    {
+        $this->content = $content;
+    }
+
+    public function getContent(): FlowCollection
+    {
+        return $this->content;
+    }
+}
\ No newline at end of file
diff --git a/qtism/data/storage/xml/QtiNamespaced.php b/qtism/data/storage/xml/QtiNamespaced.php
new file mode 100644
index 000000000..c1851ddd3
--- /dev/null
+++ b/qtism/data/storage/xml/QtiNamespaced.php
@@ -0,0 +1,8 @@
+<?php
+
+namespace qtism\data\storage\xml;
+
+interface QtiNamespaced
+{
+    public function getTargetNamespace(): string;
+}
\ No newline at end of file
diff --git a/qtism/data/storage/xml/marshalling/ContentMarshaller.php b/qtism/data/storage/xml/marshalling/ContentMarshaller.php
index d2079bdee..73627d684 100644
--- a/qtism/data/storage/xml/marshalling/ContentMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/ContentMarshaller.php
@@ -52,6 +52,8 @@
 use qtism\data\content\SimpleInline;
 use qtism\data\content\TemplateBlock;
 use qtism\data\content\TemplateInline;
+use qtism\data\content\xhtml\html5\Figcaption;
+use qtism\data\content\xhtml\html5\Figure;
 use qtism\data\content\xhtml\lists\Dl;
 use qtism\data\content\xhtml\lists\DlElement;
 use qtism\data\content\xhtml\lists\Li;
@@ -173,6 +175,8 @@ public function __construct($version)
         'hottext',
         'modalFeedback',
         'feedbackBlock',
+        Figure::QTI_CLASS_NAME,
+        Figcaption::QTI_CLASS_NAME,
     ];
 
     /**
@@ -284,6 +288,10 @@ protected function getChildrenComponents(QtiComponent $component)
             return $component->getContent()->getArrayCopy();
         } elseif ($component instanceof InfoControl) {
             return $component->getContent()->getArrayCopy();
+        } elseif ($component instanceof Figure) {
+            return $component->getContent()->getArrayCopy();
+        } elseif ($component instanceof Figcaption) {
+            return $component->getContent()->getArrayCopy();
         }
     }
 
diff --git a/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
new file mode 100644
index 000000000..ed6e53999
--- /dev/null
+++ b/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Copyright (c) 2013-2020 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
+ *
+ * @author Julien Sébire <julien@taotesting.com>
+ * @license GPLv2
+ */
+
+namespace qtism\data\storage\xml\marshalling;
+
+use DOMElement;
+use qtism\common\utils\Version;
+use qtism\data\content\BodyElement;
+use qtism\data\content\xhtml\html5\Html5Element;
+use qtism\data\QtiComponent;
+use qtism\data\storage\xml\versions\QtiVersion;
+
+/**
+ * Marshalling/Unmarshalling implementation for generic Html5.
+ */
+abstract class Html5ElementMarshaller extends Marshaller
+{
+    /**
+     * Marshall a Html5 element object into a DOMElement object.
+     *
+     * @param QtiComponent $component
+     * @return DOMElement The according DOMElement object.
+     */
+    protected function marshall(QtiComponent $component)
+    {
+        /** @var Html5Element $component */
+
+        $prefix = $component->getTargetNamespacePrefix();
+        $version = QtiVersion::create($this->getVersion());
+        $namespace = $version->getExternalNamespace($prefix);
+
+        $element = static::getDOMCradle()->createElementNS(
+            $namespace,
+            $prefix . ':' . $component->getQtiClassName()
+        );
+
+        $this->fillElement($element, $component);
+
+        if ($component->hasTitle()) {
+            $this->setDOMElementAttribute($element, 'title', $component->getTitle());
+        }
+
+        return $element;
+    }
+
+    /**
+     * Fill $bodyElement with the following Html 5 element attributes:
+     *
+     * * title
+     *
+     * @param BodyElement $bodyElement The bodyElement to fill.
+     * @param DOMElement $element The DOMElement object from where the attribute values must be retrieved.
+     * @throws UnmarshallingException If one of the attributes of $element is not valid.
+     */
+    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element)
+    {
+        if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
+            $title = $this->getDOMElementAttributeAs($element, 'title');
+            $bodyElement->setTitle($title);
+        }
+
+        parent::fillBodyElement($bodyElement, $element);
+    }
+}
\ No newline at end of file
diff --git a/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php b/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
new file mode 100644
index 000000000..876e10dcb
--- /dev/null
+++ b/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
@@ -0,0 +1,103 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Copyright (c) 2013-2020 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
+ *
+ * @author Jérôme Bogaerts <jerome@taotesting.com>
+ * @license GPLv2
+ */
+
+namespace qtism\data\storage\xml\marshalling;
+
+use DOMElement;
+use qtism\common\utils\Version;
+use qtism\data\content\FlowCollection;
+use qtism\data\content\xhtml\html5\Html5Element;
+use qtism\data\QtiComponent;
+use qtism\data\QtiComponentCollection;
+use qtism\data\storage\xml\versions\QtiVersion;
+
+/**
+ * The Marshaller implementation for object elements of the content model.
+ */
+class Html5LayoutMarshaller extends ContentMarshaller
+{
+    /**
+     * @param DOMElement $element
+     * @param QtiComponentCollection $children
+     * @return mixed
+     * @throws UnmarshallingException
+     */
+    protected function unmarshallChildrenKnown(DOMElement $element, QtiComponentCollection $children): QtiComponent
+    {
+        $fqClass = $this->lookupClass($element);
+        $component = new $fqClass();
+        $component->setContent(new FlowCollection($children->getArrayCopy()));
+
+        if (($xmlBase = self::getXmlBase($element)) !== false) {
+            $component->setXmlBase($xmlBase);
+        }
+
+        $this->fillBodyElement($component, $element);
+
+        return $component;
+    }
+
+    /**
+     * @param QtiComponent $component
+     * @param array $elements
+     * @return DOMElement
+     */
+    protected function marshallChildrenKnown(QtiComponent $component, array $elements)
+    {
+        /** @var Html5Element $component */
+        $prefix = $component->getTargetNamespacePrefix();
+        $version = QtiVersion::create($this->getVersion());
+        $namespace = $version->getExternalNamespace($prefix);
+
+        $element = static::getDOMCradle()->createElementNS(
+            $namespace,
+            $prefix . ':' . $component->getQtiClassName()
+        );
+
+        if ($component->hasXmlBase() === true) {
+            self::setXmlBase($element, $component->getXmlBase());
+        }
+
+        foreach ($elements as $e) {
+            $element->appendChild($e);
+        }
+
+        $this->fillElement($element, $component);
+
+        return $element;
+    }
+
+    protected function setLookupClasses()
+    {
+        $this->lookupClasses = [
+            "qtism\\data\\content\\xhtml",
+            "qtism\\data\\content\\xhtml\\html5",
+            "qtism\\data\\content\\xhtml\\text",
+        ];
+    }
+
+    public function getExpectedQtiClassName()
+    {
+       return Version::compare($this->getVersion(), '2.2', '>=') ? parent::getExpectedQtiClassName() : 'not_existing';
+    }
+}
\ No newline at end of file
diff --git a/qtism/data/storage/xml/marshalling/MarshallerFactory.php b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
index 377b6ee27..5d119cfcd 100644
--- a/qtism/data/storage/xml/marshalling/MarshallerFactory.php
+++ b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
@@ -25,6 +25,8 @@
 
 use DOMElement;
 use InvalidArgumentException;
+use qtism\data\content\xhtml\html5\Figcaption;
+use qtism\data\content\xhtml\html5\Figure;
 use qtism\data\QtiComponent;
 use ReflectionClass;
 use ReflectionException;
@@ -88,6 +90,8 @@ public function __construct()
         $this->addMappingEntry('equalRounded', EqualRoundedMarshaller::class);
         $this->addMappingEntry('exitResponse', ExitResponseMarshaller::class);
         $this->addMappingEntry('exitTest', ExitTestMarshaller::class);
+        $this->addMappingEntry(Figure::QTI_CLASS_NAME, Html5LayoutMarshaller::class);
+        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME, Html5LayoutMarshaller::class);
         $this->addMappingEntry('fieldValue', FieldValueMarshaller::class);
         $this->addMappingEntry('hottextInteraction', HottextInteractionMarshaller::class);
         $this->addMappingEntry('inlineChoiceInteraction', InlineChoiceInteractionMarshaller::class);
diff --git a/qtism/data/storage/xml/versions/QtiVersion.php b/qtism/data/storage/xml/versions/QtiVersion.php
index 48203484c..24d2794cd 100644
--- a/qtism/data/storage/xml/versions/QtiVersion.php
+++ b/qtism/data/storage/xml/versions/QtiVersion.php
@@ -193,4 +193,9 @@ public function getMarshallerFactoryClass(): string
     {
         return static::MARSHALLER_FACTORY;
     }
+
+    public function getExternalNamespace(string $prefix): string
+    {
+        return '';
+    }
 }
diff --git a/qtism/data/storage/xml/versions/QtiVersion220.php b/qtism/data/storage/xml/versions/QtiVersion220.php
index 12c0cd395..019a9866f 100644
--- a/qtism/data/storage/xml/versions/QtiVersion220.php
+++ b/qtism/data/storage/xml/versions/QtiVersion220.php
@@ -37,4 +37,17 @@ class QtiVersion220 extends QtiVersion
     const LOCAL_XSD = 'qtiv2p2/imsqti_v2p2.xsd';
 
     const MARSHALLER_FACTORY = Qti22MarshallerFactory::class;
+
+    const QH5_NS = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
+
+    const QH5_XSD = 'http://www.imsglobal.org/xsd/qti/qtiv2p2/imsqtiv2p2p2_html5_v1p0.xsd';
+
+    public function getExternalNamespace(string $prefix): string
+    {
+        if ($prefix === 'qh5') {
+            return self::QH5_NS;
+        }
+
+        return '';
+    }
 }
diff --git a/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php b/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
new file mode 100644
index 000000000..4c0509b45
--- /dev/null
+++ b/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace qtismtest\data\content\xhtml\html5;
+
+use qtism\data\content\xhtml\html5\Figcaption;
+use qtismtest\QtiSmTestCase;
+
+class FigcaptionTest extends QtiSmTestCase
+{
+    public function testCreateWithValues(): void
+    {
+        $title = 'title';
+        $id = 'testid';
+        $class = 'test_class';
+        $lang = 'lang';
+        $label = 'label';
+
+        $subject = new Figcaption($title, $id, $class, $lang, $label);
+
+        self::assertEquals($title, $subject->getTitle());
+        self::assertEquals($id, $subject->getId());
+        self::assertEquals($class, $subject->getClass());
+        self::assertEquals($lang, $subject->getLang());
+        self::assertEquals($label, $subject->getLabel());
+    }
+
+    public function testCreateWithDefaultValues(): void
+    {
+        $subject = new Figcaption();
+
+        self::assertEquals('', $subject->getId());
+        self::assertEquals('', $subject->getClass());
+    }
+
+    public function testGetQtiClassName(): void
+    {
+        $subject = new Figcaption();
+
+        self::assertEquals(Figcaption::QTI_CLASS_NAME, $subject->getQtiClassName());
+    }
+}
\ No newline at end of file
diff --git a/test/qtismtest/data/content/xhtml/html5/FigureTest.php b/test/qtismtest/data/content/xhtml/html5/FigureTest.php
new file mode 100644
index 000000000..b35a27e35
--- /dev/null
+++ b/test/qtismtest/data/content/xhtml/html5/FigureTest.php
@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
+ */
+
+declare(strict_types=1);
+
+namespace qtismtest\data\content\xhtml\html5;
+
+use qtism\data\content\xhtml\html5\Figure;
+use qtismtest\QtiSmTestCase;
+
+class FigureTest extends QtiSmTestCase
+{
+    public function testCreateWithValues(): void
+    {
+        $title = 'title';
+        $id = 'testid';
+        $class = 'test_class';
+        $lang = 'lang';
+        $label = 'label';
+
+        $subject = new Figure($title, $id, $class, $lang, $label);
+
+        self::assertEquals($title, $subject->getTitle());
+        self::assertEquals($id, $subject->getId());
+        self::assertEquals($class, $subject->getClass());
+        self::assertEquals($lang, $subject->getLang());
+        self::assertEquals($label, $subject->getLabel());
+    }
+
+    public function testCreateWithDefaultValues(): void
+    {
+        $subject = new Figure();
+
+        self::assertEquals('', $subject->getId());
+        self::assertEquals('', $subject->getClass());
+    }
+
+    public function testGetQtiClassName(): void
+    {
+        $subject = new Figure();
+
+        self::assertEquals(Figure::QTI_CLASS_NAME, $subject->getQtiClassName());
+    }
+}
\ No newline at end of file
diff --git a/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php b/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
new file mode 100644
index 000000000..a06c22a26
--- /dev/null
+++ b/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
@@ -0,0 +1,68 @@
+<?php
+
+namespace qtismtest\data\content\xhtml\html5;
+
+use qtism\data\content\FlowCollection;
+use qtism\data\content\xhtml\A;
+use qtism\data\content\xhtml\html5\Html5LayoutElement;
+use qtism\data\content\xhtml\text\Br;
+use qtism\data\content\xhtml\text\P;
+use qtismtest\QtiSmTestCase;
+
+class Html5LayoutElementTest extends QtiSmTestCase
+{
+    public function testCreateWithValues(): void
+    {
+        $title = 'a title';
+        $id = 'the_id';
+        $class = 'css class';
+        $lang = 'en';
+        $label = 'This is the label.';
+
+        $subject = new FakeHtml5LayoutElement($title, $id, $class, $lang, $label);
+
+        self::assertSame($title, $subject->getTitle());
+        self::assertSame($id, $subject->getId());
+        self::assertSame($class, $subject->getClass());
+        self::assertSame($lang, $subject->getLang());
+        self::assertSame($label, $subject->getLabel());
+        self::assertEquals(new FlowCollection(), $subject->getComponents());
+    }
+
+    public function testCreateWithDefaultValues(): void
+    {
+        $subject = new FakeHtml5LayoutElement();
+
+        self::assertSame('', $subject->getTitle());
+        self::assertSame('', $subject->getId());
+        self::assertSame('', $subject->getClass());
+        self::assertSame('', $subject->getLang());
+        self::assertSame('', $subject->getLabel());
+        self::assertEquals(new FlowCollection(), $subject->getComponents());
+    }
+
+    public function testSetContent(): void
+    {
+        $subject = new FakeHtml5LayoutElement();
+        $content = new FlowCollection(
+            [
+                new P(),
+                new Br(),
+                new A('blah'),
+            ]
+        );
+
+        $subject->setContent($content);
+
+        self::assertEquals($content, $subject->getContent());
+        self::assertEquals($content, $subject->getComponents());
+    }
+}
+
+class FakeHtml5LayoutElement extends Html5LayoutElement
+{
+    public function getQtiClassName(): string
+    {
+        return '';
+    }
+}
\ No newline at end of file
diff --git a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
new file mode 100644
index 000000000..d4c04ce33
--- /dev/null
+++ b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
@@ -0,0 +1,86 @@
+<?php
+
+namespace qtismtest\data\storage\xml\marshalling;
+
+use DOMDocument;
+use \RuntimeException;
+use qtism\data\content\FlowCollection;
+use qtism\data\content\TextRun;
+use qtism\data\content\xhtml\html5\Figcaption;
+use qtism\data\content\xhtml\html5\Figure;
+use qtism\data\content\xhtml\Img;
+use qtismtest\QtiSmTestCase;
+
+/**
+ * Class Html5LayoutMarshallerTest supports figure/figcaption marshalling
+ */
+class Html5LayoutMarshallerTest extends QtiSmTestCase
+{
+    private const SUBJECT_XML = '
+         <qh5:figure xmlns:qh5="http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0" id="figureId">
+            <img src="assets/local_asset.jpg" alt="alt" width="100" class="imgClass"/>
+            <qh5:figcaption id="figcaptionId">caption text</qh5:figcaption>
+         </qh5:figure>
+        ';
+
+    public function testUnmarshall()
+    {
+        $figure = $this->createComponentFromXml(self::SUBJECT_XML, '2.2.2');
+
+        $this::assertInstanceOf(Figure::class, $figure);
+        $this::assertEquals('figureId', $figure->getId());
+        $this::assertEquals('', $figure->getClass());
+
+        $figureContent = $figure->getContent();
+        $this::assertCount(5, $figureContent);
+        $this::assertInstanceOf(TextRun::class, $figureContent[0]);
+        $this::assertInstanceOf(Img::class, $figureContent[1]);
+        $this::assertInstanceOf(TextRun::class, $figureContent[2]);
+        $this::assertInstanceOf(Figcaption::class, $figureContent[3]);
+        $this::assertInstanceOf(TextRun::class, $figureContent[4]);
+
+        $figcaption = $figureContent[3];
+        $this::assertEquals('figcaptionId', $figcaption->getId());
+
+        $figcaptionContent = $figcaption->getContent();
+        $this::assertCount(1, $figcaptionContent);
+        $this::assertInstanceOf(TextRun::class, $figcaptionContent[0]);
+        $this::assertEquals('caption text', $figcaptionContent[0]->getContent());
+    }
+
+    public function testMarshall()
+    {
+        $figCaption = new Figcaption(null, "figcaptionId");
+        $figCaption->setContent(new FlowCollection([
+            new TextRun('caption text')
+        ]));
+
+        $img = new Img('assets/local_asset.jpg', 'alt', '', 'imgClass');
+        $img->setWidth('100');
+
+        $figure = new Figure(null, "figureId");
+        $figure->setContent(new FlowCollection([$img, $figCaption]));
+
+        $element = $this->getMarshallerFactory('2.2.2')->createMarshaller($figure)->marshall($figure);
+
+        $dom = new DOMDocument('1.0', 'UTF-8');
+        $element = $dom->importNode($element, true);
+
+        $expected = preg_replace('/\s\s+/', '', self::SUBJECT_XML);
+        $this::assertEquals($expected, $dom->saveXML($element));
+    }
+
+    public function testMarshallerBelow2p2Fails()
+    {
+        $figCaption = new Figcaption();
+        $figure = new Figure();
+        $figure->setContent(new FlowCollection([$figCaption]));
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage(
+            "No marshaller implementation found while marshalling component with class name 'figure"
+        );
+
+        $this->getMarshallerFactory('2.1.0')->createMarshaller($figure)->marshall($figure);
+    }
+}
\ No newline at end of file

From a75f9e0b6216709035789f0a61633b6ea6a3b42a Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Wed, 1 Jun 2022 13:29:09 +0300
Subject: [PATCH 02/11] feat: html5 role attribute

---
 qtism/common/enums/AbstractEnumeration.php    |  85 +++++
 qtism/data/content/enums/Role.php             | 297 ++++++++++++++++++
 .../data/content/xhtml/html5/Html5Element.php |  45 ++-
 .../xhtml/html5/Html5LayoutElement.php        |  14 +-
 qtism/data/storage/xml/Utils.php              |  49 +--
 .../marshalling/Html5ElementMarshaller.php    |  10 +-
 .../xml/marshalling/Html5LayoutMarshaller.php |  35 ++-
 .../qtismtest/data/content/enums/RoleTest.php |  71 +++++
 .../content/xhtml/html5/FigcaptionTest.php    |   7 +-
 .../data/content/xhtml/html5/FigureTest.php   |   7 +-
 .../xhtml/html5/Html5LayoutElementTest.php    |   5 +-
 .../marshalling/Html5LayoutMarshallerTest.php |   8 +-
 12 files changed, 580 insertions(+), 53 deletions(-)
 create mode 100644 qtism/common/enums/AbstractEnumeration.php
 create mode 100644 qtism/data/content/enums/Role.php
 create mode 100644 test/qtismtest/data/content/enums/RoleTest.php

diff --git a/qtism/common/enums/AbstractEnumeration.php b/qtism/common/enums/AbstractEnumeration.php
new file mode 100644
index 000000000..03d2e8972
--- /dev/null
+++ b/qtism/common/enums/AbstractEnumeration.php
@@ -0,0 +1,85 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
+ */
+
+namespace qtism\common\enums;
+
+use InvalidArgumentException;
+
+/**
+ * Abstract enumeration automatizes the translation from constant name to
+ * value and from value to name.
+ */
+abstract class AbstractEnumeration implements Enumeration
+{
+    abstract public static function asArray(): array;
+
+    public static function getConstantByName($name)
+    {
+        return static::asArray()[$name] ?? false;
+    }
+
+    public static function getNameByConstant($constant)
+    {
+        $constants = array_flip(static::asArray());
+
+        return $constants[$constant] ?? false;
+    }
+
+    /**
+     * Returns the default constant for the enumeration.
+     *
+     * @return int|null
+     */
+    abstract public static function getDefault(): ?int;
+
+    /**
+     * Checks that the given value is null or one of the enumeration constants.
+     *
+     * @param int|string|null $value
+     * @param string $argumentName
+     * @return int|null
+     * @throws InvalidArgumentException when $value is not in the enumeration.
+     */
+    public static function accept($value, string $argumentName): ?int
+    {
+        $enumValues = static::asArray();
+        $nameExistsInEnum = array_key_exists($value, $enumValues);
+
+        if ($value !== null
+            && !$nameExistsInEnum
+            && !in_array($value, $enumValues, true)
+        ) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'The "%s" argument must be a value from the %s enumeration, "%s" given.',
+                    $argumentName,
+                    basename(str_replace('\\', '/', static::class)),
+                    $value
+                )
+            );
+        }
+
+        if ($nameExistsInEnum) {
+            $value = $enumValues[$value];
+        }
+
+        return $value ?? static::getDefault();
+    }
+}
diff --git a/qtism/data/content/enums/Role.php b/qtism/data/content/enums/Role.php
new file mode 100644
index 000000000..45514b7df
--- /dev/null
+++ b/qtism/data/content/enums/Role.php
@@ -0,0 +1,297 @@
+<?php
+
+/**
+ * This program 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; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program 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 this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
+ */
+
+namespace qtism\data\content\enums;
+
+use qtism\common\enums\AbstractEnumeration;
+
+/**
+ * The Html5 ARIA role enumeration.
+ * Roles are defined and described by their characteristics.
+ * Characteristics define the structural function of a role, such as what a
+ * role is, concepts behind it, and what instances the role can or must contain.
+ */
+class Role extends AbstractEnumeration
+{
+    /**
+     * A section of a page that consists of a composition that forms an
+     * independent part of a document, page, or site.
+     */
+    private const ARTICLE = 1;
+
+    /**
+     * An input that allows for user-triggered actions when clicked or pressed.
+     * See related link.
+     */
+    private const BUTTON = 2;
+
+    /**
+     * A checkable input that has three possible values: true, false, or mixed.
+     */
+    private const CHECKBOX = 3;
+
+    /**
+     * A cell containing header information for a column.
+     */
+    private const COLUMN_HEADER = 4;
+
+    /**
+     * A supporting section of the document, designed to be complementary to
+     * the main content at a similar level in the DOM hierarchy, but remains
+     * meaningful when separated from the main content.
+     */
+    private const COMPLEMENTARY = 5;
+
+    /**
+     * A large perceivable region that contains information about the parent
+     * document.
+     */
+    private const CONTENT_INFO = 6;
+
+    /**
+     * A definition of a term or concept.
+     */
+    private const DEFINITION = 7;
+
+    /**
+     * A list of references to members of a group, such as a static table of
+     * contents.
+     */
+    private const DIRECTORY = 8;
+
+    /**
+     * A region containing related information that is declared as document
+     * content, as opposed to a web application.
+     */
+    private const DOCUMENT = 9;
+
+    /**
+     * A cell in a grid or treegrid.
+     */
+    private const GRID_CELL = 10;
+
+    /**
+     * A set of user interface objects which are not intended to be included
+     * in a page summary or table of contents by assistive technologies.
+     */
+    private const GROUP = 11;
+
+    /**
+     * A heading for a section of the page.
+     */
+    private const HEADING = 12;
+
+    /**
+     * A container for a collection of elements that form an image.
+     */
+    private const IMG = 13;
+
+    /**
+     * An interactive reference to an internal or external resource that, when
+     * activated, causes the user agent to navigate to that resource.
+     * See related button.
+     */
+    private const LINK = 14;
+
+    /**
+     * A group of non-interactive list items. See related listbox.
+     */
+    private const LIST = 15;
+
+    /**
+     * A widget that allows the user to select one or more items from a list of
+     * choices. See related combobox and list.
+     */
+    private const LIST_BOX = 16;
+
+    /**
+     * A single item in a list or directory.
+     */
+    private const LIST_ITEM = 17;
+
+    /**
+     * A type of live region where new information is added in meaningful order
+     * and old information may disappear. See related marquee.
+     */
+    private const LOG = 18;
+
+    /**
+     * Content that represents a mathematical expression.
+     */
+    private const MATH = 19;
+
+    /**
+     * A section whose content is parenthetic or ancillary to the main content
+     * of the resource.
+     */
+    private const NOTE = 20;
+
+    /**
+     * A selectable item in a select list.
+     */
+    private const OPTION = 21;
+
+    /**
+     * An element whose implicit native role semantics will not be mapped to
+     * the accessibility API.
+     */
+    private const PRESENTATION = 22;
+
+    /**
+     * A checkable input in a group of radio roles, only one of which can be
+     * checked at a time.
+     */
+    private const RADIO = 23;
+
+    /**
+     * A group of radio buttons.
+     */
+    private const RADIO_GROUP = 24;
+
+    /**
+     * A large perceivable section of a web page or document, that is important
+     * enough to be included in a page summary or table of contents, for
+     * example, an area of the page containing live sporting event statistics.
+     */
+    private const REGION = 25;
+
+    /**
+     * A row of cells in a grid.
+     */
+    private const ROW = 26;
+
+    /**
+     * A group containing one or more row elements in a grid.
+     */
+    private const ROW_GROUP = 27;
+
+    /**
+     * A cell containing header information for a row in a grid.
+     */
+    private const ROW_HEADER = 28;
+
+    /**
+     * A divider that separates and distinguishes sections of content or groups
+     * of menuitems.
+     */
+    private const SEPARATOR = 29;
+
+    /**
+     * A user input where the user selects a value from within a given range.
+     */
+    private const SLIDER = 30;
+
+    /**
+     * A form of range that expects the user to select from among discrete
+     * choices.
+     */
+    private const SPIN_BUTTON = 31;
+
+    /**
+     * A container whose content is advisory information for the user but is
+     * not important enough to justify an alert, often but not necessarily
+     * presented as a status bar. See related alert.
+     */
+    private const STATUS = 32;
+
+    /**
+     * A grouping label providing a mechanism for selecting the tab content
+     * that is to be rendered to the user.
+     */
+    private const TAB = 33;
+
+    /**
+     * A list of tab elements, which are references to tabpanel elements.
+     */
+    private const TAB_LIST = 34;
+
+    /**
+     * A container for the resources associated with a tab, where each tab is
+     * contained in a tablist.
+     */
+    private const TAB_PANEL = 35;
+
+    /**
+     * Input that allows free-form text as its value.
+     */
+    private const TEXT_BOX = 36;
+
+    /**
+     * A type of live region containing a numerical counter which indicates an
+     * amount of elapsed time from a start point, or the time remaining until
+     * an end point.
+     */
+    private const TIMER = 37;
+
+    /**
+     * A collection of commonly used function buttons or controls represented
+     * in compact visual form.
+     */
+    private const TOOLBAR = 38;
+
+    public static function asArray(): array
+    {
+        return [
+            'article' => self::ARTICLE,
+            'button' => self::BUTTON,
+            'checkbox' => self::CHECKBOX,
+            'columnheader' => self::COLUMN_HEADER,
+            'complementary' => self::COMPLEMENTARY,
+            'contentinfo' => self::CONTENT_INFO,
+            'definition' => self::DEFINITION,
+            'directory' => self::DIRECTORY,
+            'document' => self::DOCUMENT,
+            'gridcell' => self::GRID_CELL,
+            'group' => self::GROUP,
+            'heading' => self::HEADING,
+            'img' => self::IMG,
+            'link' => self::LINK,
+            'list' => self::LIST,
+            'listbox' => self::LIST_BOX,
+            'listitem' => self::LIST_ITEM,
+            'log' => self::LOG,
+            'math' => self::MATH,
+            'note' => self::NOTE,
+            'option' => self::OPTION,
+            'presentation' => self::PRESENTATION,
+            'radio' => self::RADIO,
+            'radiogroup' => self::RADIO_GROUP,
+            'region' => self::REGION,
+            'row' => self::ROW,
+            'rowgroup' => self::ROW_GROUP,
+            'rowheader' => self::ROW_HEADER,
+            'separator' => self::SEPARATOR,
+            'slider' => self::SLIDER,
+            'spinbutton' => self::SPIN_BUTTON,
+            'status' => self::STATUS,
+            'tab' => self::TAB,
+            'tablist' => self::TAB_LIST,
+            'tabpanel' => self::TAB_PANEL,
+            'textbox' => self::TEXT_BOX,
+            'timer' => self::TIMER,
+            'toolbar' => self::TOOLBAR,
+        ];
+    }
+
+    public static function getDefault(): ?int
+    {
+        return null;
+    }
+}
diff --git a/qtism/data/content/xhtml/html5/Html5Element.php b/qtism/data/content/xhtml/html5/Html5Element.php
index 43b488d60..3e40a07c4 100644
--- a/qtism/data/content/xhtml/html5/Html5Element.php
+++ b/qtism/data/content/xhtml/html5/Html5Element.php
@@ -8,17 +8,14 @@
  *
  * This program 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
+ * 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 this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  *
- * Copyright (c) 2020 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
- *
- * @author Julien Sébire <julien@taotesting.com>
- * @license GPLv2
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
  */
 
 namespace qtism\data\content\xhtml\html5;
@@ -26,6 +23,7 @@
 use InvalidArgumentException;
 use qtism\common\utils\Format;
 use qtism\data\content\BodyElement;
+use qtism\data\content\enums\Role;
 use qtism\data\storage\xml\QtiNamespaced;
 
 /**
@@ -49,6 +47,17 @@ abstract class Html5Element extends BodyElement implements QtiNamespaced
      */
     private $title = '';
 
+    /**
+     * The Html5 ARIA role enumeration.
+     * Roles are defined and described by their characteristics.
+     * Characteristics define the structural function of a role, such as what a
+     * role is, concepts behind it, and what instances the role can or must
+     * contain.
+     *
+     * @var ?int
+     */
+    private $role;
+
     /**
      * Create a new Html5 element.
      *
@@ -64,6 +73,7 @@ abstract class Html5Element extends BodyElement implements QtiNamespaced
      */
     public function __construct(
         $title = null,
+        $role = null,
         $id = null,
         $class = null,
         $lang = null,
@@ -72,6 +82,7 @@ public function __construct(
         parent::__construct($id ?? '', $class ?? '', $lang ?? '', $label ?? '');
 
         $this->setTitle($title);
+        $this->setRole($role);
     }
 
     /**
@@ -94,6 +105,26 @@ public function hasTitle(): bool
         return $this->title !== '';
     }
 
+    /**
+     * @param mixed $role One of the Role constants.
+     * @throws InvalidArgumentException when $role parameter is not one of Role constants.
+     */
+    public function setRole($role = null): void
+    {
+        $this->role = Role::accept($role, 'role');
+    }
+
+    public function getRole(): ?int
+    {
+        return $this->role;
+    }
+
+    public function hasRole(): bool
+    {
+        return $this->role !== null;
+    }
+
+
     protected function acceptNormalizedStringOrNull($value, string $argumentName, string $default = null): string
     {
         if ($value === null) {
@@ -126,4 +157,4 @@ public function getTargetNamespacePrefix(): string
     {
         return 'qh5';
     }
-}
\ No newline at end of file
+}
diff --git a/qtism/data/content/xhtml/html5/Html5LayoutElement.php b/qtism/data/content/xhtml/html5/Html5LayoutElement.php
index cb2aa35d5..774e9759a 100644
--- a/qtism/data/content/xhtml/html5/Html5LayoutElement.php
+++ b/qtism/data/content/xhtml/html5/Html5LayoutElement.php
@@ -8,17 +8,14 @@
  *
  * This program 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
+ * 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 this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  *
- * Copyright (c) 2021 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
- *
- * @author Julien Sébire <julien@taotesting.com>
- * @license GPLv2
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
  */
 
 namespace qtism\data\content\xhtml\html5;
@@ -56,12 +53,13 @@ abstract class Html5LayoutElement extends Html5Element implements FlowStatic
      */
     public function __construct(
         $title = null,
+        $role = null,
         $id = null,
         $class = null,
         $lang = null,
         $label = null
     ) {
-        parent::__construct($title, $id, $class, $lang, $label);
+        parent::__construct($title, $role, $id, $class, $lang, $label);
         $this->setContent(new FlowCollection());
     }
 
@@ -79,4 +77,4 @@ public function getContent(): FlowCollection
     {
         return $this->content;
     }
-}
\ No newline at end of file
+}
diff --git a/qtism/data/storage/xml/Utils.php b/qtism/data/storage/xml/Utils.php
index d833c94db..ce18833b5 100644
--- a/qtism/data/storage/xml/Utils.php
+++ b/qtism/data/storage/xml/Utils.php
@@ -26,6 +26,7 @@
 use DOMDocument;
 use DOMElement;
 use InvalidArgumentException;
+use qtism\common\enums\Enumeration;
 use SplStack;
 
 /**
@@ -198,32 +199,40 @@ public static function getDOMElementAttributeAs(DOMElement $element, $attribute,
     {
         $attr = $element->getAttribute($attribute);
 
-        if ($attr !== '') {
-            switch ($datatype) {
-                case 'string':
-                    return $attr;
-                    break;
+        if ($attr === '') {
+            return null;
+        }
 
-                case 'integer':
-                    return (int)$attr;
-                    break;
+        switch ($datatype) {
+            case 'string':
+                return $attr;
 
-                case 'double':
-                case 'float':
-                    return (float)$attr;
-                    break;
+            case 'integer':
+                return (int)$attr;
 
-                case 'boolean':
-                    return $attr === 'true';
-                    break;
+            case 'double':
+            case 'float':
+                return (float)$attr;
+
+            case 'boolean':
+                return $attr === 'true';
+        }
 
-                default:
-                    throw new InvalidArgumentException("Unknown datatype '${datatype}'.");
-                    break;
+        if (in_array(Enumeration::class, class_implements($datatype), true)){
+            if ($attr !== null) {
+                /** @var $datatype Enumeration */
+                $constant = $datatype::getConstantByName($attr);
+                // Returns the original value when it's unknown in the enumeration.
+                if ($constant === false) {
+                    return $attr;
+                }
+                $attr = $constant;
             }
-        } else {
-            return null;
+
+            return $attr;
         }
+
+        throw new InvalidArgumentException("Unknown datatype '${datatype}'.");
     }
 
     /**
diff --git a/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
index ed6e53999..4400ff14d 100644
--- a/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
@@ -26,6 +26,7 @@
 use DOMElement;
 use qtism\common\utils\Version;
 use qtism\data\content\BodyElement;
+use qtism\data\content\enums\Role;
 use qtism\data\content\xhtml\html5\Html5Element;
 use qtism\data\QtiComponent;
 use qtism\data\storage\xml\versions\QtiVersion;
@@ -60,6 +61,10 @@ protected function marshall(QtiComponent $component)
             $this->setDOMElementAttribute($element, 'title', $component->getTitle());
         }
 
+        if ($component->hasRole()) {
+            $this->setDOMElementAttribute($element, 'role', Role::getNameByConstant($component->getRole()));
+        }
+
         return $element;
     }
 
@@ -77,8 +82,11 @@ protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element
         if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
             $title = $this->getDOMElementAttributeAs($element, 'title');
             $bodyElement->setTitle($title);
+
+            $role = $this->getDOMElementAttributeAs($element, 'role', Role::class);
+            $bodyElement->setRole($role);
         }
 
         parent::fillBodyElement($bodyElement, $element);
     }
-}
\ No newline at end of file
+}
diff --git a/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php b/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
index 876e10dcb..be4ca3cb1 100644
--- a/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
@@ -8,23 +8,22 @@
  *
  * This program 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
+ * 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 this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  *
- * Copyright (c) 2013-2020 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
- *
- * @author Jérôme Bogaerts <jerome@taotesting.com>
- * @license GPLv2
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
  */
 
 namespace qtism\data\storage\xml\marshalling;
 
 use DOMElement;
 use qtism\common\utils\Version;
+use qtism\data\content\BodyElement;
+use qtism\data\content\enums\Role;
 use qtism\data\content\FlowCollection;
 use qtism\data\content\xhtml\html5\Html5Element;
 use qtism\data\QtiComponent;
@@ -62,7 +61,7 @@ protected function unmarshallChildrenKnown(DOMElement $element, QtiComponentColl
      * @param array $elements
      * @return DOMElement
      */
-    protected function marshallChildrenKnown(QtiComponent $component, array $elements)
+    protected function marshallChildrenKnown(QtiComponent $component, array $elements): DOMElement
     {
         /** @var Html5Element $component */
         $prefix = $component->getTargetNamespacePrefix();
@@ -84,6 +83,14 @@ protected function marshallChildrenKnown(QtiComponent $component, array $element
 
         $this->fillElement($element, $component);
 
+        if ($component->hasTitle()) {
+            $this->setDOMElementAttribute($element, 'title', $component->getTitle());
+        }
+
+        if ($component->hasRole()) {
+            $this->setDOMElementAttribute($element, 'role', Role::getNameByConstant($component->getRole()));
+        }
+
         return $element;
     }
 
@@ -100,4 +107,16 @@ public function getExpectedQtiClassName()
     {
        return Version::compare($this->getVersion(), '2.2', '>=') ? parent::getExpectedQtiClassName() : 'not_existing';
     }
-}
\ No newline at end of file
+
+    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element) {
+        if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
+            $title = $this->getDOMElementAttributeAs($element, 'title');
+            $bodyElement->setTitle($title);
+
+            $role = $this->getDOMElementAttributeAs($element, 'role', Role::class);
+            $bodyElement->setRole($role);
+        }
+
+        parent::fillBodyElement($bodyElement, $element);
+    }
+}
diff --git a/test/qtismtest/data/content/enums/RoleTest.php b/test/qtismtest/data/content/enums/RoleTest.php
new file mode 100644
index 000000000..13e18b1b2
--- /dev/null
+++ b/test/qtismtest/data/content/enums/RoleTest.php
@@ -0,0 +1,71 @@
+<?php
+
+namespace qtismtest\data\content\enums;
+
+use qtism\data\content\enums\Role;
+use qtismtest\QtiSmEnumTestCase;
+
+class RoleTest extends QtiSmEnumTestCase
+{
+    protected function getEnumerationFqcn()
+    {
+        return Role::class;
+    }
+
+    protected function getNames()
+    {
+        return [
+            'article',
+            'button',
+            'checkbox',
+            'columnheader',
+            'complementary',
+            'contentinfo',
+            'definition',
+            'directory',
+            'document',
+            'gridcell',
+            'group',
+            'heading',
+            'img',
+            'link',
+            'list',
+            'listbox',
+            'listitem',
+            'log',
+            'math',
+            'note',
+            'option',
+            'presentation',
+            'radio',
+            'radiogroup',
+            'region',
+            'row',
+            'rowgroup',
+            'rowheader',
+            'separator',
+            'slider',
+            'spinbutton',
+            'status',
+            'tab',
+            'tablist',
+            'tabpanel',
+            'textbox',
+            'timer',
+            'toolbar',
+        ];
+    }
+
+    protected function getKeys()
+    {
+        return $this->getNames();
+    }
+
+    protected function getConstants()
+    {
+        return array_map(
+            [Role::class, 'getConstantByName'],
+            $this->getNames()
+        );
+    }
+}
diff --git a/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php b/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
index 4c0509b45..16e60fcd5 100644
--- a/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
+++ b/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
@@ -22,6 +22,7 @@
 
 namespace qtismtest\data\content\xhtml\html5;
 
+use qtism\data\content\enums\Role;
 use qtism\data\content\xhtml\html5\Figcaption;
 use qtismtest\QtiSmTestCase;
 
@@ -30,14 +31,16 @@ class FigcaptionTest extends QtiSmTestCase
     public function testCreateWithValues(): void
     {
         $title = 'title';
+        $role = 'article';
         $id = 'testid';
         $class = 'test_class';
         $lang = 'lang';
         $label = 'label';
 
-        $subject = new Figcaption($title, $id, $class, $lang, $label);
+        $subject = new Figcaption($title, $role, $id, $class, $lang, $label);
 
         self::assertEquals($title, $subject->getTitle());
+        self::assertEquals(Role::getConstantByName($role), $subject->getRole());
         self::assertEquals($id, $subject->getId());
         self::assertEquals($class, $subject->getClass());
         self::assertEquals($lang, $subject->getLang());
@@ -56,6 +59,6 @@ public function testGetQtiClassName(): void
     {
         $subject = new Figcaption();
 
-        self::assertEquals(Figcaption::QTI_CLASS_NAME, $subject->getQtiClassName());
+        self::assertEquals(Figcaption::QTI_CLASS_NAME_FIGCAPTION, $subject->getQtiClassName());
     }
 }
\ No newline at end of file
diff --git a/test/qtismtest/data/content/xhtml/html5/FigureTest.php b/test/qtismtest/data/content/xhtml/html5/FigureTest.php
index b35a27e35..df6f79de4 100644
--- a/test/qtismtest/data/content/xhtml/html5/FigureTest.php
+++ b/test/qtismtest/data/content/xhtml/html5/FigureTest.php
@@ -22,6 +22,7 @@
 
 namespace qtismtest\data\content\xhtml\html5;
 
+use qtism\data\content\enums\Role;
 use qtism\data\content\xhtml\html5\Figure;
 use qtismtest\QtiSmTestCase;
 
@@ -30,14 +31,16 @@ class FigureTest extends QtiSmTestCase
     public function testCreateWithValues(): void
     {
         $title = 'title';
+        $role = 'article';
         $id = 'testid';
         $class = 'test_class';
         $lang = 'lang';
         $label = 'label';
 
-        $subject = new Figure($title, $id, $class, $lang, $label);
+        $subject = new Figure($title, $role, $id, $class, $lang, $label);
 
         self::assertEquals($title, $subject->getTitle());
+        self::assertEquals(Role::getConstantByName($role), $subject->getRole());
         self::assertEquals($id, $subject->getId());
         self::assertEquals($class, $subject->getClass());
         self::assertEquals($lang, $subject->getLang());
@@ -56,6 +59,6 @@ public function testGetQtiClassName(): void
     {
         $subject = new Figure();
 
-        self::assertEquals(Figure::QTI_CLASS_NAME, $subject->getQtiClassName());
+        self::assertEquals(Figure::QTI_CLASS_NAME_FIGURE, $subject->getQtiClassName());
     }
 }
\ No newline at end of file
diff --git a/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php b/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
index a06c22a26..7d32090ee 100644
--- a/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
+++ b/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
@@ -2,6 +2,7 @@
 
 namespace qtismtest\data\content\xhtml\html5;
 
+use qtism\data\content\enums\Role;
 use qtism\data\content\FlowCollection;
 use qtism\data\content\xhtml\A;
 use qtism\data\content\xhtml\html5\Html5LayoutElement;
@@ -14,14 +15,16 @@ class Html5LayoutElementTest extends QtiSmTestCase
     public function testCreateWithValues(): void
     {
         $title = 'a title';
+        $role = 'article';
         $id = 'the_id';
         $class = 'css class';
         $lang = 'en';
         $label = 'This is the label.';
 
-        $subject = new FakeHtml5LayoutElement($title, $id, $class, $lang, $label);
+        $subject = new FakeHtml5LayoutElement($title, $role, $id, $class, $lang, $label);
 
         self::assertSame($title, $subject->getTitle());
+        self::assertEquals(Role::getConstantByName($role), $subject->getRole());
         self::assertSame($id, $subject->getId());
         self::assertSame($class, $subject->getClass());
         self::assertSame($lang, $subject->getLang());
diff --git a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
index d4c04ce33..1f6f8a3a4 100644
--- a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
+++ b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
@@ -17,9 +17,9 @@
 class Html5LayoutMarshallerTest extends QtiSmTestCase
 {
     private const SUBJECT_XML = '
-         <qh5:figure xmlns:qh5="http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0" id="figureId">
+         <qh5:figure xmlns:qh5="http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0" title="title" id="figureId">
             <img src="assets/local_asset.jpg" alt="alt" width="100" class="imgClass"/>
-            <qh5:figcaption id="figcaptionId">caption text</qh5:figcaption>
+            <qh5:figcaption role="article" id="figcaptionId">caption text</qh5:figcaption>
          </qh5:figure>
         ';
 
@@ -50,7 +50,7 @@ public function testUnmarshall()
 
     public function testMarshall()
     {
-        $figCaption = new Figcaption(null, "figcaptionId");
+        $figCaption = new Figcaption(null, 'article', 'figcaptionId');
         $figCaption->setContent(new FlowCollection([
             new TextRun('caption text')
         ]));
@@ -58,7 +58,7 @@ public function testMarshall()
         $img = new Img('assets/local_asset.jpg', 'alt', '', 'imgClass');
         $img->setWidth('100');
 
-        $figure = new Figure(null, "figureId");
+        $figure = new Figure('title',null, "figureId");
         $figure->setContent(new FlowCollection([$img, $figCaption]));
 
         $element = $this->getMarshallerFactory('2.2.2')->createMarshaller($figure)->marshall($figure);

From 11101050fddef5abe5737ad4301a9d3bbaa66016 Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Wed, 1 Jun 2022 13:29:52 +0300
Subject: [PATCH 03/11] chore: code style

---
 qtism/data/content/xhtml/html5/Figcaption.php     |  6 +++---
 qtism/data/content/xhtml/html5/Figure.php         | 15 ++++++---------
 qtism/data/storage/xml/QtiNamespaced.php          |  2 +-
 .../storage/xml/marshalling/ContentMarshaller.php |  4 ++--
 .../storage/xml/marshalling/MarshallerFactory.php |  4 ++--
 5 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/qtism/data/content/xhtml/html5/Figcaption.php b/qtism/data/content/xhtml/html5/Figcaption.php
index a00290b8a..2c0219063 100644
--- a/qtism/data/content/xhtml/html5/Figcaption.php
+++ b/qtism/data/content/xhtml/html5/Figcaption.php
@@ -27,10 +27,10 @@
 
 class Figcaption extends Html5LayoutElement implements BlockStatic, FlowStatic
 {
-    public const QTI_CLASS_NAME = 'figcaption';
+    public const QTI_CLASS_NAME_FIGCAPTION = 'figcaption';
 
     public function getQtiClassName(): string
     {
-        return self::QTI_CLASS_NAME;
+        return self::QTI_CLASS_NAME_FIGCAPTION;
     }
-}
\ No newline at end of file
+}
diff --git a/qtism/data/content/xhtml/html5/Figure.php b/qtism/data/content/xhtml/html5/Figure.php
index f74c8e192..e6c775798 100644
--- a/qtism/data/content/xhtml/html5/Figure.php
+++ b/qtism/data/content/xhtml/html5/Figure.php
@@ -8,17 +8,14 @@
  *
  * This program 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
+ * 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 this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  *
- * Copyright (c) 2021 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
- *
- * @author Julien Sébire <julien@taotesting.com>
- * @license GPLv2
+ * Copyright (c) 2022 (original work) Open Assessment Technologies SA;
  */
 
 namespace qtism\data\content\xhtml\html5;
@@ -28,10 +25,10 @@
  */
 class Figure extends Html5LayoutElement
 {
-    public const QTI_CLASS_NAME = 'figure';
+    public const QTI_CLASS_NAME_FIGURE = 'figure';
 
     public function getQtiClassName(): string
     {
-        return self::QTI_CLASS_NAME;
+        return self::QTI_CLASS_NAME_FIGURE;
     }
-}
\ No newline at end of file
+}
diff --git a/qtism/data/storage/xml/QtiNamespaced.php b/qtism/data/storage/xml/QtiNamespaced.php
index c1851ddd3..b969b9b4c 100644
--- a/qtism/data/storage/xml/QtiNamespaced.php
+++ b/qtism/data/storage/xml/QtiNamespaced.php
@@ -5,4 +5,4 @@
 interface QtiNamespaced
 {
     public function getTargetNamespace(): string;
-}
\ No newline at end of file
+}
diff --git a/qtism/data/storage/xml/marshalling/ContentMarshaller.php b/qtism/data/storage/xml/marshalling/ContentMarshaller.php
index 73627d684..70143f41e 100644
--- a/qtism/data/storage/xml/marshalling/ContentMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/ContentMarshaller.php
@@ -175,8 +175,8 @@ public function __construct($version)
         'hottext',
         'modalFeedback',
         'feedbackBlock',
-        Figure::QTI_CLASS_NAME,
-        Figcaption::QTI_CLASS_NAME,
+        Figure::QTI_CLASS_NAME_FIGURE,
+        Figcaption::QTI_CLASS_NAME_FIGCAPTION,
     ];
 
     /**
diff --git a/qtism/data/storage/xml/marshalling/MarshallerFactory.php b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
index 5d119cfcd..1f4495815 100644
--- a/qtism/data/storage/xml/marshalling/MarshallerFactory.php
+++ b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
@@ -90,8 +90,8 @@ public function __construct()
         $this->addMappingEntry('equalRounded', EqualRoundedMarshaller::class);
         $this->addMappingEntry('exitResponse', ExitResponseMarshaller::class);
         $this->addMappingEntry('exitTest', ExitTestMarshaller::class);
-        $this->addMappingEntry(Figure::QTI_CLASS_NAME, Html5LayoutMarshaller::class);
-        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME, Html5LayoutMarshaller::class);
+        $this->addMappingEntry(Figure::QTI_CLASS_NAME_FIGURE, Html5LayoutMarshaller::class);
+        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME_FIGCAPTION, Html5LayoutMarshaller::class);
         $this->addMappingEntry('fieldValue', FieldValueMarshaller::class);
         $this->addMappingEntry('hottextInteraction', HottextInteractionMarshaller::class);
         $this->addMappingEntry('inlineChoiceInteraction', InlineChoiceInteractionMarshaller::class);

From a2fefcfd5ef024572acf01f8819a409a19c85654 Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Wed, 1 Jun 2022 13:34:20 +0300
Subject: [PATCH 04/11] chore: remove Html5ElementMarshaller

---
 .../marshalling/Html5ElementMarshaller.php    | 92 -------------------
 1 file changed, 92 deletions(-)
 delete mode 100644 qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php

diff --git a/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
deleted file mode 100644
index 4400ff14d..000000000
--- a/qtism/data/storage/xml/marshalling/Html5ElementMarshaller.php
+++ /dev/null
@@ -1,92 +0,0 @@
-<?php
-
-/**
- * This program 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; under version 2
- * of the License (non-upgradable).
- *
- * This program 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 this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- *
- * Copyright (c) 2013-2020 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
- *
- * @author Julien Sébire <julien@taotesting.com>
- * @license GPLv2
- */
-
-namespace qtism\data\storage\xml\marshalling;
-
-use DOMElement;
-use qtism\common\utils\Version;
-use qtism\data\content\BodyElement;
-use qtism\data\content\enums\Role;
-use qtism\data\content\xhtml\html5\Html5Element;
-use qtism\data\QtiComponent;
-use qtism\data\storage\xml\versions\QtiVersion;
-
-/**
- * Marshalling/Unmarshalling implementation for generic Html5.
- */
-abstract class Html5ElementMarshaller extends Marshaller
-{
-    /**
-     * Marshall a Html5 element object into a DOMElement object.
-     *
-     * @param QtiComponent $component
-     * @return DOMElement The according DOMElement object.
-     */
-    protected function marshall(QtiComponent $component)
-    {
-        /** @var Html5Element $component */
-
-        $prefix = $component->getTargetNamespacePrefix();
-        $version = QtiVersion::create($this->getVersion());
-        $namespace = $version->getExternalNamespace($prefix);
-
-        $element = static::getDOMCradle()->createElementNS(
-            $namespace,
-            $prefix . ':' . $component->getQtiClassName()
-        );
-
-        $this->fillElement($element, $component);
-
-        if ($component->hasTitle()) {
-            $this->setDOMElementAttribute($element, 'title', $component->getTitle());
-        }
-
-        if ($component->hasRole()) {
-            $this->setDOMElementAttribute($element, 'role', Role::getNameByConstant($component->getRole()));
-        }
-
-        return $element;
-    }
-
-    /**
-     * Fill $bodyElement with the following Html 5 element attributes:
-     *
-     * * title
-     *
-     * @param BodyElement $bodyElement The bodyElement to fill.
-     * @param DOMElement $element The DOMElement object from where the attribute values must be retrieved.
-     * @throws UnmarshallingException If one of the attributes of $element is not valid.
-     */
-    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element)
-    {
-        if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
-            $title = $this->getDOMElementAttributeAs($element, 'title');
-            $bodyElement->setTitle($title);
-
-            $role = $this->getDOMElementAttributeAs($element, 'role', Role::class);
-            $bodyElement->setRole($role);
-        }
-
-        parent::fillBodyElement($bodyElement, $element);
-    }
-}

From f0dd71ea49454cbb85c225d63460d2f756944929 Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Wed, 1 Jun 2022 13:44:12 +0300
Subject: [PATCH 05/11] refactor: renamed Html5LayoutMarshaller

---
 .../{Html5LayoutMarshaller.php => Html5ContentMarshaller.php} | 2 +-
 qtism/data/storage/xml/marshalling/MarshallerFactory.php      | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)
 rename qtism/data/storage/xml/marshalling/{Html5LayoutMarshaller.php => Html5ContentMarshaller.php} (98%)

diff --git a/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
similarity index 98%
rename from qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
rename to qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
index be4ca3cb1..9e2c2297b 100644
--- a/qtism/data/storage/xml/marshalling/Html5LayoutMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
@@ -33,7 +33,7 @@
 /**
  * The Marshaller implementation for object elements of the content model.
  */
-class Html5LayoutMarshaller extends ContentMarshaller
+class Html5ContentMarshaller extends ContentMarshaller
 {
     /**
      * @param DOMElement $element
diff --git a/qtism/data/storage/xml/marshalling/MarshallerFactory.php b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
index 1f4495815..827870003 100644
--- a/qtism/data/storage/xml/marshalling/MarshallerFactory.php
+++ b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
@@ -90,8 +90,8 @@ public function __construct()
         $this->addMappingEntry('equalRounded', EqualRoundedMarshaller::class);
         $this->addMappingEntry('exitResponse', ExitResponseMarshaller::class);
         $this->addMappingEntry('exitTest', ExitTestMarshaller::class);
-        $this->addMappingEntry(Figure::QTI_CLASS_NAME_FIGURE, Html5LayoutMarshaller::class);
-        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME_FIGCAPTION, Html5LayoutMarshaller::class);
+        $this->addMappingEntry(Figure::QTI_CLASS_NAME_FIGURE, Html5ContentMarshaller::class);
+        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME_FIGCAPTION, Html5ContentMarshaller::class);
         $this->addMappingEntry('fieldValue', FieldValueMarshaller::class);
         $this->addMappingEntry('hottextInteraction', HottextInteractionMarshaller::class);
         $this->addMappingEntry('inlineChoiceInteraction', InlineChoiceInteractionMarshaller::class);

From 3b700a7b71047005479a2b2a98f0c7409b108364 Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Wed, 1 Jun 2022 15:31:55 +0300
Subject: [PATCH 06/11] refactor: code style

---
 qtism/common/enums/AbstractEnumeration.php             |  2 +-
 qtism/data/content/xhtml/html5/Figcaption.php          |  3 +--
 qtism/data/content/xhtml/html5/Figure.php              |  4 +++-
 qtism/data/content/xhtml/html5/Html5Element.php        |  7 +++++--
 qtism/data/storage/xml/versions/QtiVersion220.php      | 10 ++++++----
 .../xml/marshalling/Html5LayoutMarshallerTest.php      |  4 ++--
 6 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/qtism/common/enums/AbstractEnumeration.php b/qtism/common/enums/AbstractEnumeration.php
index 03d2e8972..9133794e8 100644
--- a/qtism/common/enums/AbstractEnumeration.php
+++ b/qtism/common/enums/AbstractEnumeration.php
@@ -70,7 +70,7 @@ public static function accept($value, string $argumentName): ?int
                 sprintf(
                     'The "%s" argument must be a value from the %s enumeration, "%s" given.',
                     $argumentName,
-                    basename(str_replace('\\', '/', static::class)),
+                    basename(str_replace('\\', DIRECTORY_SEPARATOR, static::class)),
                     $value
                 )
             );
diff --git a/qtism/data/content/xhtml/html5/Figcaption.php b/qtism/data/content/xhtml/html5/Figcaption.php
index 2c0219063..cfcd2b966 100644
--- a/qtism/data/content/xhtml/html5/Figcaption.php
+++ b/qtism/data/content/xhtml/html5/Figcaption.php
@@ -22,10 +22,9 @@
 
 namespace qtism\data\content\xhtml\html5;
 
-use qtism\data\content\BlockStatic;
 use qtism\data\content\FlowStatic;
 
-class Figcaption extends Html5LayoutElement implements BlockStatic, FlowStatic
+class Figcaption extends Html5LayoutElement implements FlowStatic
 {
     public const QTI_CLASS_NAME_FIGCAPTION = 'figcaption';
 
diff --git a/qtism/data/content/xhtml/html5/Figure.php b/qtism/data/content/xhtml/html5/Figure.php
index e6c775798..221923010 100644
--- a/qtism/data/content/xhtml/html5/Figure.php
+++ b/qtism/data/content/xhtml/html5/Figure.php
@@ -20,10 +20,12 @@
 
 namespace qtism\data\content\xhtml\html5;
 
+use qtism\data\content\FlowStatic;
+
 /**
  * The XHTML figure class.
  */
-class Figure extends Html5LayoutElement
+class Figure extends Html5LayoutElement implements FlowStatic
 {
     public const QTI_CLASS_NAME_FIGURE = 'figure';
 
diff --git a/qtism/data/content/xhtml/html5/Html5Element.php b/qtism/data/content/xhtml/html5/Html5Element.php
index 3e40a07c4..77c9d0532 100644
--- a/qtism/data/content/xhtml/html5/Html5Element.php
+++ b/qtism/data/content/xhtml/html5/Html5Element.php
@@ -25,13 +25,16 @@
 use qtism\data\content\BodyElement;
 use qtism\data\content\enums\Role;
 use qtism\data\storage\xml\QtiNamespaced;
+use qtism\data\storage\xml\versions\QtiVersion220;
 
 /**
  * The base Html 5 element.
  */
 abstract class Html5Element extends BodyElement implements QtiNamespaced
 {
-    private const HTML5_NAMESPACE = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
+    private const HTML5_NAMESPACE = QtiVersion220::HTML5_NAMESPACE;
+
+    private const HTML5_NAMESPACE_PREFIX = QtiVersion220::HTML5_NAMESPACE_PREFIX;
 
     /**
      * The title characteristic represents advisory information for the tag,
@@ -155,6 +158,6 @@ public function getTargetNamespace(): string
 
     public function getTargetNamespacePrefix(): string
     {
-        return 'qh5';
+        return self::HTML5_NAMESPACE_PREFIX;
     }
 }
diff --git a/qtism/data/storage/xml/versions/QtiVersion220.php b/qtism/data/storage/xml/versions/QtiVersion220.php
index 019a9866f..aa8417c02 100644
--- a/qtism/data/storage/xml/versions/QtiVersion220.php
+++ b/qtism/data/storage/xml/versions/QtiVersion220.php
@@ -38,14 +38,16 @@ class QtiVersion220 extends QtiVersion
 
     const MARSHALLER_FACTORY = Qti22MarshallerFactory::class;
 
-    const QH5_NS = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
+    const HTML5_NAMESPACE = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
 
-    const QH5_XSD = 'http://www.imsglobal.org/xsd/qti/qtiv2p2/imsqtiv2p2p2_html5_v1p0.xsd';
+    const HTML5_NAMESPACE_PREFIX = 'qh5';
+
+    const HTML5_XSD = 'http://www.imsglobal.org/xsd/qti/qtiv2p2/imsqtiv2p2p2_html5_v1p0.xsd';
 
     public function getExternalNamespace(string $prefix): string
     {
-        if ($prefix === 'qh5') {
-            return self::QH5_NS;
+        if ($prefix === self::HTML5_NAMESPACE_PREFIX) {
+            return self::HTML5_NAMESPACE;
         }
 
         return '';
diff --git a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
index 1f6f8a3a4..55338c09f 100644
--- a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
+++ b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
@@ -17,9 +17,9 @@
 class Html5LayoutMarshallerTest extends QtiSmTestCase
 {
     private const SUBJECT_XML = '
-         <qh5:figure xmlns:qh5="http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0" title="title" id="figureId">
+         <qh5:figure xmlns:qh5="http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0" id="figureId" title="title">
             <img src="assets/local_asset.jpg" alt="alt" width="100" class="imgClass"/>
-            <qh5:figcaption role="article" id="figcaptionId">caption text</qh5:figcaption>
+            <qh5:figcaption id="figcaptionId" role="article">caption text</qh5:figcaption>
          </qh5:figure>
         ';
 

From b9fe5075dc81fc7e614b5f79aca14ad1865401aa Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Wed, 1 Jun 2022 15:48:15 +0300
Subject: [PATCH 07/11] refactor: moved HTML5 marhaller mapping entries to
 Qti22MarshallerFactory

---
 .../data/storage/xml/marshalling/Html5ContentMarshaller.php  | 5 -----
 qtism/data/storage/xml/marshalling/MarshallerFactory.php     | 4 ----
 .../data/storage/xml/marshalling/Qti22MarshallerFactory.php  | 4 ++++
 .../storage/xml/marshalling/Html5LayoutMarshallerTest.php    | 2 +-
 4 files changed, 5 insertions(+), 10 deletions(-)

diff --git a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
index 9e2c2297b..8d6518a89 100644
--- a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
@@ -103,11 +103,6 @@ protected function setLookupClasses()
         ];
     }
 
-    public function getExpectedQtiClassName()
-    {
-       return Version::compare($this->getVersion(), '2.2', '>=') ? parent::getExpectedQtiClassName() : 'not_existing';
-    }
-
     protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element) {
         if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
             $title = $this->getDOMElementAttributeAs($element, 'title');
diff --git a/qtism/data/storage/xml/marshalling/MarshallerFactory.php b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
index 827870003..377b6ee27 100644
--- a/qtism/data/storage/xml/marshalling/MarshallerFactory.php
+++ b/qtism/data/storage/xml/marshalling/MarshallerFactory.php
@@ -25,8 +25,6 @@
 
 use DOMElement;
 use InvalidArgumentException;
-use qtism\data\content\xhtml\html5\Figcaption;
-use qtism\data\content\xhtml\html5\Figure;
 use qtism\data\QtiComponent;
 use ReflectionClass;
 use ReflectionException;
@@ -90,8 +88,6 @@ public function __construct()
         $this->addMappingEntry('equalRounded', EqualRoundedMarshaller::class);
         $this->addMappingEntry('exitResponse', ExitResponseMarshaller::class);
         $this->addMappingEntry('exitTest', ExitTestMarshaller::class);
-        $this->addMappingEntry(Figure::QTI_CLASS_NAME_FIGURE, Html5ContentMarshaller::class);
-        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME_FIGCAPTION, Html5ContentMarshaller::class);
         $this->addMappingEntry('fieldValue', FieldValueMarshaller::class);
         $this->addMappingEntry('hottextInteraction', HottextInteractionMarshaller::class);
         $this->addMappingEntry('inlineChoiceInteraction', InlineChoiceInteractionMarshaller::class);
diff --git a/qtism/data/storage/xml/marshalling/Qti22MarshallerFactory.php b/qtism/data/storage/xml/marshalling/Qti22MarshallerFactory.php
index 7d8f7547a..6281e1c13 100644
--- a/qtism/data/storage/xml/marshalling/Qti22MarshallerFactory.php
+++ b/qtism/data/storage/xml/marshalling/Qti22MarshallerFactory.php
@@ -24,6 +24,8 @@
 namespace qtism\data\storage\xml\marshalling;
 
 use qtism\common\utils\Reflection;
+use qtism\data\content\xhtml\html5\Figcaption;
+use qtism\data\content\xhtml\html5\Figure;
 use ReflectionClass;
 
 /**
@@ -38,6 +40,8 @@ class Qti22MarshallerFactory extends MarshallerFactory
     public function __construct()
     {
         parent::__construct();
+        $this->addMappingEntry(Figure::QTI_CLASS_NAME_FIGURE, Html5ContentMarshaller::class);
+        $this->addMappingEntry(Figcaption::QTI_CLASS_NAME_FIGCAPTION, Html5ContentMarshaller::class);
     }
 
     /**
diff --git a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
index 55338c09f..d1efc4d9d 100644
--- a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
+++ b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
@@ -78,7 +78,7 @@ public function testMarshallerBelow2p2Fails()
 
         $this->expectException(RuntimeException::class);
         $this->expectExceptionMessage(
-            "No marshaller implementation found while marshalling component with class name 'figure"
+            "No marshaller implementation could be found for component 'figure'."
         );
 
         $this->getMarshallerFactory('2.1.0')->createMarshaller($figure)->marshall($figure);

From 384a4217f0f6cfa4dd5858f4fe2204ce3ef84fff Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Thu, 2 Jun 2022 18:34:32 +0300
Subject: [PATCH 08/11] refactor: type hints and code style

---
 .../storage/xml/marshalling/Html5ContentMarshaller.php    | 2 +-
 qtism/data/storage/xml/versions/QtiVersion220.php         | 6 +++---
 test/qtismtest/data/content/enums/RoleTest.php            | 8 ++++----
 .../qtismtest/data/content/xhtml/html5/FigcaptionTest.php | 2 +-
 test/qtismtest/data/content/xhtml/html5/FigureTest.php    | 2 +-
 .../data/content/xhtml/html5/Html5LayoutElementTest.php   | 2 +-
 .../storage/xml/marshalling/Html5LayoutMarshallerTest.php | 8 ++++----
 7 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
index 8d6518a89..984d64557 100644
--- a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
@@ -103,7 +103,7 @@ protected function setLookupClasses()
         ];
     }
 
-    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element) {
+    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element): void {
         if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
             $title = $this->getDOMElementAttributeAs($element, 'title');
             $bodyElement->setTitle($title);
diff --git a/qtism/data/storage/xml/versions/QtiVersion220.php b/qtism/data/storage/xml/versions/QtiVersion220.php
index aa8417c02..7d58578b5 100644
--- a/qtism/data/storage/xml/versions/QtiVersion220.php
+++ b/qtism/data/storage/xml/versions/QtiVersion220.php
@@ -38,11 +38,11 @@ class QtiVersion220 extends QtiVersion
 
     const MARSHALLER_FACTORY = Qti22MarshallerFactory::class;
 
-    const HTML5_NAMESPACE = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
+    public const HTML5_NAMESPACE = 'http://www.imsglobal.org/xsd/imsqtiv2p2_html5_v1p0';
 
-    const HTML5_NAMESPACE_PREFIX = 'qh5';
+    public const HTML5_NAMESPACE_PREFIX = 'qh5';
 
-    const HTML5_XSD = 'http://www.imsglobal.org/xsd/qti/qtiv2p2/imsqtiv2p2p2_html5_v1p0.xsd';
+    public const HTML5_XSD = 'http://www.imsglobal.org/xsd/qti/qtiv2p2/imsqtiv2p2p2_html5_v1p0.xsd';
 
     public function getExternalNamespace(string $prefix): string
     {
diff --git a/test/qtismtest/data/content/enums/RoleTest.php b/test/qtismtest/data/content/enums/RoleTest.php
index 13e18b1b2..1b69d1691 100644
--- a/test/qtismtest/data/content/enums/RoleTest.php
+++ b/test/qtismtest/data/content/enums/RoleTest.php
@@ -7,12 +7,12 @@
 
 class RoleTest extends QtiSmEnumTestCase
 {
-    protected function getEnumerationFqcn()
+    protected function getEnumerationFqcn(): string
     {
         return Role::class;
     }
 
-    protected function getNames()
+    protected function getNames(): array
     {
         return [
             'article',
@@ -56,12 +56,12 @@ protected function getNames()
         ];
     }
 
-    protected function getKeys()
+    protected function getKeys(): array
     {
         return $this->getNames();
     }
 
-    protected function getConstants()
+    protected function getConstants(): array
     {
         return array_map(
             [Role::class, 'getConstantByName'],
diff --git a/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php b/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
index 16e60fcd5..8bbdc5b52 100644
--- a/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
+++ b/test/qtismtest/data/content/xhtml/html5/FigcaptionTest.php
@@ -61,4 +61,4 @@ public function testGetQtiClassName(): void
 
         self::assertEquals(Figcaption::QTI_CLASS_NAME_FIGCAPTION, $subject->getQtiClassName());
     }
-}
\ No newline at end of file
+}
diff --git a/test/qtismtest/data/content/xhtml/html5/FigureTest.php b/test/qtismtest/data/content/xhtml/html5/FigureTest.php
index df6f79de4..3f48b91bb 100644
--- a/test/qtismtest/data/content/xhtml/html5/FigureTest.php
+++ b/test/qtismtest/data/content/xhtml/html5/FigureTest.php
@@ -61,4 +61,4 @@ public function testGetQtiClassName(): void
 
         self::assertEquals(Figure::QTI_CLASS_NAME_FIGURE, $subject->getQtiClassName());
     }
-}
\ No newline at end of file
+}
diff --git a/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php b/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
index 7d32090ee..8f0ed57f3 100644
--- a/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
+++ b/test/qtismtest/data/content/xhtml/html5/Html5LayoutElementTest.php
@@ -68,4 +68,4 @@ public function getQtiClassName(): string
     {
         return '';
     }
-}
\ No newline at end of file
+}
diff --git a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
index d1efc4d9d..a10e37d45 100644
--- a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
+++ b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
@@ -23,7 +23,7 @@ class Html5LayoutMarshallerTest extends QtiSmTestCase
          </qh5:figure>
         ';
 
-    public function testUnmarshall()
+    public function testUnmarshall(): void
     {
         $figure = $this->createComponentFromXml(self::SUBJECT_XML, '2.2.2');
 
@@ -48,7 +48,7 @@ public function testUnmarshall()
         $this::assertEquals('caption text', $figcaptionContent[0]->getContent());
     }
 
-    public function testMarshall()
+    public function testMarshall(): void
     {
         $figCaption = new Figcaption(null, 'article', 'figcaptionId');
         $figCaption->setContent(new FlowCollection([
@@ -70,7 +70,7 @@ public function testMarshall()
         $this::assertEquals($expected, $dom->saveXML($element));
     }
 
-    public function testMarshallerBelow2p2Fails()
+    public function testMarshallerBelow2p2Fails(): void
     {
         $figCaption = new Figcaption();
         $figure = new Figure();
@@ -83,4 +83,4 @@ public function testMarshallerBelow2p2Fails()
 
         $this->getMarshallerFactory('2.1.0')->createMarshaller($figure)->marshall($figure);
     }
-}
\ No newline at end of file
+}

From 7412d64dec9290175a080069cd9e9f3a5313208b Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Fri, 3 Jun 2022 17:59:43 +0300
Subject: [PATCH 09/11] refactor: type hints and code style

---
 .../storage/xml/marshalling/Html5ContentMarshaller.php |  5 +++--
 .../xml/marshalling/Html5LayoutMarshallerTest.php      | 10 ++++++----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
index 984d64557..5ef016cb6 100644
--- a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
@@ -94,7 +94,7 @@ protected function marshallChildrenKnown(QtiComponent $component, array $element
         return $element;
     }
 
-    protected function setLookupClasses()
+    protected function setLookupClasses(): void
     {
         $this->lookupClasses = [
             "qtism\\data\\content\\xhtml",
@@ -103,7 +103,8 @@ protected function setLookupClasses()
         ];
     }
 
-    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element): void {
+    protected function fillBodyElement(BodyElement $bodyElement, DOMElement $element): void
+    {
         if (Version::compare($this->getVersion(), '2.2.0', '>=') === true) {
             $title = $this->getDOMElementAttributeAs($element, 'title');
             $bodyElement->setTitle($title);
diff --git a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
index a10e37d45..80e2bea36 100644
--- a/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
+++ b/test/qtismtest/data/storage/xml/marshalling/Html5LayoutMarshallerTest.php
@@ -51,14 +51,16 @@ public function testUnmarshall(): void
     public function testMarshall(): void
     {
         $figCaption = new Figcaption(null, 'article', 'figcaptionId');
-        $figCaption->setContent(new FlowCollection([
-            new TextRun('caption text')
-        ]));
+        $figCaption->setContent(
+            new FlowCollection([
+                new TextRun('caption text')
+            ])
+        );
 
         $img = new Img('assets/local_asset.jpg', 'alt', '', 'imgClass');
         $img->setWidth('100');
 
-        $figure = new Figure('title',null, "figureId");
+        $figure = new Figure('title', null, "figureId");
         $figure->setContent(new FlowCollection([$img, $figCaption]));
 
         $element = $this->getMarshallerFactory('2.2.2')->createMarshaller($figure)->marshall($figure);

From fb38e9927dbfaaa81626f67b62124b50a5683ef5 Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Fri, 10 Jun 2022 09:47:52 +0300
Subject: [PATCH 10/11] fix: phpdoc return type

---
 qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
index 5ef016cb6..eaeb60da7 100644
--- a/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
+++ b/qtism/data/storage/xml/marshalling/Html5ContentMarshaller.php
@@ -38,7 +38,7 @@ class Html5ContentMarshaller extends ContentMarshaller
     /**
      * @param DOMElement $element
      * @param QtiComponentCollection $children
-     * @return mixed
+     * @return QtiComponent
      * @throws UnmarshallingException
      */
     protected function unmarshallChildrenKnown(DOMElement $element, QtiComponentCollection $children): QtiComponent

From c31d3365fa542c81d56ecd00bdcc33208abd2d4f Mon Sep 17 00:00:00 2001
From: Nikita Pimenov <nikita.pimenov@taotesting.com>
Date: Fri, 10 Jun 2022 09:52:06 +0300
Subject: [PATCH 11/11] fix: phpdoc fix

---
 qtism/common/enums/AbstractEnumeration.php | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/qtism/common/enums/AbstractEnumeration.php b/qtism/common/enums/AbstractEnumeration.php
index 9133794e8..3a4704e17 100644
--- a/qtism/common/enums/AbstractEnumeration.php
+++ b/qtism/common/enums/AbstractEnumeration.php
@@ -30,11 +30,19 @@ abstract class AbstractEnumeration implements Enumeration
 {
     abstract public static function asArray(): array;
 
+    /**
+     * @param $name
+     * @return false|int
+     */
     public static function getConstantByName($name)
     {
         return static::asArray()[$name] ?? false;
     }
 
+    /**
+     * @param $constant
+     * @return false|string
+     */
     public static function getNameByConstant($constant)
     {
         $constants = array_flip(static::asArray());