README

English | 中文

A comprehensive dynamic form builder system for Symfony applications, designed for creating surveys, questionnaires, and custom forms with advanced features.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Field Types
• Advanced Usage
• API Documentation
• Dependencies
• Testing
• Contributing
• Security
• License

Features

• Dynamic Form Creation: Create forms with various field types including text, select, radio, checkbox, date, file uploads, and more
• Mobile Captcha Support: Built-in mobile phone verification with SMS captcha
• Rich Field Types: Support for 13 different field types including rich text, images, and files
• Form Analytics: Track form submissions and analyze responses
• EasyAdmin Integration: Administrative interface for managing forms and responses
• Session Management: Step-by-step form completion with session tracking
• Expression Language: Advanced form logic with conditional fields
• JSON-RPC API: Complete API for form management and submission
• Multi-language Support: Full internationalization support

Installation

Install the package via Composer:

composer require tourze/diy-form-bundle

Quick Start

1. Enable the Bundle

Add the bundle to your config/bundles.php:

<?php

return [
    // ... other bundles
    DiyFormBundle\DiyFormBundle::class => ['all' => true],
];

2. Configure Database

Run the migrations to create the required tables:

php bin/console doctrine:migrations:migrate

3. Basic Usage

Create a simple form programmatically:

<?php

use DiyFormBundle\Entity\Form;
use DiyFormBundle\Entity\Field;
use DiyFormBundle\Enum\FieldType;

// Create a new form
$form = new Form();
$form->setTitle('Customer Survey');
$form->setDescription('Please help us improve our service');

// Add fields
$field = new Field();
$field->setTitle('Your Name');
$field->setType(FieldType::STRING);
$field->setRequired(true);
$form->addField($field);

// Save form
$entityManager->persist($form);
$entityManager->flush();

4. JSON-RPC API Usage

// Get form details
$result = $jsonRpcClient->call('GetDiyFormDetail', [
    'formId' => '1'
]);

// Submit form data
$result = $jsonRpcClient->call('SubmitDiyFormFullRecord', [
    'formId' => '1',
    'data' => [
        'field1' => 'value1',
        'field2' => 'value2'
    ]
]);

Configuration

Services Configuration

The bundle provides several services that can be configured:

# config/services.yaml
services:
    DiyFormBundle\Service\SmsService:
        arguments:
            $smsProvider: '@your_sms_provider'
    
    DiyFormBundle\Service\ExpressionService:
        arguments:
            $expressionLanguage: '@expression_language'

Routing Configuration

# config/routes.yaml
diy_form:
    resource: '@DiyFormBundle/Resources/config/routes.yaml'
    prefix: /api/diy-form

Field Types

The bundle supports the following field types:

• Text Fields: STRING, TEXT, RICH_TEXT
• Selection Fields: SINGLE_SELECT, RADIO_SELECT, MULTIPLE_SELECT, CHECKBOX_SELECT
• Date Fields: DATE, DATE_TIME
• Numeric Fields: INTEGER, DECIMAL
• File Fields: SINGLE_IMAGE, MULTIPLE_IMAGE, SINGLE_FILE
• Special Fields: CAPTCHA_MOBILE_PHONE

Advanced Usage

Form Logic and Conditional Fields

Use expression language to create dynamic forms:

$field->setShowExpression('answer_item("previous_field") == "yes"');

Analytics and Reporting

Track form submissions and generate reports:

use DiyFormBundle\Service\TagCalculator;

$calculator = new TagCalculator();
$analytics = $calculator->calculateTags($form, $records);

Custom Field Types

Extend the field types by implementing custom handlers:

use DiyFormBundle\Event\FieldFormatEvent;

class CustomFieldHandler
{
    public function onFieldFormat(FieldFormatEvent $event): void
    {
        // Custom field formatting logic
    }
}

API Documentation

Form Management

• GetDiyFormDetail - Get form configuration
• GetFullDiyFormDetail - Get complete form with all fields

Record Management

• CreateDiyFormRecord - Start a new form session
• SubmitDiyFormFullRecord - Submit complete form data
• GetDiyFormRecordDetail - Get submission details

Step-by-Step Forms

• GetNextDiyFormField - Get next field in sequence
• AnswerSingleDiyFormQuestion - Answer individual questions

Dependencies

Core Requirements

• PHP: ^8.1
• Symfony: ^6.4
• Doctrine ORM: ^3.0
• EasyAdmin Bundle: ^4.0

Key Features Dependencies

• Expression Language: For conditional field logic
• Notifier Component: For SMS captcha functionality
• Serializer Component: For API data transformation
• Security Bundle: For user authentication and authorization

Optional Integrations

• JSON-RPC Bundle: For API endpoints (tourze/json-rpc-*)
• Doctrine Extensions: For advanced entity features (tourze/doctrine-*)
• File Storage: For file upload handling

Testing

Running Unit Tests

The bundle includes comprehensive unit tests covering all business logic:

vendor/bin/phpunit packages/diy-form-bundle/tests

Test Coverage:

• ✅ 187 Unit Tests: All unit tests pass, covering entities, enums, events, and core business logic
• ⚠️ 23 Integration Tests: Currently under development due to complex dependency setup (see Issue #811)

Test Categories

• Entity Tests: Data models and relationships
• Enum Tests: Field types and validation
• Event Tests: Form submission events
• Service Tests: Business logic services
• Controller Tests: API endpoints (integration tests)

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email security@tourze.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Design References

This bundle was inspired by various form systems:

• Wenjuanxing (问卷星)
• Tencent Questionnaire
• SurveyMonkey
• Mikecrm