Skip to content

Modifiers

Modifiers implement ModifierInterface and receive the field value by reference. A field applies modifiers in collection order whenever its value is read through getFieldValue() or during object hydration.

$form->addField(
    'name',
    new StringType(),
    modifiers: [new TrimModifier(), new ToLowerModifier()],
);

PHP attribute support

Small Forms 2.3.0 contains 38 modifier classes. All 38 are declared as PHP attributes and support property targets, so they can be placed directly on entity/DTO properties when their constructor arguments are valid PHP attribute expressions.

The built-in modifiers are:

ArrayToCollectionModifier, CsvToArrayModifier, EmptyStringToNullModifier, ExplodeModifier, FalseIfEmptyModifier, FilterEmptyArrayModifier, FormBooleanToPhpModifier, ImplodeModifier, JoinModifier, JsonDecodeModifier, JsonEncodeModifier, LTrimModifier, LowercaseArrayModifier, MapModifier, NormalizeWhitespaceModifier, NullIfBlankModifier, NullIfEmptyModifier, RegexReplaceModifier, ReplaceModifier, RoundModifier, RTrimModifier, SortArrayModifier, SplitModifier, StringToBooleanModifier, StringToDateTimeImmutableModifier, StringToDateTimeModifier, StringToEnumModifier, StripTagsModifier, SubStrModifier, ToFloatModifier, ToIntModifier, ToLowerModifier, ToStringModifier, ToUpperModifier, TrimModifier, UcFirstModifier, UcWordsModifier, UniqueArrayModifier.

Examples:

#[StringType]
#[NormalizeWhitespaceModifier]
#[EmptyStringToNullModifier]
private ?string $label = null;

#[StringType]
#[TrimModifier]
#[ToLowerModifier]
private string $slugSource = '';

#[StringType]
#[SubStrModifier(0, 64)]
private string $summary = '';

All modifiers also remain available programmatically through addField() or addModifier().

Empty and boolean normalization

new EmptyStringToNullModifier();
new NullIfEmptyModifier();
new NullIfBlankModifier();
new FalseIfEmptyModifier(false);
new StringToBooleanModifier();

StringToBooleanModifier defaults to:

trueValues: ['1', 'true', 'yes', 'on']
falseValues: ['0', 'false', 'no', 'off', '']
caseInsensitive: true

BooleanType already adds FalseIfEmptyModifier and FormBooleanToPhpModifier automatically.

Type conversion

new ToIntModifier();
new ToFloatModifier();
new ToStringModifier();
new StringToEnumModifier(Status::class);
new StringToDateTimeModifier('Y-m-d H:i:s');
new StringToDateTimeImmutableModifier('Y-m-d');

StringToEnumModifier validates the configured class at construction time and requires an enum.

Arrays and collections

Useful modifiers include:

new CsvToArrayModifier();
new FilterEmptyArrayModifier();
new UniqueArrayModifier();
new SortArrayModifier(descending: true);
new LowercaseArrayModifier();
new MapModifier(new ToIntModifier());
new ArrayToCollectionModifier();

ArrayToCollectionModifier defaults to Small\Collection\Collection\Collection and checks the target collection class befor conversion.

Split/join equivalents are available through ExplodeModifier and ImplodeModifier, both as property attributes and programmatically.

JSON conversion

new JsonDecodeModifier(associative: true, depth: 512);
new JsonEncodeModifier(flags: JSON_UNESCAPED_UNICODE);

JsonDecodeModifier leaves existing null, array and object values unchanged. JsonEncodeModifier enables JSON_THROW_ON_ERROR in addition to caller-supplied flags.

String normalization

String normalization includes whitespace normalization, tag stripping and replacement:

new NormalizeWhitespaceModifier();
new StripTagsModifier('<b><i>');
new ReplaceModifier(['foo', 'bar'], ['x', 'y']);
new RegexReplaceModifier('/\s+/', ' ');

Case conversion and trim helpers are also valid property attributes, including ToLowerModifier, ToUpperModifier, TrimModifier, LTrimModifier and RTrimModifier.

Read-time behavior

Modifiers do not mutate the raw value stored by Field::setValue().

$form = FormBuilder::createInlineForm()
    ->addField('name', new StringType(), modifiers: [new TrimModifier()])
    ->fillFromArray(['name' => '  Ada  ']);

$form->getFieldValue('name'); // "Ada"
$form->toArray();             // raw stored value: "  Ada  "

This is important when deciding whether toArray() represents transport input or normalized application data. Hydration uses getValue(), so modifiers are applied before values are written into the destination object.