README

中文 | English

A Symfony bundle for WeChat Official Account QR code generation, management, and tracking.

Features
Installation
Dependencies
Quick Start
Configuration
Entities
QR Code Types
API Examples
- Create QR Code Request
- Manage QR Code Jump Rules
Advanced Usage
Events
Testing
License

Features

Generate WeChat Official Account QR codes (temporary and permanent)
Track QR code scan logs
Manage QR code jump rules between WeChat Official Account and Mini Program
Support for both scene ID and scene string parameters
Real-time scan event handling

Installation

composer require tourze/wechat-official-account-qrcode-bundle

Dependencies

This bundle requires the following dependencies:

PHP: ^8.1
Symfony: ^6.4
Doctrine ORM: ^3.0
tourze/wechat-official-account-bundle: Core WeChat Official Account integration
tourze/doctrine-indexed-bundle: Database indexing support
tourze/doctrine-timestamp-bundle: Entity timestamp management
tourze/doctrine-snowflake-bundle: Snowflake ID generation

Quick Start

1. Register the Bundle

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

2. Create QR Code

use WechatOfficialAccountQrcodeBundle\Entity\QrcodeTicket;
use WechatOfficialAccountQrcodeBundle\Enum\QrcodeActionName;

// Create a temporary QR code with scene ID
$qrcode = new QrcodeTicket();
$qrcode->setActionName(QrcodeActionName::QR_SCENE);
$qrcode->setSceneId(123);
$qrcode->setExpireTime(new \DateTimeImmutable('+1 hour'));

// Create a permanent QR code with scene string
$qrcode = new QrcodeTicket();
$qrcode->setActionName(QrcodeActionName::QR_LIMIT_STR_SCENE);
$qrcode->setSceneStr('user_invitation');

3. Handle QR Code Scan Events

use WechatOfficialAccountQrcodeBundle\EventSubscriber\TicketMessageSubscriber;

// The bundle automatically handles scan events and creates scan logs
// You can subscribe to these events in your application

Configuration

The bundle requires the following dependencies:

tourze/doctrine-indexed-bundle - For database indexing
tourze/wechat-official-account-bundle - For WeChat Official Account integration

Entities

QrcodeTicket

Main entity for QR code tickets
Supports temporary and permanent QR codes
Tracks expiration time, scene parameters, and ticket information

ScanLog

Records QR code scan events
Links to the QR code ticket and user information
Immutable entity for audit trail

QrcodeJump

Manages QR code jump rules
Enables jumping from WeChat Official Account to Mini Program
Supports rule publishing and editing

QR Code Types

QR_SCENE - Temporary QR code with integer scene ID
QR_STR_SCENE - Temporary QR code with string scene parameter
QR_LIMIT_SCENE - Permanent QR code with integer scene ID
QR_LIMIT_STR_SCENE - Permanent QR code with string scene parameter

API Examples

Create QR Code Request

use WechatOfficialAccountQrcodeBundle\Request\CreateQrcodeRequest;

$request = new CreateQrcodeRequest();
$request->setActionName(QrcodeActionName::QR_SCENE);
$request->setSceneId(123);
$request->setExpireSeconds(3600);

Manage QR Code Jump Rules

use WechatOfficialAccountQrcodeBundle\Request\QrcodeJumpAddRequest;

$request = new QrcodeJumpAddRequest();
$request->setPrefix('http://weixin.qq.com/q/xxx');
$request->setAppid('your_mini_program_appid');
$request->setPath('pages/index/index');

Advanced Usage

Custom Event Handling

You can create custom event subscribers to handle QR code scan events:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use WechatOfficialAccountServerMessageBundle\Event\MessageEvent;

class CustomQrcodeEventSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            MessageEvent::class => 'handleScanEvent',
        ];
    }

    public function handleScanEvent(MessageEvent $event): void
    {
        $message = $event->getMessage();
        if ($message->getMsgType() === 'event' && $message->getEvent() === 'SCAN') {
            // Handle custom scan logic
            $sceneId = $message->getEventKey();
            // Your custom logic here
        }
    }
}

Database Migrations

Create the required database tables:

php bin/console doctrine:migrations:migrate

Performance Optimization

For high-traffic applications, consider:

Database Indexing: The bundle automatically creates indexes for scan logs
Caching: Cache frequently accessed QR code data
Async Processing: Handle scan events asynchronously using Symfony Messenger

// config/packages/messenger.yaml
framework:
    messenger:
        transports:
            qrcode_scan: '%env(MESSENGER_TRANSPORT_DSN)%'
        routing:
            'WechatOfficialAccountQrcodeBundle\Message\*': qrcode_scan

Events

The bundle provides event subscribers for:

QR code scan event handling
Jump rule management
Automatic scan log creation

Testing

Run the test suite:

./vendor/bin/phpunit packages/wechat-official-account-qrcode-bundle/tests

Test Coverage

All 84 tests pass successfully with 258 assertions.

Note: Repository tests are currently implemented as unit tests instead of integration tests due to a known dependency resolution issue with UserInterface in the test environment. See Issue #814 for tracking progress on this issue.

Contributing

We welcome contributions! Please follow these guidelines:

Report Issues: Use the GitHub issue tracker to report bugs or request features
Submit Pull Requests: Fork the repository and submit pull requests with your changes
Code Style: Follow PSR-12 coding standards and existing code patterns
Testing: Ensure all tests pass and add tests for new functionality
Documentation: Update documentation for any new features or changes

Development Setup

Clone the repository
Install dependencies: composer install
Run tests: ./vendor/bin/phpunit packages/wechat-official-account-qrcode-bundle/tests
Run static analysis: ./vendor/bin/phpstan analyse packages/wechat-official-account-qrcode-bundle

Changelog

[Unreleased]

Initial release
QR code generation and management
Scan event tracking
Jump rule management
Comprehensive test coverage

License

MIT License. See LICENSE for details.

tourze / wechat-official-account-qrcode-bundle

Maintainers

Details