README

English | 中文

A comprehensive lottery system bundle for Symfony applications featuring multiple lottery types, advanced prize pool management, chance control, and automated prize distribution.

Features
Installation
- Requirements
- Install via Composer
Quick Start
Console Commands
JSON-RPC API
System Architecture
Event System
Advanced Usage
Contributing
License

Features

Multiple Lottery Types - Support for wheel, grid, slot machine, and on-site lotteries
Advanced Prize Pool Management - Multi-pool system with configurable probabilities and constraints
Intelligent Chance Management - User chances with expiration tracking and status control
Automated Prize Distribution - Automatic prize sending with consignee management
Admin Interface - Complete EasyAdmin integration for lottery management
Responsive H5 Frontend - Mobile-optimized lottery interface with multiple themes
Event-Driven Architecture - Customizable event system for business logic extension
JSON-RPC API - RESTful API endpoints for external system integration
Cron Job Integration - Automated background tasks for maintenance and processing
Expression Language - Flexible configuration with dynamic rule evaluation
Concurrent Safety - Database-level locking for high-concurrency scenarios

Installation

Requirements

PHP 8.1 or higher
Symfony 7.3 or higher
Doctrine ORM 3.0 or higher
MySQL 5.7+ or PostgreSQL 10+
Redis (recommended for caching)

Install via Composer

composer require tourze/lottery-bundle

Quick Start

<?php

use LotteryBundle\Service\LotteryService;
use LotteryBundle\Service\PrizeService;
use LotteryBundle\Entity\Chance;

// Execute lottery draw
$lotteryService = $container->get(LotteryService::class);
$result = $lotteryService->doLottery($chance);

// Count valid chances for user
$validChances = $lotteryService->countValidChance($user, $activity);

// Award chances to user
$lotteryService->giveChance($user, $chance);

// Prize management
$prizeService = $container->get(PrizeService::class);
$prizeService->sendPrize($chance);

// Check if activity is currently active
$isActive = $activity->isActive();

// Get available lottery templates
$templates = $lotteryService->getAvailableTemplates();

Bundle Registration

Add to config/bundles.php:

LotteryBundle\LotteryBundle::class => ['all' => true],

Database Setup

# Create database tables
php bin/console doctrine:migrations:migrate

# Load sample data (optional)
php bin/console doctrine:fixtures:load --group=lottery

Configuration

The bundle provides flexible configuration through:

Activity Settings - Configure lottery activities with time constraints and participation rules
Prize Pool Management - Set up multiple pools with different probability algorithms
Prize Configuration - Define virtual rewards, physical prizes, and distribution methods
Chance Control - Monitor user participation limits and success tracking

Console Commands

lottery:check-expire-chance

Checks and processes expired lottery chances. This command runs every minute via cron job.

php bin/console lottery:check-expire-chance

Purpose: Automatically marks expired chances as invalid and triggers expire events for cleanup.

lottery:check-review-chance-send-prize

Processes reviewed chances and sends prizes to winners. This command runs every hour at 43 minutes.

php bin/console lottery:check-review-chance-send-prize

Purpose: Automatically sends prizes to users whose chances have been reviewed and approved.

JSON-RPC API

The bundle exposes JSON-RPC procedures for external integrations:

Lottery Operations

JoinLottery - Execute lottery participation with concurrent safety
GetAllLotteryChance - Retrieve comprehensive lottery chance data
GetLotteryDetail - Get detailed activity information and rules
ServerSendLotteryChance - Administrative chance distribution

User Management

GetUserLotteryChanceList - User's participation history with pagination
GetUserValidLotteryChanceCounts - Real-time valid chance counts
GetLotteryConsignee - User delivery address information
SaveOrUpdateLotteryConsignee - Manage shipping addresses

Prize Information

GetLotteryPrizeList - Available prizes with stock information

System Architecture

The lottery system implements a robust workflow with concurrent safety:

Activity Validation - Verify lottery timing, status, and participation eligibility
Chance Authentication - Validate user's available chances with database locking
Chance Pre-deduction - Atomically reserve chances to prevent overselling
Pool Selection - Dynamic pool determination based on configurable rules
Prize Algorithm - Probability-based prize selection with stock management
Result Confirmation - Transactional commit with event dispatching
Prize Distribution - Automated or manual prize fulfillment process

Event System

Extensive event system for business logic customization:

Core Events

UserJoinSuccessEvent - Dispatched after successful lottery participation
AfterChanceExpireEvent - Triggered when user chances expire
ChanceEvent - General chance lifecycle event

Customization Events

DecidePoolEvent - Override default pool selection algorithm
DecidePrizeProbabilityEvent - Implement custom probability calculations
AllLotteryChanceEvent - Global event for all chance operations

Advanced Usage

Custom Event Subscribers

Extend lottery functionality with event subscribers:

use LotteryBundle\Event\UserJoinSuccessEvent;
use LotteryBundle\Event\DecidePoolEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CustomLotterySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UserJoinSuccessEvent::class => 'onUserJoinSuccess',
            DecidePoolEvent::class => 'onDecidePool',
        ];
    }

    public function onUserJoinSuccess(UserJoinSuccessEvent $event): void
    {
        // Send notification, award points, etc.
        $chance = $event->getChance();
        $this->notificationService->sendLotteryResult($chance);
    }

    public function onDecidePool(DecidePoolEvent $event): void
    {
        // Custom pool selection based on user VIP level
        $user = $event->getUser();
        if ($user->isVip()) {
            $event->setPool($this->getVipPool());
        }
    }
}

Expression Language

Implement complex business rules with expression language:

# config/packages/lottery.yaml
lottery:
    pools:
        vip_pool:
            # Only VIP users with 5+ chances
            expression: 'user.isVip() and chance.count() > 5'
        weekend_pool:
            # Special weekend prizes
            expression: 'date("N") >= 6'
        high_value_pool:
            # High-value prizes for frequent players
            expression: 'user.getLotteryCount() > 100'

External Integration

Integrate with external systems via JSON-RPC:

// Join lottery from external application
$result = $client->call('JoinLottery', [
    'activityId' => 1,
    'count' => 3, // Draw 3 times
]);

// Get user's lottery history
$history = $client->call('GetUserLotteryChanceList', [
    'page' => 1,
    'limit' => 20,
]);

// Check available chances
$chances = $client->call('GetUserValidLotteryChanceCounts', [
    'activityId' => 1,
]);

Contributing

Please see CONTRIBUTING.md for details.

License

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

tourze / lottery-bundle

Maintainers

Details