26455457147

Committed 26 May 2026 02:44PM UTC coverage: 93.345%. Remained the same

Build Type

push

github

Committed by

Commit Message

fixed PHPStan errors

Coverage Stats

48 of 51 new or added lines in 12 files covered. (94.12%)

34 existing lines in 10 files now uncovered.

2104 of 2254 relevant lines covered (93.35%)

0.93 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

89.66

/src/Forms/Form.php

<?php declare(strict_types=1);

/**
 * This file is part of the Nette Framework (https://nette.org)
 * Copyright (c) 2004 David Grudl (https://davidgrudl.com)
 */

namespace Nette\Forms;

use Nette;
use Nette\Utils\Arrays;
use Nette\Utils\Html;
use Stringable;
use function array_key_first, array_merge, array_search, array_unique, count, headers_sent, in_array, is_array, is_scalar, is_string, sprintf, strcasecmp, strtolower;
use const PHP_SAPI;


/**
 * Creates, validates and renders HTML forms.
 *
 * @property-read string[] $errors
 * @property-read array<string|Stringable> $ownErrors
 * @property-read Html $elementPrototype
 * @property-read FormRenderer $renderer
 * @property string $action
 * @property string $method
 */
class Form extends Container implements Nette\HtmlStringable
{
        /** validator */
        public const
                Equal = ':equal',
                IsIn = self::Equal,
                NotEqual = ':notEqual',
                IsNotIn = self::NotEqual,
                Filled = ':filled',
                Blank = ':blank',
                Required = self::Filled,
                Valid = ':valid',

                // button
                Submitted = ':submitted',

                // text
                MinLength = ':minLength',
                MaxLength = ':maxLength',
                Length = ':length',
                Email = ':email',
                URL = ':url',
                Pattern = ':pattern',
                PatternInsensitive = ':patternCaseInsensitive',
                Integer = ':integer',
                Numeric = ':numeric',
                Float = ':float',
                Min = ':min',
                Max = ':max',
                Range = ':range',

                // multiselect
                Count = self::Length,

                // file upload
                MaxFileSize = ':fileSize',
                MimeType = ':mimeType',
                Image = ':image',
                MaxPostSize = ':maxPostSize';

        /** method */
        public const
                Get = 'get',
                Post = 'post';

        /** submitted data types */
        public const
                DataText = 1,
                DataLine = 2,
                DataFile = 3,
                DataKeys = 8;

        /** @internal tracker ID */
        public const TrackerId = '_form_';

        /** @internal protection token ID */
        public const ProtectorId = '_token_';

        /** @deprecated use Form::Equal */
        public const EQUAL = self::Equal;

        /** @deprecated use Form::IsIn */
        public const IS_IN = self::IsIn;

        /** @deprecated use Form::NotEqual */
        public const NOT_EQUAL = self::NotEqual;

        /** @deprecated use Form::IsNotIn */
        public const IS_NOT_IN = self::IsNotIn;

        /** @deprecated use Form::Filled */
        public const FILLED = self::Filled;

        /** @deprecated use Form::Blank */
        public const BLANK = self::Blank;

        /** @deprecated use Form::Required */
        public const REQUIRED = self::Required;

        /** @deprecated use Form::Valid */
        public const VALID = self::Valid;

        /** @deprecated use Form::Submitted */
        public const SUBMITTED = self::Submitted;

        /** @deprecated use Form::MinLength */
        public const MIN_LENGTH = self::MinLength;

        /** @deprecated use Form::MaxLength */
        public const MAX_LENGTH = self::MaxLength;

        /** @deprecated use Form::Length */
        public const LENGTH = self::Length;

        /** @deprecated use Form::Email */
        public const EMAIL = self::Email;

        /** @deprecated use Form::Pattern */
        public const PATTERN = self::Pattern;

        /** @deprecated use Form::PatternCI */
        public const PATTERN_ICASE = self::PatternInsensitive;

        /** @deprecated use Form::Integer */
        public const INTEGER = self::Integer;

        /** @deprecated use Form::Numeric */
        public const NUMERIC = self::Numeric;

        /** @deprecated use Form::Float */
        public const FLOAT = self::Float;

        /** @deprecated use Form::Min */
        public const MIN = self::Min;

        /** @deprecated use Form::Max */
        public const MAX = self::Max;

        /** @deprecated use Form::Range */
        public const RANGE = self::Range;

        /** @deprecated use Form::Count */
        public const COUNT = self::Count;

        /** @deprecated use Form::MaxFileSize */
        public const MAX_FILE_SIZE = self::MaxFileSize;

        /** @deprecated use Form::MimeType */
        public const MIME_TYPE = self::MimeType;

        /** @deprecated use Form::Image */
        public const IMAGE = self::Image;

        /** @deprecated use Form::MaxPostSize */
        public const MAX_POST_SIZE = self::MaxPostSize;

        /** @deprecated use Form::Get */
        public const GET = self::Get;

        /** @deprecated use Form::Post */
        public const POST = self::Post;

        /** @deprecated use Form::DataText */
        public const DATA_TEXT = self::DataText;

        /** @deprecated use Form::DataLine */
        public const DATA_LINE = self::DataLine;

        /** @deprecated use Form::DataFile */
        public const DATA_FILE = self::DataFile;

        /** @deprecated use Form::DataKeys */
        public const DATA_KEYS = self::DataKeys;

        /** @deprecated use Form::TrackerId */
        public const TRACKER_ID = self::TrackerId;

        /** @deprecated use Form::ProtectorId */
        public const PROTECTOR_ID = self::ProtectorId;

        /**
         * Occurs when the form is submitted and successfully validated
         * @var array<callable(static, mixed[]|object): void | callable(mixed[]|object): void>
         */
        public array $onSuccess = [];

        /** @var array<callable(static): void>  Occurs when the form is submitted and is not valid */
        public array $onError = [];

        /** @var array<callable(static): void>  Occurs when the form is submitted */
        public array $onSubmit = [];

        /** @var array<callable(static): void>  Occurs before the form is rendered */
        public array $onRender = [];

        /** @internal used only by standalone form */
        public Nette\Http\IRequest $httpRequest;

        /** @var bool */
        protected $crossOrigin = false;
        private static ?Nette\Http\IRequest $defaultHttpRequest = null;
        private SubmitterControl|bool $submittedBy = false;

        /** @var mixed[] */
        private array $httpData;
        private Html $element;
        private FormRenderer $renderer;
        private ?Nette\Localization\Translator $translator = null;

        /** @var ControlGroup[] */
        private array $groups = [];

        /** @var list<string|Stringable> */
        private array $errors = [];
        private bool $beforeRenderCalled = false;


        public function __construct(?string $name = null)
        {
                if ($name !== null) {
                        $this->getElementPrototype()->id = 'frm-' . $name;
                        $tracker = new Controls\HiddenField($name);
                        $tracker->setOmitted();
                        $this[self::TrackerId] = $tracker;
                        $this->setParent(null, $name);
                }

                $this->monitor(self::class, function (): void {
                        throw new Nette\InvalidStateException('Nested forms are forbidden.');
                });
        }


        public function getForm(bool $throw = true): static
        {
                return $this;
        }


        public function setAction(string|Stringable $url): static
        {
                $this->getElementPrototype()->action = $url;
                return $this;
        }


        public function getAction(): string
        {
                return (string) $this->getElementPrototype()->action;
        }


        public function setMethod(string $method): static
        {
                if (isset($this->httpData)) {
                        throw new Nette\InvalidStateException(__METHOD__ . '() must be called until the form is empty.');
                }

                $this->getElementPrototype()->method = strtolower($method);
                return $this;
        }


        public function getMethod(): string
        {
                return (string) $this->getElementPrototype()->method;
        }


        /**
         * Checks if the request method is the given one.
         */
        public function isMethod(string $method): bool
        {
                return strcasecmp((string) $this->getElementPrototype()->method, $method) === 0;
        }


        /**
         * Sets a form-level HTML attribute.
         */
        public function setHtmlAttribute(string $name, mixed $value = true): static
        {
                $this->getElementPrototype()->$name = $value;
                return $this;
        }


        /**
         * Disables the SameSite cookie CSRF protection, allowing cross-origin form submissions.
         */
        public function allowCrossOrigin(): void
        {
                $this->crossOrigin = true;
        }


        /**
         * Adds a CSRF protection token field using a SameSite cookie.
         */
        public function addProtection(?string $errorMessage = null): Controls\CsrfProtection
        {
                $control = new Controls\CsrfProtection($errorMessage);
                $children = $this->getComponents();
                $first = $children ? (string) array_key_first($children) : null;
                $this->addComponent($control, self::ProtectorId, $first);
                return $control;
        }


        /**
         * Creates a new control group and optionally sets it as current for subsequent addXxx() calls.
         */
        public function addGroup(string|Stringable|null $caption = null, bool $setAsCurrent = true): ControlGroup
        {
                $group = new ControlGroup;
                $group->setOption('label', $caption);
                $group->setOption('visual', true);

                if ($setAsCurrent) {
                        $this->setCurrentGroup($group);
                }

                return !is_scalar($caption) || isset($this->groups[$caption])
                        ? $this->groups[] = $group
                        : $this->groups[$caption] = $group;
        }


        /**
         * Removes a group and all its controls from the form.
         */
        public function removeGroup(string|ControlGroup $name): void
        {
                if (is_string($name) && isset($this->groups[$name])) {
                        $group = $this->groups[$name];

                } elseif ($name instanceof ControlGroup && in_array($name, $this->groups, strict: true)) {
                        $group = $name;
                        $name = array_search($group, $this->groups, strict: true);

                } else {
                        throw new Nette\InvalidArgumentException("Group not found in form '{$this->getName()}'");
                }

                foreach ($group->getControls() as $control) {
                        $control->getParent()->removeComponent($control);
                }

                unset($this->groups[$name]);
        }


        /**
         * Returns all defined groups.
         * @return ControlGroup[]
         */
        public function getGroups(): array
        {
                return $this->groups;
        }


        /**
         * Returns the specified group.
         */
        public function getGroup(string|int $name): ?ControlGroup
        {
                return $this->groups[$name] ?? null;
        }


        /********************* translator ****************d*g**/


        public function setTranslator(?Nette\Localization\Translator $translator): static
        {
                $this->translator = $translator;
                return $this;
        }


        public function getTranslator(): ?Nette\Localization\Translator
        {
                return $this->translator;
        }


        /********************* submission ****************d*g**/


        /**
         * Checks whether the form is attached to a request (always true for standalone forms).
         */
        public function isAnchored(): bool
        {
                return true;
        }


        /**
         * Returns the submitter control if the form was submitted, or false.
         */
        public function isSubmitted(): SubmitterControl|bool
        {
                if (!isset($this->httpData)) {
                        $this->getHttpData();
                }

                return $this->submittedBy;
        }


        /**
         * Tells if the form was submitted and successfully validated.
         */
        public function isSuccess(): bool
        {
                return $this->isSubmitted() && $this->isValid();
        }


        /**
         * @internal
         */
        public function setSubmittedBy(?SubmitterControl $by): static
        {
                $this->submittedBy = $by ?? false;
                return $this;
        }


        /**
         * Returns raw submitted HTTP data for a control, or all form data when called without arguments.
         * @return string|string[]|Nette\Http\FileUpload|null
         */
        public function getHttpData(?int $type = null, ?string $htmlName = null): string|array|Nette\Http\FileUpload|null
        {
                if (!isset($this->httpData)) {
                        if (!$this->isAnchored()) {
                                throw new Nette\InvalidStateException('Form is not anchored and therefore can not determine whether it was submitted.');
                        }

                        $data = $this->receiveHttpData();
                        $this->httpData = (array) $data;
                        $this->submittedBy = is_array($data);
                }

                if ($htmlName === null) {
                        return $this->httpData;
                }

                return Helpers::extractHttpData(
                        $this->httpData,
                        $htmlName,
                        $type ?? throw new Nette\InvalidArgumentException('Parameter $type must be provided when $htmlName is specified.'),
                );
        }


        /**
         * Fires onSuccess, onError, onSubmit and onClick events based on submission and validation state.
         */
        public function fireEvents(): void
        {
                if (!$this->isSubmitted()) {
                        return;

                } elseif (!$this->getErrors()) {
                        $this->validate();
                }

                $handled = count($this->onSuccess) || count($this->onSubmit) || $this->submittedBy === true;

                if ($this->submittedBy instanceof Controls\SubmitButton) {
                        $handled = $handled || count($this->submittedBy->onClick);
                        if ($this->isValid()) {
                                $this->invokeHandlers($this->submittedBy->onClick, $this->submittedBy);
                        } else {
                                Arrays::invoke($this->submittedBy->onInvalidClick, $this->submittedBy);
                        }
                }

                if ($this->isValid()) {
                        $this->invokeHandlers($this->onSuccess);
                }

                if (!$this->isValid()) {
                        Arrays::invoke($this->onError, $this);
                }

                Arrays::invoke($this->onSubmit, $this);

                if (!$handled) {
                        trigger_error("Form was submitted but there are no associated handlers (form '{$this->getName()}').", E_USER_WARNING);
                }
        }


        /** @param  iterable<callable>  $handlers */
        private function invokeHandlers(iterable $handlers, ?SubmitterControl $button = null): void
        {
                foreach ($handlers as $handler) {
                        $params = Nette\Utils\Callback::toReflection($handler)->getParameters();
                        $args = [];
                        if ($params) {
                                $type = Helpers::getSingleType($params[0]);
                                $args[] = match (true) {
                                        !$type => $button ?? $this,
                                        $this instanceof $type => $this,
                                        $button instanceof $type => $button,
                                        default => $this->getValues($type),
                                };
                                if (isset($params[1])) {
                                        $args[] = $this->getValues(Helpers::getSingleType($params[1]));
                                }
                        }

                        $handler(...$args);

                        if (!$this->isValid()) {
                                return;
                        }
                }
        }


        /**
         * Clears the submission state and resets all control values to defaults.
         */
        public function reset(): static
        {
                $this->setSubmittedBy(null);
                $this->setValues([], erase: true);
                return $this;
        }


        /**
         * Internal: returns submitted HTTP data or null when form was not submitted.
         * @return ?mixed[]
         */
        protected function receiveHttpData(): ?array
        {
                $httpRequest = $this->getHttpRequest();
                if (strcasecmp($this->getMethod(), $httpRequest->getMethod())) {
                        return null;
                }

                if ($httpRequest->isMethod('post')) {
                        if (!$this->crossOrigin && !$httpRequest->isSameSite()) {
                                return null;
                        }

                        $data = Nette\Utils\Arrays::mergeTree($httpRequest->getPost(), $httpRequest->getFiles());
                } else {
                        $data = $httpRequest->getQuery();
                        if (!$data) {
                                return null;
                        }
                }

                if ($tracker = $this->getComponent(self::TrackerId, throw: false)) {
                        if (!isset($data[self::TrackerId]) || $data[self::TrackerId] !== $tracker->getValue()) {
                                return null;
                        }
                }

                return $data;
        }


        /********************* validation ****************d*g**/


        /** @param  ?(Control|Container)[]  $controls */
        public function validate(?array $controls = null): void
        {
                $this->cleanErrors();
                if ($controls === null && $this->submittedBy instanceof SubmitterControl) {
                        $controls = $this->submittedBy->getValidationScope();
                }

                $this->validateMaxPostSize();
                parent::validate($controls);
        }


        /** @internal */
        public function validateMaxPostSize(): void
        {
                if (!$this->submittedBy || !$this->isMethod('post') || empty($_SERVER['CONTENT_LENGTH'])) {
                        return;
                }

                $maxSize = Helpers::iniGetSize('post_max_size');
                if ($maxSize > 0 && $maxSize < $_SERVER['CONTENT_LENGTH']) {
                        $this->addError(sprintf(Validator::$messages[self::MaxFileSize], $maxSize));
                }
        }


        /**
         * Adds a form-level (not control-level) error message.
         */
        public function addError(string|Stringable $message, bool $translate = true): void
        {
                if ($translate && $this->translator) {
                        $message = $this->translator->translate($message);
                }

                $this->errors[] = $message;
        }


        /**
         * Returns all validation errors (own form errors merged with control errors).
         * @return list<string|Stringable>
         */
        public function getErrors(): array
        {
                return array_values(array_unique(array_merge($this->errors, parent::getErrors())));
        }


        public function hasErrors(): bool
        {
                return (bool) $this->getErrors();
        }


        public function cleanErrors(): void
        {
                $this->errors = [];
        }


        /**
         * Returns form-level errors only, excluding control errors.
         * @return list<string|Stringable>
         */
        public function getOwnErrors(): array
        {
                return array_values(array_unique($this->errors));
        }


        /********************* rendering ****************d*g**/


        /**
         * Returns form's HTML element template.
         */
        public function getElementPrototype(): Html
        {
                if (!isset($this->element)) {
                        $this->element = Html::el('form');
                        $this->element->action = ''; // RFC 1808 -> empty uri means 'this'
                        $this->element->method = self::Post;
                }

                return $this->element;
        }


        public function setRenderer(?FormRenderer $renderer): static
        {
                $this->renderer = $renderer;
                return $this;
        }


        public function getRenderer(): FormRenderer
        {
                if (!isset($this->renderer)) {
                        $this->renderer = new Rendering\DefaultFormRenderer;
                }

                return $this->renderer;
        }


        protected function beforeRender()
        {
        }


        /**
         * Triggers beforeRender() and onRender events. Must be called before manual rendering (when not using render()).
         */
        public function fireRenderEvents(): void
        {
                if (!$this->beforeRenderCalled) {
                        $this->beforeRenderCalled = true;
                        $this->beforeRender();
                        Arrays::invoke($this->onRender, $this);
                }
        }


        public function render(mixed ...$args): void
        {
                $this->fireRenderEvents();
                echo $this->getRenderer()->render($this, ...$args);
        }


        public function __toString(): string
        {
                $this->fireRenderEvents();
                return $this->getRenderer()->render($this);
        }


        /**
         * Returns current visibility states of all toggle targets across all controls.
         * @return array<string, bool>
         */
        public function getToggles(): array
        {
                $toggles = [];
                foreach ($this->getComponentTree() as $control) {
                        if ($control instanceof Controls\BaseControl) {
                                $toggles = $control->getRules()->getToggleStates($toggles);
                        }
                }

                return $toggles;
        }


        /********************* backend ****************d*g**/


        /**
         * Initializes HTTP request and SameSite CSRF cookie for standalone (non-DI) usage.
         */
        public static function initialize(bool $reinit = false): void
        {
                if ($reinit) {
                        self::$defaultHttpRequest = null;
                        return;
                } elseif (self::$defaultHttpRequest) {
                        return;
                }

                self::$defaultHttpRequest = (new Nette\Http\RequestFactory)->fromGlobals();

                if (!in_array(PHP_SAPI, ['cli', 'phpdbg', 'embed'], strict: true)) {
                        if (headers_sent($file, $line)) {
                                throw new Nette\InvalidStateException(
                                        'Create a form or call Nette\Forms\Form::initialize() before the headers are sent to initialize CSRF protection.'
                                        . ($file ? " (output started at $file:$line)" : '') . '. ',
                                );
                        }

                        $response = new Nette\Http\Response;
                        $response->cookieSecure = self::$defaultHttpRequest->isSecured();
                        Nette\Http\Helpers::initCookie(self::$defaultHttpRequest, $response);
                }
        }


        private function getHttpRequest(): Nette\Http\IRequest
        {
                if (!isset($this->httpRequest)) {
                        self::initialize();
                        $this->httpRequest = self::$defaultHttpRequest;
                }

                return $this->httpRequest;
        }
}

1	<?php declare(strict_types=1);	1✔
2
3	/**
4	* This file is part of the Nette Framework (https://nette.org)
5	* Copyright (c) 2004 David Grudl (https://davidgrudl.com)
6	*/
7
8	namespace Nette\Forms;
9
10	use Nette;
11	use Nette\Utils\Arrays;
12	use Nette\Utils\Html;
13	use Stringable;
14	use function array_key_first, array_merge, array_search, array_unique, count, headers_sent, in_array, is_array, is_scalar, is_string, sprintf, strcasecmp, strtolower;
15	use const PHP_SAPI;
16
17
18	/**
19	* Creates, validates and renders HTML forms.
20	*
21	* @property-read string[] $errors
22	* @property-read array<string\|Stringable> $ownErrors
23	* @property-read Html $elementPrototype
24	* @property-read FormRenderer $renderer
25	* @property string $action
26	* @property string $method
27	*/
28	class Form extends Container implements Nette\HtmlStringable
29	{
30	/** validator */
31	public const
32	Equal = ':equal',
33	IsIn = self::Equal,
34	NotEqual = ':notEqual',
35	IsNotIn = self::NotEqual,
36	Filled = ':filled',
37	Blank = ':blank',
38	Required = self::Filled,
39	Valid = ':valid',
40
41	// button
42	Submitted = ':submitted',
43
44	// text
45	MinLength = ':minLength',
46	MaxLength = ':maxLength',
47	Length = ':length',
48	Email = ':email',
49	URL = ':url',
50	Pattern = ':pattern',
51	PatternInsensitive = ':patternCaseInsensitive',
52	Integer = ':integer',
53	Numeric = ':numeric',
54	Float = ':float',
55	Min = ':min',
56	Max = ':max',
57	Range = ':range',
58
59	// multiselect
60	Count = self::Length,
61
62	// file upload
63	MaxFileSize = ':fileSize',
64	MimeType = ':mimeType',
65	Image = ':image',
66	MaxPostSize = ':maxPostSize';
67
68	/** method */
69	public const
70	Get = 'get',
71	Post = 'post';
72
73	/** submitted data types */
74	public const
75	DataText = 1,
76	DataLine = 2,
77	DataFile = 3,
78	DataKeys = 8;
79
80	/** @internal tracker ID */
81	public const TrackerId = '_form_';
82
83	/** @internal protection token ID */
84	public const ProtectorId = '_token_';
85
86	/** @deprecated use Form::Equal */
87	public const EQUAL = self::Equal;
88
89	/** @deprecated use Form::IsIn */
90	public const IS_IN = self::IsIn;
91
92	/** @deprecated use Form::NotEqual */
93	public const NOT_EQUAL = self::NotEqual;
94
95	/** @deprecated use Form::IsNotIn */
96	public const IS_NOT_IN = self::IsNotIn;
97
98	/** @deprecated use Form::Filled */
99	public const FILLED = self::Filled;
100
101	/** @deprecated use Form::Blank */
102	public const BLANK = self::Blank;
103
104	/** @deprecated use Form::Required */
105	public const REQUIRED = self::Required;
106
107	/** @deprecated use Form::Valid */
108	public const VALID = self::Valid;
109
110	/** @deprecated use Form::Submitted */
111	public const SUBMITTED = self::Submitted;
112
113	/** @deprecated use Form::MinLength */
114	public const MIN_LENGTH = self::MinLength;
115
116	/** @deprecated use Form::MaxLength */
117	public const MAX_LENGTH = self::MaxLength;
118
119	/** @deprecated use Form::Length */
120	public const LENGTH = self::Length;
121
122	/** @deprecated use Form::Email */
123	public const EMAIL = self::Email;
124
125	/** @deprecated use Form::Pattern */
126	public const PATTERN = self::Pattern;
127
128	/** @deprecated use Form::PatternCI */
129	public const PATTERN_ICASE = self::PatternInsensitive;
130
131	/** @deprecated use Form::Integer */
132	public const INTEGER = self::Integer;
133
134	/** @deprecated use Form::Numeric */
135	public const NUMERIC = self::Numeric;
136
137	/** @deprecated use Form::Float */
138	public const FLOAT = self::Float;
139
140	/** @deprecated use Form::Min */
141	public const MIN = self::Min;
142
143	/** @deprecated use Form::Max */
144	public const MAX = self::Max;
145
146	/** @deprecated use Form::Range */
147	public const RANGE = self::Range;
148
149	/** @deprecated use Form::Count */
150	public const COUNT = self::Count;
151
152	/** @deprecated use Form::MaxFileSize */
153	public const MAX_FILE_SIZE = self::MaxFileSize;
154
155	/** @deprecated use Form::MimeType */
156	public const MIME_TYPE = self::MimeType;
157
158	/** @deprecated use Form::Image */
159	public const IMAGE = self::Image;
160
161	/** @deprecated use Form::MaxPostSize */
162	public const MAX_POST_SIZE = self::MaxPostSize;
163
164	/** @deprecated use Form::Get */
165	public const GET = self::Get;
166
167	/** @deprecated use Form::Post */
168	public const POST = self::Post;
169
170	/** @deprecated use Form::DataText */
171	public const DATA_TEXT = self::DataText;
172
173	/** @deprecated use Form::DataLine */
174	public const DATA_LINE = self::DataLine;
175
176	/** @deprecated use Form::DataFile */
177	public const DATA_FILE = self::DataFile;
178
179	/** @deprecated use Form::DataKeys */
180	public const DATA_KEYS = self::DataKeys;
181
182	/** @deprecated use Form::TrackerId */
183	public const TRACKER_ID = self::TrackerId;
184
185	/** @deprecated use Form::ProtectorId */
186	public const PROTECTOR_ID = self::ProtectorId;
187
188	/**
189	* Occurs when the form is submitted and successfully validated
190	* @var array<callable(static, mixed[]\|object): void \| callable(mixed[]\|object): void>
191	*/
192	public array $onSuccess = [];
193
194	/** @var array<callable(static): void> Occurs when the form is submitted and is not valid */
195	public array $onError = [];
196
197	/** @var array<callable(static): void> Occurs when the form is submitted */
198	public array $onSubmit = [];
199
200	/** @var array<callable(static): void> Occurs before the form is rendered */
201	public array $onRender = [];
202
203	/** @internal used only by standalone form */
204	public Nette\Http\IRequest $httpRequest;
205
206	/** @var bool */
207	protected $crossOrigin = false;
208	private static ?Nette\Http\IRequest $defaultHttpRequest = null;
209	private SubmitterControl\|bool $submittedBy = false;
210
211	/** @var mixed[] */
212	private array $httpData;
213	private Html $element;
214	private FormRenderer $renderer;
215	private ?Nette\Localization\Translator $translator = null;
216
217	/** @var ControlGroup[] */
218	private array $groups = [];
219
220	/** @var list<string\|Stringable> */
221	private array $errors = [];
222	private bool $beforeRenderCalled = false;
223
224
225	public function __construct(?string $name = null)	1✔
226	{
227	if ($name !== null) {	1✔
228	$this->getElementPrototype()->id = 'frm-' . $name;	1✔
229	$tracker = new Controls\HiddenField($name);	1✔
230	$tracker->setOmitted();	1✔
231	$this[self::TrackerId] = $tracker;	1✔
232	$this->setParent(null, $name);	1✔
233	}
234
235	$this->monitor(self::class, function (): void {	1✔
236	throw new Nette\InvalidStateException('Nested forms are forbidden.');
237	});	1✔
238	}	1✔
239
240
241	public function getForm(bool $throw = true): static	1✔
242	{
243	return $this;	1✔
244	}
245
246
247	public function setAction(string\|Stringable $url): static	1✔
248	{
249	$this->getElementPrototype()->action = $url;	1✔
250	return $this;	1✔
251	}
252
253
254	public function getAction(): string
255	{
256	return (string) $this->getElementPrototype()->action;	1✔
257	}
258
259
260	public function setMethod(string $method): static	1✔
261	{
262	if (isset($this->httpData)) {	1✔
263	throw new Nette\InvalidStateException(__METHOD__ . '() must be called until the form is empty.');	×
264	}
265
266	$this->getElementPrototype()->method = strtolower($method);	1✔
267	return $this;	1✔
268	}
269
270
271	public function getMethod(): string
272	{
273	return (string) $this->getElementPrototype()->method;	1✔
274	}
275
276
277	/**
278	* Checks if the request method is the given one.
279	*/
280	public function isMethod(string $method): bool	1✔
281	{
282	return strcasecmp((string) $this->getElementPrototype()->method, $method) === 0;	1✔
283	}
284
285
286	/**
287	* Sets a form-level HTML attribute.
288	*/
289	public function setHtmlAttribute(string $name, mixed $value = true): static
290	{
291	$this->getElementPrototype()->$name = $value;	×
292	return $this;	×
293	}
294
295
296	/**
297	* Disables the SameSite cookie CSRF protection, allowing cross-origin form submissions.
298	*/
299	public function allowCrossOrigin(): void
300	{
301	$this->crossOrigin = true;	1✔
302	}	1✔
303
304
305	/**
306	* Adds a CSRF protection token field using a SameSite cookie.
307	*/
308	public function addProtection(?string $errorMessage = null): Controls\CsrfProtection	1✔
309	{
310	$control = new Controls\CsrfProtection($errorMessage);	1✔
311	$children = $this->getComponents();	1✔
312	$first = $children ? (string) array_key_first($children) : null;	1✔
313	$this->addComponent($control, self::ProtectorId, $first);	1✔
314	return $control;	1✔
315	}
316
317
318	/**
319	* Creates a new control group and optionally sets it as current for subsequent addXxx() calls.
320	*/
321	public function addGroup(string\|Stringable\|null $caption = null, bool $setAsCurrent = true): ControlGroup	1✔
322	{
323	$group = new ControlGroup;	1✔
324	$group->setOption('label', $caption);	1✔
325	$group->setOption('visual', true);	1✔
326
327	if ($setAsCurrent) {	1✔
328	$this->setCurrentGroup($group);	1✔
329	}
330
331	return !is_scalar($caption) \|\| isset($this->groups[$caption])	1✔
332	? $this->groups[] = $group	1✔
333	: $this->groups[$caption] = $group;	1✔
334	}
335
336
337	/**
338	* Removes a group and all its controls from the form.
339	*/
340	public function removeGroup(string\|ControlGroup $name): void
341	{
342	if (is_string($name) && isset($this->groups[$name])) {	×
343	$group = $this->groups[$name];	×
344
345	} elseif ($name instanceof ControlGroup && in_array($name, $this->groups, strict: true)) {	×
346	$group = $name;	×
347	$name = array_search($group, $this->groups, strict: true);	×
348
349	} else {
350	throw new Nette\InvalidArgumentException("Group not found in form '{$this->getName()}'");	×
351	}
352
353	foreach ($group->getControls() as $control) {	×
354	$control->getParent()->removeComponent($control);	×
355	}
356
357	unset($this->groups[$name]);	×
358	}
359
360
361	/**
362	* Returns all defined groups.
363	* @return ControlGroup[]
364	*/
365	public function getGroups(): array
366	{
367	return $this->groups;	1✔
368	}
369
370
371	/**
372	* Returns the specified group.
373	*/
374	public function getGroup(string\|int $name): ?ControlGroup	1✔
375	{
376	return $this->groups[$name] ?? null;	1✔
377	}
378
379
380	/******************* translator *************dg**/
381
382
383	public function setTranslator(?Nette\Localization\Translator $translator): static	1✔
384	{
385	$this->translator = $translator;	1✔
386	return $this;	1✔
387	}
388
389
390	public function getTranslator(): ?Nette\Localization\Translator
391	{
392	return $this->translator;	1✔
393	}
394
395
396	/******************* submission *************dg**/
397
398
399	/**
400	* Checks whether the form is attached to a request (always true for standalone forms).
401	*/
402	public function isAnchored(): bool
403	{
404	return true;	1✔
405	}
406
407
408	/**
409	* Returns the submitter control if the form was submitted, or false.
410	*/
411	public function isSubmitted(): SubmitterControl\|bool
412	{
413	if (!isset($this->httpData)) {	1✔
414	$this->getHttpData();	1✔
415	}
416
417	return $this->submittedBy;	1✔
418	}
419
420
421	/**
422	* Tells if the form was submitted and successfully validated.
423	*/
424	public function isSuccess(): bool
425	{
426	return $this->isSubmitted() && $this->isValid();	1✔
427	}
428
429
430	/**
431	* @internal
432	*/
433	public function setSubmittedBy(?SubmitterControl $by): static	1✔
434	{
435	$this->submittedBy = $by ?? false;	1✔
436	return $this;	1✔
437	}
438
439
440	/**
441	* Returns raw submitted HTTP data for a control, or all form data when called without arguments.
442	* @return string\|string[]\|Nette\Http\FileUpload\|null
443	*/
444	public function getHttpData(?int $type = null, ?string $htmlName = null): string\|array\|Nette\Http\FileUpload\|null	1✔
445	{
446	if (!isset($this->httpData)) {	1✔
447	if (!$this->isAnchored()) {	1✔
448	throw new Nette\InvalidStateException('Form is not anchored and therefore can not determine whether it was submitted.');	×
449	}
450
451	$data = $this->receiveHttpData();	1✔
452	$this->httpData = (array) $data;	1✔
453	$this->submittedBy = is_array($data);	1✔
454	}
455
456	if ($htmlName === null) {	1✔
457	return $this->httpData;	1✔
458	}
459
460	return Helpers::extractHttpData(	1✔
461	$this->httpData,	1✔
NEW 462	$htmlName,	×
463	$type ?? throw new Nette\InvalidArgumentException('Parameter $type must be provided when $htmlName is specified.'),	1✔
464	);
465	}
466
467
468	/**
469	* Fires onSuccess, onError, onSubmit and onClick events based on submission and validation state.
470	*/
471	public function fireEvents(): void
472	{
473	if (!$this->isSubmitted()) {	1✔
474	return;	1✔
475
476	} elseif (!$this->getErrors()) {	1✔
477	$this->validate();	1✔
478	}
479
480	$handled = count($this->onSuccess) \|\| count($this->onSubmit) \|\| $this->submittedBy === true;	1✔
481
482	if ($this->submittedBy instanceof Controls\SubmitButton) {	1✔
483	$handled = $handled \|\| count($this->submittedBy->onClick);	1✔
484	if ($this->isValid()) {	1✔
485	$this->invokeHandlers($this->submittedBy->onClick, $this->submittedBy);	1✔
486	} else {
487	Arrays::invoke($this->submittedBy->onInvalidClick, $this->submittedBy);	1✔
488	}
489	}
490
491	if ($this->isValid()) {	1✔
492	$this->invokeHandlers($this->onSuccess);	1✔
493	}
494
495	if (!$this->isValid()) {	1✔
496	Arrays::invoke($this->onError, $this);	1✔
497	}
498
499	Arrays::invoke($this->onSubmit, $this);	1✔
500
501	if (!$handled) {	1✔
502	trigger_error("Form was submitted but there are no associated handlers (form '{$this->getName()}').", E_USER_WARNING);	1✔
503	}
504	}	1✔
505
506
507	/** @param iterable<callable> $handlers */
508	private function invokeHandlers(iterable $handlers, ?SubmitterControl $button = null): void	1✔
509	{
510	foreach ($handlers as $handler) {	1✔
511	$params = Nette\Utils\Callback::toReflection($handler)->getParameters();	1✔
512	$args = [];	1✔
513	if ($params) {	1✔
514	$type = Helpers::getSingleType($params[0]);	1✔
515	$args[] = match (true) {	1✔
516	!$type => $button ?? $this,	1✔
517	$this instanceof $type => $this,	1✔
518	$button instanceof $type => $button,	1✔
519	default => $this->getValues($type),	1✔
520	};
521	if (isset($params[1])) {	1✔
522	$args[] = $this->getValues(Helpers::getSingleType($params[1]));	1✔
523	}
524	}
525
526	$handler(...$args);	1✔
527
528	if (!$this->isValid()) {	1✔
529	return;	1✔
530	}
531	}
532	}	1✔
533
534
535	/**
536	* Clears the submission state and resets all control values to defaults.
537	*/
538	public function reset(): static
539	{
540	$this->setSubmittedBy(null);	1✔
541	$this->setValues([], erase: true);	1✔
542	return $this;	1✔
543	}
544
545
546	/**
547	* Internal: returns submitted HTTP data or null when form was not submitted.
548	* @return ?mixed[]
549	*/
550	protected function receiveHttpData(): ?array
551	{
552	$httpRequest = $this->getHttpRequest();	1✔
553	if (strcasecmp($this->getMethod(), $httpRequest->getMethod())) {	1✔
554	return null;	1✔
555	}
556
557	if ($httpRequest->isMethod('post')) {	1✔
558	if (!$this->crossOrigin && !$httpRequest->isSameSite()) {	1✔
559	return null;	1✔
560	}
561
562	$data = Nette\Utils\Arrays::mergeTree($httpRequest->getPost(), $httpRequest->getFiles());	1✔
563	} else {
564	$data = $httpRequest->getQuery();	1✔
565	if (!$data) {	1✔
566	return null;	1✔
567	}
568	}
569
570	if ($tracker = $this->getComponent(self::TrackerId, throw: false)) {	1✔
571	if (!isset($data[self::TrackerId]) \|\| $data[self::TrackerId] !== $tracker->getValue()) {	1✔
UNCOV 572	return null;	×
573	}
574	}
575
576	return $data;	1✔
577	}
578
579
580	/******************* validation *************dg**/
581
582
583	/** @param ?(Control\|Container)[] $controls */
584	public function validate(?array $controls = null): void	1✔
585	{
586	$this->cleanErrors();	1✔
587	if ($controls === null && $this->submittedBy instanceof SubmitterControl) {	1✔
588	$controls = $this->submittedBy->getValidationScope();	1✔
589	}
590
591	$this->validateMaxPostSize();	1✔
592	parent::validate($controls);	1✔
593	}	1✔
594
595
596	/** @internal */
597	public function validateMaxPostSize(): void
598	{
599	if (!$this->submittedBy \|\| !$this->isMethod('post') \|\| empty($_SERVER['CONTENT_LENGTH'])) {	1✔
600	return;	1✔
601	}
602
603	$maxSize = Helpers::iniGetSize('post_max_size');	1✔
604	if ($maxSize > 0 && $maxSize < $_SERVER['CONTENT_LENGTH']) {	1✔
605	$this->addError(sprintf(Validator::$messages[self::MaxFileSize], $maxSize));	1✔
606	}
607	}	1✔
608
609
610	/**
611	* Adds a form-level (not control-level) error message.
612	*/
613	public function addError(string\|Stringable $message, bool $translate = true): void	1✔
614	{
615	if ($translate && $this->translator) {	1✔
616	$message = $this->translator->translate($message);	1✔
617	}
618
619	$this->errors[] = $message;	1✔
620	}	1✔
621
622
623	/**
624	* Returns all validation errors (own form errors merged with control errors).
625	* @return list<string\|Stringable>
626	*/
627	public function getErrors(): array
628	{
629	return array_values(array_unique(array_merge($this->errors, parent::getErrors())));	1✔
630	}
631
632
633	public function hasErrors(): bool
634	{
635	return (bool) $this->getErrors();	1✔
636	}
637
638
639	public function cleanErrors(): void
640	{
641	$this->errors = [];	1✔
642	}	1✔
643
644
645	/**
646	* Returns form-level errors only, excluding control errors.
647	* @return list<string\|Stringable>
648	*/
649	public function getOwnErrors(): array
650	{
651	return array_values(array_unique($this->errors));	1✔
652	}
653
654
655	/******************* rendering *************dg**/
656
657
658	/**
659	* Returns form's HTML element template.
660	*/
661	public function getElementPrototype(): Html
662	{
663	if (!isset($this->element)) {	1✔
664	$this->element = Html::el('form');	1✔
665	$this->element->action = ''; // RFC 1808 -> empty uri means 'this'	1✔
666	$this->element->method = self::Post;	1✔
667	}
668
669	return $this->element;	1✔
670	}
671
672
673	public function setRenderer(?FormRenderer $renderer): static	1✔
674	{
675	$this->renderer = $renderer;	1✔
676	return $this;	1✔
677	}
678
679
680	public function getRenderer(): FormRenderer
681	{
682	if (!isset($this->renderer)) {	1✔
683	$this->renderer = new Rendering\DefaultFormRenderer;	1✔
684	}
685
686	return $this->renderer;	1✔
687	}
688
689
690	protected function beforeRender()
691	{
692	}	1✔
693
694
695	/**
696	* Triggers beforeRender() and onRender events. Must be called before manual rendering (when not using render()).
697	*/
698	public function fireRenderEvents(): void
699	{
700	if (!$this->beforeRenderCalled) {	1✔
701	$this->beforeRenderCalled = true;	1✔
702	$this->beforeRender();	1✔
703	Arrays::invoke($this->onRender, $this);	1✔
704	}
705	}	1✔
706
707
708	public function render(mixed ...$args): void	1✔
709	{
710	$this->fireRenderEvents();	1✔
711	echo $this->getRenderer()->render($this, ...$args);	1✔
712	}	1✔
713
714
715	public function __toString(): string
716	{
717	$this->fireRenderEvents();	1✔
718	return $this->getRenderer()->render($this);	1✔
719	}
720
721
722	/**
723	* Returns current visibility states of all toggle targets across all controls.
724	* @return array<string, bool>
725	*/
726	public function getToggles(): array
727	{
728	$toggles = [];	1✔
729	foreach ($this->getComponentTree() as $control) {	1✔
730	if ($control instanceof Controls\BaseControl) {	1✔
731	$toggles = $control->getRules()->getToggleStates($toggles);	1✔
732	}
733	}
734
735	return $toggles;	1✔
736	}
737
738
739	/******************* backend *************dg**/
740
741
742	/**
743	* Initializes HTTP request and SameSite CSRF cookie for standalone (non-DI) usage.
744	*/
745	public static function initialize(bool $reinit = false): void	1✔
746	{
747	if ($reinit) {	1✔
748	self::$defaultHttpRequest = null;	1✔
749	return;	1✔
750	} elseif (self::$defaultHttpRequest) {	1✔
751	return;	1✔
752	}
753
754	self::$defaultHttpRequest = (new Nette\Http\RequestFactory)->fromGlobals();	1✔
755
756	if (!in_array(PHP_SAPI, ['cli', 'phpdbg', 'embed'], strict: true)) {	1✔
UNCOV 757	if (headers_sent($file, $line)) {	×
UNCOV 758	throw new Nette\InvalidStateException(	×
759	'Create a form or call Nette\Forms\Form::initialize() before the headers are sent to initialize CSRF protection.'
UNCOV 760	. ($file ? " (output started at $file:$line)" : '') . '. ',	×
761	);
762	}
763
764	$response = new Nette\Http\Response;	×
UNCOV 765	$response->cookieSecure = self::$defaultHttpRequest->isSecured();	×
766	Nette\Http\Helpers::initCookie(self::$defaultHttpRequest, $response);	×
767	}
768	}	1✔
769
770
771	private function getHttpRequest(): Nette\Http\IRequest
772	{
773	if (!isset($this->httpRequest)) {	1✔
774	self::initialize();	1✔
775	$this->httpRequest = self::$defaultHttpRequest;	1✔
776	}
777
778	return $this->httpRequest;	1✔
779	}
780	}

nette / forms / 26455457147

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous