README

English | 中文

A Symfony Bundle that provides Doctrine entity checking and processing capabilities. Through custom checkers, you can automatically handle specific logic before entity persistence.

Features
Installation
Requirements
Quick Start
Configuration
Advanced Usage
API Reference
Testing
Contributing
License

Features

Automatic entity processing before persistence
Support for custom ID generators with #[ORM\CustomIdGenerator] attribute
Entity primary key management utilities
SQL formatting and generation tools
Lazy-loaded services for optimal performance
Support for composite primary keys

Installation

Install via Composer:

composer require tourze/doctrine-entity-checker-bundle

Requirements

PHP 8.1 or higher
Symfony 6.4 or higher
Doctrine ORM 3.0 or higher

Quick Start

// config/bundles.php
return [
    // ...
    Tourze\DoctrineEntityCheckerBundle\DoctrineEntityCheckerBundle::class => ['all' => true],
];

Create a custom entity checker

<?php

namespace App\Doctrine\Checker;

use Doctrine\ORM\Event\PreUpdateEventArgs;
use Doctrine\Persistence\ObjectManager;
use Tourze\DoctrineEntityCheckerBundle\Checker\EntityCheckerInterface;

class TimestampEntityChecker implements EntityCheckerInterface
{
    public function prePersistEntity(ObjectManager $objectManager, object $entity): void
    {
        if (property_exists($entity, 'createTime') && $entity->createTime === null) {
            $entity->createTime = new \DateTimeImmutable();
        }
    }

    public function preUpdateEntity(ObjectManager $objectManager, object $entity, PreUpdateEventArgs $eventArgs): void
    {
        if (property_exists($entity, 'updatedAt')) {
            $entity->updatedAt = new \DateTimeImmutable();
        }
    }
}

The checker will be automatically registered due to the #[AutoconfigureTag] attribute.

Configuration

The bundle works out of the box with minimal configuration. All services are automatically configured with lazy loading for optimal performance.

Service Configuration

All services in this bundle are configured as lazy-loaded by default:

EntityChecker - Main entity processing service
EntityPrimaryKeyService - Primary key utilities
SqlFormatter - SQL generation utilities

These services are automatically injected when needed and support dependency injection.

Custom Configuration

If you need to customize service behavior, you can override services in your config/services.yaml:

services:
    # Override the main entity checker if needed
    Tourze\DoctrineEntityCheckerBundle\Service\EntityChecker:
        # Your custom configuration

Advanced Usage

Custom ID Generator

Use the #[ORM\CustomIdGenerator] attribute to specify custom ID generators:

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use App\Generator\SnowflakeIdGenerator;

#[ORM\Entity]
class MyEntity
{
    #[ORM\Id]
    #[ORM\CustomIdGenerator(class: SnowflakeIdGenerator::class)]
    #[ORM\Column(type: 'bigint')]
    private ?int $id = null;

    // ... other properties
}

Primary Key Service

Get primary key information from entities:

<?php

use Tourze\DoctrineEntityCheckerBundle\Service\EntityPrimaryKeyService;

class MyService
{
    public function __construct(
        private EntityPrimaryKeyService $primaryKeyService
    ) {}

    public function analyzeEntity(object $entity): void
    {
        // Get primary key values
        $pkValues = $this->primaryKeyService->getPrimaryKeyValues($entity);
        
        // Check if entity has composite primary key
        $hasComposite = $this->primaryKeyService->hasCompositeIdentifier($entity);
        
        // Get primary key field names
        $fieldNames = $this->primaryKeyService->getIdentifierFieldNames($entity);
    }
}

SQL Formatting

Generate SQL from entities:

<?php

use Tourze\DoctrineEntityCheckerBundle\Service\SqlFormatter;

class MyService
{
    public function __construct(
        private SqlFormatter $sqlFormatter
    ) {}

    public function generateInsertSql(object $entity): array
    {
        // Returns [tableName, parameters]
        [$tableName, $params] = $this->sqlFormatter->getObjectInsertSql(
            $this->entityManager, 
            $entity
        );
        
        // Build INSERT SQL
        $fields = implode(', ', array_keys($params));
        $placeholders = ':' . implode(', :', array_keys($params));
        $sql = "INSERT INTO {$tableName} ({$fields}) VALUES ({$placeholders})";
        
        return [$sql, $params];
    }
}

API Reference

EntityCheckerInterface

prePersistEntity(ObjectManager $objectManager, object $entity): void - Called before entity persistence
preUpdateEntity(ObjectManager $objectManager, object $entity, PreUpdateEventArgs $eventArgs): void
- Called before entity update

EntityPrimaryKeyService

getPrimaryKeyValues(object $entity): array - Get primary key values
hasCompositeIdentifier(string|object $entityClass): bool - Check for composite primary key
getIdentifierFieldNames(string|object $entityClass): array - Get primary key field names

SqlFormatter

getObjectInsertSql(ObjectManager $objectManager, object $object): array - Generate insert SQL data
fromOrmQuery(OrmQuery $query): string - Format DQL with parameters

Testing

Run tests:

# From project root
./vendor/bin/phpunit packages/doctrine-entity-checker-bundle/tests

Run PHPStan analysis:

php -d memory_limit=2G ./vendor/bin/phpstan analyse packages/doctrine-entity-checker-bundle

Contributing

Please see CONTRIBUTING.md for details.

License

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

tourze / doctrine-entity-checker-bundle

Maintainers

Details