1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 279: 280: 281: 282: 283: 284: 285: 286: 287: 288: 289: 290: 291: 292: 293: 294: 295: 296: 297: 298: 299: 300: 301: 302: 303: 304: 305: 306: 307: 308: 309: 310: 311: 312: 313: 314: 315: 316: 317: 318: 319: 320: 321: 322: 323: 324: 325: 326: 327: 328: 329: 330: 331: 332: 333: 334: 335: 336: 337: 338: 339: 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: 350: 351: 352: 353: 354: 355: 356: 357: 358: 

<?php

/**
 * MvcCore
 *
 * This source file is subject to the BSD 3 License
 * For the full copyright and license information, please view
 * the LICENSE.md file that are distributed with this source code.
 *
 * @copyright   Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
 * @license     https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
 */

namespace MvcCore\Ext\Form;

/**
 * Trait for class `MvcCore\Ext\Form` containing submitting logic and methods.
 */
trait Submitting {

    /**
     * Process standard low level submit process.
     * If no params passed as first argument, all params from object
     * `\MvcCore\Application::GetInstance()->GetRequest()` are used.
     * - If fields are not initialized - initialize them by calling `$form->Init();`.
     * - Check maximum post size by php configuration if form is posted.
     * - Check cross site request forgery tokens with session tokens.
     * - Process all field values and their validators and call `$form->AddError()` where necessary.
     *   `AddError()` method automatically switch `$form->Result` property to zero - `0`, it means error submit result.
     * Return array with form result, safe values from validators and errors array.
     * @param array $rawRequestParams optional
     * @return array An array to list: `[$form->result, $form->data, $form->errors];`
     */
    public function Submit (array & $rawRequestParams = []) {
        /** @var $this \MvcCore\Ext\Form */
        if ($this->dispatchState < \MvcCore\IController::DISPATCH_STATE_INITIALIZED) 
            $this->Init(TRUE);
        if ($this->dispatchState < \MvcCore\IController::DISPATCH_STATE_PRE_DISPATCHED) 
            $this->PreDispatch(TRUE);
        if (!$rawRequestParams) 
            $rawRequestParams = $this->request->GetParams(FALSE);
        $this->SubmitSetStartResultState($rawRequestParams);
        if ($this->SubmitValidateMaxPostSizeIfNecessary()) {
            $this
                ->SubmitCsrfTokens($rawRequestParams)
                ->SubmitAllFields($rawRequestParams);
        }
        $this->SaveSession();
        return [
            $this->result,
            $this->values,
            $this->errors,
        ];
    }

    /**
     * Try to set up form submit result state into any special positive
     * value by presented submit button name in `$rawRequestParams` array
     * if there is any special submit result value configured by button names
     * in `$form->customResultStates` array. If no special button submit result
     * value configured, submit result state is set to `1` by default.
     * @param array $rawRequestParams
     * @return \MvcCore\Ext\Form
     */
    public function SubmitSetStartResultState (array & $rawRequestParams = []) {
        /** @var $this \MvcCore\Ext\Form */
        if (!$this->customResultStates) {
            $this->result = \MvcCore\Ext\IForm::RESULT_SUCCESS;
        } else {
            // try to find if there is any field name (button:submit or input:submit)
            // in raw request params with submit start custom result state:
            $customResultStateDefined = FALSE;
            foreach ($this->customResultStates as $fieldName => $customResultState) {
                if (isset($rawRequestParams[$fieldName])) {
                    $customResultStateDefined = TRUE;
                    $this->result = $customResultState;
                    break;
                }
            }
            if (!$customResultStateDefined)
                $this->result = \MvcCore\Ext\IForm::RESULT_SUCCESS;
        }
        return $this;
    }

    /**
     * Validate maximum posted size in POST request body by `Content-Length` HTTP header.
     * If there is no `Content-Length` request header, add error.
     * If `Content-Length` value is bigger than `post_max_size` from PHP INI, add form error.
     * @return boolean
     */
    public function SubmitValidateMaxPostSizeIfNecessary () {
        /** @var $this \MvcCore\Ext\Form */
        if ($this->method != \MvcCore\Ext\IForm::METHOD_POST) 
            return TRUE;
        $contentLength = $this->request->GetContentLength();
        if ($contentLength === NULL) $this->AddError(
            $this->GetDefaultErrorMsg(\MvcCore\Ext\Forms\IError::EMPTY_CONTENT)
        );
        $maxSize = $this->GetPhpIniSizeLimit('post_max_size');
        if ($maxSize !== NULL && $maxSize < $contentLength) {
            $viewClass = $this->viewClass;
            $displayErrors = @ini_get("display_errors");
            if ($displayErrors || strtolower($displayErrors) == 'on') {
                $obContent = ob_get_contents();
                if (preg_match(
                    "#Warning([^\:]*)\:\s+POST Content\-Length of ([0-9]+) bytes exceeds the limit of ([0-9]+) bytes#", 
                    $obContent
                )) ob_clean();
            }
            $this->AddError($viewClass::Format(
                $this->GetDefaultErrorMsg(\MvcCore\Ext\Forms\IError::MAX_POST_SIZE),
                [static::ConvertBytesIntoHumanForm($maxSize)]
            ));
            return FALSE;
        }
        return TRUE;
    }

    /**
     * Go through all fields, which are not `button:submit` or `input:submit` types
     * and call on every `$field->Submit()` method to process all configured field validators.
     * If method `$field->Submit()` returns anything else than `NULL`, that value is automatically
     * assigned under field name into form result values and into form field value.
     * @param array $rawRequestParams
     * @return \MvcCore\Ext\Form
     */
    public function SubmitAllFields (array & $rawRequestParams = []) {
        /** @var $this \MvcCore\Ext\Form */
        $rawRequestParams = $this->submitAllFieldsEncodeAcceptCharsets($rawRequestParams);
        $this->values = [];
        foreach ($this->fields as $fieldName => $field) {
            if ($field instanceof \MvcCore\Ext\Forms\Fields\ISubmit) continue;
            $safeValue = $field->Submit($rawRequestParams);
            if ($safeValue === NULL) {
                $this->values[$fieldName] = NULL;
            } else {
                $field->SetValue($safeValue);
                $this->values[$fieldName] = $safeValue;
            }
        }
        return $this;
    }


    /**
     * Call this function in custom `\MvcCore\Ext\Form::Submit();` method implementation
     * at the end of custom `Submit()` method to redirect user by configured success/error/prev/next
     * step URL address into final place and store everything into session.
     * You can also to redirect form after submit by yourself.
     * @return void
     */
    public function SubmittedRedirect () {
        /** @var $this \MvcCore\Ext\Form */
        if ($this->dispatchState < \MvcCore\IController::DISPATCH_STATE_INITIALIZED) 
            $this->Init(TRUE);
        if ($this->dispatchState < \MvcCore\IController::DISPATCH_STATE_PRE_DISPATCHED) 
            $this->PreDispatch(TRUE);
        $urlPropertyName = '';
        $redirectMsg = '';
        if ($this->result === \MvcCore\Ext\IForm::RESULT_ERRORS) {
            $urlPropertyName = 'errorUrl';
            $redirectMsg = 'error URL';
        } else if ($this->result === \MvcCore\Ext\IForm::RESULT_SUCCESS) {
            $urlPropertyName = 'successUrl';
            $redirectMsg = 'success URL';
        } else if ($this->result === \MvcCore\Ext\IForm::RESULT_PREV_PAGE) {
            $urlPropertyName = 'prevStepUrl';
            $redirectMsg = 'previous step URL';
        } else if ($this->result === \MvcCore\Ext\IForm::RESULT_NEXT_PAGE) {
            $urlPropertyName = 'nextStepUrl';
            $redirectMsg = 'next step URL';
        }
        $url = isset($this->{$urlPropertyName}) ? $this->{$urlPropertyName} : NULL;
        $errorMsg = $url ? '' : 'Specify `' . $urlPropertyName . '` property.' ;
        if ($this->result) $this->values = [];
        $this->SaveSession();
        if (!$url && $this->result > -1 && $this->result < 4)
            throw new \RuntimeException(
                '['.get_class().'] No url specified to redirect. ' . $errorMsg
            );
        if ($url) self::Redirect(
            $url,
            \MvcCore\IResponse::SEE_OTHER,
            'Form has been submitted and redirected to ' . $redirectMsg
        );
    }

    /**
     * Get cached validator instance by name. If validator instance doesn't exist
     * in `$this->validators` array, create new validator instance, cache it and return it.
     * @param string $validatorName
     * @return \MvcCore\Ext\Forms\Validator
     */
    public function & GetValidator ($validatorName) {
        /** @var $this \MvcCore\Ext\Form */
        if (isset($this->validators[$validatorName])) {
            $validator = $this->validators[$validatorName];
        } else {
            $validator = NULL;
            $toolClass = self::$toolClass;
            foreach (static::$validatorsNamespaces as $validatorsNamespace) {
                $validatorFullClassName =  $validatorsNamespace . $validatorName;
                if (
                    class_exists($validatorFullClassName) &&
                    $toolClass::CheckClassInterface(
                        $validatorFullClassName, 'MvcCore\\Ext\\Forms\\IValidator', TRUE, TRUE
                    )
                ) {
                    $validator = $validatorFullClassName::CreateInstance()
                        ->SetForm($this);
                    break;
                }
            }
            if ($validator === NULL) $this->throwNewInvalidArgumentException(
                "Validator `{$validatorName}` not found in any namespace: `"
                . implode('`, `', static::$validatorsNamespaces) . '`.'
            );
            $this->validators[$validatorName] = $validator;
        }
        return $validator;
    }

    /**
     * Get error message string from internal protected static property
     * `\MvcCore\Ext\Form::$defaultErrorMessages` by given integer index.
     * @param int $index
     * @return string
     */
    public function GetDefaultErrorMsg ($index) {
        /** @var $this \MvcCore\Ext\Form */
        return static::$defaultErrorMessages[$index];
    }

    /**
     * If form has defined any `accept-charset` attribute values,
     * go through all accept charset(s) and try to transcode all raw values
     * and collect translation statistics from this process. Then decode
     * best translation charset and return by given param `$rawRequestParams`
     * new translated raw values by first best charset in `accept-charset` attribute.
     * @param array & $rawRequestParams
     * @return array
     */
    protected function & submitAllFieldsEncodeAcceptCharsets (array & $rawRequestParams = []) {
        /** @var $this \MvcCore\Ext\Form */
        if (count($this->acceptCharsets) === 0) return $rawRequestParams;
        $toEncoding = strtoupper($this->GetResponse()->GetEncoding());
        if (!static::$toolClass) static::$toolClass = \MvcCore\Application::GetInstance()->GetToolClass();
        // try to translate one accepting charset by one and collect success statistics
        $bestCharset = NULL;
        $translatedStats = [];
        $translatedRawRequestParams = [];
        foreach ($this->acceptCharsets as $acceptCharset) {
            if ($acceptCharset === 'UNKNOWN') $acceptCharset = $toEncoding;
            list($stats, $total, $rawTranslatedValues) = $this->encodeAcceptCharsetsArrayOrString(
                $rawRequestParams, $acceptCharset, $toEncoding
            );
            $translatedRawRequestParams[$acceptCharset] = $rawTranslatedValues;
            if ($total === $stats) {
                $bestCharset = $acceptCharset;
                break;
            } else {
                $translatedStats[$acceptCharset] = $stats;
            }
        }
        if (!$bestCharset) {
            // decide which charset is the best
            asort($translatedStats);
            $translatedStats = array_reverse($translatedStats);
            reset($translatedStats);
            $firstCharset = current(array_keys($translatedStats));
            $bestScore = $translatedStats[$firstCharset];
            foreach ($this->acceptCharsets as $acceptCharset) {
                if ($acceptCharset === 'UNKNOWN') $acceptCharset = $toEncoding;
                if ($translatedStats[$acceptCharset] === $bestScore) {
                    $bestCharset = $acceptCharset;
                    break;
                }
            }
        }
        return $translatedRawRequestParams[$bestCharset];
    }

    /**
     * Try to encode raw input `array` or `string` by `iconv()`
     * from given `$fromEncoding` charset to given `$toEncoding`
     * charset. Return array with records:
     * - `0` - Wow many items has been transcoded without error.
     * - `1` - How many items has been transcoded.
     * - `2` - Transcoded raw input string by `iconv()`.
     * @param string|\string[] $rawValue
     * @param string $fromEncoding
     * @param string $toEncoding
     * @return array
     */
    protected function encodeAcceptCharsetsArrayOrString (& $rawValue, $fromEncoding, $toEncoding) {
        /** @var $this \MvcCore\Ext\Form */
        if (gettype($rawValue) == 'array') {
            $stats = 0;
            $totalCount = 0;
            $rawTranslatedValues = [];
            foreach ($rawValue as $rawKey => & $rawValueItem) {
                if (gettype($rawValueItem) == 'array') {
                    list ($rawItemStats, $rawItemsTotal, $rawTranslatedValue) = $this->encodeAcceptCharsetsArrayOrString(
                        $rawValueItem, $fromEncoding, $toEncoding
                    );
                } else {
                    list ($rawItemStats, $rawItemsTotal, $rawTranslatedValue) = $this->encodeAcceptCharsetsString(
                        $rawValueItem, $fromEncoding, $toEncoding
                    );
                }
                $totalCount += $rawItemsTotal;
                if ($rawItemStats) {
                    $stats += $rawItemStats;
                    $rawTranslatedValues[$rawKey] = $rawTranslatedValue;
                } else {
                    $rawTranslatedValues[$rawKey] = $rawValue;
                }
            }
            return [$stats, $totalCount, $rawTranslatedValues];
        } else {
            return $this->encodeAcceptCharsetsString(
                $rawValue, $fromEncoding, $toEncoding
            );
        }
    }

    /**
     * Try to encode raw input `string` by `iconv()`
     * from given `$fromEncoding` charset to given `$toEncoding`
     * charset. Return array with records:
     * - `0` - Wow many items has been transcoded without error.
     * - `1` - How many items has been transcoded.
     * - `2` - Transcoded raw input string by `iconv()`.
     * @param string|\string[] $rawValue
     * @param string $fromEncoding
     * @param string $toEncoding
     * @return array
     */
    protected function encodeAcceptCharsetsString (& $rawValue, $fromEncoding, $toEncoding) {
        /** @var $this \MvcCore\Ext\Form */
        $errors = [];
        $toolClass = static::$toolClass;
        $translatedValue = $toolClass::Invoke(
            'iconv',
            [$fromEncoding, $toEncoding . '//TRANSLIT', $rawValue],
            function () use (& $errors) {
                $errors[] = func_get_args();
            }
        );
        if ($errors || $translatedValue === FALSE) {
            return [0, 1, NULL];
        } else {
            return [1, 1, $translatedValue];
        }
    }
}