HtmlForm.php

Go to the documentation of this file.

<?php


 
namespace Depage\HtmlForm;
 

function autoload($class)
{
    $class = str_replace('\\', '/', str_replace(__NAMESPACE__ . '\\', '', $class));
    $filePath = __DIR__ . '/' . $class . '.php';
    $filePath = str_replace('..', '', $filePath);
 
    $resolved = realpath($filePath);
    if ($resolved !== false && file_exists($resolved)) {
        require_once($resolved);
    }
}
 
spl_autoload_register(__NAMESPACE__ . '\autoload');

class HtmlForm extends Abstracts\Container
{
    public const priorityCountries = [
        'en' => ['us','gb','ie','au','nz'],
        'de' => ['de','at','ch'],
        'fr' => ['fr','ch','be','lu','ca'],
        'it' => ['it','ch'],
    ];
    protected $method;

    protected $url;

    protected $submitURL;

    protected $successURL;

    protected $cancelURL;

    protected $label;

    protected $backLabel;

    protected $cancelLabel;

    protected $class;

    protected $validator;

    protected $jsValidation;

    protected $jsAutosave;

    protected $sessionSlotName;

    protected $sessionSlot;

    private $currentStepId;

    private $steps = [];

    protected $ttl;

    public $valid;

    public $isAutoSaveRequest = false;

    protected $internalFields = [
        'formIsValid',
        'formIsAutosaved',
        'formName',
        'formTimestamp',
        'formStep',
        'formFinalPost',
        'formCsrfToken',
        'formCaptcha',
    ];

    protected $namespaces = ['\\Depage\\HtmlForm\\Elements'];
    public function __construct(string $name, array $parameters = [], HtmlForm|null $form = null)
    {
        // workaround for crash with gettext when LANG is not set in the environment
        // gettext is used in default settings of some input elements (e,g, error messages)
        if (empty(getenv('LANG'))) {
            $fallback = getenv('LANGUAGE') ?: 'en_US.UTF-8';
            putenv('LANG=' . $fallback);
        }
        $this->isAutoSaveRequest = isset($_POST['formAutosave']) && $_POST['formAutosave'] === "true";
 
        parent::__construct($name, $parameters, $this);
 
        $this->url = parse_url($this->submitURL);
        if (!empty($this->successURL)) {
            $this->validateRedirectUrl($this->successURL, true);
        }
        if (!empty($this->cancelURL)) {
            $this->validateRedirectUrl($this->cancelURL, true);
        }
        if (empty($this->successURL)) {
            $this->successURL = $this->submitURL;
        }
        if (empty($this->cancelURL)) {
            $this->cancelURL = $this->submitURL;
        }
 
        $this->currentStepId = isset($_GET['step']) ? $_GET['step'] : 0;
 
        $this->startSession();
 
        $this->valid = (isset($this->sessionSlot['formIsValid'])) ? $this->sessionSlot['formIsValid'] : null;
 
        // set CSRF Token
        if (!isset($this->sessionSlot['formCsrfToken'])) {
            $this->sessionSlot['formCsrfToken'] = $this->getNewCsrfToken();
        }
 
        if (!isset($this->sessionSlot['formFinalPost'])) {
            $this->sessionSlot['formFinalPost'] = false;
        }
 
        // create a hidden input to tell forms apart
        $this->addHidden('formName')->setValue($this->name);
 
        // create hidden input for submitted step
        $this->addHidden('formStep')->setValue($this->currentStepId);
 
        // create hidden input for CSRF token
        $this->addHidden('formCsrfToken')->setValue($this->sessionSlot['formCsrfToken']);
 
        $this->addChildElements();
    }

    protected function setDefaults(): void
    {
        parent::setDefaults();
 
        $this->defaults['label']        = 'submit';
        $this->defaults['cancelLabel']  = '';
        $this->defaults['backLabel']    = '';
        $this->defaults['class']        = '';
        $this->defaults['method']       = 'post';
        // @todo adjust submit url for steps when used
        $this->defaults['submitURL']    = $_SERVER['REQUEST_URI'];
        $this->defaults['successURL']   = null;
        $this->defaults['cancelURL']    = null;
        $this->defaults['validator']    = null;
        $this->defaults['ttl']          = 60 * 60; // 60 minutes
        $this->defaults['jsValidation'] = 'blur';
        $this->defaults['jsAutosave']   = 'false';
    }

    private function startSession(): void
    {
        // check if there's an open session
        if (!session_id()) {
            $params = session_get_cookie_params();
            $sessionName = session_name();
 
            session_set_cookie_params([
                'lifetime' => $this->ttl,
                'path' => $params['path'],
                'domain' => $params['domain'],
                'secure' => $params['secure'],
                'httponly' => $params['httponly'],
                'samesite' => 'Lax',
            ]);
            session_start();
 
            // Extend the expiration time upon page load
            if (isset($_COOKIE[$sessionName])) {
                setcookie(
                    $sessionName,
                    $_COOKIE[$sessionName],
                    time() + $this->ttl,
                    $params['path'],
                    $params['domain'],
                    $params['secure'],
                    $params['httponly'],
                );
            }
        }
        $this->sessionSlotName  = 'htmlform-' . $this->name . '-data';
        $this->sessionSlot      = & $_SESSION[$this->sessionSlotName];
 
        $this->sessionExpiry();
    }
    private function sessionExpiry(): void
    {
        if (isset($this->ttl) && is_numeric($this->ttl)) {
            $timestamp = time();
 
            if (
                isset($this->sessionSlot['formTimestamp'])
                && ($timestamp - $this->sessionSlot['formTimestamp'] > $this->ttl)
            ) {
                $this->clearSession();
                $this->sessionSlot = & $_SESSION[$this->sessionSlotName];
            }
 
            $this->sessionSlot['formTimestamp'] = $timestamp;
        }
    }
    public function isEmpty()
    {
        return !isset($this->sessionSlot['formName']);
    }

    protected function getNewCsrfToken(): string
    {
        // Keep drawing fresh tokens until the OS CSPRNG reports the bytes are
        // cryptographically strong. If the RNG is in degraded mode the token
        // would be predictable and CSRF protection would be defeated.
        do {
            $csrfToken = base64_encode(openssl_random_pseudo_bytes(16, $cryptoStrong));
        } while (!$cryptoStrong && strlen($csrfToken) > 0);
 
        return $csrfToken;
    }

    protected function addElement(string $type, string $name, array $parameters): Abstracts\Element
    {
        $this->checkElementName($name);
 
        $newElement = parent::addElement($type, $name, $parameters);
 
        if ($newElement instanceof Elements\Step) {
            $this->steps[] = $newElement;
        }
        if ($newElement instanceof Abstracts\Input) {
            $this->updateInputValue($name);
        }
 
        return $newElement;
    }

    public function checkElementName(string $name): void
    {
        foreach ($this->getElements(true) as $element) {
            if ($element->getName() === $name) {
                throw new Exceptions\DuplicateElementNameException("Element name \"{$name}\" already in use.");
            }
        }
    }

    private function getCurrentElements(): array
    {
        $currentElements = [];
 
        foreach ($this->elements as $element) {
            if ($element instanceof Abstracts\Container) {
                if (
                    !($element instanceof Elements\Step)
                    || (isset($this->steps[$this->currentStepId]) && ($element == $this->steps[$this->currentStepId]))
                ) {
                    $currentElements = array_merge($currentElements, $element->getElements());
                }
            } else {
                $currentElements[] = $element;
            }
        }
 
        return $currentElements;
    }
    public function registerNamespace(string $namespace): void
    {
        $this->namespaces[] = $namespace;
    }

    public function getNamespaces(): array
    {
        return $this->namespaces;
    }

    private function inCurrentStep(string $name): bool
    {
        return in_array($this->getElement($name), $this->getCurrentElements());
    }
    public function setCurrentStep(int|null $step = null): void
    {
        if (!is_null($step)) {
            $this->currentStepId = $step;
        }
        if (!is_numeric($this->currentStepId)
            || ($this->currentStepId > count($this->steps) - 1)
            || ($this->currentStepId < 0)
        ) {
            $this->currentStepId = $this->getFirstInvalidStep();
        }
    }
    public function getUrl(): array
    {
        return $this->url;
    }

    public function getSteps(): array
    {
        return $this->steps;
    }

    public function getCurrentStepId(): int
    {
        return $this->currentStepId;
    }

    public function getFirstInvalidStep(): int
    {
        if (count($this->steps) > 0) {
            foreach ($this->steps as $stepNumber => $step) {
                if (!$step->validate()) {
                    return $stepNumber;
                }
            }
            return count($this->steps) - 1;
        } else {
            return 0;
        }
    }

    public function buildUrl(array $args = []): string
    {
        $url = isset($this->url['scheme']) ? $this->url['scheme'] . '://' : '';
        $url .= $this->url['host'] ?? '';
        $url .= isset($this->url['port']) ? ':' . $this->url['port'] : '';
        $url .= $this->url['path'] ?? '';
        $url .= $this->buildUrlQuery($args);
 
        return $url;
    }

    public function buildUrlQuery(array $args = []): string
    {
        $query = '';
        $queryParts = [];
 
        if (isset($this->url['query']) && $this->url['query'] != "") {
            //decoding query string
            $query = html_entity_decode($this->url['query']);
 
            //parsing the query into an array
            parse_str($query, $queryParts);
        }
 
        foreach ($args as $name => $value) {
            if ($value != "") {
                $queryParts[$name] = $value;
            } elseif (isset($queryParts[$name])) {
                unset($queryParts[$name]);
            }
        }
 
        // build the query again
        $query = http_build_query($queryParts);
 
        if ($query == "") {
            return "";
        }
 
        return "?" . $query;
    }

    public function updateInputValue(string $name): void
    {
        $element = $this->getElement($name);
 
        // handle captcha phrase
        if ($this->getElement($name) instanceof Elements\Captcha) {
            $element->setSessionSlot($this->sessionSlot);
        }
 
        // if it's a post, take the value from there and save it to the session
        if (
            isset($_POST['formName']) && ($_POST['formName'] === $this->name)
            && $this->inCurrentStep($name)
            && isset($_POST['formCsrfToken']) && $_POST['formCsrfToken'] === $this->sessionSlot['formCsrfToken']
        ) {
            if ($this->getElement($name) instanceof Elements\File) {
                // handle uploaded file
                $oldValue = isset($this->sessionSlot[$name]) ? $this->sessionSlot[$name] : null;
                $this->sessionSlot[$name] = $element->handleUploadedFiles($oldValue);
            } elseif (!$element->getDisabled()) {
                // save value
                $value = isset($_POST[$name]) ? $_POST[$name] : null;
                $this->sessionSlot[$name] = $element->setValue($value);
            } elseif (!isset($this->sessionSlot[$name])) {
                // set default value for disabled elements
                $this->sessionSlot[$name] = $element->setValue($element->getDefaultValue());
            }
        }
        // if it's not a post, try to get the value from the session
        elseif (isset($this->sessionSlot[$name])) {
            $element->setValue($this->sessionSlot[$name]);
        }
    }

    public function clearInputValue(string $name): void
    {
        $element = $this->getElement($name);
 
        $this->sessionSlot[$name] = $element->clearValue();
    }

    public function populate(array|object $data = []): void
    {
        foreach ($this->getElements() as $element) {
            $name = $element->name;
            if (!in_array($name, $this->internalFields)) {
                if (is_array($data) && isset($data[$name])) {
                    $value = $data[$name];
                } elseif (is_object($data) && isset($data->$name)) {
                    $value = $data->$name;
                }
 
                if (isset($value)) {
                    $element->setDefaultValue($value);
                    if ($element->getDisabled() && !isset($this->sessionSlot[$name])) {
                        $this->sessionSlot[$name] = $value;
                    }
                }
 
                unset($value);
            }
        }
    }

    public function process(): void
    {
        $this->setCurrentStep();
        // if there's post-data from this form
        if (isset($_POST['formName']) && ($_POST['formName'] === $this->name)) {
            // CSRF verification: a form submission with a missing or incorrect
            // token is rejected here, before any onPost() business logic or
            // session mutation (formFinalPost, value population) can run.
            $csrfToken = isset($_POST['formCsrfToken']) ? $_POST['formCsrfToken'] : null;
            if (!is_string($csrfToken) || $csrfToken !== $this->sessionSlot['formCsrfToken']) {
                $this->httpResponseCode(400);
                $this->log('HtmlForm: Request rejected because of a missing or incorrect CsrfToken');
                return;
            }
 
            // save in session if submission was from last step
            $this->sessionSlot['formFinalPost'] = count($this->steps) == 0 || $_POST['formStep'] + 1 == count($this->steps)
                && !$this->isAutoSaveRequest;
 
            if (!empty($this->cancelLabel) && isset($_POST['formSubmit']) && $_POST['formSubmit'] === $this->cancelLabel) {
                // cancel button was pressed
                $this->clearSession();
                $this->redirect($this->cancelURL);
            } elseif ($this->isAutoSaveRequest) {
                // do not redirect -> is autosave
                $this->onPost();
            } elseif (!empty($this->backLabel) && isset($_POST['formSubmit']) && $_POST['formSubmit'] === $this->backLabel) {
                // back button was pressed
                $this->onPost();
 
                $this->sessionSlot['formFinalPost'] = false;
                $prevStep = $this->currentStepId - 1;
                if ($prevStep < 0) {
                    $prevStep = 0;
                }
                $this->redirect($this->buildUrl(['step' => ($prevStep <= 0) ? '' : $prevStep]));
            } elseif ($this->validate()) {
                // form was successfully submitted
                $this->onPost();
 
                $this->redirect($this->successURL);
            } else {
                // goto to next step or display first invalid step
                $this->onPost();
 
                $nextStep = $this->currentStepId + 1;
                $firstInvalidStep = $this->getFirstInvalidStep();
                if ($nextStep > $firstInvalidStep) {
                    $nextStep = $firstInvalidStep;
                }
                if ($nextStep > count($this->steps)) {
                    $nextStep = count($this->steps) - 1;
                }
                $this->redirect($this->buildUrl(['step' => ($nextStep == 0) ? '' : $nextStep]));
            }
        }
    }

    public function validate(): bool
    {
        // onValidate hook for custom required/validation rules
        $this->valid = $this->onValidate();
 
        $this->valid = $this->valid && $this->validateAutosave();
 
        if ($this->valid && !is_null($this->validator)) {
            if (is_callable($this->validator)) {
                $this->valid = call_user_func($this->validator, $this, $this->getValues());
            } else {
                throw new Exceptions\ValidatorNotCallable("The validator paramater must be callable");
            }
        }
        $this->valid = $this->valid && $this->sessionSlot['formFinalPost'];
 
        // save validation-state in session
        $this->sessionSlot['formIsValid'] = $this->valid;
 
        return $this->valid;
    }

    protected function onPost(): bool
    {
        return true;
    }

    protected function onValidate(): bool
    {
        return true;
    }

    public function validateAutosave(): bool
    {
        parent::validate();
 
        if (isset($_POST['formName'])) {
            // Enforce CSRF for the submission itself: a missing or incorrect
            // token here is treated as invalid (not silently accepted). This is
            // scoped to actual form submissions only, so a direct validate()
            // call (no POST) used to check a finalized form stays unaffected.
            $csrfToken = isset($_POST['formCsrfToken']) ? $_POST['formCsrfToken'] : null;
            $hasCorrectToken = is_string($csrfToken) && ($csrfToken === $this->sessionSlot['formCsrfToken']);
            $this->valid = $this->valid && $hasCorrectToken;
 
            if (!$hasCorrectToken) {
                $this->httpResponseCode(400);
                $this->log('HtmlForm: Request invalid because of a missing or incorrect CsrfToken');
            }
        }
 
        $partValid = $this->valid;
 
        // save data in session when autosaving but don't validate successfully
        if ($this->isAutoSaveRequest
            || (isset($this->sessionSlot['formIsAutosaved'])
            && $this->sessionSlot['formIsAutosaved'] === true)
        ) {
            $this->valid = false;
        }
 
        // save whether form was autosaved the last time
        $this->sessionSlot['formIsAutosaved'] = $this->isAutoSaveRequest;
 
        return $partValid;
    }

    public function getValues(): ?array
    {
        if (isset($this->sessionSlot)) {
            // remove internal attributes from values
            return array_diff_key($this->sessionSlot, array_fill_keys($this->internalFields, ''));
        } else {
            return null;
        }
    }

    public function getValuesWithLabel(): ?array
    {
        //get values first
        $values = $this->getValues();
        $valuesWithLabel = [];
        if (isset($values)) {
            foreach ($values as $element => $value) {
                $elem = $this->getElement($element);
 
                if ($elem) {
                    $valuesWithLabel[$element] = [
                        "value" => $value,
                        "label" => $elem->getLabel(),
                    ];
                }
            }
 
            return $valuesWithLabel;
        } else {
            return null;
        }
    }

    private function validateRedirectUrl(string $url, $allowExternal = false): void
    {
        if (empty($url)) {
            return;
        }
 
        $parsed = parse_url($url);
 
        if ($parsed === false) {
            throw new \InvalidArgumentException("Invalid redirect URL.");
        }
 
        if (isset($parsed['scheme']) && !in_array(strtolower($parsed['scheme']), ['http', 'https'], true)) {
            throw new \InvalidArgumentException("Redirect to non-HTTP scheme not allowed.");
        }
 
        if (!isset($parsed['host'])) {
            return;
        }
 
        if (!$allowExternal) {
            $allowedHosts = $_SERVER['HTTP_HOST'] ?? '';
            $allowedHosts = array_map('trim', explode(',', $allowedHosts));
            if (!in_array($parsed['host'], $allowedHosts, true)) {
                throw new \InvalidArgumentException("Redirect to external host not allowed.");
            }
        }
    }
    private function validateRedirect(string $url): void
    {
        if (empty($url)) {
            throw new \InvalidArgumentException("Empty URL.");
        }
 
        if (preg_match('/[\r\n]/', $url)) {
            throw new \InvalidArgumentException("Invalid URL: newline characters detected.");
        }
 
        $parsed = parse_url($url);
        if ($parsed === false) {
            throw new \InvalidArgumentException("Invalid URL format.");
        }
 
        if (isset($parsed['scheme'])) {
            $allowedSchemes = ['http', 'https'];
            if (!in_array(strtolower($parsed['scheme']), $allowedSchemes, true)) {
                throw new \InvalidArgumentException("Invalid URL scheme.");
            }
        }
    }
    public function redirect(string $url): void
    {
        $this->validateRedirect($url);
        $safeUrl = htmlspecialchars($url, ENT_QUOTES | FILTER_FLAG_NO_ENCODE_QUOTES, 'UTF-8');
        header('Location: ' . $safeUrl);
        exit;
    }

    public function httpResponseCode(int $code): void
    {
        http_response_code($code);
    }

    public function clearSession(bool $clearCsrfToken = true): void
    {
        if ($clearCsrfToken) {
            // clear everything
            $this->clearValue();
 
            unset($_SESSION[$this->sessionSlotName]);
            unset($this->sessionSlot);
        } else {
            // clear everything except internal fields
            foreach ($this->getElements(false) as $element) {
                if (!$element->getDisabled() && !in_array($element->name, $this->internalFields)) {
                    unset($this->sessionSlot[$element->name]);
                }
            }
        }
    }

    public static function clearOldSessions(int $ttl = 3600, string $pattern = "/^htmlform-.*/"): void
    {
        $timestamp = time();
 
        if (empty($_SESSION)) {
            return;
        }
        foreach ($_SESSION as $key => &$val) {
            if (preg_match($pattern, $key)
                && isset($val['formTimestamp'])
                && ($timestamp - $val['formTimestamp'] > $ttl)
            ) {
                unset($_SESSION[$key]);
            }
        }
    }

    protected function htmlDataAttributes(): string
    {
        $this->dataAttr['jsvalidation'] = $this->jsValidation;
        $this->dataAttr['jsautosave'] = $this->jsAutosave === true ? "true" : $this->jsAutosave;
 
        return parent::htmlDataAttributes();
    }

    protected function htmlSubmitURL(): string
    {
        $step = $this->currentStepId != 0 ? $this->currentStepId : '';
 
        return $this->htmlEscape($this->buildUrl(['step' => $step]));
    }

    public function __toString(): string
    {
        $renderedElements = '';
        $submit           = '';
        $cancel           = '';
        $back             = '';
        $label            = $this->htmlLabel();
        $cancellabel      = $this->htmlCancelLabel();
        $backlabel        = $this->htmlBackLabel();
        $class            = $this->htmlClass();
        $method           = $this->htmlMethod();
        $submitURL        = $this->htmlSubmitURL();
        $dataAttr         = $this->htmlDataAttributes();
        $disabledAttr     = $this->disabled ? " disabled=\"disabled\"" : "";
 
        foreach ($this->elementsAndHtml as $element) {
            // leave out inactive step elements
            if (!($element instanceof Elements\Step)
                || (isset($this->steps[$this->currentStepId]) && $this->steps[$this->currentStepId] == $element)
            ) {
                $renderedElements .= $element;
            }
        }
 
        if (!empty($this->cancelLabel)) {
            $cancel = "<p id=\"{$this->name}-cancel\" class=\"cancel\"><input type=\"submit\" name=\"formSubmit\" value=\"{$cancellabel}\"$disabledAttr></p>\n";
        }
        if (!empty($this->backLabel) && $this->currentStepId > 0) {
            $back = "<p id=\"{$this->name}-back\" class=\"back\"><input type=\"submit\" name=\"formSubmit\" value=\"{$backlabel}\"$disabledAttr></p>\n";
        }
        if (!empty($this->label)) {
            $submit = "<p id=\"{$this->name}-submit\" class=\"submit\"><input type=\"submit\" name=\"formSubmit\" value=\"{$label}\"$disabledAttr></p>\n";
        }
 
 
        return "<form id=\"{$this->name}\" name=\"{$this->name}\" class=\"depage-form {$class}\" method=\"{$method}\" action=\"{$submitURL}\"{$dataAttr} enctype=\"multipart/form-data\">" . "\n" .
            $renderedElements .
            $submit .
            $cancel .
            $back .
        "</form>";
    }
}












 
/* vim:set ft=php sw=4 sts=4 fdm=marker et : */