# PHP微信模板消息推送服务

**Repository Path**: web/php-wxpush

## Basic Information

- **Project Name**: PHP微信模板消息推送服务
- **Description**: PHP微信模板消息推送服务 开发的微信测试公众号模板消息推送服务 极简且免费 测试公众号每天有10万次额度 不会技术也能玩推送
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-23
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PHP微信模板消息推送服务

一个基于PHP开发的微信模板消息推送服务支持PHP5.6+版本。

## 功能特性

- ✅ 支持GET和POST请求方式
- ✅ 支持JSON和表单参数解析
- ✅ 微信AccessToken自动获取与缓存
- ✅ 支持多appid独立缓存
- ✅ 自动处理AccessToken过期
- ✅ 消息详情页面展示
- ✅ 动态粒子背景效果
- ✅ 响应式设计，适配各种设备
- ✅ 兼容PHP5.6+版本
- ✅ 支持自定义时区
- ✅ 完整的错误处理机制

## ⚠️ 部署条件

- [微信公众平台接口测试帐号申请](https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login)
![wx1.png](img/wx1.png)
- 获取appid 、appsecret
![wx2.png](img/wx2.png)
- 关注测试公众号，获取userid(微信号)，新增测试模板(注意模版内容填写格式 `内容: {{content.DATA}}`)  获取template_id(模板ID)
![wx3.png](img/wx3.png)
- 将以上获取到的参数代入下面使用即可
![wx3.png](img/w0.jpg)
![wx3.png](img/w1.jpg)

### 体验接口权限
| 接口	|官方文档|		每日调用上限/次|
|--------|------|------|
| 获取access_token	|[查看](https://developers.weixin.qq.com/doc/service/api/base/api_getstableaccesstoken.html)	|2000|
| 模板消息（业务通知）	|[查看](https://mp.weixin.qq.com/debug/cgi-bin/readtmpl?t=tmplmsg/faq_tmpl)|100000|
## 安装部署

### 环境要求

- PHP 5.6 或更高版本
- cURL 扩展
- JSON 扩展

### 部署步骤

1. **下载项目文件**
   ```bash
   git clone https://gitee.com/web/php-wxpush.git
   cd php-wxpush
   ```

2. **配置默认参数和API密钥**
   - 编辑 `config.php` 文件，配置默认参数和API密钥
   - 可以根据不同appid配置不同的默认参数
   - 可以配置API密钥，增强API调用安全性
   - 示例配置：
     ```php
     return [
         // 默认模板配置
         'default' => [
             'template_id' => 'your_template_id',
             'title' => '默认标题',
             'content' => '默认内容',
             'base_url' => 'https://your-domain.com',
             'tz' => 'Asia/Shanghai',
         ],
         
         // API密钥配置（可选，用于增强API安全性）
         // 默认为空数组，不启用API密钥验证
         // 配置后，调用/wxsend接口必须传递有效的apikey参数
         'apikeys' => [
             'your_api_key_1',
             'your_api_key_2',
         ],
         
         // 按appid配置不同的默认参数
         'appids' => [
             'your_appid_here' => [
                 'template_id' => 'your_template_id',
                 'title' => '应用专属标题',
                 'content' => '应用专属内容',
                 'base_url' => 'https://your-domain.com',
                 'tz' => 'Asia/Shanghai',
             ],
         ],
         
         // 系统配置
         'system' => [
             'cache_dir' => './cache/',
             'timezone' => 'Asia/Shanghai',
         ],
     ];
     ```

3. **部署到Web服务器**
   - 将项目文件上传到Web服务器的根目录或子目录
   - 确保Web服务器配置正确，能够解析PHP文件
   - 确保缓存目录有写入权限

4. **配置Web服务器**
   - Apache：确保`.htaccess`文件配置正确（可选）
   - Nginx：示例配置
     ```nginx
     server {
         listen 80;
         server_name your-domain.com;
         root /path/to/php-wxpush;
         index index.php;
         
         location / {
             try_files $uri $uri/ /index.php$is_args$args;
         }
         
         location ~ \.php$ {
             fastcgi_pass 127.0.0.1:9000;
             fastcgi_index index.php;
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             include fastcgi_params;
         }
     }
     ```
5. **测试域名(仅供测试，请勿用于生效环境)**

```
https://wxpush.bitefu.net/wxsend
```


## 使用方法

### 1. 通过HTTP请求使用

#### 发送微信模板消息

**GET请求（完整参数）**
```
http://your-domain/index.php/wxsend?appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&title=测试标题&content=测试内容
```

**GET请求（使用默认参数）**
```
http://your-domain/index.php/wxsend?appid=your_appid&secret=your_secret&userid=your_userid
```

**GET请求（使用API密钥）**
```
http://your-domain/index.php/wxsend?appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&apikey=your_api_key
```

**POST请求（JSON，完整参数）**
```bash
curl -X POST -H "Content-Type: application/json" -d '{
    "appid": "your_appid",
    "secret": "your_secret",
    "userid": "your_userid",
    "template_id": "your_template_id",
    "title": "测试标题",
    "content": "测试内容"
}' http://your-domain/index.php/wxsend
```

**POST请求（JSON，使用默认参数）**
```bash
curl -X POST -H "Content-Type: application/json" -d '{
    "appid": "your_appid",
    "secret": "your_secret",
    "userid": "your_userid"
}' http://your-domain/index.php/wxsend
```

**POST请求（JSON，使用API密钥）**
```bash
curl -X POST -H "Content-Type: application/json" -d '{
    "appid": "your_appid",
    "secret": "your_secret",
    "userid": "your_userid",
    "template_id": "your_template_id",
    "apikey": "your_api_key"
}' http://your-domain/index.php/wxsend
```

**POST请求（表单，完整参数）**
```bash
curl -X POST -d "appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&title=测试标题&content=测试内容" http://your-domain/index.php/wxsend
```

**POST请求（表单，使用默认参数）**
```bash
curl -X POST -d "appid=your_appid&secret=your_secret&userid=your_userid" http://your-domain/index.php/wxsend
```

**POST请求（表单，使用API密钥）**
```bash
curl -X POST -d "appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&apikey=your_api_key" http://your-domain/index.php/wxsend
```

##### ThinkPHP伪静态模式

**GET请求（使用s参数）**
```
http://your-domain/index.php?s=/wxsend&appid=your_appid&secret=your_secret&userid=your_userid
```

**GET请求（使用s参数和API密钥）**
```
http://your-domain/index.php?s=/wxsend&appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&apikey=your_api_key
```

**POST请求（JSON，使用s参数）**
```bash
curl -X POST -H "Content-Type: application/json" -d '{"appid":"your_appid","secret":"your_secret","userid":"your_userid"}' "http://your-domain/index.php?s=/wxsend"
```

**POST请求（JSON，使用s参数和API密钥）**
```bash
curl -X POST -H "Content-Type: application/json" -d '{"appid":"your_appid","secret":"your_secret","userid":"your_userid","template_id":"your_template_id","apikey":"your_api_key"}' "http://your-domain/index.php?s=/wxsend"
```

**POST请求（表单，使用s参数）**
```bash
curl -X POST -d "appid=your_appid&secret=your_secret&userid=your_userid" "http://your-domain/index.php?s=/wxsend"
```

**POST请求（表单，使用s参数和API密钥）**
```bash
curl -X POST -d "appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&apikey=your_api_key" "http://your-domain/index.php?s=/wxsend"
```

#### 查看消息详情

**标准模式**
```
http://your-domain/index.php/detail?title=测试标题&message=测试内容&date=2023-01-01%2012:00:00
```

**ThinkPHP伪静态模式**
```
http://your-domain/index.php?s=/detail&title=测试标题&message=测试内容&date=2023-01-01%2012:00:00
```
![wx3.png](img/msg.png)
### 2. 作为PHP类使用

```php
// 引入微信推送类
require_once 'wxpush.php';

// 实例化微信推送类
$wxPush = new WxPush();

// 处理请求
$wxPush->handleRequest();
```

## API文档

### 1. 发送微信模板消息

**接口地址**：`/wxsend`

**请求方式**：GET/POST

**请求参数**：

| 参数名 | 类型 | 必选 | 描述 | 默认值 |
|--------|------|------|------|--------|
| appid | string | 是 | 微信AppID | 无 |
| secret | string | 是 | 微信AppSecret | 无 |
| userid | string | 是 | 接收消息的用户openid | 无 |
| template_id | string | 是 | 模板消息ID | 无 |
| apikey | string | 否 | API密钥，当config.php中配置了apikeys时必填 | 无 |
| title | string | 否 | 消息标题 | 测试标题 |
| content | string | 否 | 消息内容 | 测试内容 |
| base_url | string | 否 | 详情页基础URL | 当前域名 |
| tz | string | 否 | 时区 | Asia/Shanghai |
| template_data | array | 否 | 完整的模板数据数组，格式：{"keyword1":{"value":"值1"},"keyword2":{"value":"值2"}} | 无 |
| template_params | array | 否 | 模板参数数组，格式：{"keyword1":{"value":"值1"},"keyword2":{"value":"值2"}} | 无 |
| template_* | mixed | 否 | 单个模板参数，如template_keyword1=值1，会转换为{"keyword1":{"value":"值1"}} | 无 |

**返回结果**：

```json
{
    "errcode": 0,
    "errmsg": "ok"
}
```

### 2. 查看消息详情

**接口地址**：`/detail`

**请求方式**：GET

**请求参数**：

| 参数名 | 类型 | 必选 | 描述 | 默认值 |
|--------|------|------|------|--------|
| title | string | 否 | 消息标题 | 消息推送 |
| message | string | 否 | 消息内容 | 无告警信息 |
| date | string | 否 | 发送时间 | 无时间信息 |

**返回结果**：HTML页面

### 3. 服务状态

**接口地址**：`/`

**请求方式**：GET

**返回结果**：

```json
{
    "message": "php-wxpush is running..."
}
```

## 示例代码

### 1. 直接调用类文件示例

#### 完整参数示例

```php
<?php
// 直接调用WxPush类发送消息
require_once 'wxpush.php';

// 初始化微信推送类
$wxPush = new WxPush();

// 准备发送参数
$params = [
    'appid' => 'your_appid',
    'secret' => 'your_secret',
    'userid' => 'your_userid',
    'template_id' => 'your_template_id',
    'title' => '测试标题',
    'content' => '测试内容',
    'base_url' => 'https://your-domain.com', // 可选，默认使用当前域名
    'tz' => 'Asia/Shanghai' // 可选，默认时区
];

try {
    // 直接调用public方法发送消息（推荐方式）
    $result = $wxPush->sendMessage($params);
    
    echo "发送结果：\n";
    print_r($result);
} catch (Exception $e) {
    echo "发送失败：" . $e->getMessage() . "\n";
}
```

#### 使用自定义模板参数示例

```php
<?php
// 直接调用WxPush类发送消息（使用自定义模板参数）
require_once 'wxpush.php';

// 初始化微信推送类
$wxPush = new WxPush();

// 方式1：使用template_data参数（完整的模板数据）
$params1 = [
    'appid' => 'your_appid',
    'secret' => 'your_secret',
    'userid' => 'your_userid',
    'template_id' => 'your_template_id',
    'template_data' => [
        'keyword1' => ['value' => '订单号：123456'],
        'keyword2' => ['value' => '支付金额：100元'],
        'keyword3' => ['value' => '支付时间：2023-01-01 12:00:00'],
        'keyword4' => ['value' => '支付状态：成功']
    ]
];

// 方式2：使用template_params参数（数组形式的模板参数）
$params2 = [
    'appid' => 'your_appid',
    'secret' => 'your_secret',
    'userid' => 'your_userid',
    'template_id' => 'your_template_id',
    'template_params' => [
        'keyword1' => ['value' => '订单号：123456'],
        'keyword2' => ['value' => '支付金额：100元']
    ]
];

// 方式3：使用单个template_*参数
$params3 = [
    'appid' => 'your_appid',
    'secret' => 'your_secret',
    'userid' => 'your_userid',
    'template_id' => 'your_template_id',
    'title' => '订单通知',
    'content' => '您的订单已支付成功',
    'template_keyword1' => '订单号：123456',
    'template_keyword2' => '支付金额：100元',
    'template_keyword3' => ['value' => '支付时间：2023-01-01 12:00:00', 'color' => '#FF0000']
];

try {
    // 使用方式1发送消息
    $result = $wxPush->sendMessage($params1);
    
    echo "发送结果：\n";
    print_r($result);
} catch (Exception $e) {
    echo "发送失败：" . $e->getMessage() . "\n";
}
```

#### 使用API密钥示例

```php
<?php
// 直接调用WxPush类发送消息（使用API密钥）
require_once 'wxpush.php';

// 初始化微信推送类
$wxPush = new WxPush();

// 当config.php中配置了apikeys时，必须传递apikey参数
$params = [
    'appid' => 'your_appid',
    'secret' => 'your_secret',
    'userid' => 'your_userid',
    'template_id' => 'your_template_id',
    'apikey' => 'your_api_key', // API密钥，与config.php中配置的apikeys数组中的某个值匹配
    'title' => '测试标题',
    'content' => '测试内容'
];

try {
    // 发送消息
    $result = $wxPush->sendMessage($params);
    
    echo "发送结果：\n";
    print_r($result);
} catch (Exception $e) {
    echo "发送失败：" . $e->getMessage() . "\n";
}
```

### 2. PHP HTTP请求示例

```php
<?php
// 发送HTTP请求示例
function sendWechatMessage($params) {
    $url = 'http://your-domain/index.php/wxsend';
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// 使用示例
$params = [
    'appid' => 'your_appid',
    'secret' => 'your_secret',
    'userid' => 'your_userid',
    'template_id' => 'your_template_id',
    'title' => '测试标题',
    'content' => '测试内容'
];

$result = sendWechatMessage($params);
print_r($result);
```

### 3. Python示例

```python
import requests
import json

url = 'http://your-domain/index.php/wxsend'

params = {
    'appid': 'your_appid',
    'secret': 'your_secret',
    'userid': 'your_userid',
    'template_id': 'your_template_id',
    'title': '测试标题',
    'content': '测试内容'
}

response = requests.post(url, data=json.dumps(params), headers={'Content-Type': 'application/json'})
print(response.json())
```

### 4. Shell示例

```bash
# GET请求
curl "http://your-domain/index.php/wxsend?appid=your_appid&secret=your_secret&userid=your_userid&template_id=your_template_id&title=测试标题&content=测试内容"

# POST JSON请求
curl -X POST -H "Content-Type: application/json" -d '{"appid":"your_appid","secret":"your_secret","userid":"your_userid","template_id":"your_template_id","title":"测试标题","content":"测试内容"}' http://your-domain/index.php/wxsend
```

## 注意事项

1. **微信模板消息配置**
   - 需要在微信公众平台中配置好模板消息
   - 模板消息必须包含`title`和`content`字段
   - 确保模板ID与实际配置一致

2. **AccessToken缓存**
   - AccessToken默认缓存7000秒（约1小时56分钟）
   - 缓存文件存储在`./cache/`目录下
   - 确保缓存目录有写入权限
   - 每个appid独立缓存，互不影响

3. **错误处理**
   - 接口返回的错误码与微信官方保持一致
   - 详细错误信息可查看服务器日志

4. **安全性**
   - 建议在生产环境中使用HTTPS协议
   - 不要将AppSecret泄露给第三方
   - 建议设置IP白名单限制访问

5. **性能优化**
   - 对于高并发场景，建议使用Redis等内存缓存替代文件缓存
   - 可以根据实际情况调整缓存过期时间

## 许可证

MIT License

## 更新日志

### v1.0.0 (2026-01-23)
- 初始版本
- 实现微信模板消息推送功能
- 支持GET和POST请求
- 实现AccessToken缓存机制
- 提供消息详情页面
- 兼容PHP5.6+版本

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

如有问题或建议，请通过以下方式联系：
- Gitee: [web/php-wxpush](https://gitee.com/web/php-wxpush.git)

## 参考项目

本项目参考了以下优秀项目：
- [go-wxpush](https://gitee.com/lisbitid/go-wxpush) - Go语言实现的微信模板消息推送服务

## 感谢

感谢原项目作者的开源贡献，本项目是基于 [go-wxpush](https://gitee.com/lisbitid/go-wxpush) 项目的PHP实现，保持了与原项目完全兼容的API功能。

---

**PHP微信模板消息推送服务** - 简单、高效、可靠的微信消息推送解决方案！