The decorated elements */
private ?WeakMap $decoratedElements = null;
/**
* Custom Element decorator loader paths
*
* Override this property to add custom decorator loader paths.
*
* @var loaderPaths
*/
protected array $elementDecoratorLoaderPaths = [];
/**
* Default element decorators
*
* Override this property to change the default decorators of the elements.
*
* Please see {@see DecoratorChain::addDecorators()} for the supported array formats.
*
* @var decoratorsFormat
*/
protected array $defaultElementDecorators = [];
/** @var FormElement[] */
private $elements = [];
/** @var array> */
private $populatedValues = [];
/**
* Get the default element decorators.
*
* @return decoratorsFormat
*/
public function getDefaultElementDecorators(): array
{
return $this->defaultElementDecorators;
}
public function setDefaultElementDecorators(array $decorators): static
{
if ($this->hasDefaultElementDecorator()) {
throw new RuntimeException(sprintf(
'Cannot use element decorators of type %s and legacy decorator of type %s together',
FormElementDecoration::class,
FormElementDecorator::class
));
}
$this->defaultElementDecorators = $decorators;
return $this;
}
public function addElementDecoratorLoaderPaths(array $loaderPaths): static
{
$this->elementDecoratorLoaderPaths = $loaderPaths;
return $this;
}
public function getElements()
{
return $this->elements;
}
public function hasElement($element)
{
if (is_string($element)) {
return array_key_exists($element, $this->elements);
}
if ($element instanceof FormElement) {
return in_array($element, $this->elements, true);
}
return false;
}
public function getElement($name)
{
if (! array_key_exists($name, $this->elements)) {
throw new InvalidArgumentException(sprintf(
"Can't get element '%s'. Element does not exist",
$name
));
}
return $this->elements[$name];
}
public function addElement($typeOrElement, $name = null, $options = null)
{
if (is_string($typeOrElement)) {
if ($name === null) {
throw new InvalidArgumentException(sprintf(
'%s expects parameter 2 to be set if parameter 1 is a string',
__METHOD__
));
}
$element = $this->createElement($typeOrElement, $name, $options);
} elseif ($typeOrElement instanceof FormElement) {
$element = $typeOrElement;
} else {
throw new InvalidArgumentException(sprintf(
'%s() expects parameter 1 to be a string or an instance of %s, %s given',
__METHOD__,
FormElement::class,
get_php_type($typeOrElement)
));
}
$this
->registerElement($element) // registerElement() must be called first because of the name check
->decorate($element)
->addHtml($element);
return $this;
}
/**
* Create an element
*
* @param string $type Type of the element
* @param string $name Name of the element
* @param mixed $options Element options as key-value pairs
*
* @return FormElement
*
* @throws InvalidArgumentException If the type of the element is unknown
*/
public function createElement($type, $name, $options = null)
{
$this->ensureDefaultElementLoaderRegistered();
$class = $this->loadPlugin('element', $type);
if (! $class) {
throw new InvalidArgumentException(sprintf(
"Can't create element of unknown type '%s",
$type
));
}
/** @var FormElement $element */
$element = new $class($name);
if ($element instanceof DecorableFormElement) {
$customDecoratorPaths = $this->elementDecoratorLoaderPaths;
$elementDecoratorChain = $element->getDecorators();
if (! empty($customDecoratorPaths)) {
if ($element instanceof DefaultFormElementDecoration) {
$element->addElementDecoratorLoaderPaths($customDecoratorPaths);
}
foreach ($customDecoratorPaths as $path) {
$elementDecoratorChain->addDecoratorLoader($path[0], $path[1] ?? '');
}
}
$defaultDecorators = $this->getDefaultElementDecorators();
if (
! empty($defaultDecorators)
&& ! $this->hasDefaultElementDecorator()
&& empty($options['hidden'])
&& ! $element instanceof HiddenElement
&& $element->getAttributes()->get('hidden')->isEmpty()
) {
if ($element instanceof DefaultFormElementDecoration) {
$element->setDefaultElementDecorators($defaultDecorators);
}
if (! isset($options['decorators'])) {
$elementDecoratorChain->addDecorators($defaultDecorators);
}
}
}
if ($options !== null) {
$element->addAttributes($options);
}
return $element;
}
public function registerElement(FormElement $element)
{
$name = $element->getName();
if ($name === null) {
throw new InvalidArgumentException(sprintf(
'%s expects the element to provide a name',
__METHOD__
));
}
$this->elements[$name] = $element;
if (array_key_exists($name, $this->populatedValues)) {
$element->setValue($this->populatedValues[$name][count($this->populatedValues[$name]) - 1]);
if ($element instanceof ValueCandidates) {
$element->setValueCandidates($this->populatedValues[$name]);
}
}
$this->onElementRegistered($element);
$this->emit(Form::ON_ELEMENT_REGISTERED, [$element]);
return $this;
}
/**
* Get whether a default element decorator exists
*
* @return bool
* @deprecated This is not of general use anymore. The new decorator implementation handles defaults entirely
* internally now. Use {@see getDefaultElementDecorators()} instead only if you absolutely have to.
*/
public function hasDefaultElementDecorator()
{
return $this->defaultElementDecorator !== null;
}
/**
* Get the default element decorator, if any
*
* @return FormElementDecorator|null
* @deprecated Use {@see getDefaultElementDecorators()} instead
*/
public function getDefaultElementDecorator()
{
return $this->defaultElementDecorator;
}
/**
* Set the default element decorator
*
* If $decorator is a string, the decorator will be automatically created from a registered decorator loader.
* A loader for the namespace ipl\\Html\\FormDecorator is automatically registered by default.
* See {@link addDecoratorLoader()} for registering a custom loader.
*
* @param FormElementDecorator|string $decorator
*
* @return $this
*
* @deprecated Use {@see setDefaultElementDecorators()} instead
* @throws InvalidArgumentException If $decorator is a string and can't be loaded from registered decorator loaders
* or if a decorator loader does not return an instance of
* {@link FormElementDecorator}
*/
public function setDefaultElementDecorator($decorator)
{
if (! empty($this->getDefaultElementDecorators())) {
throw new RuntimeException(sprintf(
'Cannot use element decorators of type %s and legacy decorator of type %s together',
FormElementDecoration::class,
FormElementDecorator::class
));
}
if ($decorator instanceof FormElementDecorator || $decorator instanceof DecoratorInterface) {
$this->defaultElementDecorator = $decorator;
} else {
$this->ensureDefaultElementDecoratorLoaderRegistered();
$class = $this->loadPlugin('decorator', $decorator);
if (! $class) {
throw new InvalidArgumentException(sprintf(
"Can't create decorator of unknown type '%s",
$decorator
));
}
$d = new $class();
if (! $d instanceof FormElementDecorator && ! $d instanceof DecoratorInterface) {
throw new InvalidArgumentException(sprintf(
"Expected instance of %s for decorator '%s',"
. " got %s from a decorator loader instead",
FormElementDecorator::class,
$decorator,
get_php_type($d)
));
}
$this->defaultElementDecorator = $d;
}
return $this;
}
public function getValue($name, $default = null)
{
if ($this->hasElement($name)) {
$value = $this->getElement($name)->getValue();
if ($value !== null) {
return $value;
}
}
return $default;
}
public function getValues()
{
$values = [];
foreach ($this->getElements() as $element) {
if (! $element->isIgnored()) {
$values[$element->getName()] = $element->getValue();
}
}
return $values;
}
public function populate($values)
{
foreach ($values as $name => $value) {
$this->populatedValues[$name][] = $value;
if ($this->hasElement($name)) {
$this->getElement($name)->setValue($value);
}
}
return $this;
}
/**
* Get the populated value of the element specified by name
*
* Returns $default if there is no populated value for this element.
*
* @param string $name
* @param mixed $default
*
* @return mixed
*/
public function getPopulatedValue($name, $default = null)
{
return isset($this->populatedValues[$name])
? $this->populatedValues[$name][count($this->populatedValues[$name]) - 1]
: $default;
}
/**
* Clear populated value of the given element
*
* @param string $name
*
* @return $this
*/
public function clearPopulatedValue($name)
{
if (isset($this->populatedValues[$name])) {
unset($this->populatedValues[$name]);
}
return $this;
}
/**
* Add all elements from the given element collection
*
* @param Form $form
*
* @return $this
*/
public function addElementsFrom($form)
{
foreach ($form->getElements() as $element) {
$this->addElement($element);
}
return $this;
}
/**
* Add a decorator loader
*
* @param string $namespace Namespace of the decorators
* @param ?string $postfix Decorator name postfix, if any
*
* @return $this
* @deprecated Use {@see addElementDecoratorLoaderPaths()} instead
*/
public function addDecoratorLoader(string $namespace, ?string $postfix = null): static
{
$this->addPluginLoader('decorator', $namespace, $postfix);
return $this;
}
/**
* Add an element loader
*
* @param string $namespace Namespace of the elements
* @param ?string $postfix Element name postfix, if any
*
* @return $this
*/
public function addElementLoader(string $namespace, ?string $postfix = null): static
{
$this->addPluginLoader('element', $namespace, $postfix);
return $this;
}
/**
* Ensure that our default element decorator loader is registered
*
* @return $this
*/
protected function ensureDefaultElementDecoratorLoaderRegistered()
{
if (! $this->defaultElementDecoratorLoaderRegistered) {
$this->addDefaultPluginLoader(
'decorator',
'ipl\\Html\\FormDecorator',
'Decorator'
);
$this->defaultElementDecoratorLoaderRegistered = true;
}
return $this;
}
/**
* Ensure that our default element loader is registered
*
* @return $this
*/
protected function ensureDefaultElementLoaderRegistered()
{
if (! $this->defaultElementLoaderRegistered) {
$this->addDefaultPluginLoader('element', __NAMESPACE__, 'Element');
$this->defaultElementLoaderRegistered = true;
}
return $this;
}
/**
* Decorate the given element
*
* @param FormElement $element
*
* @return $this
*
* @throws UnexpectedValueException If the default decorator is set but not an instance of
* {@link FormElementDecorator}
*/
protected function decorate(FormElement $element)
{
if ($element instanceof DecorableFormElement && $element->hasDecorators()) {
// new decorator implementation in use
$this->decoratedElements ??= new WeakMap();
if (! isset($this->decoratedElements[$element])) {
$this->decoratedElements[$element] = false;
}
return $this;
}
if ($this->hasDefaultElementDecorator()) {
$decorator = $this->getDefaultElementDecorator();
if (! $decorator instanceof FormElementDecorator && ! $decorator instanceof DecoratorInterface) {
throw new UnexpectedValueException(sprintf(
'%s expects the default decorator to be an instance of %s, got %s instead',
__METHOD__,
FormElementDecorator::class,
get_php_type($decorator)
));
}
$decorator->decorate($element);
}
return $this;
}
public function isValidEvent($event)
{
return in_array($event, [
Form::ON_SUBMIT,
Form::ON_SENT,
Form::ON_ERROR,
Form::ON_REQUEST,
Form::ON_VALIDATE,
Form::ON_ELEMENT_REGISTERED,
]);
}
public function removeElement(string|FormElement $element)
{
if (is_string($element)) {
if (! $this->hasElement($element)) {
return $this;
}
$element = $this->getElement($element);
}
return $this->remove($element);
}
public function remove(ValidHtml $content)
{
if ($content instanceof FormElement) {
if ($this->hasElement($content)) {
if (isset($this->decoratedElements[$content])) {
unset($this->decoratedElements[$content]);
}
$name = array_search($content, $this->elements, true);
if ($name !== false) {
unset($this->elements[$name]);
}
}
}
return parent::remove($content);
}
protected function beforeRender(): void
{
if ($this instanceof HtmlDocument) {
parent::beforeRender();
}
foreach ($this->decoratedElements ?? [] as $element => &$decorated) {
if (! $decorated) {
$element->applyDecoration();
$decorated = true;
}
}
}
/**
* Handler which is called after an element has been registered
*
* @param FormElement $element
*/
protected function onElementRegistered(FormElement $element)
{
}
}