README

English | 中文

A powerful Symfony bundle for generating WeChat Mini Program QR codes and share links with advanced features including custom logos, colors, transparent backgrounds, and comprehensive JSON-RPC API integration.

Table of Contents

• Features
• Installation
• Dependencies
• Security
• Quick Start
  • Basic Usage
  • JSON-RPC API
  • Console Command
• Command Parameters
• Configuration
  • Environment Variables
  • Services Configuration
• Advanced Usage
  • Custom Logo Overlay
  • Color Customization
  • Transparent Background
  • Batch Processing
• API Reference
  • CodeUnLimitRequest
  • GetUserShareCode
• Contributing
• License

Features

• 🔗 Generate unlimited WeChat Mini Program QR codes
• 🎨 Custom colors and transparent backgrounds
• 🖼️ Logo overlay support (including user avatars)
• 🚀 JSON-RPC API integration
• 💾 Share code management with database persistence
• 🔒 User authentication and security
• 🛠️ Console command for batch generation
• 📊 Multiple environment support (release, trial, develop)

Installation

composer require tourze/wechat-mini-program-qrcode-link-bundle

Dependencies

This bundle requires:

• PHP 8.1 or higher
• Symfony 6.4 or higher
• WeChat Mini Program Bundle
• Doctrine ORM
• Flysystem
• Intervention Image v3

Security

This bundle implements several security measures:

• User authentication required for JSON-RPC procedures
• Input validation for all parameters
• Safe image processing with size limits
• URL validation for logo sources

Quick Start

Basic Usage

<?php

use WechatMiniProgramQrcodeLinkBundle\Request\CodeUnLimitRequest;
use WechatMiniProgramBundle\Service\Client;

// Create unlimited QR code request
$request = new CodeUnLimitRequest();
$request->setAccount($account);
$request->setScene('user-123');
$request->setPage('pages/product/detail');
$request->setCheckPath(false);
$request->setEnvVersion('release');
$request->setWidth(750);

// Generate QR code
$png = $client->request($request);
file_put_contents('qrcode.png', $png);

JSON-RPC API

// Get user share code with custom logo
{
  "method": "GetUserShareCode",
  "params": {
    "appId": "wx1234567890abcdef",
    "link": "pages/share/index",
    "size": 200,
    "envVersion": "release",
    "hyaline": true,
    "lineColor": {"r": 255, "g": 0, "b": 0},
    "logoUrl": "https://example.com/logo.png"
  }
}

Console Command

Generate QR codes via command line:

# Generate unlimited QR code
php bin/console wechat-mini-program:generate-unlimited-code \
  --account-id=1 \
  --path="pages/product/detail" \
  --scene="product-123" \
  --env="release" \
  --width=750 \
  --output="qrcode.png"

Command Parameters

• accountId (required): WeChat Mini Program account ID
• path (required): Target page path (e.g., "pages/index/index")
• scene (required): Scene value (max 32 characters)
• env (optional): Environment version (release|trial|develop, default: release)
• width (optional): QR code width in pixels (default: 750)
• output (optional): Output file path

Configuration

Environment Variables

# Default index page
WECHAT_MINI_PROGRAM_INDEX_PAGE=/pages/index/index

# Share redirect path
WECHAT_MINI_PROGRAM_SHARE_REDIRECT_PATH=pages/share/index

Services Configuration

Register in your services.yaml:

services:
  WechatMiniProgramQrcodeLinkBundle\Command\GenerateUnlimitedCodeCommand:
    arguments:
      $accountRepository: '@WechatMiniProgramBundle\Repository\AccountRepository'
      $client: '@WechatMiniProgramBundle\Service\Client'
    tags:
      - { name: console.command }

Advanced Usage

Custom Logo Overlay

// Using direct URL
$procedure = new GetUserShareCode();
$procedure->logoUrl = 'https://example.com/logo.png';

// Using user avatar
$procedure->logoUrl = 'user-avatar';

Avatar Download Domains (Mini Program)

⚠️ When you fetch a head image inside a Mini Program (for example to upload it to your backend before calling this bundle), wx.downloadFile only works for hosts that exist in your allowlist. Missing entries are the reason why https://thirdwx.qlogo.cn/... often fails.

1. Go to WeChat Mini Program Console → Development → Development management → Development settings → downloadFile legal domain and add every WeChat avatar CDN host you rely on (wildcards are not accepted).
2. Normalize any http:// avatar URL to https:// before using it: const safeAvatar = avatarUrl.replace(/^http:\/\//, 'https://');.
3. If you are out of allowlist slots, proxy avatars through one of your own domains and whitelist that proxy once.

Known WeChat avatar domains you should keep in sync with the allowlist:

Keep this list updated whenever WeChat announces new CDN domains so that poster generation using logoUrl=user-avatar never breaks in production.

Color Customization

// RGB color array
$request->setLineColor(['r' => 255, 'g' => 0, 'b' => 0]);

// Color string
$request->setLineColor('#FF0000');

Transparent Background

$request->setHyaline(true);

Batch Processing

// Process multiple QR codes
$codes = [];
foreach ($products as $product) {
    $request = new CodeUnLimitRequest();
    $request->setScene("product-{$product->getId()}");
    $codes[] = $client->request($request);
}

API Reference

CodeUnLimitRequest

Main request class for generating unlimited QR codes.

Properties

• scene: Scene value (max 32 characters)
• page: Target page path
• checkPath: Validate page existence
• envVersion: Environment (release|trial|develop)
• width: QR code width (280-1280px)
• autoColor: Auto color configuration
• hyaline: Transparent background
• lineColor: Custom line color

GetUserShareCode

JSON-RPC procedure for generating user share codes with logo support.

Parameters

• appId: WeChat Mini Program App ID
• link: Target page link
• size: QR code size (default: 200)
• envVersion: Environment version
• hyaline: Transparent background
• lineColor: Custom line color
• logoUrl: Logo overlay URL

Contributing

Please see CONTRIBUTING.md for details.

License

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