tourze/wechat-official-account-oauth2-bundle

微信公众号OAuth2授权

0.0.1 2025-11-11 13:24 UTC

Requires

• ext-json: *
• doctrine/collections: ^2.3
• doctrine/data-fixtures: ^2.0
• doctrine/dbal: ^4.0
• doctrine/doctrine-bundle: ^2.13
• doctrine/doctrine-fixtures-bundle: ^4.0
• doctrine/orm: ^3.0
• doctrine/persistence: ^4.1
• easycorp/easyadmin-bundle: ^4
• knplabs/knp-menu: ^3.7
• monolog/monolog: ^3.1
• psr/log: ^3|^2|^1
• symfony/config: ^7.3
• symfony/console: ^7.3
• symfony/dependency-injection: ^7.3
• symfony/doctrine-bridge: ^7.3
• symfony/event-dispatcher: ^7.3
• symfony/framework-bundle: ^7.3
• symfony/http-foundation: ^7.3
• symfony/http-kernel: ^7.3
• symfony/property-access: ^7.3
• symfony/routing: ^7.3
• symfony/security-bundle: ^7.3
• symfony/twig-bundle: ^7.3
• symfony/yaml: ^7.3
• tourze/bundle-dependency: 1.*
• tourze/doctrine-indexed-bundle: 1.0.*
• tourze/doctrine-resolve-target-entity-bundle: 1.*
• tourze/doctrine-snowflake-bundle: 1.1.*
• tourze/doctrine-timestamp-bundle: 1.1.*
• tourze/doctrine-track-bundle: 1.1.*
• tourze/doctrine-user-bundle: 1.0.*
• tourze/easy-admin-menu-bundle: 1.0.*
• tourze/http-client-bundle: 1.1.*
• tourze/symfony-dependency-service-loader: 1.0.*
• tourze/symfony-routing-auto-loader-bundle: 1.0.*
• tourze/wechat-official-account-bundle: 0.1.*
• tourze/wechat-official-account-contracts: 0.0.*

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.5
• tourze/phpunit-base: 1.*
• tourze/phpunit-doctrine-entity: 1.*
• tourze/phpunit-symfony-kernel-test: 1.0.*
• tourze/phpunit-symfony-unit-test: 1.*
• tourze/phpunit-symfony-web-test: 1.*
• tourze/symfony-testing-framework: 1.*

MIT

README

English | 中文

A complete OAuth2 authorization solution for WeChat Official Accounts in Symfony applications.

Table of Contents

• Features
• Installation
• Usage
• API Endpoints
• Authorization Scopes
• Error Handling
• Security Recommendations
• Development and Testing
• Service Classes
• Dependencies
• License
• Contributing

Features

• 🔐 Standard OAuth2 authorization code flow
• 🎯 WeChat Official Account user authorization
• 👤 Get user basic and detailed information
• 🔄 Automatic access token refresh
• 🗃️ Token management and cleanup
• 🛡️ Secure client authentication
• 📊 EasyAdmin backend integration
• 🧪 Complete unit and integration tests

Installation

1. Install via Composer

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

2. Add Bundle to Kernel

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

3. Database Migration

# Generate migration files
php bin/console doctrine:migrations:diff

# Execute migrations
php bin/console doctrine:migrations:migrate

4. Configure WeChat Official Account

Ensure you have configured your WeChat Official Account information in wechat-official-account-bundle.

Usage

1. Create OAuth2 Application

php bin/console oauth2:create-application 1 \
    --redirect-uri="https://example.com/callback" \
    --redirect-uri="https://example.com/auth/callback" \
    --scope="snsapi_userinfo"

Parameters:

• 1: WeChat Official Account ID
• --redirect-uri: Authorization callback URL (multiple allowed)
• --scope: Default authorization scope

2. OAuth2 Authorization Flow

Step 1: User Authorization

Redirect users to the authorization page:

GET /oauth2/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=snsapi_base&state=STATE&response_type=code

Parameters:

• client_id: OAuth2 client ID
• redirect_uri: Authorization callback URL
• scope: Authorization scope (snsapi_base or snsapi_userinfo)
• state: Random string for CSRF protection
• response_type: Fixed value code

Step 2: Get Access Token

Exchange authorization code for access token:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Response Example:

{
  "access_token": "AT_...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "RT_...",
  "scope": "snsapi_base",
  "openid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
  "unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL"
}

Step 3: Get User Information

Get user information using access token:

# Query parameter method
GET /oauth2/userinfo?access_token=ACCESS_TOKEN

# Header method
GET /oauth2/userinfo
Authorization: Bearer ACCESS_TOKEN

Step 4: Refresh Access Token

POST /oauth2/refresh
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

3. Token Management

Revoke Token

POST /oauth2/revoke
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Token Introspection

POST /oauth2/introspect
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN

4. Console Commands

OAuth2 Configuration Command

Configure OAuth2 settings for WeChat Official Account:

# Configure OAuth2 settings
php bin/console wechat:oauth2:configure <account-id> [--scope=SCOPE] [--remark=REMARK]

Parameters:

• account-id: WeChat Official Account ID
• --scope: Authorization scope (optional, default: snsapi_base)
• --remark: Configuration remark (optional)

Examples:

# Basic configuration
php bin/console wechat:oauth2:configure 1

# Configure user info authorization
php bin/console wechat:oauth2:configure 1 --scope=snsapi_userinfo --remark="User info authorization config"

Refresh Token Command

Automatically refresh expiring access tokens:

# Refresh all expiring tokens (default: within 2 hours)
php bin/console wechat:oauth2:refresh-tokens

# Refresh tokens expiring within 1 hour
php bin/console wechat:oauth2:refresh-tokens --expires-within="1 hour"

# Force refresh all tokens
php bin/console wechat:oauth2:refresh-tokens --force

Parameters:

• --expires-within: Tokens expiring within specified time range (optional, default: 2 hours)
• --force: Force refresh all tokens regardless of expiration (optional)

5. Scheduled Cleanup

It's recommended to set up a cron job to clean up expired tokens:

# Clean up expired tokens every hour
0 * * * * php /path/to/your/app/bin/console oauth2:cleanup

# Preview cleanup (without deletion)
php bin/console oauth2:cleanup --dry-run

# Clean up tokens before specified time
php bin/console oauth2:cleanup --before="-1 week"

API Endpoints

| Endpoint | Method | Description | | /oauth2/authorize | GET | User authorization page | | /oauth2/callback | GET | WeChat authorization callback | | /oauth2/token | POST | Get access token | | /oauth2/refresh | POST | Refresh access token | | /oauth2/revoke | POST | Revoke token | | /oauth2/userinfo | GET/POST | Get user information | | /oauth2/introspect | POST | Token introspection |

Authorization Scopes

• snsapi_base: Silent authorization, only get user's openid
• snsapi_userinfo: Requires user's manual consent, can get user's basic information

Error Handling

All error responses follow the OAuth2 standard format:

{
  "error": "invalid_request",
  "error_description": "Invalid request parameters"
}

Common Error Codes:

• invalid_request: Invalid request parameters
• invalid_client: Client authentication failed
• invalid_grant: Invalid or expired authorization code
• invalid_token: Invalid access token
• unsupported_grant_type: Unsupported grant type

Security Recommendations

1. 🔒 Keep Client Secret secure and avoid leakage
2. 🌐 Only use OAuth2 features in HTTPS environment
3. ✅ Strictly validate redirect_uri parameter
4. ⏰ Set reasonable token expiration times
5. 🧹 Regularly clean up expired authorization codes and tokens

Development and Testing

Running Tests

# Run all tests
vendor/bin/phpunit packages/wechat-official-account-oauth2-bundle/tests/

# Run unit tests (Entity and basic functionality tests)
vendor/bin/phpunit packages/wechat-official-account-oauth2-bundle/tests/Entity/
vendor/bin/phpunit packages/wechat-official-account-oauth2-bundle/tests/Exception/

# Run specific test file
vendor/bin/phpunit packages/wechat-official-account-oauth2-bundle/tests/Entity/OAuth2AccessTokenTest.php

Note: Some integration tests may experience conflicts due to Symfony configuration class loading in the same PHP process. This is a known issue tracked in Issue #774. Unit tests (Entity, Exception tests) run without issues.

Code Quality Checks

# PHPStan static analysis
vendor/bin/phpstan analyse packages/wechat-official-account-oauth2-bundle/src/

# PHP CS Fixer code formatting
vendor/bin/php-cs-fixer fix packages/wechat-official-account-oauth2-bundle/src/

Service Classes

OAuth2AuthorizationService

use Tourze\WechatOfficialAccountOAuth2Bundle\Service\OAuth2AuthorizationService;

// Build WeChat authorization URL
$authUrl = $authorizationService->buildWechatAuthUrl($account, 'snsapi_userinfo', $redirectUri);

// Get user info by authorization code
$userInfo = $authorizationService->getUserInfoByCode($account, $code);

// Create internal access token
$accessToken = $authorizationService->exchangeCodeForToken($code, $redirectUri, $account);

OAuth2UserInfoService

use Tourze\WechatOfficialAccountOAuth2Bundle\Service\OAuth2UserInfoService;

// Get user info (via internal access token)
$userInfo = $userInfoService->getUserInfo($oAuth2AccessToken);

WechatOAuth2Service

use Tourze\WechatOfficialAccountOAuth2Bundle\Service\WechatOAuth2Service;

// Build WeChat authorization URL
$authUrl = $wechatOAuth2Service->buildAuthorizationUrl($account, $redirectUri, 'snsapi_base');

// Get WeChat access token
$tokenData = $wechatOAuth2Service->getAccessTokenByCode($account, $code);

// Validate WeChat access token
$isValid = $wechatOAuth2Service->validateAccessToken($account, $accessToken, $openid);

Dependencies

This bundle depends on the following components:

• wechat-official-account-bundle: WeChat Official Account basic functionality
• http-client-bundle: HTTP client wrapper
• symfony-routing-auto-loader-bundle: Automatic route loading
• doctrine-snowflake-bundle: Snowflake ID generation
• doctrine-indexed-bundle: Database indexing support
• doctrine-timestamp-bundle: Automatic timestamp handling
• doctrine-track-bundle: Entity tracking features
• doctrine-user-bundle: User management features

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📝 Note: Before using in production, ensure all features are thoroughly tested and configured according to WeChat's official documentation.