Add Hint and Placeholder attributes (#65)

README.md

@@ -34,8 +34,8 @@ composer require yiisoft/form-model
 Define a [form model](docs/guide/en/form-model.md):
 
 ```php
+use Yiisoft\FormModel\Attribute\Safe;
 use Yiisoft\FormModel\FormModel;
-use Yiisoft\FormModel\Safe;
 use Yiisoft\Validator\Rule\Email;
 use Yiisoft\Validator\Rule\Length;
 use Yiisoft\Validator\Rule\Required;

docs/guide/en/form-model.md

@@ -250,11 +250,8 @@ final class LoginForm extends FormModel
 This package also provides `Safe` rule that marks a model property as safe for filling from user input.
 
 ```php
+use Yiisoft\FormModel\Attribute\Safe;
 use Yiisoft\FormModel\FormModel;
-use Yiisoft\FormModel\Safe;
-use Yiisoft\Validator\Rule\Email;
-use Yiisoft\Validator\Rule\Length;
-use Yiisoft\Validator\Rule\Required;
 
 final class LoginForm extends FormModel
 { 

src/Attribute/Hint.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\FormModel\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Hint
+{
+ public function __construct(
+ private string $hint,
+ ) {
+ }
+
+ public function getHint(): string
+ {
+ return $this->hint;
+ }
+}

src/Attribute/Placeholder.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\FormModel\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Placeholder
+{
+ public function __construct(
+ private string $placeholder,
+ ) {
+ }
+
+ public function getPlaceholder(): string
+ {
+ return $this->placeholder;
+ }
+}

src/Safe.php → src/Attribute/Safe.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Yiisoft\FormModel;
+namespace Yiisoft\FormModel\Attribute;
 
 use Attribute;
 use Yiisoft\Validator\Result;

src/FormModel.php

@@ -8,6 +8,9 @@
 use ReflectionAttribute;
 use ReflectionClass;
 use ReflectionException;
+use ReflectionProperty;
+use Yiisoft\FormModel\Attribute\Hint;
+use Yiisoft\FormModel\Attribute\Placeholder;
 use Yiisoft\FormModel\Exception\PropertyNotSupportNestedValuesException;
 use Yiisoft\FormModel\Exception\StaticObjectPropertyException;
 use Yiisoft\FormModel\Exception\UndefinedArrayElementException;
@@ -239,16 +242,9 @@ private function readPropertyMetaValue(int $metaKey, string $path): ?string
  return null;
  }
 
- /**
- * Try to get label from {@see Label} PHP attribute.
- */
- if ($metaKey === self::META_LABEL) {
- $attributes = $property->getAttributes(Label::class, ReflectionAttribute::IS_INSTANCEOF);
- foreach ($attributes as $attribute) {
- /** @var Label $instance */
- $instance = $attribute->newInstance();
- return $instance->getLabel();
- }
+ $valueByAttribute = $this->getPropertyMetaValueByAttribute($metaKey, $property);
+ if ($valueByAttribute !== null) {
+ return $valueByAttribute;
  }
 
  $value = $property->getValue($value);
@@ -319,4 +315,48 @@ private function makePropertyPathString(array $keys): string
  }
  return $path;
  }
+
+ /**
+ * @psalm-param self::META_* $metaKey
+ */
+ private function getPropertyMetaValueByAttribute(int $metaKey, ReflectionProperty $property): ?string
+ {
+ switch ($metaKey) {
+ /** Try to get label from {@see Label} PHP attribute. */
+ case self::META_LABEL:
+ $attributes = $property->getAttributes(Label::class, ReflectionAttribute::IS_INSTANCEOF);
+ if (!empty($attributes)) {
+ /** @var Label $instance */
+ $instance = $attributes[0]->newInstance();
+
+ return $instance->getLabel();
+ }
+
+ break;
+ /** Try to get label from {@see Hint} PHP attribute. */
+ case self::META_HINT:
+ $attributes = $property->getAttributes(Hint::class, ReflectionAttribute::IS_INSTANCEOF);
+ if (!empty($attributes)) {
+ /** @var Hint $instance */
+ $instance = $attributes[0]->newInstance();
+
+ return $instance->getHint();
+ }
+
+ break;
+ /** Try to get label from {@see Placeholder} PHP attribute. */
+ case self::META_PLACEHOLDER:
+ $attributes = $property->getAttributes(Placeholder::class, ReflectionAttribute::IS_INSTANCEOF);
+ if (!empty($attributes)) {
+ /** @var Placeholder $instance */
+ $instance = $attributes[0]->newInstance();
+
+ return $instance->getPlaceholder();
+ }
+
+ break;
+ }
+
+ return null;
+ }
 }

tests/FormModelTest.php

@@ -9,19 +9,19 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 use stdClass;
+use Yiisoft\FormModel\Attribute\Safe;
 use Yiisoft\FormModel\Exception\PropertyNotSupportNestedValuesException;
 use Yiisoft\FormModel\Exception\StaticObjectPropertyException;
 use Yiisoft\FormModel\Exception\UndefinedObjectPropertyException;
 use Yiisoft\FormModel\FormModel;
 use Yiisoft\FormModel\FormModelInputData;
 use Yiisoft\FormModel\FormModelInterface;
-use Yiisoft\FormModel\Safe;
 use Yiisoft\FormModel\Tests\Support\Dto\Coordinates;
 use Yiisoft\FormModel\Tests\Support\Form\CustomFormNameForm;
 use Yiisoft\FormModel\Tests\Support\Form\DefaultFormNameForm;
 use Yiisoft\FormModel\Tests\Support\Form\FormWithNestedProperty;
 use Yiisoft\FormModel\Tests\Support\Form\FormWithNestedStructures;
-use Yiisoft\FormModel\Tests\Support\Form\LabelForm;
+use Yiisoft\FormModel\Tests\Support\Form\AttributeForm;
 use Yiisoft\FormModel\Tests\Support\Form\LoginForm;
 use Yiisoft\FormModel\Tests\Support\Form\NestedForm;
 use Yiisoft\FormModel\Tests\Support\Form\NestedMixedForm\NestedMixedForm;
@@ -686,17 +686,49 @@ public function testAddErrorWithoutValidation(): void
 
  public static function dataLabel(): iterable
  {
- yield ['AgeFromAttribute', 'age'];
- yield ['NameFromGetter', 'name'];
+ yield ['AgeLabelFromAttribute', 'age'];
+ yield ['NameLabelFromGetter', 'name'];
  }
 
  #[DataProvider('dataLabel')]
  public function testLabel(string $expected, string $property): void
  {
- $form = new LabelForm();
+ $form = new AttributeForm();
 
  $label = $form->getPropertyLabel($property);
 
  $this->assertSame($expected, $label);
  }
+
+ public static function dataHint(): iterable
+ {
+ yield ['AgeHintFromAttribute', 'age'];
+ yield ['NameHintFromGetter', 'name'];
+ }
+
+ #[DataProvider('dataHint')]
+ public function testHint(string $expected, string $property): void
+ {
+ $form = new AttributeForm();
+
+ $label = $form->getPropertyHint($property);
+
+ $this->assertSame($expected, $label);
+ }
+
+ public static function dataPlaceholder(): iterable
+ {
+ yield ['AgePlaceholderFromAttribute', 'age'];
+ yield ['NamePlaceholderFromGetter', 'name'];
+ }
+
+ #[DataProvider('dataPlaceholder')]
+ public function testPlaceholder(string $expected, string $property): void
+ {
+ $form = new AttributeForm();
+
+ $label = $form->getPropertyPlaceholder($property);
+
+ $this->assertSame($expected, $label);
+ }
 }

tests/SafeTest.php

@@ -5,7 +5,7 @@
 namespace Yiisoft\FormModel\Tests;
 
 use PHPUnit\Framework\TestCase;
-use Yiisoft\FormModel\Safe;
+use Yiisoft\FormModel\Attribute\Safe;
 
 final class SafeTest extends TestCase
 {

tests/Support/Form/AttributeForm.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\FormModel\Tests\Support\Form;
+
+use Yiisoft\FormModel\Attribute\Hint;
+use Yiisoft\FormModel\Attribute\Placeholder;
+use Yiisoft\FormModel\FormModel;
+use Yiisoft\Validator\Label;
+
+final class AttributeForm extends FormModel
+{
+ #[Label('AgeLabelFromAttribute')]
+ #[Hint('AgeHintFromAttribute')]
+ #[Placeholder('AgePlaceholderFromAttribute')]
+ public string $age;
+
+ #[Label('NameLabelFromAttribute')]
+ #[Hint('NameHintFromAttribute')]
+ #[Placeholder('NamePlaceholderFromAttribute')]
+ public string $name;
+
+ public function getPropertyLabels(): array
+ {
+ return [
+ 'name' => 'NameLabelFromGetter',
+ ];
+ }
+
+ public function getPropertyHints(): array
+ {
+ return [
+ 'name' => 'NameHintFromGetter',
+ ];
+ }
+
+ public function getPropertyPlaceholders(): array
+ {
+ return [
+ 'name' => 'NamePlaceholderFromGetter',
+ ];
+ }
+}

tests/Support/Form/FormWithNestedStructures.php

@@ -4,8 +4,8 @@
 
 namespace Yiisoft\FormModel\Tests\Support\Form;
 
+use Yiisoft\FormModel\Attribute\Safe;
 use Yiisoft\FormModel\FormModel;
-use Yiisoft\FormModel\Safe;
 use Yiisoft\FormModel\Tests\Support\Dto\Coordinates;
 
 final class FormWithNestedStructures extends FormModel

tests/Support/Form/LoginForm.php

@@ -4,8 +4,8 @@
 
 namespace Yiisoft\FormModel\Tests\Support\Form;
 
+use Yiisoft\FormModel\Attribute\Safe;
 use Yiisoft\FormModel\FormModel;
-use Yiisoft\FormModel\Safe;
 use Yiisoft\Validator\Rule\Email;
 use Yiisoft\Validator\Rule\Length;
 use Yiisoft\Validator\Rule\Required;

tests/Support/Form/NestedRuleForm/MainForm.php

@@ -4,8 +4,8 @@
 
 namespace Yiisoft\FormModel\Tests\Support\Form\NestedRuleForm;
 
+use Yiisoft\FormModel\Attribute\Safe;
 use Yiisoft\FormModel\FormModel;
-use Yiisoft\FormModel\Safe;
 use Yiisoft\Validator\Rule\Nested;
 use Yiisoft\Validator\Rule\Required;
 use Yiisoft\Validator\RulesProviderInterface;