README

English | 中文

A Symfony bundle that provides automatic random string generation for Doctrine entity properties and random database query functionality with PHP attributes.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• RandomService Usage
• Advanced Usage
• Advanced Details
• Security
• Contribution Guide
• License
• Changelog
• Author

Features

• Random String Generation: Generate random string values for entity properties using PHP attributes
• Random Database Queries: Service to fetch random records from database with caching and locking support
• Configurable: Customizable prefix and string length for random strings
• Automatic Generation: Triggers on entity creation (Doctrine prePersist event)
• Non-Destructive: Skips generation if property already has a value
• Performance Optimized: Uses caching and distributed locking to prevent conflicts
• Symfony Integration: Simple integration with Symfony auto-configuration

Requirements

• PHP 8.1 or higher
• Symfony 6.4 or higher
• Doctrine Bundle 2.13 or higher
• Doctrine ORM 2.20/3.0 or higher

Installation

composer require tourze/doctrine-random-bundle

This bundle is auto-registered by Symfony Flex. No extra configuration is required.

Quick Start

Add the RandomStringColumn attribute to your entity property:

use Tourze\DoctrineRandomBundle\Attribute\RandomStringColumn;

class YourEntity
{
    #[RandomStringColumn(prefix: 'user_', length: 20)]
    private string $randomId;

    public function getRandomId(): string
    {
        return $this->randomId;
    }

    public function setRandomId(string $randomId): self
    {
        $this->randomId = $randomId;
        return $this;
    }
}

When you persist a new entity, the randomId property will be automatically filled if it is empty:

$entity = new YourEntity();
$entityManager->persist($entity);
$entityManager->flush();
// $entity->getRandomId() will return something like 'user_a1b2c3d4e5f6g7h8i9'

Configuration

The RandomStringColumn attribute accepts the following parameters:

• prefix: String prefix for the random value (default: '')
• length: Length of the random string (default: 16)

RandomService Usage

The bundle also provides a RandomService for fetching random records from the database with caching and locking support:

use Tourze\DoctrineRandomBundle\Service\RandomService;

// Inject the service
public function __construct(
    private readonly RandomService $randomService,
    private readonly EntityManagerInterface $entityManager,
) {}

// Get random records
$queryBuilder = $this->entityManager->createQueryBuilder()
    ->select('u')
    ->from(User::class, 'u')
    ->where('u.active = :active')
    ->setParameter('active', true);

// Get 3 random users
$randomUsers = $this->randomService->getRandomResult($queryBuilder, 3);

foreach ($randomUsers as $user) {
    // Process each random user
}

RandomService Features

• Distributed Locking: Prevents multiple processes from getting the same random record
• Caching: Caches ID lists for better performance (1-minute TTL)
• Flexible Querying: Works with any QueryBuilder with WHERE conditions
• Configurable Range: Limits the cached ID range to optimize memory usage

Advanced Usage

Custom Random String Generation

You can use multiple RandomStringColumn attributes on different properties:

class Product
{
    #[RandomStringColumn(prefix: 'SKU-', length: 12)]
    private string $sku;

    #[RandomStringColumn(length: 8)]
    private string $code;

    #[RandomStringColumn(prefix: 'REF_', length: 16)]
    private string $reference;
}

Advanced RandomService Usage

The RandomService supports complex queries and offers fine-grained control:

// Get random products with specific conditions
$queryBuilder = $this->entityManager->createQueryBuilder()
    ->select('p')
    ->from(Product::class, 'p')
    ->join('p.category', 'c')
    ->where('p.active = :active')
    ->andWhere('c.featured = :featured')
    ->andWhere('p.stock > :minStock')
    ->setParameter('active', true)
    ->setParameter('featured', true)
    ->setParameter('minStock', 0);

$randomProducts = $this->randomService->getRandomResult($queryBuilder, 5);

Advanced Details

• The bundle uses a Doctrine event listener (RandomStringListener) to automatically generate random strings for properties marked with the RandomStringColumn attribute during the prePersist event.
• If the property already has a value, it will not be overwritten.
• The random string is composed of numbers and upper/lowercase letters.
• The RandomService uses Symfony's Lock component and Cache component for performance optimization.

Security

• Random strings are generated using PHP's random_int() function for cryptographic security
• The bundle respects existing property values and never overwrites them
• Distributed locking prevents race conditions in concurrent environments

Contribution Guide

Contributions are welcome! To contribute:

• Open an issue for bug reports or feature requests.
• Submit a pull request with clear description and relevant tests.
• Follow PSR coding standards.
• Run tests with PHPUnit before submitting.

License

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

Changelog

• v0.1.0: Initial release with random string attribute and random query service support.

Author

Maintained by tourze.