Search by

ui-awesome / form-model

terabytesoftw

Form metadata and validation errors for model-driven PHP forms.

Package info

github.com/ui-awesome/form-model

pkg:composer/ui-awesome/form-model

Statistics

Installs: 1 360

Dependents: 3

Suggesters: 0

Stars: 1

Open Issues: 0

0.2.3 2026-11-15 14:38 UTC

This package is auto-updated.

Last update: 2026-11-17 11:32:39 UTC


README

UI Awesome

Form Model for PHP


PHPUnit Coverage Mutation Testing PHPStan

Form metadata and validation errors for model-driven PHP forms
Hints, labels, placeholders, field configuration, nested field metadata, and field-scoped error handling

Features

Feature Overview

Installation

composer require ui-awesome/form-model:^0.2

Quick start

<?php

declare(strict_types=1);

namespace App\FormModel;

use UIAwesome\FormModel\BaseFormModel;
use UIAwesome\FormModel\Attribute\{FieldConfig, Hint, Label, Placeholder};

final class SignInForm extends BaseFormModel
{
    #[Hint('Use your account email address.')]
    #[Label('Email address')]
    #[Placeholder('name@example.com')]
    #[FieldConfig(['class' => ['w-full rounded-md border border-slate-300 px-3 py-2']])]
    public string $email = '';

    public string $password = '';

    public function getHints(): array
    {
        return [
            'password' => 'Use at least 8 characters.',
        ];
    }

    public function getLabels(): array
    {
        return [
            'password' => 'Password',
        ];
    }

    public function getPlaceholders(): array
    {
        return [
            'password' => 'Enter your password',
        ];
    }

    public function getRules(): array
    {
        return [
            'email' => ['required', 'email'],
            'password' => ['required', 'string'],
        ];
    }

    public function getFieldConfigs(): array
    {
        return [
            'password' => [
                'class' => ['w-full rounded-md border border-slate-300 px-3 py-2'],
            ],
        ];
    }
}

$form = new SignInForm();

$form->addError('email', 'Email is required.');
$errors = $form->getErrors();
/*
[
    'email' => ['Email is required.'],
]
*/

$summary = $form->getErrorSummary();
// ['Email is required.']

$label = $form->getLabel('email');
// 'Email address'

Nested field metadata

You can request metadata using dot notation when a field contains another BaseFormModel.

$hint = $form->getHint('profile.address.city');
$label = $form->getLabel('profile.address.city');
$placeholder = $form->getPlaceholder('profile.address.city');
$rules = $form->getRule('profile.address.city');

Property attributes

Property attributes are resolved first for metadata (Hint, Label, Placeholder, FieldConfig). Map methods (getHints(), getLabels(), getPlaceholders(), getFieldConfigs()) remain as fallback.

$emailHint = $form->getHint('email');
$emailLabel = $form->getLabel('email');
$emailPlaceholder = $form->getPlaceholder('email');
$emailFieldConfig = $form->getFieldConfig('email');

Error collection and first-error mode

Use first-error mode when you need one message per field.

$form->setErrors(
    [
        'email' => ['Email is required.', 'Email is invalid.'],
        'password' => ['Password is required.'],
    ],
);

$firstErrors = $form->getFirstErrors();
/*
[
    'email' => 'Email is required.',
    'password' => 'Password is required.',
]
*/

Documentation

For detailed configuration options and advanced usage.

AI assistance

AI agents: read the documentation index and fetch the Markdown version of a page by appending index.md to its URL. The AI agents guide covers skill installation, client setup and verification.

  • ๐Ÿค– ui-awesome-form-model skill: labels, hints, placeholders, field configuration, nested field paths and field-scoped errors.

See the repository guides, the skill source, the source PHPDoc and the changelog. This package stores rules and errors but does not run validation, and it does not depend on Yii; no Yii application skill is required.

Package information

PHP Latest Stable Version Total Downloads

Project status

PHPStan Level Max Quality StyleCI

Security

OpenSSF Scorecard Zizmor

Built with AI

Built with Claude Code Built with Codex Reviewed by CodeRabbit

Our social networks

Follow on X Follow on Facebook

License

License