README

Modern PHP Form Generator

A production-ready form builder library offering nested forms, type system, cross-field validation, dynamic form modification, advanced error handling, internationalization, and automatic CSRF protection.

Production Ready

SpiderForm is a comprehensive form building library with an intuitive fluent API.

Key Features

Enterprise-Grade Form Builder

• Comprehensive form building capabilities
• Fluent chain pattern API
• Framework-agnostic design (standalone or integrate with Symfony/Laravel)
• 500+ comprehensive unit tests

🌍 Internationalization (NEW in v3.0.0)

• Multi-language form labels and messages
• Built-in translator with PHP and YAML loaders
• Parameter interpolation ({{ param }} syntax)
• Locale fallback chains

🔒 Automatic CSRF Protection (NEW in v3.0.0)

• Session-based token management
• Automatic token generation and validation
• Configurable token lifetime (default: 2 hours)
• Zero configuration required

📖 Read Full Documentation →

Quick Start - Simple Contact Form with i18n & CSRF

use SpiderForm\V2\Builder\FormBuilder;
use SpiderForm\V2\Translation\FormTranslator;
use SpiderForm\V2\Translation\Loader\PhpLoader;

// Setup translator (optional)
$translator = new FormTranslator('en_US');
$translator->addLoader('php', new PhpLoader());
$translator->loadTranslationFile(__DIR__ . '/translations/forms.en_US.php', 'en_US', 'php');

FormBuilder::setTranslator($translator);

// Build form with CSRF protection (automatic!)
$form = FormBuilder::create('contact_form')
    ->setAction('/contact/send')
    ->setMethod('POST')
    ->setCsrfTokenId('contact_form') // Automatic CSRF protection

    ->addText('name', 'form.label.name') // Translated automatically
        ->required()
        ->minLength(3)
        ->add()

    ->addEmail('email', 'form.label.email')
        ->required()
        ->add()

    ->addTextarea('message', 'form.label.message')
        ->required()
        ->minLength(20)
        ->add()

    ->addSubmit('send', 'form.button.send')
    ->build();

// Render with automatic CSRF token
echo $form;

Nested Forms with Cross-Field Validation

use SpiderForm\V2\Builder\FormBuilder;
use SpiderForm\V2\Form\Form;
use SpiderForm\V2\Validation\Constraints\Callback;

// Create address sub-form
$addressForm = new Form('address');
$addressForm->add('street', FormBuilder::text('street', 'Street'));
$addressForm->add('city', FormBuilder::text('city', 'City'));
$addressForm->add('zipcode', FormBuilder::text('zipcode', 'ZIP Code'));

// Create user form with nested address
$form = FormBuilder::create('user_registration')
    ->setCsrfTokenId('register')

    ->addText('username', 'Username')
        ->required()
        ->minLength(3)
        ->add()

    ->addPassword('password', 'Password')
        ->required()
        ->minLength(8)
        ->add()

    ->addPassword('password_confirm', 'Confirm Password')
        ->required()
        ->add()

    ->add('address', $addressForm) // Nested form!

    ->build();

// Add cross-field validation
$form->addConstraint(new Callback(function($data, $context) {
    if ($data['password'] !== $data['password_confirm']) {
        $context->buildViolation('Passwords do not match')
                ->atPath('password_confirm')
                ->addViolation();
    }
}));

// Validate and handle errors
$form->submit($_POST);
if ($form->isValid()) {
    // Process data
} else {
    $errors = $form->getErrorList(deep: true);
}

Dynamic Form Modification with Events

use SpiderForm\V2\Builder\FormBuilder;
use SpiderForm\V2\Event\FormEvents;

$form = FormBuilder::create('product_form')
    ->setCsrfTokenId('product')

    ->addSelect('product_type', 'Product Type')
        ->options([
            'physical' => 'Physical Product',
            'digital' => 'Digital Product',
        ])
        ->add()

    ->build();

// Add fields dynamically based on product type
$form->addEventListener(FormEvents::PRE_SET_DATA, function($event) {
    $data = $event->getData();
    $form = $event->getForm();

    if ($data['product_type'] === 'physical') {
        // Add shipping fields
        $form->add('weight', FormBuilder::number('weight', 'Weight (kg)'));
        $form->add('dimensions', FormBuilder::text('dimensions', 'Dimensions'));
    } else {
        // Add download fields
        $form->add('file_size', FormBuilder::text('file_size', 'File Size'));
        $form->add('download_limit', FormBuilder::number('download_limit', 'Downloads'));
    }
});

📊 Complete Feature Set

v3.0.0 - Internationalization & CSRF (Current)

• 🌍 Multi-language support with built-in translator
• 🔒 Automatic CSRF protection
• 📝 Multiple translation loaders (PHP, YAML)
• 🔄 Parameter interpolation in messages

v2.9.0 - Advanced Error Handling

• ⚠️ Three error levels (ERROR, WARNING, INFO)
• 🎯 Error bubbling from nested forms
• 📋 Rich error metadata
• 🔍 Error filtering and grouping

v2.8.0 - Dynamic Form Modification

• 🎭 Event-driven form building
• 🔄 Modify forms based on data
• ➕ Add/remove fields dynamically
• 🎬 Full event lifecycle

v2.7.0 - Cross-Field Validation

• ✅ Field relationship validation
• 🎯 Validation groups
• 📝 Custom callback constraints
• 🔧 Execution context

v2.5.0 - Type System

• 🏗️ Custom field types
• 🎨 Type inheritance
• 🔌 Type extensions
• ⚙️ Options resolver

v2.4.0 - Nested Forms

• 🌳 Unlimited nesting
• 🔁 Form collections
• 👨‍👩‍👧 Parent-child relationships
• 🗺️ Data mapping

Earlier Features

• 🔄 Data transformation (v2.3.1)
• 🎯 Event-driven dependencies (v2.3.0)
• ✅ Laravel-style validation (v2.1.0)
• 🎨 Bootstrap 5 & Tailwind themes
• 🔐 CSRF, XSS protection
• 🚀 Symfony & Laravel integration

📦 Installation

composer require selcukmart/spider-form

🧪 Testing

500+ Comprehensive Unit Tests

# Run all tests
vendor/bin/phpunit

# Run specific test suite
vendor/bin/phpunit tests/V2/Type/          # Type system tests
vendor/bin/phpunit tests/V2/Validation/    # Validation tests
vendor/bin/phpunit tests/V2/Event/         # Event system tests
vendor/bin/phpunit tests/V2/Error/         # Error handling tests
vendor/bin/phpunit tests/V2/Translation/   # i18n tests
vendor/bin/phpunit tests/V2/Security/      # CSRF tests

# With coverage
vendor/bin/phpunit --coverage-html coverage/

Test Coverage:

• ✅ 400+ unit tests
• ✅ 100+ integration tests
• ✅ Full API coverage
• ✅ Edge case handling
• ✅ Real-world scenarios

🔄 Migration from Symfony Forms

Before (Symfony Form Component)

$form = $this->createFormBuilder()
    ->add('username', TextType::class, [
        'required' => true,
        'constraints' => [new Length(['min' => 3])]
    ])
    ->add('email', EmailType::class)
    ->getForm();

After (SpiderForm)

$form = FormBuilder::create('user_form')
    ->addText('username')->required()->minLength(3)->add()
    ->addEmail('email')->required()->add()
    ->build();

Advantages:

• 🎯 Chain pattern is more readable
• 🚀 No need for type classes
• 🔧 Less boilerplate code
• 💡 Better IDE autocomplete
• 🎨 Cleaner syntax

See SYMFONY_ALTERNATIVE_ROADMAP.md for complete migration guide.

📚 Complete Documentation

Core Documentation

• Full Documentation - Full feature guide ⭐
• Symfony Alternative Guide - Migration from Symfony Forms
• Upgrade Guide - Version migration guides
• Changelog - Version history
• Contributing - Contribution guidelines

Examples by Version

🌍 v3.0.0 - Internationalization & CSRF (NEW!)

• Internationalization Example
• Multi-language Forms
• Auto CSRF Protection

⚠️ v2.9.0 - Error Handling

• Advanced Error Handling
• Error Levels & Filtering
• Error Bubbling

🎭 v2.8.0 - Dynamic Forms

• Dynamic Form Modification
• Event-based Form Building

✅ v2.7.0 - Cross-Field Validation

• Callback Validation
• Validation Groups
• Cross-Field Rules

🏗️ v2.5.0 - Type System

• Custom Types
• Type Extensions
• Options Resolver

🌳 v2.4.0 - Nested Forms

• Nested Forms
• Form Collections
• Parent-Child Forms

Earlier Features

• Data Transformation (v2.3.1)
• Event-Driven Dependencies (v2.3.0)
• Laravel-Style Validation (v2.1.0)
• Form Wizard/Stepper
• Built-in Pickers
• Doctrine Integration
• Laravel Integration

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for contribution:

• Additional field types
• More translation loaders
• Framework integrations
• Theme development
• Documentation improvements

📝 Version History

• v3.0.0 (2025) - i18n & Auto CSRF - Current ⭐
• v2.9.0 (2025) - Advanced Error Handling & Bubbling
• v2.8.0 (2025) - Dynamic Form Modification
• v2.7.0 (2024) - Cross-Field Validation & Groups
• v2.5.0 (2024) - Type System & Extensions
• v2.4.0 (2024) - Nested Forms & Collections
• v2.3.1 (2024) - Data Transformation
• v2.3.0 (2024) - Event-Driven Dependencies
• v2.1.0 (2024) - Laravel-Style Validation
• v2.0.0 (2024) - Complete rewrite with chain pattern

See CHANGELOG.md for details.

📄 License

MIT License - see LICENSE for details.

👨‍💻 Author

selcukmart

• Email: admin@hostingdevi.com
• GitHub: @selcukmart

🌟 Star History

If this project helped you, please give it a ⭐ on GitHub!

Made with ❤️ using modern PHP 8.1+

Production-ready • Secure by Default • Internationalized • Framework-agnostic