README

English | 中文

WeChatWork Bundle provides WeChatWork API integration capabilities for Symfony applications.

Table of Contents

• Dependencies
• Installation
• Features
• Configuration
  • Basic Configuration
  • Database Configuration
• Quick Start
  • 1. Configure Enterprise Information
  • 2. Using Services
  • 3. Automatic Access Token Refresh
• Console Commands
  • Refresh Access Token
  • Synchronize Application Information
• Advanced Usage
  • Custom Request Implementation
  • Service Extension
• Entity Description
  • Corp (Enterprise)
  • Agent (Application)
• Security
  • Access Token Management
  • Sensitive Data
• Reference Documentation
• License

Dependencies

This bundle requires:

• PHP 8.1 or higher
• Symfony 7.3 or higher
• Doctrine ORM 3.0 or higher
• tourze/wechat-work-contracts for interface definitions
• tourze/doctrine-timestamp-bundle for timestamp handling
• tourze/doctrine-track-bundle for tracking changes
• tourze/doctrine-user-bundle for user-related functionality
• tourze/doctrine-ip-bundle for IP tracking
• tourze/doctrine-resolve-target-entity-bundle for entity resolution
• tourze/http-client-bundle for HTTP client functionality
• tourze/symfony-cron-job-bundle for scheduled tasks
• tourze/enum-extra for enum utilities
• nesbot/carbon for date/time handling
• yiisoft/json for JSON processing

Installation

composer require tourze/wechat-work-bundle

Features

• WeChatWork application management
• Automatic access token refresh
• Application information synchronization
• Enterprise information management
• Full Doctrine ORM support
• Scheduled task support

Configuration

Basic Configuration

Enable the bundle in your config/bundles.php:

<?php

return [
    // Other bundles...
    WechatWorkBundle\WechatWorkBundle::class => ['all' => true],
];

Database Configuration

Run migrations to create required tables:

php bin/console doctrine:migrations:migrate

Quick Start

1. Configure Enterprise Information

First, create a Corp entity and at least one Agent:

use WechatWorkBundle\Entity\Corp;
use WechatWorkBundle\Entity\Agent;

// Create enterprise
$corp = new Corp();
$corp->setName('My Company');
$corp->setCorpId('your_corp_id');

// Create application
$agent = new Agent();
$agent->setName('My App');
$agent->setAgentId('your_agent_id');
$agent->setSecret('your_agent_secret');
$agent->setCorp($corp);

$entityManager->persist($corp);
$entityManager->persist($agent);
$entityManager->flush();

2. Using Services

use WechatWorkBundle\Service\WorkService;

class MyService
{
    public function __construct(
        private WorkService $workService
    ) {}

    public function sendMessage(): void
    {
        // The service automatically handles access token refresh
        $this->workService->refreshAgentAccessToken($agent);
        
        // Use the service to make API calls
        // Implementation depends on your specific needs
    }
}

3. Automatic Access Token Refresh

The bundle automatically handles access token refresh. You can also manually refresh tokens:

php bin/console wechat-work:refresh-agent-access-token

Console Commands

Refresh Access Token

Refresh access tokens for all agents:

php bin/console wechat-work:refresh-agent-access-token

Synchronize Application Information

Synchronize application information from WeChatWork API:

php bin/console wechat-work:sync-agent-info

Advanced Usage

Custom Request Implementation

You can extend the WorkService to implement custom API requests:

use WechatWorkBundle\Service\WorkService;
use WechatWorkBundle\Entity\Agent;

class CustomWorkService extends WorkService
{
    public function sendTextMessage(Agent $agent, string $content): array
    {
        $this->refreshAgentAccessToken($agent);
        
        $data = [
            'touser' => '@all',
            'msgtype' => 'text',
            'agentid' => $agent->getAgentId(),
            'text' => [
                'content' => $content
            ]
        ];
        
        return $this->request([
            'url' => $this->getBaseUrl() . '/cgi-bin/message/send',
            'method' => 'POST',
            'query' => ['access_token' => $agent->getAccessToken()],
            'json' => $data
        ]);
    }
}

Service Extension

Create custom services that utilize the WeChatWork API:

use WechatWorkBundle\Service\WorkService;
use WechatWorkBundle\Repository\AgentRepository;

class NotificationService
{
    public function __construct(
        private WorkService $workService,
        private AgentRepository $agentRepository
    ) {}

    public function sendNotification(string $message): void
    {
        $agents = $this->agentRepository->findBy(['active' => true]);
        
        foreach ($agents as $agent) {
            // Send notification via each active agent
            $this->workService->refreshAgentAccessToken($agent);
            // Implement your notification logic here
        }
    }
}

Entity Description

Corp (Enterprise)

Represents a WeChatWork enterprise:

• name: Enterprise name
• corpId: Unique enterprise identifier
• agents: Collection of associated applications

Agent (Application)

Represents a WeChatWork application within an enterprise:

• name: Application name
• agentId: Application identifier
• secret: Application secret for API access
• accessToken: Current access token (auto-managed)
• accessTokenExpireTime: Token expiration time
• corp: Associated enterprise

Security

Access Token Management

Access tokens are automatically managed by the bundle:

• Tokens are refreshed before expiration
• Failed refresh attempts are logged
• Tokens are stored securely in the database

Sensitive Data

Ensure proper protection of sensitive information:

• Agent secrets should be stored securely
• Access tokens are auto-generated and managed
• Consider encryption for sensitive database fields

Reference Documentation

• WeChatWork API Documentation
• Application Management
• Message API

License

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