Skip to content

Commit 5dce20e

Browse files
calchencalchen
committed
完善翻译与细节
1 parent 7632e0d commit 5dce20e

File tree

4 files changed

+102
-37
lines changed

4 files changed

+102
-37
lines changed

‎README.md

+36-9
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<h1 align="center"> laravel-dingtalk-robot-notification </h1>
2-
<p align="center"> 阿里云消息服务（MNS） Laravel/Lumen 扩 扩展包 </p>
2+
<p align="center"> 钉钉群机器人 Laravel/Lumen 扩展包 </p>
33
<p align="center">
44
<a href="https://github.styleci.io/repos/205573394">
55
<img alt="Style CI" src="https://github.styleci.io/repos/166196221/shield?style=flat">
@@ -27,17 +27,16 @@
2727

2828
## 安装
2929

30-
Laravel/Lumen 5.5 ~ 6.x
30+
推荐使用 composer 进行安装：
3131

3232
```shell
3333
$ composer require calchen/laravel-dingtalk-robot-notification:^2.0
3434
```
3535

3636
### Laravel
3737

38-
Laravel 5.5+ 已经实现了扩展包发现机制，您不需要进行额外的加载操作
38+
Laravel 5.5+ 已经实现了扩展包发现机制，您不需要进行额外的加载操作，但是依然需要将配置文件发布出来：
3939

40-
除此之外还需要将配置文件发布出来：
4140
```shell
4241
php artisan vendor:publish --provider="Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider"
4342
```
@@ -53,6 +52,10 @@ $app->register(Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider::
5352

5453
将文件系统配置文件从 `vendor/calchen/laravel-dingtalk-robot-notification/config/dingtalk_robot.php` 复制到 `config/dingtalk_robot.php`
5554

55+
### 非 Laravel/Lumen 框架
56+
57+
无需考虑加载问题，请使用全局函数 `\dingtalk_robot()` 或直接创建 \Calchen\LaravelDingtalkRobot\DingtalkRobot 实例，以发送消息。
58+
5659
## 配置
5760

5861
打开配置文件 `config/dingtalk_robot.php` 并按照如下格式添加或修改配置：
@@ -71,13 +74,13 @@ $app->register(Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider::
7174
### 配置说明
7275
| 配置项 | 必须 | 数据类型 | 说明 | 备注 |
7376
|-------------------- |------ |------------- |----------------------------------------------- |------------------------------------------------------------------------------------------------------------ |
74-
| http_client_name | 否 | string/null | 驱动名称 | 默认值：null，注入在 Laravel 中的 Guzzle 实例的名称，以便替换 HTTP 客户端 |
77+
| http_client_name | 否 | string/null | Guzzle 实例的名称 | 默认值：null，注入在 Laravel 中的 Guzzle 实例的名称，以便替换 HTTP 客户端 |
7578
| robotName | 是 | string | 机器人名称 | 这个名称为了区别不同的机器人 |
7679
| access_token | 是 | string | 创建机器人后 Webhook URL 中 access_token 的值 | |
77-
| timeout | 否 | int/float | 超时时间 | 默认值：2.0秒，具体见 http://docs.guzzlephp.org/en/stable/request-options.html#timeout |
80+
| timeout | 否 | int/float | 超时时间 | 默认值：2.0秒，具体见 [Guzzle 文档](http://docs.guzzlephp.org/en/stable/request-options.html#timeout) |
7881
| security_types | 是 | array | 安全设置 | 旧机器人是不存在该项配置的传 null 或不设置该配置项；新机器人可以组合选择：自定义关键字、加签、IP地址（段） |
7982
| security_types.* | 是 | string/null | 设置项 | 枚举值：null、keywords、signature、ip |
80-
| security_signature | 否 | string | 安全模式包含加签时需要的密钥字符串 | 应当以 SEC 开头 |
83+
| security_signature | 否 | string | 安全模式包含加签时需要的密钥字符串 | 应当以 SEC 开头 | |
8184

8285
### 获取 access_token 并设置安全设置
8386

@@ -88,7 +91,7 @@ $app->register(Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider::
8891

8992
### HTTP 客户端注入
9093

91-
为了方便在某些情况下需要统一管理扩展包使用的 HTTP 客户端，提供了 `http_client_name` 配置项，以实现从 Laravel 容器中获取已经注入的 Guzzle 实例
94+
为了方便在某些情况下需要统一管理扩展包使用的 HTTP 客户端，提供了 `http_client_name` 配置项，以实现从 Laravel 容器中获取已经注入的 Guzzle 实例。如果您不需要手动管理 HTTP 客户端，您可以不设置该配置项或将该配置项值设置成 null。
9295

9396
## 使用方法
9497

@@ -380,13 +383,37 @@ $message->setRobot('机器人名字');
380383

381384
首先感谢您使用 1.x 版本的扩展包，因为钉钉机器人更新了安全设置，在升级过程中为了使得代码更整洁因此出现了无法兼容的情况，故此将新版升级至2.x版本。这里将明确给出两个版本的差异，以便您以最少的成本进行升级。
382385

386+
### 配置项的差异
383387

388+
#### 新增
384389

385-
### 配置项的差异
390+
##### http_client_name
391+
392+
为了方便在某些情况下需要统一管理扩展包使用的 HTTP 客户端，提供了 `http_client_name` 配置项，以实现从 Laravel 容器中获取已经注入的 Guzzle 实例。如果您不需要手动管理 HTTP 客户端，您可以不设置该配置项或将该配置项值设置成 null。
393+
394+
##### 机器人名称.security_types
395+
396+
数据结构为数组。如果您使用的是旧机器人，配置项中无“安全设置”相关内容，那么您可以不设置该字段，或将其设置成：
386397

398+
```php
399+
'security_types' => [
400+
null,
401+
],
402+
```
403+
404+
如果您使用的是新机器人，请按照机器人的实际情况配置该项，可以组合选择：自定义关键字、加签、IP地址（段），如：
387405

406+
```php
407+
'security_types' => [
408+
'keywords', // 自定义关键字
409+
'signature', // 加签
410+
'ip', // IP地址（段）
411+
],
412+
```
388413

414+
##### 机器人名称.security_signature
389415

416+
密钥字符串。当安全模式包含加签时该字段是必须的。请注意，该字符串前三位应该是 SEC。
390417

391418
## 鸣谢
392419

‎README_en.md

+56-24
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<h1 align="center"> laravel-dingtalk-robot-notification </h1>
2-
<p align="center"> 阿里云消息服务（MNS） Laravel/Lumen 扩 扩展包 </p>
2+
<p align="center"> Dingtalk Robot for Laravel/Lumen </p>
33
<p align="center">
44
<a href="https://github.styleci.io/repos/205573394">
55
<img alt="Style CI" src="https://github.styleci.io/repos/166196221/shield?style=flat">
@@ -21,41 +21,44 @@
2121
</a>
2222
</p>
2323

24-
> [English](https://github.com/calchen/laravel-dingtalk-robot-notification/blob/master/README_en.md)
24+
> [中文](https://github.com/calchen/laravel-dingtalk-robot-notification/blob/master/README.md)
2525
26-
这是一个[钉钉群机器人](https://ding-doc.dingtalk.com/doc#/serverapi2/qf2nxq)的 Laravel/Lumen 消息通知（Notification）扩展包
26+
This is Laravel/Lumen custom notification channel for [DingTalk group assistant](https://ding-doc.dingtalk.com/doc#/serverapi2/qf2nxq).
2727

28-
## 安装
28+
## Installing
2929

30-
Laravel/Lumen 5.5 ~ 6.x
30+
Composer is recommended for installation:
3131

3232
```shell
3333
$ composer require calchen/laravel-dingtalk-robot-notification:^2.0
3434
```
3535

3636
### Laravel
3737

38-
Laravel 5.5+ 已经实现了扩展包发现机制，您不需要进行额外的加载操作
38+
For Laravel 5.5+ package auto discovery feature will help you loading everything you need. But you still need to publish the configuration file:
3939

40-
除此之外还需要将配置文件发布出来：
4140
```shell
4241
php artisan vendor:publish --provider="Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider"
4342
```
4443

4544
### Lumen
4645

47-
Lumen 并未移植扩展包自动发现机制，所以需要手动加载扩展包并复制配置文件。
46+
Open your `bootstrap/app.php` and add this line:
4847

49-
打开配置文件 `bootstrap/app.php` 并在大约 81 行左右添加如下内容：
5048
```php
5149
$app->register(Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider::class);
5250
```
5351

54-
将文件系统配置文件从 `vendor/calchen/laravel-dingtalk-robot-notification/config/dingtalk_robot.php` 复制到 `config/dingtalk_robot.php`
52+
Copy configuration file from `vendor/calchen/laravel-dingtalk-robot-notification/config/dingtalk_robot.php` to `config/dingtalk_robot.php`
5553

56-
## 配置
54+
### Other frameworks
55+
56+
Without considering the loading problem, please use the global function `\dingtalk_robot()` or directly create the \Calchen\LaravelDingtalkRobot\DingtalkRobot instance to send the message.
57+
58+
## Configuration
59+
60+
Open your `config/dingtalk_robot.php` and add these lines:
5761

58-
打开配置文件 `config/dingtalk_robot.php` 并按照如下格式添加或修改配置：
5962
```php
6063
'robotName' => [
6164
'access_token' => 'xxxx',
@@ -66,18 +69,20 @@ $app->register(Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider::
6669
'security_signature' => 'SECxxxx',
6770
],
6871
```
69-
请注意，如果需要配置多个机器人，请重复以上操作，并为不同机器人给予不同的 robotName
7072

71-
### 配置说明
72-
| 配置项 | 必须 | 数据类型 | 说明 | 备注 |
73+
If you need to configure more than one robot, repeat the above and give different `robotName` to different robots
74+
75+
### Details
76+
77+
| key | required | type | remarks | 备注 |
7378
|-------------------- |------ |------------- |----------------------------------------------- |------------------------------------------------------------------------------------------------------------ |
74-
| http_client_name | 否 | string/null | 驱动名称 | 默认值：null，注入在 Laravel 中的 Guzzle 实例的名称，以便替换 HTTP 客户端 |
75-
| robotName | 是 | string | 机器人名称 | 这个名称为了区别不同的机器人 |
76-
| access_token | 是 | string | 创建机器人后 Webhook URL 中 access_token 的值 | |
77-
| timeout | 否 | int/float | 超时时间 | 默认值：2.0秒，具体见 http://docs.guzzlephp.org/en/stable/request-options.html#timeout |
78-
| security_types | 是 | array | 安全设置 | 旧机器人是不存在该项配置的传 null 或不设置该配置项；新机器人可以组合选择：自定义关键字、加签、IP地址（段） |
79-
| security_types.* | 是 | string/null | 设置项 | 枚举值：null、keywords、signature、ip |
80-
| security_signature | 否 | string | 安全模式包含加签时需要的密钥字符串 | 应当以 SEC 开头 |
79+
| http_client_name | N | string/null | Guzzle 实例的名称 | 默认值：null，注入在 Laravel 中的 Guzzle 实例的名称，以便替换 HTTP 客户端 |
80+
| robotName | Y | string | 机器人名称 | 这个名称为了区别不同的机器人 |
81+
| access_token | Y | string | 创建机器人后 Webhook URL 中 access_token 的值 | |
82+
| timeout | N | int/float | 超时时间 | 默认值：2.0秒，具体见 [Guzzle 文档](http://docs.guzzlephp.org/en/stable/request-options.html#timeout) |
83+
| security_types | Y | array | 安全设置 | 旧机器人是不存在该项配置的传 null 或不设置该配置项；新机器人可以组合选择：自定义关键字、加签、IP地址（段） |
84+
| security_types.* | Y | string/null | 设置项 | 枚举值：null、keywords、signature、ip |
85+
| security_signature | N | string | 安全模式包含加签时需要的密钥字符串 | 应当以 SEC 开头 | |
8186

8287
### 获取 access_token 并设置安全设置
8388

@@ -88,7 +93,7 @@ $app->register(Calchen\LaravelDingtalkRobot\DingtalkRobotNoticeServiceProvider::
8893

8994
### HTTP 客户端注入
9095

91-
为了方便在某些情况下需要统一管理扩展包使用的 HTTP 客户端，提供了 `http_client_name` 配置项，以实现从 Laravel 容器中获取已经注入的 Guzzle 实例
96+
为了方便在某些情况下需要统一管理扩展包使用的 HTTP 客户端，提供了 `http_client_name` 配置项，以实现从 Laravel 容器中获取已经注入的 Guzzle 实例。如果您不需要手动管理 HTTP 客户端，您可以不设置该配置项或将该配置项值设置成 null。
9297

9398
## 使用方法
9499

@@ -156,11 +161,13 @@ class TestDingtalkNotification extends Notification
156161
```
157162

158163
根据 [Laravel](https://laravel.com/docs/6.x/notifications) 文档发送通知可以使用 Notifiable Trait
164+
159165
```php
160166
use Calchen\LaravelDingtalkRobot\Robot;
161167

162168
(new Robot)->notify(new TestDingtalkNotification());
163169
```
170+
164171
也可以使用 Notification Facade
165172

166173
```php
@@ -366,6 +373,7 @@ dingtalk_robot()->setMessage($message)->send();
366373
```
367374

368375
### 直接创建并调用接口
376+
369377
```php
370378
use Calchen\LaravelDingtalkRobot\DingtalkRobot;
371379
use Calchen\LaravelDingtalkRobot\Message\TextMessage;
@@ -380,13 +388,37 @@ $message->setRobot('机器人名字');
380388

381389
首先感谢您使用 1.x 版本的扩展包，因为钉钉机器人更新了安全设置，在升级过程中为了使得代码更整洁因此出现了无法兼容的情况，故此将新版升级至2.x版本。这里将明确给出两个版本的差异，以便您以最少的成本进行升级。
382390

391+
### 配置项的差异
383392

393+
#### 新增
384394

385-
### 配置项的差异
395+
##### http_client_name
386396

397+
为了方便在某些情况下需要统一管理扩展包使用的 HTTP 客户端，提供了 `http_client_name` 配置项，以实现从 Laravel 容器中获取已经注入的 Guzzle 实例。如果您不需要手动管理 HTTP 客户端，您可以不设置该配置项或将该配置项值设置成 null。
387398

399+
##### 机器人名称.security_types
400+
401+
数据结构为数组。如果您使用的是旧机器人，配置项中无“安全设置”相关内容，那么您可以不设置该字段，或将其设置成：
402+
403+
```php
404+
'security_types' => [
405+
null,
406+
],
407+
```
408+
409+
如果您使用的是新机器人，请按照机器人的实际情况配置该项，可以组合选择：自定义关键字、加签、IP地址（段），如：
410+
411+
```php
412+
'security_types' => [
413+
'keywords', // 自定义关键字
414+
'signature', // 加签
415+
'ip', // IP地址（段）
416+
],
417+
```
388418

419+
##### 机器人名称.security_signature
389420

421+
密钥字符串。当安全模式包含加签时该字段是必须的。请注意，该字符串前三位应该是 SEC。
390422

391423
## 鸣谢
392424

‎composer.json

+8-2
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,19 @@
44
"keywords": [
55
"laravel",
66
"lumen",
7-
"dingtalk",
7+
"notification",
88
"laravel notification",
9+
"lumen notification",
910
"钉钉",
1011
"钉钉群机器人",
1112
"群机器人",
1213
"钉钉智能群助手",
13-
"智能群助手"
14+
"智能群助手",
15+
"dingtalk",
16+
"group assistant",
17+
"robot",
18+
"group robot",
19+
"custom channel"
1420
],
1521
"license": "MIT",
1622
"authors": [

‎src/DingtalkRobot.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -94,8 +94,8 @@ public function robot($name = 'default'): self
9494
throw new InvalidConfigurationException(null, ErrorCodes::ACCESS_TOKEN_IS_NECESSARY);
9595
}
9696

97-
// security_types 只能是允许的值
98-
$securityTypes = Arr::get($config, 'security_types', []);
97+
// security_types 只能是允许的值，默认认为是旧机器人
98+
$securityTypes = Arr::get($config, 'security_types', [null]);
9999
if (! is_array($securityTypes) || count($securityTypes) == 0 ||
100100
count(array_diff($securityTypes, self::SECURITY_TYPES)) != 0
101101
) {

0 commit comments

Comments
 (0)