README

DDMBundle (Data Definition Model) is a Symfony bundle for the VIS ecosystem that simplifies the definition and handling of data models for datatables and forms. It provides a structured way to centrally define fields, validations, and rendering logic.

🚀 Features

Centralized Data Definition via DDM and DDMField
Automated Datatable Engine for server-side processing (sorting, searching, pagination)
Advanced Search Functionality via DDMDatatableSearchHandler
Flexible Form Handler for AJAX-based form processing and validation
Attribute-based Field Configuration for easy integration into entities
Extensive Validation (Required, String, Unique, Email, etc.)
Twig Integration for easy rendering of forms and tables
Seamless Integration into the VIS ecosystem

⚙️ Requirements

PHP 8.2 or higher
Symfony Framework 7.4 or higher
Doctrine ORM

📦 Installation

Use Composer to install the bundle:

composer require jbsnewmedia/ddm-bundle

🛠 Setup & Configuration

1. Define Fields

Fields are defined as services and can be configured with the #[DDMFieldAttribute] attribute to associate them with specific entities or contexts. In the __construct method or via initialization, field properties such as identifier, name, and behavior can be set.

use JBSNewMedia\DDMBundle\Attribute\DDMFieldAttribute;
use JBSNewMedia\DDMBundle\Service\DDMField;

#[DDMFieldAttribute(entity: 'User', order: 10)]
class UserNameField extends DDMField
{
    public function __construct()
    {
        $this->setIdentifier('username');
        $this->setName('Username');
        $this->setSortable(true);
        $this->setLivesearch(true);
    }
}

2. Create DDM Instance

Use the DDMFactory to create a DDM instance for an entity and a context:

use JBSNewMedia\DDMBundle\Service\DDMFactory;

public function index(DDMFactory $ddmFactory)
{
    $ddm = $ddmFactory->create(User::class, 'admin_list');
    // ...
}

📋 Usage Examples

Using Datatable in a Controller

The DDMDatatableEngine handles all the logic for providing the data:

use JBSNewMedia\DDMBundle\Service\DDMDatatableEngine;
use JBSNewMedia\DDMBundle\Service\DDMFactory;
use Symfony\Component\HttpFoundation\Request;

public function list(Request $request, DDMFactory $ddmFactory, DDMDatatableEngine $engine)
{
    $ddm = $ddmFactory->create(User::class, 'list');
    
    if ($request->isXmlHttpRequest()) {
        return $engine->handleRequest($request, $ddm);
    }
    
    return $this->render('user/list.html.twig', [
        'ddm' => $ddm
    ]);
}

Processing a Form

The DDMDatatableFormHandler automates loading, validating, and saving entities. It returns either a rendered form or a JSON response.

use JBSNewMedia\DDMBundle\Service\DDMDatatableFormHandler;
use Symfony\Component\HttpFoundation\Response;

public function edit(Request $request, User $user, DDMDatatableFormHandler $formHandler)
{
    $ddm = $this->ddmFactory->create(User::class, 'edit');
    
    $response = $formHandler->handle($request, $ddm, $user);
    
    return $response;
}

🎨 Template Integration

Datatable Rendering

<div id="user-datatable" 
     data-avalynx-datatable-url="{{ path('user_list_ajax') }}"
     data-avalynx-datatable-config="{{ ddm.datatableConfig|json_encode }}">
    <!-- The engine provides data suitable for AvalynX Datatable -->
</div>

📁 Architecture Overview

Core Components

src/
├── Attribute/           # PHP Attributes for field configuration
├── Contract/            # Interfaces for fields, validators and values
├── DependencyInjection/ # Bundle configuration & extension
├── Doctrine/            # Doctrine-specific extensions (e.g. CAST function)
├── Service/
│   ├── DDM.php              # Central model of a data definition
│   ├── DDMFactory.php       # Factory for creating DDM instances
│   ├── DDMField.php         # Base class for all fields
│   ├── DDMDatatableEngine.php # Engine for datatable requests
│   ├── DDMDatatableFormHandler.php # Handler for form logic
│   └── DDMDatatableSearchHandler.php # Handler for datatable search
├── Trait/               # Shared functionalities (e.g. entity access)
├── Validator/           # Validators (Required, String, Unique, Email, etc.)
├── Value/               # Value objects (String, Array, etc.)
└── DDMBundle.php        # Bundle class

🧪 Developer Tools

The following commands are available for development:

# Tool installation
composer bin-ecs-install
composer bin-phpstan-install
composer bin-phpunit-install
composer bin-rector-install

# Code quality checks
composer bin-ecs           # PHP-CS-Fixer check
composer bin-phpstan       # Static analysis
composer bin-rector        # Code transformation (dry-run)
composer test              # PHPUnit tests

# Automatic fixes
composer bin-ecs-fix       # Fix coding standards
composer bin-rector-process # Apply code transformation

# CI Pipelines
composer ci                # Execute all checks

📜 License

This bundle is licensed under the MIT License. See the LICENSE file for more details.

Developed by Jürgen Schwind and other contributors.

🤝 Contributing

Contributions are welcome! If you would like to contribute, please create a pull request or open an issue.

📫 Contact

If you have questions or problems, please open an issue in our GitHub repository.

Data Definition Model. Modular. Efficient. VIS-Ready.

jbsnewmedia / ddm-bundle

Maintainers

Details