Merge branch 'main' into issue-3911issue-3911

1 files changed, 208 insertions, 0 deletions

diff --git a/lib/flexi/Template.php b/lib/flexi/Template.php
new file mode 100644
index 0000000..44eefbe
--- /dev/null
+++ b/lib/flexi/Template.php
@@ -0,0 +1,208 @@
+<?php
+/**
+ * Abstract template class representing the presentation layer of an action.
+ *  Output can be customized by supplying attributes, which a template can
+ *  manipulate and display.
+ *
+ * @copyright 2008 Marcus Lunzenauer <mlunzena@uos.de>
+ * @author Marcus Lunzenauer <mlunzena@uos.de>
+ * @license MIT
+ */
+
+namespace Flexi;
+
+abstract class Template
+{
+    /**
+     * Parse, render and return the presentation.
+     *
+     * @return string A string representing the rendered presentation.
+     */
+    abstract protected function _render(): string;
+
+    protected array $attributes = [];
+    protected Template|null $layout = null;
+
+    /**
+     * Constructor
+     *
+     * @param string  $template the path of the template.
+     * @param Factory $factory  the factory creating this template
+     * @param array   $options  optional array of options
+     */
+    public function __construct(
+        protected string $template,
+        protected Factory $factory,
+        protected array $options = []
+    ) {
+    }
+
+    /**
+     * __set() is a magic method run when writing data to inaccessible members.
+     * In this class it is used to set attributes for the template in a
+     * comfortable way.
+     *
+     * @param string $name  the name of the member field
+     * @param mixed  $value the value for the member field
+     *
+     * @see http://php.net/__set
+     */
+    public function __set(string $name, mixed $value): void
+    {
+        $this->set_attribute($name, $value);
+    }
+
+    /**
+     * __get() is a magic method utilized for reading data from inaccessible
+     * members.
+     * In this class it is used to get attributes for the template in a
+     * comfortable way.
+     *
+     * @param string $name the name of the member field
+     *
+     * @return mixed the value for the member field
+     * @see http://php.net/__get
+     */
+    public function __get(string $name): mixed
+    {
+        return $this->get_attribute($name);
+    }
+
+    /**
+     * __isset() is a magic method triggered by calling isset() or empty() on
+     * inaccessible members.
+     * In this class it is used to check for attributes for the template in a
+     * comfortable way.
+     *
+     * @param string $name the name of the member field
+     *
+     * @return bool TRUE if that attribute exists, FALSE otherwise
+     * @see http://php.net/__isset
+     */
+    public function __isset(string $name): bool
+    {
+        return isset($this->attributes[$name]);
+    }
+
+    /**
+     * __unset() is a magic method invoked when unset() is used on inaccessible
+     * members.
+     * In this class it is used to check for attributes for the template in a
+     * comfortable way.
+     *
+     * @param string $name the name of the member field
+     *
+     * @see http://php.net/__set
+     */
+    public function __unset(string $name): void
+    {
+        $this->clear_attribute($name);
+    }
+
+    /**
+     * Parse, render and return the presentation.
+     *
+     * @param array $attributes An optional associative array of attributes and
+     *                          their associated values.
+     * @param string|Template|null $layout A name of a layout template.
+     *
+     * @return string A string representing the rendered presentation.
+     * @throws TemplateNotFoundException
+     */
+    public function render(array $attributes = [], string|Template $layout = null): string
+    {
+        if (isset($layout)) {
+            $this->set_layout($layout);
+        }
+
+        # merge attributes
+        $this->set_attributes($attributes);
+
+        return $this->_render();
+    }
+
+    /**
+     * Returns the value of an attribute.
+     *
+     * @param string $name An attribute name.
+     * @return mixed  An attribute value.
+     */
+    public function get_attribute(string $name)
+    {
+        return $this->attributes[$name] ?? null;
+    }
+
+    /**
+     * Set an array of attributes.
+     *
+     * @return array An associative array of attributes and their associated
+     *               values.
+     */
+    public function get_attributes(): array
+    {
+        return $this->attributes;
+    }
+
+    /**
+     * Set an attribute.
+     *
+     * @param string $name  An attribute name.
+     * @param mixed  $value An attribute value.
+     */
+    public function set_attribute(string $name, mixed $value): void
+    {
+        $this->attributes[$name] = $value;
+    }
+
+    /**
+     * Set an array of attributes.
+     *
+     * @param array $attributes An associative array of attributes and their
+     *                          associated values.
+     */
+    public function set_attributes(array $attributes): void
+    {
+        $this->attributes = $attributes + $this->attributes;
+    }
+
+
+    /**
+     * Clear all attributes associated with this template.
+     */
+    public function clear_attributes(): void
+    {
+        $this->attributes = [];
+    }
+
+    /**
+     * Clear an attribute associated with this template.
+     *
+     * @param string $name The name of the attribute to be cleared.
+     */
+    public function clear_attribute(string $name): void
+    {
+        unset($this->attributes[$name]);
+    }
+
+    /**
+     * Set the template's layout.
+     *
+     * @param Template|string|null $layout A name of a layout template or a
+     *                                     layout template.
+     * @throws TemplateNotFoundException
+     */
+    public function set_layout(Template|string|null $layout): void
+    {
+        $this->layout = $layout ? $this->factory->open($layout) : null;
+    }
+
+    /**
+     * Returns the template's layout.
+     *
+     * @return Template|null
+     */
+    public function get_layout(): ?Template
+    {
+        return $this->layout;
+    }
+}