From a8e0fc3a15ff1ac1b1d48c491c0f7018c79c2749 Mon Sep 17 00:00:00 2001 From: huangzhhui Date: Mon, 21 Nov 2022 15:40:45 +0800 Subject: [PATCH 1/7] Update --- docs/en/release-planning.md | 16 ++++++++-------- docs/zh-cn/release-planning.md | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/en/release-planning.md b/docs/en/release-planning.md index d45989f9f..b379072ca 100644 --- a/docs/en/release-planning.md +++ b/docs/en/release-planning.md @@ -2,14 +2,14 @@ ## Life cycle -| Version | Status | End of mainstream support | End of Security-fixes support | Release Date (or estimated date) | -| ------- | ------------------ | ------------------------- | ----------------------------- | -------------------------------- | -| 3.0 | Developing (RC1 has been released) | 2023-06-20 | 2023-12-31 | 2022-08-30~2022-09-30 | -| 2.2 | Mainstream Support | 2022-06-20 | 2022-12-31 | 2021-07-19 | -| 2.1 | Deprecated | 2021-06-30 | 2021-12-31 | 2020-12-28 | -| 2.0 | Deprecated | 2020-12-28 | 2021-06-30 | 2020-06-22 | -| 1.1 | Deprecated | 2020-06-23 | 2020-12-31 | 2019-10-08 | -| 1.0 | Deprecated | 2019-10-08 | 2019-12-31 | 2019-06-20 | +| Version | Status | End of mainstream support | End of Security-fixes support | Release Date (or estimated date) | +| ------- |-------------------------------------|---------------------------|-------------------------------|----------------------------------| +| 3.0 | Developing (RC13 has been released) | 2023-06-30 | 2023-12-31 | About 2022-12-31 | +| 2.2 | Security fixes support | 2022-06-20 | 2023-6-30 | 2021-07-19 | +| 2.1 | Deprecated | 2021-06-30 | 2021-12-31 | 2020-12-28 | +| 2.0 | Deprecated | 2020-12-28 | 2021-06-30 | 2020-06-22 | +| 1.1 | Deprecated | 2020-06-23 | 2020-12-31 | 2019-10-08 | +| 1.0 | Deprecated | 2019-10-08 | 2019-12-31 | 2019-06-20 | * Mainstream support including BUG fixes, security fixes, function upgrade and new functions support in a regular iteration cycles; * Security fixes support only includes the fixes of security issues; diff --git a/docs/zh-cn/release-planning.md b/docs/zh-cn/release-planning.md index 42c016a9f..441fbb8dc 100644 --- a/docs/zh-cn/release-planning.md +++ b/docs/zh-cn/release-planning.md @@ -2,14 +2,14 @@ ## 版本生命周期 -| 版本 | 状态 | 积极支持截止时间 | 安全维护截止时间 | 发布或预计发布时间 | -| ---- |--------|------------|------------|------------| -| 3.0 | 研发中 (RC1已发布) | 2023-06-20 | 2023-12-31 | 2022-08-30~2022-09-30 | -| 2.2 | 积极支持中 | 2022-06-20 | 2022-12-31 | 2021-07-19 | -| 2.1 | 停止维护 | 2021-06-30 | 2021-12-31 | 2020-12-28 | -| 2.0 | 停止维护 | 2020-12-28 | 2021-06-30 | 2020-06-22 | -| 1.1 | 停止维护 | 2020-06-23 | 2020-12-31 | 2019-10-08 | -| 1.0 | 停止维护 | 2019-10-08 | 2019-12-31 | 2019-06-20 | +| 版本 | 状态 | 积极支持截止时间 | 安全维护截止时间 | 发布或预计发布时间 | +| ---- |----------------|------------|------------|---------------| +| 3.0 | 研发中 (RC13 已发布) | 2023-06-30 | 2023-12-31 | 大概 2022-12-31 | +| 2.2 | 安全维护 | 2022-06-20 | 2023-06-30 | 2021-07-19 | +| 2.1 | 停止维护 | 2021-06-30 | 2021-12-31 | 2020-12-28 | +| 2.0 | 停止维护 | 2020-12-28 | 2021-06-30 | 2020-06-22 | +| 1.1 | 停止维护 | 2020-06-23 | 2020-12-31 | 2019-10s-08 | +| 1.0 | 停止维护 | 2019-10-08 | 2019-12-31 | 2019-06-20 | * 积极支持将包含常规迭代周期的 BUG 修复、安全问题修复、功能迭代和功能新增； * 安全维护仅包含安全问题的修复； From 83678582c3efb74d8e2d5c0b0a0ef377c0a68c46 Mon Sep 17 00:00:00 2001 From: huangzhhui Date: Mon, 21 Nov 2022 07:41:58 +0000 Subject: [PATCH 2/7] Update docs and translate --- docs/zh-hk/release-planning.md | 16 ++++++++-------- docs/zh-tw/release-planning.md | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/zh-hk/release-planning.md b/docs/zh-hk/release-planning.md index d3ce8f8fd..eaebc0f05 100644 --- a/docs/zh-hk/release-planning.md +++ b/docs/zh-hk/release-planning.md @@ -2,14 +2,14 @@ ## 版本生命週期 -| 版本 | 狀態 | 積極支持截止時間 | 安全維護截止時間 | 發佈或預計發佈時間 | -| ---- |--------|------------|------------|------------| -| 3.0 | 研發中 (RC1已發佈) | 2023-06-20 | 2023-12-31 | 2022-08-30~2022-09-30 | -| 2.2 | 積極支持中 | 2022-06-20 | 2022-12-31 | 2021-07-19 | -| 2.1 | 停止維護 | 2021-06-30 | 2021-12-31 | 2020-12-28 | -| 2.0 | 停止維護 | 2020-12-28 | 2021-06-30 | 2020-06-22 | -| 1.1 | 停止維護 | 2020-06-23 | 2020-12-31 | 2019-10-08 | -| 1.0 | 停止維護 | 2019-10-08 | 2019-12-31 | 2019-06-20 | +| 版本 | 狀態 | 積極支持截止時間 | 安全維護截止時間 | 發佈或預計發佈時間 | +| ---- |----------------|------------|------------|---------------| +| 3.0 | 研發中 (RC13 已發佈) | 2023-06-30 | 2023-12-31 | 大概 2022-12-31 | +| 2.2 | 安全維護 | 2022-06-20 | 2023-06-30 | 2021-07-19 | +| 2.1 | 停止維護 | 2021-06-30 | 2021-12-31 | 2020-12-28 | +| 2.0 | 停止維護 | 2020-12-28 | 2021-06-30 | 2020-06-22 | +| 1.1 | 停止維護 | 2020-06-23 | 2020-12-31 | 2019-10s-08 | +| 1.0 | 停止維護 | 2019-10-08 | 2019-12-31 | 2019-06-20 | * 積極支持將包含常規迭代週期的 BUG 修復、安全問題修復、功能迭代和功能新增； * 安全維護僅包含安全問題的修復； diff --git a/docs/zh-tw/release-planning.md b/docs/zh-tw/release-planning.md index c64c0cf20..2e8f1d604 100644 --- a/docs/zh-tw/release-planning.md +++ b/docs/zh-tw/release-planning.md @@ -2,14 +2,14 @@ ## 版本生命週期 -| 版本 | 狀態 | 積極支援截止時間 | 安全維護截止時間 | 釋出或預計釋出時間 | -| ---- |--------|------------|------------|------------| -| 3.0 | 研發中 (RC1已釋出) | 2023-06-20 | 2023-12-31 | 2022-08-30~2022-09-30 | -| 2.2 | 積極支援中 | 2022-06-20 | 2022-12-31 | 2021-07-19 | -| 2.1 | 停止維護 | 2021-06-30 | 2021-12-31 | 2020-12-28 | -| 2.0 | 停止維護 | 2020-12-28 | 2021-06-30 | 2020-06-22 | -| 1.1 | 停止維護 | 2020-06-23 | 2020-12-31 | 2019-10-08 | -| 1.0 | 停止維護 | 2019-10-08 | 2019-12-31 | 2019-06-20 | +| 版本 | 狀態 | 積極支援截止時間 | 安全維護截止時間 | 釋出或預計釋出時間 | +| ---- |----------------|------------|------------|---------------| +| 3.0 | 研發中 (RC13 已釋出) | 2023-06-30 | 2023-12-31 | 大概 2022-12-31 | +| 2.2 | 安全維護 | 2022-06-20 | 2023-06-30 | 2021-07-19 | +| 2.1 | 停止維護 | 2021-06-30 | 2021-12-31 | 2020-12-28 | +| 2.0 | 停止維護 | 2020-12-28 | 2021-06-30 | 2020-06-22 | +| 1.1 | 停止維護 | 2020-06-23 | 2020-12-31 | 2019-10s-08 | +| 1.0 | 停止維護 | 2019-10-08 | 2019-12-31 | 2019-06-20 | * 積極支援將包含常規迭代週期的 BUG 修復、安全問題修復、功能迭代和功能新增； * 安全維護僅包含安全問題的修復； From f2bdc6e564586d0dbbc6025d4e4fc32425a299c8 Mon Sep 17 00:00:00 2001 From: huangzhhui Date: Mon, 21 Nov 2022 16:06:45 +0800 Subject: [PATCH 3/7] Update the sec-fixes support date --- docs/en/release-planning.md | 2 +- docs/zh-cn/release-planning.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/release-planning.md b/docs/en/release-planning.md index b379072ca..da336babe 100644 --- a/docs/en/release-planning.md +++ b/docs/en/release-planning.md @@ -4,7 +4,7 @@ | Version | Status | End of mainstream support | End of Security-fixes support | Release Date (or estimated date) | | ------- |-------------------------------------|---------------------------|-------------------------------|----------------------------------| -| 3.0 | Developing (RC13 has been released) | 2023-06-30 | 2023-12-31 | About 2022-12-31 | +| 3.0 | Developing (RC13 has been released) | 2023-06-30 | 2024-06-30 | About 2022-12-31 | | 2.2 | Security fixes support | 2022-06-20 | 2023-6-30 | 2021-07-19 | | 2.1 | Deprecated | 2021-06-30 | 2021-12-31 | 2020-12-28 | | 2.0 | Deprecated | 2020-12-28 | 2021-06-30 | 2020-06-22 | diff --git a/docs/zh-cn/release-planning.md b/docs/zh-cn/release-planning.md index 441fbb8dc..2d3a1848b 100644 --- a/docs/zh-cn/release-planning.md +++ b/docs/zh-cn/release-planning.md @@ -4,7 +4,7 @@ | 版本 | 状态 | 积极支持截止时间 | 安全维护截止时间 | 发布或预计发布时间 | | ---- |----------------|------------|------------|---------------| -| 3.0 | 研发中 (RC13 已发布) | 2023-06-30 | 2023-12-31 | 大概 2022-12-31 | +| 3.0 | 研发中 (RC13 已发布) | 2023-06-30 | 2024-06-30 | 大概 2022-12-31 | | 2.2 | 安全维护 | 2022-06-20 | 2023-06-30 | 2021-07-19 | | 2.1 | 停止维护 | 2021-06-30 | 2021-12-31 | 2020-12-28 | | 2.0 | 停止维护 | 2020-12-28 | 2021-06-30 | 2020-06-22 | From fff4cb5e2c8fa0d9e6cdcc42fcbb3583776c11e0 Mon Sep 17 00:00:00 2001 From: huangzhhui Date: Wed, 23 Nov 2022 11:14:43 +0800 Subject: [PATCH 4/7] Update --- docs/en/db/model.md | 226 ++++++++++++++++++++++------ docs/zh-cn/db/model.md | 47 +++++- docs/zh-cn/quick-start/questions.md | 38 ----- 3 files changed, 223 insertions(+), 88 deletions(-) diff --git a/docs/en/db/model.md b/docs/en/db/model.md index bbd727ec9..abc336515 100644 --- a/docs/en/db/model.md +++ b/docs/en/db/model.md @@ -7,16 +7,65 @@ Hyperf 提供了创建模型的命令，您可以很方便的根据数据表创建对应模型。命令通过 `AST` 生成模型，所以当您增加了某些方法后，也可以使用脚本方便的重置模型。 ``` -$ php bin/hyperf.php db:model table_name +php bin/hyperf.php gen:model table_name ``` -创建的模型如下 +可选参数如下： + +| 参数 | 类型 | 默认值 | 备注 | +| :----------------: | :----: | :-------------------------------: | :-----------------------------------------------: | +| --pool | string | `default` | 连接池，脚本会根据当前连接池配置创建 | +| --path | string | `app/Model` | 模型路径 | +| --force-casts | bool | `false` | 是否强制重置 `casts` 参数 | +| --prefix | string | 空字符串 | 表前缀 | +| --inheritance | string | `Model` | 父类 | +| --uses | string | `Hyperf\DbConnection\Model\Model` | 配合 `inheritance` 使用 | +| --refresh-fillable | bool | `false` | 是否刷新 `fillable` 参数 | +| --table-mapping | array | `[]` | 为表名 -> 模型增加映射关系 比如 ['users:Account'] | +| --ignore-tables | array | `[]` | 不需要生成模型的表名 比如 ['users'] | +| --with-comments | bool | `false` | 是否增加字段注释 | +| --property-case | int | `0` | 字段类型 0 蛇形 1 驼峰 | + +当使用 `--property-case` 将字段类型转化为驼峰时，还需要手动在模型中加入 `Hyperf\Database\Model\Concerns\CamelCase`。 + +对应配置也可以配置到 `databases.{pool}.commands.gen:model` 中，如下 + +> 中划线都需要转化为下划线 + ```php [ + // 忽略其他配置 + 'commands' => [ + 'gen:model' => [ + 'path' => 'app/Model', + 'force_casts' => true, + 'inheritance' => 'Model', + 'uses' => '', + 'refresh_fillable' => true, + 'table_mapping' => [], + 'with_comments' => true, + 'property_case' => ModelOption::PROPERTY_SNAKE_CASE, + ], + ], + ], +]; +``` + +创建的模型如下 + +```php +where('id', 1)->first(); @@ -203,7 +254,8 @@ $user->save(); 你可以使用 `fresh` 和 `refresh` 方法重新加载模型。 `fresh` 方法会重新从数据库中检索模型。现有的模型实例不受影响： ```php -use App\Models\User; +find(1); @@ -214,7 +266,8 @@ $freshUser = $user->fresh(); `refresh` 方法使用数据库中的新数据重新赋值现有模型。此外，已经加载的关系会被重新加载： ```php -use App\Models\User; +where('name','Hyperf')->first(); @@ -242,7 +295,8 @@ $users = $users->reject(function ($user) { 除了从指定的数据表检索所有记录外，你可以使用 `find` 或 `first` 方法来检索单条记录。这些方法返回单个模型实例，而不是返回模型集合： ```php -use App\Models\User; +where('id', 1)->first(); @@ -254,46 +308,61 @@ $user = User::query()->find(1); 当然 `find` 的方法不止支持单个模型。 ```php -use App\Models\User; +find([1, 2, 3]); ``` +### 『未找到』异常 + +有时你希望在未找到模型时抛出异常，这在控制器和路由中非常有用。 +`findOrFail` 和 `firstOrFail` 方法会检索查询的第一个结果，如果未找到，将抛出 `Hyperf\Database\Model\ModelNotFoundException` 异常： + +```php +', 18)->firstOrFail(); +``` + ### 聚合函数 你还可以使用 查询构造器 提供的 `count`，`sum`, `max`, 和其他的聚合函数。这些方法只会返回适当的标量值而不是一个模型实例： ```php -use App\Models\User; +where('gender', 1)->count(); ``` -## 插入&更新模型 +## 插入 & 更新模型 ### 插入 要往数据库新增一条记录，先创建新模型实例，给实例设置属性，然后调用 `save` 方法： ```php -use App\Models\User; +use App\Model\User; /** @var User $user */ $user = new User(); -$user->name = 'Hi Hyperf'; +$user->name = 'Hyperf'; $user->save(); ``` -在这个示例中，我们赋值给了 `App\Models\User` 模型实例的 `name` 属性。当调用 `save` 方法时，将会插入一条新记录。 `created_at` 和 `updated_at` 时间戳将会自动设置，不需要手动赋值。 +在这个示例中，我们赋值给了 `App\Model\User` 模型实例的 `name` 属性。当调用 `save` 方法时，将会插入一条新记录。 `created_at` 和 `updated_at` 时间戳将会自动设置，不需要手动赋值。 ### 更新 `save` 方法也可以用来更新数据库已经存在的模型。更新模型，你需要先检索出来，设置要更新的属性，然后调用 `save` 方法。同样， `updated_at` 时间戳会自动更新，所以也不需要手动赋值： ```php -use App\Models\User; +use App\Model\User; /** @var User $user */ $user = User::query()->find(1); @@ -305,15 +374,15 @@ $user->save(); ### 批量更新 -也可以更新匹配查询条件的多个模型。在这个示例中，所有的 `gender` 为1的用户，修改 `gender_show` 为 男性： +也可以更新匹配查询条件的多个模型。在这个示例中，所有的 `gender` 为 `1` 的用户，修改 `gender_show` 为 男性： ```php -use App\Models\User; +use App\Model\User; User::query()->where('gender', 1)->update(['gender_show' => '男性']); ``` -> 批量更新时， 更新的模型不会触发 saved 和 updated 事件。因为在批量更新时，从不会去检索模型。 +> 批量更新时， 更新的模型不会触发 `saved` 和 `updated` 事件。因为在批量更新时，并没有实例化模型。同时，也不会执行相应的 `casts`，例如数据库中 `json` 格式，在 Model 类中 `casts` 字段标记为 `array`，若是用批量更新，则插入时不会自动将 `array` 转换为 `json` 字符串格式。 ### 批量赋值 @@ -328,7 +397,7 @@ User::query()->where('gender', 1)->update(['gender_show' => '男性']); declare(strict_types=1); -namespace App\Models; +namespace App\Model; use Hyperf\DbConnection\Model\Model; @@ -341,7 +410,7 @@ class User extends Model 一旦我们设置好了可以批量赋值的属性，就可以通过 `create` 方法插入新数据到数据库中了。 `create` 方法将返回保存的模型实例： ```php -use App\Models\User; +use App\Model\User; $user = User::create(['name' => 'Hyperf']); ``` @@ -361,7 +430,7 @@ $user->fill(['name' => 'Hyperf']); declare(strict_types=1); -namespace App\Models; +namespace App\Model; use Hyperf\DbConnection\Model\Model; @@ -371,12 +440,45 @@ class User extends Model } ``` +### 其他创建方法 + +`firstOrCreate` / `firstOrNew` + +这里有两个你可能用来批量赋值的方法： `firstOrCreate` 和 `firstOrNew`。 + +`firstOrCreate` 方法会通过给定的 列 / 值 来匹配数据库中的数据。如果在数据库中找不到对应的模型， 则会从第一个参数的属性乃至第二个参数的属性中创建一条记录插入到数据库。 + +`firstOrNew` 方法像 `firstOrCreate` 方法一样尝试通过给定的属性查找数据库中的记录。不同的是，如果 `firstOrNew` 方法找不到对应的模型，会返回一个新的模型实例。注意 `firstOrNew` 返回的模型实例尚未保存到数据库中，你需要手动调用 `save` 方法来保存： + +```php + 'Hyperf']); + +// 通过 name 查找用户，不存在则使用 name 和 gender, age 属性创建... +$user = User::firstOrCreate( + ['name' => 'Hyperf'], + ['gender' => 1, 'age' => 20] +); + +// 通过 name 查找用户，不存在则创建一个实例... +$user = User::firstOrNew(['name' => 'Hyperf']); + +// 通过 name 查找用户，不存在则使用 name 和 gender, age 属性创建一个实例... +$user = User::firstOrNew( + ['name' => 'Hyperf'], + ['gender' => 1, 'age' => 20] +); +``` + ### 删除模型 可以在模型实例上调用 `delete` 方法来删除实例： ```php -use App\Models\User; +use App\Model\User; $user = User::query()->find(1); @@ -388,7 +490,7 @@ $user->delete(); 您可通过在查询上调用 `delete` 方法来删除模型数据，在这个例子中，我们将删除所有 `gender` 为 `1` 的用户。与批量更新一样，批量删除不会为删除的模型启动任何模型事件： ```php -use App\Models\User; +use App\Model\User; // 注意使用 delete 方法时必须建立在某些查询条件基础之上才能安全删除数据，不存在 where 条件，会导致删除整个数据表 User::query()->where('gender', 1)->delete(); @@ -399,7 +501,7 @@ User::query()->where('gender', 1)->delete(); 在上面的例子中，在调用 `delete` 之前需要先去数据库中查找对应的模型。事实上，如果你知道了模型的主键，您可以直接通过 `destroy` 静态方法来删除模型数据，而不用先去数据库中查找。 `destroy` 方法除了接受单个主键作为参数之外，还接受多个主键，或者使用数组，集合来保存多个主键： ```php -use App\Models\User; +use App\Model\User; User::destroy(1); @@ -415,14 +517,52 @@ User::destroy([1,2,3]); ```php resume(); ``` - -## ORM 不支持 bit 类型 - -若想要使 `ORM` 支持 `bit` 类型，只需要增加以下监听器代码即可。 - -```php - Date: Wed, 23 Nov 2022 03:16:00 +0000 Subject: [PATCH 5/7] Update docs and translate --- docs/zh-hk/db/model.md | 47 ++++++++++++++++++++++++----- docs/zh-hk/quick-start/questions.md | 38 ----------------------- docs/zh-tw/db/model.md | 47 ++++++++++++++++++++++++----- docs/zh-tw/quick-start/questions.md | 38 ----------------------- 4 files changed, 80 insertions(+), 90 deletions(-) diff --git a/docs/zh-hk/db/model.md b/docs/zh-hk/db/model.md index 619b2ee99..f581405a3 100644 --- a/docs/zh-hk/db/model.md +++ b/docs/zh-hk/db/model.md @@ -6,14 +6,8 @@ Hyperf 提供了創建模型的命令，您可以很方便的根據數據表創建對應模型。命令通過 `AST` 生成模型，所以當您增加了某些方法後，也可以使用腳本方便的重置模型。 -1.1.0 + 版本： ``` -$ php bin/hyperf.php gen:model table_name -``` - -1.0.* 版本： -``` -$ php bin/hyperf.php db:model table_name +php bin/hyperf.php gen:model table_name ``` 可選參數如下： @@ -533,3 +527,42 @@ class User extends Model use SoftDeletes; } ``` + +## Bit 類型 + +默認情況下，Hyperf 中的數據庫模型轉 SQL 過程中，會將參數值統一轉為 String 類型，以解決 int 在大數問題和使值類型更容易匹配索引，若想要使 `ORM` 支持 `bit` 類型，只需要增加以下事件監聽器代碼即可。 + +```php +resume(); ``` - -## ORM 不支持 bit 類型 - -若想要使 `ORM` 支持 `bit` 類型，只需要增加以下監聽器代碼即可。 - -```php -resume(); ``` - -## ORM 不支援 bit 型別 - -若想要使 `ORM` 支援 `bit` 型別，只需要增加以下監聽器程式碼即可。 - -```php - Date: Wed, 23 Nov 2022 11:35:34 +0800 Subject: [PATCH 6/7] Update --- docs/en/component-guide/configprovider.md | 104 ++++++++++++++++++++++ docs/en/component-guide/create.md | 49 ++++++++++ docs/en/component-guide/intro.md | 12 +-- docs/en/release-planning.md | 2 +- docs/zh-cn/release-planning.md | 4 +- 5 files changed, 162 insertions(+), 9 deletions(-) create mode 100644 docs/en/component-guide/configprovider.md create mode 100644 docs/en/component-guide/create.md diff --git a/docs/en/component-guide/configprovider.md b/docs/en/component-guide/configprovider.md new file mode 100644 index 000000000..2ff2d90ef --- /dev/null +++ b/docs/en/component-guide/configprovider.md @@ -0,0 +1,104 @@ +# ConfigProvider 机制 + +ConfigProvider 机制对于 Hyperf 组件化来说是个非常重要的机制，`组件间的解耦` 和 `组件的独立性` 以及 `组件的可重用性` 都是基于这个机制才得以实现。 + +# 什么是 ConfigProvider 机制 ？ + +简单来说，就是每个组件都会提供一个 `ConfigProvider`，通常是在组件的根目录提供一个 `ConfigProvider` 的类，`ConfigProvider` 会提供对应组件的所有配置信息，这些信息都会被 Hyperf 框架在启动时加载，最终`ConfigProvider` 内的配置信息会被合并到 `Hyperf\Contract\ConfigInterface` 对应的实现类去，从而实现各个组件在 Hyperf 框架下使用时要进行的配置初始化。 + +`ConfigProvider` 本身不具备任何依赖，不继承任何的抽象类和不要求实现任何的接口，只需提供一个 `__invoke` 方法并返回一个对应配置结构的数组即可。 + +# 如何定义一个 ConfigProvider ？ + +通常来说，`ConfigProvider` 会定义在组件的根目录下，一个 `ConfigProvider` 类通常如下： + +```php + [], + // 合并到 config/autoload/annotations.php 文件 + 'annotations' => [ + 'scan' => [ + 'paths' => [ + __DIR__, + ], + ], + ], + // 默认 Command 的定义，合并到 Hyperf\Contract\ConfigInterface 内，换个方式理解也就是与 config/autoload/commands.php 对应 + 'commands' => [], + // 与 commands 类似 + 'listeners' => [], + // 组件默认配置文件，即执行命令后会把 source 的对应的文件复制为 destination 对应的的文件 + 'publish' => [ + [ + 'id' => 'config', + 'description' => 'description of this config file.', // 描述 + // 建议默认配置放在 publish 文件夹中，文件命名和组件名称相同 + 'source' => __DIR__ . '/../publish/file.php', // 对应的配置文件路径 + 'destination' => BASE_PATH . '/config/autoload/file.php', // 复制为这个路径下的该文件 + ], + ], + // 亦可继续定义其它配置，最终都会合并到与 ConfigInterface 对应的配置储存器中 + ]; + } +} +``` + +## 默认配置文件说明 + +在 `ConfigProvider` 中定义好 `publish` 后，可以使用如下命令快速生成配置文件 + +```bash +php bin/hyperf.php vendor:publish 包名称 +``` + +如包名称为 `hyperf/amqp`，可执行命令来生成 `amqp` 默认的配置文件 +```bash +php bin/hyperf.php vendor:publish hyperf/amqp +``` + +只创建一个类并不会被 Hyperf 自动的加载，您仍需在组件的 `composer.json` 添加一些定义，告诉 Hyperf 这是一个 ConfigProvider 类需要被加载，您需要在组件内的 `composer.json` 文件内增加 `extra.hyperf.config` 配置，并指定对应的 `ConfigProvider` 类的命名空间，如下所示： + +```json +{ + "name": "hyperf/foo", + "require": { + "php": ">=7.3" + }, + "autoload": { + "psr-4": { + "Hyperf\\Foo\\": "src/" + } + }, + "extra": { + "hyperf": { + "config": "Hyperf\\Foo\\ConfigProvider" + } + } +} +``` + +定义了之后需执行 `composer install` 或 `composer update` 或 `composer dump-autoload` 等会让 Composer 重新生成 `composer.lock` 文件的命令，才能被正常读取。 + +# ConfigProvider 机制的执行流程 + +关于 `ConfigProvider` 的配置并非一定就是这样去划分，这是一些约定成俗的格式，实际上最终如何来解析这些配置的决定权也在于用户，用户可通过修改 Skeleton 项目的 `config/container.php` 文件内的代码来调整相关的加载，也就意味着，`config/container.php` 文件决定了 `ConfigProvider` 的扫描和加载。 + +# 组件设计规范 + +由于 `composer.json` 内的 `extra` 属性在数据不被利用时无其它作用和影响，故这些组件内的定义在其它框架使用时，不会造成任何的干扰和影响，故`ConfigProvider` 是一种仅作用于 Hyperf 框架的机制，对其它没有利用此机制的框架不会造成任何的影响，这也就为组件的复用打下了基础，但这也要求在进行组件设计时，必须遵循以下规范： + +- 所有类的设计都必须允许通过标准 `OOP` 的使用方式来使用，所有 Hyperf 专有的功能必须作为增强功能并以单独的类来提供，也就意味着在非 Hyperf 框架下仍能通过标准的手段来实现组件的使用； +- 组件的依赖设计如果可满足 [PSR 标准](https://www.php-fig.org/psr) 则优先满足且依赖对应的接口而不是实现类；如 [PSR 标准](https://www.php-fig.org/psr) 没有包含的功能，则可满足由 Hyperf 定义的契约库 [Hyperf/contract](https://github.com/hyperf/contract) 内的接口时优先满足且依赖对应的接口而不是实现类； +- 对于实现 Hyperf 专有功能所增加的增强功能类，通常来说也会对 Hyperf 的一些组件有依赖，那么这些组件的依赖不应该写在 `composer.json` 的 `require` 项，而是写在 `suggest` 项作为建议项存在； +- 组件设计时不应该通过注解进行任何的依赖注入，注入方式应只使用 `构造函数注入` 的方式，这样同时也能满足在 `OOP` 下的使用； +- 组件设计时不应该通过注解进行任何的功能定义，功能定义应只通过 `ConfigProvider` 来定义； +- 类的设计时应尽可能的不储存状态数据，因为这会导致这个类不能作为长生命周期的对象来提供，也无法很方便的使用依赖注入功能，这样会在一定程度下降低性能，状态数据应都通过 `Hyperf\Utils\Context` 协程上下文来储存； diff --git a/docs/en/component-guide/create.md b/docs/en/component-guide/create.md new file mode 100644 index 000000000..4b0b1cc70 --- /dev/null +++ b/docs/en/component-guide/create.md @@ -0,0 +1,49 @@ +# 创建新的组件 + +`Hyperf` 官方提供了工具来快速创建组件包。 + +``` +# 创建适配 Hyperf 最新版本的组件包 +composer create-project hyperf/component-creator your_component dev-master + +# 创建适配 Hyperf 2.0 版本的组件包 +composer create-project hyperf/component-creator your_component "2.0.*" +``` + +## 在项目中使用未发布的组件包 + +假设项目目录如下 + +``` +/opt/project // 项目目录 +/opt/your_component // 组件包目录 +``` + +假设组件名为 `your_component/your_component` + +修改 /opt/project/composer.json + +> 以下省略其他不相干的配置 + +```json +{ + "require": { + "your_component/your_component": "dev-master" + }, + "repositories": { + "your_component": { + "type": "path", + "url": "/opt/your_component" + } + } +} +``` + +最后在目录 `/opt/project` 中执行 `composer update -o` 即可。 + + + + + + + diff --git a/docs/en/component-guide/intro.md b/docs/en/component-guide/intro.md index ac47833e7..39ddbdf38 100644 --- a/docs/en/component-guide/intro.md +++ b/docs/en/component-guide/intro.md @@ -1,6 +1,6 @@ # 指南前言 -为了帮助开发者更好的为 Hyperf 开发组件，共建生态，我们提供了本指南用于指导开发者进行组件开发，在阅读本指南前，需要您对 Hyperf 的文档进行了 **全面** 的阅读，特别是 [协程](en/coroutine.md) 和 [依赖注入](en/di.md) 章节，如果对 Hyperf 的基础组件缺少充分的理解，可能会导致开发时出现错误。 +为了帮助开发者更好的为 Hyperf 开发组件，共建生态，我们提供了本指南用于指导开发者进行组件开发，在阅读本指南前，需要您对 Hyperf 的文档进行了 **全面** 的阅读，特别是 [协程](zh-cn/coroutine.md) 和 [依赖注入](zh-cn/di.md) 章节，如果对 Hyperf 的基础组件缺少充分的理解，可能会导致开发时出现错误。 # 组件开发的目的 @@ -9,14 +9,14 @@ # 组件开发准备工作 这里所指的开发准备工作，除了 Hyperf 的基础运行条件外，这里关注的更多是如何更加便捷的组织代码的结构以便于组件的开发工作，注意以下方式可能会由于 *软连接无法跳转的问题* 而并不适用于 Windows for Docker 下的开发环境。 -在代码组织上，我们建议在同一个目录下 Clone [hyperf-cloud/hyperf-skeleton](https://github.com/hyperf-cloud/hyperf-skeleton) 项目骨架和 [hyperf-cloud/hyperf](https://github.com/hyperf-cloud/hyperf) 项目组件库两个项目。进行下面的操作并呈以下结构： +在代码组织上，我们建议在同一个目录下 Clone [hyperf/hyperf-skeleton](https://github.com/hyperf/hyperf-skeleton) 项目骨架和 [hyperf/hyperf](https://github.com/hyperf/hyperf) 项目组件库两个项目。进行下面的操作并呈以下结构： ```bash // 安装 skeleton，并配置完成 composer create-project hyperf/hyperf-skeleton -// 克隆 hyperf 组件库项目，这里记得要替换 hyperf-cloud 为您的 Github ID，也就是克隆您所 Fork 的项目 -git clone git@github.com:hyperf-cloud/hyperf.git +// 克隆 hyperf 组件库项目，这里记得要替换 hyperf 为您的 Github ID，也就是克隆您所 Fork 的项目 +git clone git@github.com:hyperf/hyperf.git ``` 呈以下结构： @@ -43,7 +43,7 @@ git clone git@github.com:hyperf-cloud/hyperf.git "hyperf": { "type": "path", "url": "../hyperf/src/*" - } + }, "packagist": { "type": "composer", "url": "https://mirrors.aliyun.com/composer" @@ -94,4 +94,4 @@ testing -> ../../../hyperf/src/testing utils -> ../../../hyperf/src/utils ``` -此时，我们便可达到在 IDE 内直接对 `vendor/hyperf` 内的文件进行修改，而修改的却是 `hyperf` 内的代码的目的，这样最终我们便可直接对 `hyperf` 项目内进行 `commit`，然后向主干提交 `Pull Request(PR)` 了。 \ No newline at end of file +此时，我们便可达到在 IDE 内直接对 `vendor/hyperf` 内的文件进行修改，而修改的却是 `hyperf` 内的代码的目的，这样最终我们便可直接对 `hyperf` 项目内进行 `commit`，然后向主干提交 `Pull Request(PR)` 了。 diff --git a/docs/en/release-planning.md b/docs/en/release-planning.md index da336babe..7d63108e2 100644 --- a/docs/en/release-planning.md +++ b/docs/en/release-planning.md @@ -4,7 +4,7 @@ | Version | Status | End of mainstream support | End of Security-fixes support | Release Date (or estimated date) | | ------- |-------------------------------------|---------------------------|-------------------------------|----------------------------------| -| 3.0 | Developing (RC13 has been released) | 2023-06-30 | 2024-06-30 | About 2022-12-31 | +| 3.0 | Developing (RC17 has been released) | 2023-06-30 | 2024-06-30 | About 2022-12-31 | | 2.2 | Security fixes support | 2022-06-20 | 2023-6-30 | 2021-07-19 | | 2.1 | Deprecated | 2021-06-30 | 2021-12-31 | 2020-12-28 | | 2.0 | Deprecated | 2020-12-28 | 2021-06-30 | 2020-06-22 | diff --git a/docs/zh-cn/release-planning.md b/docs/zh-cn/release-planning.md index 2d3a1848b..759bcbcdf 100644 --- a/docs/zh-cn/release-planning.md +++ b/docs/zh-cn/release-planning.md @@ -4,8 +4,8 @@ | 版本 | 状态 | 积极支持截止时间 | 安全维护截止时间 | 发布或预计发布时间 | | ---- |----------------|------------|------------|---------------| -| 3.0 | 研发中 (RC13 已发布) | 2023-06-30 | 2024-06-30 | 大概 2022-12-31 | -| 2.2 | 安全维护 | 2022-06-20 | 2023-06-30 | 2021-07-19 | +| 3.0 | 研发中 (RC17 已发布) | 2023-06-30 | 2024-06-30 | 大概 2022-12-31 | +| 2.2 | 安全维护 | 2022-06-20 | 2023-06-30 | 2021-07-19 | | 2.1 | 停止维护 | 2021-06-30 | 2021-12-31 | 2020-12-28 | | 2.0 | 停止维护 | 2020-12-28 | 2021-06-30 | 2020-06-22 | | 1.1 | 停止维护 | 2020-06-23 | 2020-12-31 | 2019-10s-08 | From 3b0ec2bf634d72db003b63886eca688e69bc5447 Mon Sep 17 00:00:00 2001 From: huangzhhui Date: Wed, 23 Nov 2022 03:37:07 +0000 Subject: [PATCH 7/7] Update docs and translate --- docs/zh-hk/release-planning.md | 4 ++-- docs/zh-tw/release-planning.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/zh-hk/release-planning.md b/docs/zh-hk/release-planning.md index eaebc0f05..6e1f5ec61 100644 --- a/docs/zh-hk/release-planning.md +++ b/docs/zh-hk/release-planning.md @@ -4,8 +4,8 @@ | 版本 | 狀態 | 積極支持截止時間 | 安全維護截止時間 | 發佈或預計發佈時間 | | ---- |----------------|------------|------------|---------------| -| 3.0 | 研發中 (RC13 已發佈) | 2023-06-30 | 2023-12-31 | 大概 2022-12-31 | -| 2.2 | 安全維護 | 2022-06-20 | 2023-06-30 | 2021-07-19 | +| 3.0 | 研發中 (RC17 已發佈) | 2023-06-30 | 2024-06-30 | 大概 2022-12-31 | +| 2.2 | 安全維護 | 2022-06-20 | 2023-06-30 | 2021-07-19 | | 2.1 | 停止維護 | 2021-06-30 | 2021-12-31 | 2020-12-28 | | 2.0 | 停止維護 | 2020-12-28 | 2021-06-30 | 2020-06-22 | | 1.1 | 停止維護 | 2020-06-23 | 2020-12-31 | 2019-10s-08 | diff --git a/docs/zh-tw/release-planning.md b/docs/zh-tw/release-planning.md index 2e8f1d604..5a1d25dad 100644 --- a/docs/zh-tw/release-planning.md +++ b/docs/zh-tw/release-planning.md @@ -4,8 +4,8 @@ | 版本 | 狀態 | 積極支援截止時間 | 安全維護截止時間 | 釋出或預計釋出時間 | | ---- |----------------|------------|------------|---------------| -| 3.0 | 研發中 (RC13 已釋出) | 2023-06-30 | 2023-12-31 | 大概 2022-12-31 | -| 2.2 | 安全維護 | 2022-06-20 | 2023-06-30 | 2021-07-19 | +| 3.0 | 研發中 (RC17 已釋出) | 2023-06-30 | 2024-06-30 | 大概 2022-12-31 | +| 2.2 | 安全維護 | 2022-06-20 | 2023-06-30 | 2021-07-19 | | 2.1 | 停止維護 | 2021-06-30 | 2021-12-31 | 2020-12-28 | | 2.0 | 停止維護 | 2020-12-28 | 2021-06-30 | 2020-06-22 | | 1.1 | 停止維護 | 2020-06-23 | 2020-12-31 | 2019-10s-08 |