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: 

<?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\Auths\Basics;

/**
 * Responsibility - base authentication sign-in/sign-out form class specification.
 */
interface IForm {

    /**
     * Default html `<form>` element id for authentication sign in form.
     */
    const HTML_ID_SIGNIN = 'authentication_signin';

    /**
     * Default html `<form>` element id for authentication sign out form.
     */
    const HTML_ID_SIGNOUT = 'authentication_signout';

    /**
     * Set form id, required to configure.
     * Used to identify session data, error messages,
     * CSRF tokens, html form attribute id value and much more.
     * @requires
     * @param string $id
     * @return \MvcCore\Ext\Form
     */
    public function SetId ($id);

    /**
     * Set form submitting URL value.
     * It could be relative or absolute, anything
     * to complete classic html form attribute `action`.
     * @param string|NULL $url
     * @return \MvcCore\Ext\Form
     */
    public function SetAction ($url = NULL);

    /**
     * Set form http submitting method.`POST` by default. 
     * Use `GET` only if form data contains only ASCII characters.
     * Possible values: `'POST' | 'GET'`
     * You can use constants:
     * - `\MvcCore\Ext\IForm::METHOD_POST`
     * - `\MvcCore\Ext\IForm::METHOD_GET`
     * @param string $method
     * @return \MvcCore\Ext\Form
     */
    public function SetMethod ($method = \MvcCore\Ext\IForm::METHOD_POST);

    /**
     * Set form HTML element css classes strings.
     * All previously defined css classes will be removed.
     * Default value is an empty array to not render HTML `class` attribute.
     * You can define css classes as single string, more classes separated 
     * by space or you can define css classes as array with strings.
     * @param string|\string[] $cssClasses
     * @return \MvcCore\Ext\Form
     */
    public function SetCssClasses ($cssClasses);

    /**
     * Set form success submit URL string to redirect after, relative or absolute,
     * to specify, where to redirect user after form has been submitted successfully.
     * It's required to use `\MvcCore\Ext\Form` like this, if you want to use method
     * `$form->SubmittedRedirect();`, at the end of custom `Submit()` method implementation,
     * you need to specify at least success and error URL strings.
     * @param string|NULL $url
     * @return \MvcCore\Ext\Form
     */
    public function SetSuccessUrl ($url = NULL);

    /**
     * Set form error submit URL string, relative or absolute, to specify,
     * where to redirect user after has not been submitted successfully.
     * It's not required to use `\MvcCore\Ext\Form` like this, but if you want to use method
     * `$form->SubmittedRedirect();` at the end of custom `Submit()` method implementation,
     * you need to specify at least success and error URL strings.
     * @param string|NULL $url
     * @return \MvcCore\Ext\Form
     */
    public function SetErrorUrl ($url = NULL);

    /**
     * Set translator to translate field labels, options, placeholders and error messages.
     * Translator has to be `callable` (it could be `closure function` or `array`
     * with `class_name/instance` and `method name` string). First argument
     * of `callable` has to be a translation key and second argument
     * has to be language string (`en`, `de` ...) to translate the key into.
     * Result of `callable` object has to be a string - translated key for called language.
     * @param callable|NULL $handler
     * @return \MvcCore\Ext\Form
     */
    public function SetTranslator (callable $translator = NULL);

    /**
     * Render whole `<form>` with all content into HTML string to display it.
     * - If form is not initialized, there is automatically
     *   called `$form->Init();` method.
     * - If form is not pre-dispatched for rendering, there is
     *   automatically called `$form->PreDispatch();` method.
     * - Create new form view instance and set up the view with local
     *   context variables.
     * - Render form naturally or by custom template.
     * - Clean session errors, because errors should be rendered
     *   only once, only when it's used and it's now - in this rendering process.
     * @return string
     */
    public function Init ();

    /**
     * Add multiple fully configured form field instances,
     * function have infinite params with new field instances.
     * @param \MvcCore\Ext\Forms\Field[] $fields,... Any `\MvcCore\Ext\Forms\IField` fully configured instance to add into form.
     * @return \MvcCore\Ext\Form
     */
    public function AddFields ($fields);

    /**
     * Add fully configured form field instance.
     * @param \MvcCore\Ext\Forms\Field $field
     * @return \MvcCore\Ext\Form
     */
    public function AddField (\MvcCore\Ext\Forms\IField $field);

    /**
     * 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 Array to list: `array($form->Result, $form->Data, $form->Errors);`
     */
    public function Submit (array & $rawRequestParams = []);

    /**
     * Clear form values to empty array and clear form values in form session namespace,
     * clear form errors to empty array and clear form errors in form session namespace and
     * clear form CSRF tokens clear CRSF tokens in form session namespace.
     * @return \MvcCore\Ext\Form
     */
    public function ClearSession ();

    /**
     * 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 ();

    /**
     * Rendering process alias for `\MvcCore\Ext\Form::Render();`.
     * @return string
     */
    public function __toString ();

    /**
     * Render whole `<form>` with all content into HTML string to display it.
     * - If form is not initialized, there is automatically
     *   called `$form->Init();` method.
     * - If form is not pre-dispatched for rendering, there is
     *   automatically called `$form->PreDispatch();` method.
     * - Create new form view instance and set up the view with local
     *   context variables.
     * - Render form naturally or by custom template.
     * - Clean session errors, because errors should be rendered
     *   only once, only when it's used and it's now - in this rendering process.
     * @return string
     */
    public function Render ($controllerDashedName = '', $actionDashedName = '');
}