[FRAM-166] Improve APIs

src/Aggregate/ArrayElement.php

@@ -294,6 +294,14 @@ public function valid(): bool
         return $this->valid;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function failed(): bool
+    {
+        return !$this->valid;
+    }
+
     /**
      * {@inheritdoc}
      */

src/Aggregate/Form.php

@@ -184,6 +184,14 @@
         return $this->valid;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function failed(): bool
+    {
+        return !$this->valid;
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -312,7 +320,7 @@
      */
     public function offsetSet($offset, $value): void
     {
         throw new BadMethodCallException(__CLASS__.' is immutable');
     }
 
     /**

src/Aggregate/FormBuilder.php

@@ -14,6 +14,8 @@
 use Bdf\Form\Custom\CustomForm;
 use Bdf\Form\ElementBuilderInterface;
 use Bdf\Form\ElementInterface;
+use Bdf\Form\Leaf\AnyElement;
+use Bdf\Form\Leaf\AnyElementBuilder;
 use Bdf\Form\Leaf\BooleanElement;
 use Bdf\Form\Leaf\BooleanElementBuilder;
 use Bdf\Form\Leaf\Date\DateTimeChildBuilder;
@@ -128,6 +130,20 @@ public function add(string $name, string $element): ChildBuilderInterface
         return $this->children[$name] = $this->registry()->childBuilder($element, $name);
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @psalm-param non-empty-string $name
+     * @psalm-return ChildBuilder<AnyElementBuilder>
+     *
+     * @psalm-suppress MoreSpecificReturnType
+     * @psalm-suppress LessSpecificReturnStatement
+     */
+    public function any(string $name): ChildBuilderInterface
+    {
+        return $this->add($name, AnyElement::class);
+    }
+
     /**
      * {@inheritdoc}
      *

src/Aggregate/FormBuilderInterface.php

@@ -9,6 +9,7 @@
 use Bdf\Form\Csrf\CsrfElementBuilder;
 use Bdf\Form\ElementBuilderInterface;
 use Bdf\Form\ElementInterface;
+use Bdf\Form\Leaf\AnyElementBuilder;
 use Bdf\Form\Leaf\BooleanElementBuilder;
 use Bdf\Form\Leaf\Date\DateTimeChildBuilder;
 use Bdf\Form\Leaf\Date\DateTimeElementBuilder;
@@ -36,6 +37,8 @@
  * </code>
  *
  * @extends ElementBuilderInterface<FormInterface>
+ *
+ * @method ChildBuilderInterface any(string $name)
  */
 interface FormBuilderInterface extends ElementBuilderInterface
 {
@@ -56,6 +59,25 @@ interface FormBuilderInterface extends ElementBuilderInterface
      */
     public function add(string $name, string $element): ChildBuilderInterface;
 
+    /**
+     * Add a new child element which can be of any type
+     *
+     * Note: the any element remove all type safety, and should be used with caution
+     *
+     * <code>
+     * $builder->any('value', IntegerElement::class)->required();
+     * </code>
+     *
+     * @param non-empty-string $name The child name
+     *
+     * @return ChildBuilder|AnyElementBuilder
+     * @return ChildBuilderInterface<AnyElementBuilder> The child builder
+     *
+     * @since 1.5
+     * @todo uncomment in 2.0
+     */
+    //public function any(string $name): ChildBuilderInterface;
+
     /**
      * Add a new string element on the form
      *

src/Aggregate/RootForm.php

@@ -171,6 +171,15 @@ public function valid(): bool
         return $this->form->get()->valid();
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function failed(): bool
+    {
+        // Do not use $this->form->get()->failed() because it may be not implemented
+        return !$this->valid();
+    }
+
     /**
      * {@inheritdoc}
      */

src/Child/ChildBuilder.php

@@ -333,6 +333,34 @@ final public function setter($propertyName = null, ?callable $transformer = null
         return $this->hydrator(new Setter($propertyName, $transformer, $customAccessor));
     }
 
+    /**
+     * Helper method for define both simple getter and setter
+     * This method is a shortcut for `$builder->getter($name)->setter($name)`
+     *
+     * This method does not supports transformer and custom accessor.
+     * To define one of them, use the getter() and setter() methods.
+     *
+     * <code>
+     * $builder->string('foo')->getset(); // fill() and import()  the "foo" property
+     * $builder->string('foo')->getset('bar'); // fill() and import() the "bar" property
+     * </code>
+     *
+     * @param string|null $propertyName The property name. If null use the child name.
+     *
+     * @return $this
+     *
+     * @see Setter
+     * @see Getter
+     * @see ChildBuilder::getter()
+     * @see ChildBuilder::setter()
+     *
+     * @since 1.5
+     */
+    final public function getset(?string $propertyName = null): self
+    {
+        return $this->getter($propertyName)->setter($propertyName);
+    }
+
     /**
      * Define the child class name
      *

src/Csrf/CsrfElement.php

@@ -130,6 +130,14 @@ public function valid(): bool
         return $this->value && $this->error->empty();
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function failed(): bool
+    {
+        return !$this->valid();
+    }
+
     /**
      * {@inheritdoc}
      */

src/Custom/CustomForm.php

@@ -183,6 +183,15 @@ public function valid(): bool
         return $this->form()->valid();
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function failed(): bool
+    {
+        // Do not use $this->form()->failed() because it may be not implemented
+        return !$this->valid();
+    }
+
     /**
      * {@inheritdoc}
      */

src/ElementInterface.php

@@ -20,6 +20,8 @@
  * </code>
  *
  * @template T
+ *
+ * @method bool failed()
  */
 interface ElementInterface
 {
@@ -124,6 +126,22 @@ public function httpValue();
      */
     public function valid(): bool;
 
+    /**
+     * Check if the element value validation has failed
+     * On aggregate element, if at least on child is invalid, this method will return true
+     *
+     * This method is a shortcut for `!$element->valid()`
+     *
+     * Note: A non-submit()'ed element will return true
+     *
+     * @return bool
+     *
+     * @see ElementInterface::error() To get error
+     * @since 1.5
+     * @todo uncomment in 2.0
+     */
+    //public function failed(): bool;
+
     /**
      * Get the errors related to the element
      *

src/Error/FormError.php

@@ -114,6 +114,37 @@ public function empty(): bool
         return empty($this->global) && empty($this->code) && empty($this->children);
     }
 
+    /**
+     * Get a single error message
+     *
+     * Note: if the error is an aggregate error, the method will return null,
+     *       so it must not be used to check if a child has an error
+     *
+     * @param string $child The child name
+     *
+     * @return string|null The child error message, or null if the child has no global error, or is not found
+     * @since 1.5
+     */
+    public function get(string $child): ?string
+    {
+        $child = $this->children[$child] ?? null;
+
+        return $child ? $child->global : null;
+    }
+
+    /**
+     * Get the error of a child
+     * An object is always returned, even if the child has no error, so check {@see FormError::empty()} to know if the child has an error
+     * @param string $child The child name
+     *
+     * @return FormError The child error
+     * @since 1.5
+     */
+    public function child(string $child): FormError
+    {
+        return $this->children[$child] ?? self::null();
+    }
+
     /**
      * Export the errors into an array
      *

src/Leaf/LeafElement.php

@@ -130,6 +130,14 @@ final public function valid(): bool
         return $this->submitted && $this->error->empty();
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    final public function failed(): bool
+    {
+        return !$this->valid();
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -188,14 +196,14 @@ final public function root(): RootElementInterface
      */
     public function view(?HttpFieldPath $field = null): ElementViewInterface
     {
-        $normalizedConstraints = ConstraintsNormalizer::normalize($this->validator);
+        [$required, $normalizedConstraints] = $this->parseConstraints($this->validator);
 
         return new SimpleElementView(
             static::class,
             (string) $field,
             $this->httpValue(),
             $this->error->global(),
-            isset($normalizedConstraints[NotBlank::class]),
+            $required,
             $normalizedConstraints,
             $this->choiceView()
         );
@@ -278,4 +286,22 @@ protected function choiceView(): ?array
             $view->setValue($this->transformer->transformToHttp($this->toHttp($view->value()), $this));
         });
     }
+
+    /**
+     * Parse constraints and required value
+     *
+     * By default, will use {@see ConstraintsNormalizer} to extract constraints,
+     * and check the presence of {@see NotBlank} constraint to determine if the field is required
+     *
+     * @return list{bool, array}
+     */
+    protected function parseConstraints(ValueValidatorInterface $validator): array
+    {
+        $normalizedConstraints = ConstraintsNormalizer::normalize($validator);
+
+        return [
+            isset($normalizedConstraints[NotBlank::class]),
+            $normalizedConstraints
+        ];
+    }
 }

src/Leaf/LeafRootElement.php

@@ -96,6 +96,15 @@ public function valid(): bool
         return $this->element->valid();
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function failed(): bool
+    {
+        // Do not use $this->element->failed() because it may be not implemented
+        return !$this->valid();
+    }
+
     /**
      * {@inheritdoc}
      */

src/Leaf/View/SimpleFieldHtmlRenderer.php

@@ -62,7 +62,11 @@ public function render(FieldViewInterface $view, array $attributes): string
 
         $attributes['name'] = $view->name();
         $attributes['value'] = $view->value();
-        $attributes['required'] = $view->required();
+
+        if (!isset($attributes['required'])) {
+            $attributes['required'] = $view->required();
+        }
+
         $attributes += $this->constraintsToAttributes($view->constraints());
 
         return HtmlRenderer::element('input', $attributes);

src/Phone/PhoneElement.php

@@ -129,4 +129,25 @@ public function parseValue(string $rawPhoneNumber): PhoneNumber
             return (new PhoneNumber())->setRawInput($rawPhoneNumber);
         }
     }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function parseConstraints(ValueValidatorInterface $validator): array
+    {
+        $result = parent::parseConstraints($validator);
+
+        if (!$result[0]) {
+            // PhoneElement use NotEmptyPhoneNumber instead of NotBlank
+            // So we need to check if this constraint is present
+            foreach ($validator->constraints() as $constraint) {
+                if ($constraint instanceof NotEmptyPhoneNumber) {
+                    $result[0] = true;
+                    break;
+                }
+            }
+        }
+
+        return $result;
+    }
 }

src/View/ElementViewInterface.php

@@ -4,6 +4,8 @@
 
 /**
  * Base form element view type
+ *
+ * @method self setError(?string $error)
  */
 interface ElementViewInterface
 {
@@ -22,6 +24,21 @@ public function type(): string;
      */
     public function error(): ?string;
 
+    /**
+     * Overwrite the current element error
+     * In case of aggregate element, this method should set the global error and not the children errors
+     *
+     * This method can be used to display error from an external source, for example from an API error.
+     * Set to null to remove the error
+     *
+     * @param string|null $error The error message, or null to mark the element as valid
+     *
+     * @return $this
+     * @since 1.5
+     * @todo uncomment in 2.0
+     */
+    //public function setError(?string $error): self;
+
     /**
      * Check if the current element is on error
      * In case of aggregate element, this method will return false if there is at least one child on error or a global error