Small Forms integration

Small Forms is the optional input-contract layer for Small Swoole Entity Manager applications. Core 3 remains focused on persistence; small/forms handles transport input, validation, normalization and object hydration before an entity is persisted.

Compatibility

Package	Documentation baseline
PHP	8.3+
small/swoole-entity-manager-core	3.x
small/forms	2.3.0
small/collection	4.x

Install it next to Core:

composer require small/forms:^2.3

Attribute-driven forms use AnnotationAdapter, which checks for Symfony Validator at runtime:

composer require symfony/validator

Optional integration

Core does not require Small Forms and persist() does not trigger validation automatically. The application decides which form contract applies to each create, update, import or internal workflow.

Recommended flow

For an Entity Manager entity, use explicit Small Forms attributes on writable properties, build a form from the entity, fill it from input, validate it, hydrate the entity, then persist it.

use Small\Collection\Collection\StringCollection;
use Small\Forms\Form\FormBuilder;

$form = FormBuilder::createFromAttributes($user)
    ->fillFromArray($payload, $user);

$messages = new StringCollection();
$form->validate($messages);

if ($messages->count() !== 0) {
    // Convert these messages to your API/application error format.
    return;
}

$form->hydrate($user);
$user->persist();

Passing the entity as the second argument to fillFromArray() is important when relation input can create new related entities: Small Forms can then ask the relation manager for correctly constructed entity instances instead of trying to instantiate an AbstractEntity directly.

What Small Forms adds

Small Forms 2.3.0 provides:

• eight field types;
• 75 validation-rule classes;
• 38 modifiers;
• inline and reusable forms;
• attribute-driven forms generated from objects;
• array, JSON, URL-encoded and object input;
• nested forms and arrays of nested forms;
• form-aware cross-field validation;
• hydration back into objects and Entity Manager entities.

All built-in validators and modifiers are declared as PHP attributes and support property targets. They can also be used programmatically when runtime construction is more appropriate.

Documentation map

• Entity attributes and type resolution
• Field types
• Validation rules
• Modifiers
• Entity workflow
• Relations and nested forms
• Behavior and caveats

Separation of responsibilities

Use ORM attributes and Small Forms attributes on the same property when useful, but keep their purposes separate:

#[Field(type: FieldValueType::string)]
#[StringType]
#[ValidateNotEmpty]
private string $name = '';

Field defines database persistence. StringType defines the form representation. ValidateNotEmpty defines accepted input. Modifiers define normalization when the value is read or hydrated.