Add Documentation

Merge branch 'master' into tracer Pass PHPStan
caoqiang1990 · Aug 31, 2019 · bf4ad4a · bf4ad4a
2 parents fcad7ce + 41e53da
commit bf4ad4a
Show file tree

Hide file tree

Showing 62 changed files with 2,748 additions and 160 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -44,5 +44,5 @@ before_script:
   - composer config -g process-timeout 900 && composer update
 
 script:
-  - composer analyse src/di src/json-rpc
+  - composer analyse src/di src/json-rpc src/tracer
   - composer test
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,7 +21,25 @@
 
 - [#448](https://github.com/hyperf-cloud/hyperf/pull/448) Fixed TCP Server does not works when HTTP Server or WebSocket Server exists.
 
-# v1.0.13 - TBD
+# v1.0.14 - TBD
+
+# v1.0.13 - 2019-08-28
+
+## Added
+
+- [#449](https://github.com/hyperf-cloud/hyperf/pull/428) Added an independent component [hyperf/translation](https://github.com/hyperf-cloud/translation), forked by illuminate/translation.
+- [#449](https://github.com/hyperf-cloud/hyperf/pull/449) Added standard error code for grpc-server.
+- [#450](https://github.com/hyperf-cloud/hyperf/pull/450) Added comments of static methods for `Hyperf\Database\Schema\Schema`.
+
+## Changed
+
+- [#451](https://github.com/hyperf-cloud/hyperf/pull/451) Removed routes of magic methods from `AuthController`.
+- [#468](https://github.com/hyperf-cloud/hyperf/pull/468) Default exception handlers catch all exceptions.
+
+## Fixed 
+
+- [#466](https://github.com/hyperf-cloud/hyperf/pull/466) Fixed error when the number of data is not enough to paginate.
+- [#466](https://github.com/hyperf-cloud/hyperf/pull/470) Optimized `vendor:publish` command, if the destination folder exists, then will not repeatedly create the folder.
 
 # v1.0.12 - 2019-08-21
 
@@ -30,6 +48,10 @@
 - [#405](https://github.com/hyperf-cloud/hyperf/pull/405) Added Context::override() method.
 - [#415](https://github.com/hyperf-cloud/hyperf/pull/415) Added handlers configuration for logger, now you could config multiple handlers to logger.
 
+## Changed
+
+- [#431](https://github.com/hyperf-cloud/hyperf/pull/431) The third parameter of Hyperf\GrpcClient\GrpcClient::openStream() have been removed.
+
 ## Fixed
 
 - [#414](https://github.com/hyperf-cloud/hyperf/pull/414) Fixed WebSocketExceptionHandler typo
@@ -39,7 +61,7 @@
 
 ## Deprecated
 
-- [#425](https://github.com/hyperf-cloud/hyperf/pull/425) Marked `Hyperf\HttpServer\HttpServerFactory`, `Hyperf\JsonRpc\HttpServerFactory`, `Hyperf\JsonRpc\TcpServerFactory` as deprecated.
+- [#425](https://github.com/hyperf-cloud/hyperf/pull/425) Marked `Hyperf\HttpServer\HttpServerFactory`, `Hyperf\JsonRpc\HttpServerFactory`, `Hyperf\JsonRpc\TcpServerFactory` as deprecated, will be removed in `v1.1`.
 
 # v1.0.11 - 2019-08-15
 

diff --git a/composer.json b/composer.json
@@ -95,6 +95,7 @@
         "hyperf/swoole-enterprise": "self.version",
         "hyperf/task": "self.version",
         "hyperf/tracer": "self.version",
+        "hyperf/translation": "self.version",
         "hyperf/utils": "self.version",
         "hyperf/view": "self.version",
         "hyperf/websocket-client": "self.version",
@@ -105,6 +106,7 @@
         "files": [
             "src/config/src/Functions.php",
             "src/di/src/Functions.php",
+            "src/translation/src/Functions.php",
             "src/utils/src/Functions.php"
         ],
         "psr-4": {
@@ -160,6 +162,7 @@
             "Hyperf\\Task\\": "src/task/src/",
             "Hyperf\\Testing\\": "src/testing/src/",
             "Hyperf\\Tracer\\": "src/tracer/src/",
+            "Hyperf\\Translation\\": "src/translation/src/",
             "Hyperf\\Utils\\": "src/utils/src/",
             "Hyperf\\View\\": "src/view/src/",
             "Hyperf\\WebSocketClient\\": "src/websocket-client/src/",
@@ -188,6 +191,7 @@
             "HyperfTest\\Etcd\\": "src/etcd/tests/",
             "HyperfTest\\Event\\": "src/event/tests/",
             "HyperfTest\\GrpcClient\\": "src/grpc-client/tests/",
+            "HyperfTest\\GrpcServer\\": "src/grpc-server/tests/",
             "HyperfTest\\Guzzle\\": "src/guzzle/tests/",
             "HyperfTest\\HttpMessage\\": "src/http-message/tests/",
             "HyperfTest\\HttpServer\\": "src/http-server/tests/",
@@ -206,6 +210,7 @@
             "HyperfTest\\Snowflake\\": "src/snowflake/tests/",
             "HyperfTest\\Task\\": "src/task/tests/",
             "HyperfTest\\Testing\\": "src/testing/tests/",
+            "HyperfTest\\Translation\\": "src/translation/tests/",
             "HyperfTest\\Utils\\": "src/utils/tests/",
             "HyperfTest\\WebSocketClient\\": "src/websocket-client/tests/"
         }
@@ -259,6 +264,7 @@
                 "Hyperf\\SwooleEnterprise\\ConfigProvider",
                 "Hyperf\\Task\\ConfigProvider",
                 "Hyperf\\Tracer\\ConfigProvider",
+                "Hyperf\\Translation\\ConfigProvider",
                 "Hyperf\\Utils\\ConfigProvider",
                 "Hyperf\\View\\ConfigProvider",
                 "Hyperf\\WebSocketClient\\ConfigProvider",

diff --git a/doc/zh/logger.md b/doc/zh/logger.md
@@ -1,6 +1,6 @@
 # 日志
 
-`hyperf/logger` 组件是基于 [psr/logger](https://github.com/php-fig/logger) 实现的，默认使用 [monolog/monolog](https://github.com/Seldaek/monolog) 作为驱动，在 `hyperf-skeleton` 项目内默认提供了一些日志配置，默认使用 `Monolog\Handler\StreamHandler`, 由于 `Swoole` 已经对 `fopen`, `fwrite` 等函数进行了协程化处理，所以只要不将 `useLocking` 参数设置为 `true`，就是协程安全的。
+`hyperf/logger` 组件是基于 [psr/logger](https://github.com/php-fig/log) 实现的，默认使用 [monolog/monolog](https://github.com/Seldaek/monolog) 作为驱动，在 `hyperf-skeleton` 项目内默认提供了一些日志配置，默认使用 `Monolog\Handler\StreamHandler`, 由于 `Swoole` 已经对 `fopen`, `fwrite` 等函数进行了协程化处理，所以只要不将 `useLocking` 参数设置为 `true`，就是协程安全的。
 
 ## 安装
 

diff --git a/doc/zh/rate-limit.md b/doc/zh/rate-limit.md
@@ -86,7 +86,7 @@ use Hyperf\RateLimit\Annotation\RateLimit;
 
 /**
  * @Controller(prefix="rate-limit")
- * @RateLimit(limitCallback={RateLimitController::class, 'limitCallback'})
+ * @RateLimit(limitCallback={RateLimitController::class, "limitCallback"})
  */
 class RateLimitController
 {
@@ -107,4 +107,4 @@ class RateLimitController
         return $proceedingJoinPoint->process();
     }
 }
-```
+```
diff --git a/doc/zh/summary.md b/doc/zh/summary.md
@@ -35,6 +35,7 @@
   * [命令行](zh/command.md)
   * [自动化测试](zh/testing.md)
   * [视图](zh/view.md)
+  * [国际化](zh/translation.md)
 
 * 数据库模型
 

diff --git a/doc/zh/tracer.md b/doc/zh/tracer.md
@@ -1,7 +1,7 @@
 # 调用链追踪
 
 在微服务场景下，我们会拆分出来很多的服务，也就意味着一个业务请求，少则跨越 3-4 个服务，多则几十个甚至更多，在这种架构下我们需要对某一个问题进行 Debug 的时候是极其困难的一件事情，那么我们就需要一个调用链追踪系统来帮助我们动态地展示服务调用的链路，以便我们可以快速地对问题点进行定位，亦可根据链路信息对服务进行调优。   
-在 `Hyperf` 里我们提供了 [hyperf/tracer](https://github.com/hyperf-cloud/tracer) 组件来对各个跨网络请求来进行调用的追踪以及分析，目前仅根据 [Opentracing](https://opentracing.io) 协议对接了 [Zipkin](https://zipkin.io/) 系统。
+在 `Hyperf` 里我们提供了 [hyperf/tracer](https://github.com/hyperf-cloud/tracer) 组件来对各个跨网络请求来进行调用的追踪以及分析，目前根据 [OpenTracing](https://opentracing.io) 协议对接了 [Zipkin](https://zipkin.io/) 系统和[Jaeger](https://www.jaegertracing.io/)系统，用户也可以根据OpenTracing协议定制实现。
 
 ## 安装
 
@@ -11,6 +11,12 @@
 composer require hyperf/tracer
 ```
 
+hyperf/tracer默认安装了Zipkin相关依赖。如果要使用Jaeger，还需要执行：
+
+```bash
+composer require jonahgeorge/jaeger-client-php
+```
+
 ### 增加组件配置
 
 如文件不存在，可执行下面的命令增加 `config/autoload/opentracing.php` 配置文件：
@@ -23,6 +29,8 @@ php bin/hyperf.php vendor:publish
 
 ### 配置
 
+- 配置追踪开关
+
 默认提供了对 `Guzzle HTTP` 调用、`Redis` 调用、`DB` 调用进行了监听或 `AOP` 切面处理，以实现对调用链的传播与追踪，默认情况下这些追踪不会打开，您需要通过更改 `config/autoload/opentracing.php` 配置文件内的 `enable` 项内的开关来打开对某些远程调用的追踪。
 
 ```php
@@ -36,44 +44,125 @@ return [
         'redis' => false,
         // 打开或关闭对 DB  调用的追踪
         'db' => false,
+        // 打开或关闭对方法调用的追踪
+        'method' => false,
     ],
 ];
 ```
 
-在开始追踪之前我们还需要配置一下 `zipkin` 的服务配置，还是在同一个文件下
+在开始追踪之前，我们还需要选择所使用的Tracer驱动，并对Tracer进行配置。
+
+- 选择追踪器驱动
+
+在同一配置文件中，我们要增加'default'这一项，它对应的值则为默认使用的驱动名称。驱动的具体配置在'opentracing.tracer'项下定义。
+
+```php
+<?php
+
+return [
+    // 选择默认的Tracer驱动。所选Tracer名称对应'opentracing.tracers'下定义的键。
+    'default' => env('TRACER_DRIVER', 'staging_zipkin'),
+
+    // 这里暂时省略其他配置
+    'enable' => [],
+
+    'tracer' => [
+        'staging_zipkin' => [
+            'driver' => Hyperf\Tracer\Adapter\ZipkinTracerFactory::class,
+            // Zipkin配置
+        ],
+        'producton_zipkin' => [
+            'driver' => Hyperf\Tracer\Adapter\ZipkinTracerFactory::class,
+            // 另一套Zipkin配置
+        ],
+        'jaeger' => [
+            'driver' => Hyperf\Tracer\Adapter\JaegerTracerFactory::class,
+            // Jaeger配置
+        ],
+    ]
+]
+```
+
+注意，如示例所示，您可以配置多套Zipkin驱动或Jaeger驱动。虽然采用的底层系统一样，但他们的具体配置可以不同。一种常见情况是我们希望测试环境100%采样，但在生产环境下1%采样，就可以配置两套驱动，然后根据default项下的环境变量来选择不同的驱动。
+
+- 配置Zipkin
+
+使用Zipkin时，还是在同一个文件下，在'opentracing.tracer'项增加Zipkin的具体配置。
 
 ```php
 <?php
 use Zipkin\Samplers\BinarySampler;
 
 return [
+    // 选择默认的Tracer。
+    'default' => env('TRACER_DRIVER', 'zipkin'),
+
     // 这里的代码演示不对 enable 内的配置进行展开
     'enable' => [],
-    // zipkin 服务配置
-    'zipkin' => [
-        // 当前应用的配置
-        'app' => [
-            'name' => env('APP_NAME', 'skeleton'),
-            // 如果 ipv6 和 ipv6 为空组件会自动从 Server 中检测
-            'ipv4' => '127.0.0.1',
-            'ipv6' => null,
-            'port' => 9501,
+
+    'tracer' => [
+        // zipkin 驱动配置
+        'zipkin' => [
+            // 当前应用的配置
+            'app' => [
+                'name' => env('APP_NAME', 'skeleton'),
+                // 如果 ipv6 和 ipv6 为空组件会自动从 Server 中检测
+                'ipv4' => '127.0.0.1',
+                'ipv6' => null,
+                'port' => 9501,
+            ],
+            'options' => [
+                // zipkin 服务的 endpoint 地址
+                'endpoint_url' => env('ZIPKIN_ENDPOINT_URL', 'http://localhost:9411/api/v2/spans'),
+                // 请求超时秒数
+                'timeout' => env('ZIPKIN_TIMEOUT', 1),
+            ],
+            // 采样器，默认为所有请求的都追踪
+            'sampler' => BinarySampler::createAsAlwaysSample(),
         ],
-        'options' => [
-            // zipkin 服务的 endpoint 地址
-            'endpoint_url' => env('ZIPKIN_ENDPOINT_URL', 'http://localhost:9411/api/v2/spans'),
-            // 请求超时秒数
-            'timeout' => env('ZIPKIN_TIMEOUT', 1),
+    ],
+]
+```
+
+- 配置Jaeger
+
+使用Jaeger时，还是在同一个文件下，在'opentracing.tracer'项增加Jaeger的具体配置。
+
+```php
+return [
+    // 选择默认的Tracer。
+    'default' => env('TRACER_DRIVER', 'jaeger'),
+
+    // 这里的代码演示不对 enable 内的配置进行展开
+    'enable' => [],
+
+    'tracer' => [
+        // jaeger 驱动配置
+        'jaeger' => [
+            'driver' => Hyperf\Tracer\Adapter\JaegerTracerFactory::class,
+            // 项目名称
+            'name' => env('APP_NAME', 'skeleton'),
+            'options' => [
+                // 采样器，默认为所有请求的都追踪
+                'sampler' => [
+                    'type' => \Jaeger\SAMPLER_TYPE_CONST,
+                    'param' => true,
+                ],,
+                // 上报地址
+                'local_agent' => [
+                    'reporting_host' => env('JAEGER_REPORTING_HOST', 'localhost'),
+                    'reporting_port' => env('JAEGER_REPORTING_PORT', 5775),
+                ],
+            ],
         ],
-        // 采样器，默认为所有请求的都追踪
-        'sampler' => BinarySampler::createAsAlwaysSample(),
     ],
 ];
 ```
+关于Jaeger的更多配置可以在[这里](https://github.com/jonahgeorge/jaeger-client-php)查看。
 
 ### 配置中间件
 
-配置完 zipkin 之后，采集信息还需要配置一下中间件才能启用采集功能。
+配置完驱动之后，采集信息还需要配置一下中间件才能启用采集功能。
 打开 `config/autoload/middlewares.php` 文件，在 `http` 节点启用中间件。
 
 ```php
@@ -92,14 +181,19 @@ return [
 
 ### 更换采样器
 
-默认的采样器为所有请求都记录调用链，这对性能会存在一定程度上的影响，尤其是内存的占用，所以我们只需要在我们希望的时候才对调用链进行追踪，那么我们就需要对采样器进行更换，更换也很简单，只需对配置项 `opentracing.zipkin.sampler` 对应的值改为您的采样器对象实例即可，只要您的采样器对象实现了 `Zipkin\Sampler` 接口类即可。
+默认的采样器为所有请求都记录调用链，这对性能会存在一定程度上的影响，尤其是内存的占用，所以我们只需要在我们希望的时候才对调用链进行追踪，那么我们就需要对采样器进行更换，更换也很简单，以Zipkin为例，只需对配置项 `opentracing.zipkin.sampler` 对应的值改为您的采样器对象实例即可，只要您的采样器对象实现了 `Zipkin\Sampler` 接口类即可。
 
 ### 接入阿里云链路追踪服务
 
 当我们在使用阿里云的链路追踪服务时，由于对端也是支持 `Zipkin` 的协议的，故可以直接通过在 `condif/autoload/opentracing.php` 配置文件内修改 `endpoint_url` 的值为您对应的阿里云 `region` 的地址，具体地址可在阿里云的链路追踪服务内得到，更多细节可参考 [阿里云链路追踪服务帮助文档](https://help.aliyun.com/document_detail/100031.html?spm=a2c4g.11186623.6.547.68f974dcZlg4Mv)。
 
+### 使用其他Tracer驱动
+
+您也可以使用其他任意符合OpenTracing协议的Tracer驱动。在Driver项中，填写任意实现了`Hyperf\Tracer\Contract\NamedFactoryInterface`的类就可以了。该接口只有一个make函数，参数为驱动名称，需返回一个实现了OpenTracing\Tracer的实例。
+
 ## Reference
 
 - [Opentracing](https://opentracing.io)
 - [Zipkin](https://zipkin.io/)
+- [Jaeger](https://www.jaegertracing.io/)
 - [Dapper, 大规模分布式系统的跟踪系统](https://bigbully.github.io/Dapper-translation/)