diff --git a/docs/zh-hk/components/amqp-job.md b/docs/zh-hk/components/amqp-job.md index 461dcd43e..3c946600b 100644 --- a/docs/zh-hk/components/amqp-job.md +++ b/docs/zh-hk/components/amqp-job.md @@ -3,7 +3,7 @@ ## 簡介 `friendsofhyperf/amqp-job` 通過 `hyperf/amqp` 分發 PHP 任務對象。任務使用 `AmqpJob` -註解聲明 AMQP 綁定，服務啟動時，組件會為每個已啟用且帶有該註解的任務自動註冊消費者。 +註解聲明 AMQP 綁定，服務啓動時，組件會為每個已啓用且帶有該註解的任務自動註冊消費者。 組件默認使用 PHP 序列化，因此只應分發可信的任務對象，並確保消費者可以加載對應的類。 @@ -60,11 +60,11 @@ function dispatchFoo(Producer $producer, int $id): bool ``` `dispatch(JobInterface $payload, ?bool $confirm = null, ?int $timeout = null): bool` -是創建並發布 `JobMessage` 的便捷函數。如果任務尚無任務 ID，它會為其分配唯一 ID。可選的 +是創建併發布 `JobMessage` 的便捷函數。如果任務尚無任務 ID，它會為其分配唯一 ID。可選的 `confirm` 和 `timeout` 參數會覆蓋本次分發使用的任務值。 當前 `dispatch()` 不會將任務的交換機、路由鍵或連接池複製到 `JobMessage`。因此生成的生產者 -消息會使用空交換機、空路由鍵和 Hyperf 的 `default` AMQP 連接池。若要發布到 `AmqpJob` +消息會使用空交換機、空路由鍵和 Hyperf 的 `default` AMQP 連接池。若要發佈到 `AmqpJob` 聲明的綁定，請像上例一樣創建 `JobMessage`、設置目的地，再交給 `Hyperf\Amqp\Producer`。 ## 註解選項 @@ -83,7 +83,7 @@ function dispatchFoo(Producer $producer, int $id): bool | `name` | `?string` | `null` | 消費者進程名稱。 | 如果任務未使用該註解，其 getter 默認返回交換機 `hyperf`、路由鍵 `hyperf.job`、無指定 -連接池、關閉發布確認、5 秒發布超時和不重試。子類可以提供 `$exchange`、`$routingKey`、 +連接池、關閉發佈確認、5 秒發佈超時和不重試。子類可以提供 `$exchange`、`$routingKey`、 `$poolName`、`$confirm`、`$timeout` 或 `$maxAttempts` 等受保護屬性來覆蓋這些 getter 值。 如上所述，`dispatch()` 只使用確認和超時 getter。 @@ -106,7 +106,7 @@ public function fail(Throwable $e): void } ``` -默認 Redis 次數鍵使用 `hyperf:amqp-job:attempts:` 前綴，並在 86,400 秒後過期，因此啟用 +默認 Redis 次數鍵使用 `hyperf:amqp-job:attempts:` 前綴，並在 86,400 秒後過期，因此啓用 重試時必須可用 Redis。綁定 `FriendsOfHyperf\AmqpJob\Contract\Attempt` 或 `FriendsOfHyperf\AmqpJob\Contract\Packer` 可以替換默認實現。記錄異常時，消費者會依次 解析 `FriendsOfHyperf\AmqpJob\Contract\LoggerInterface` 和 diff --git a/docs/zh-hk/components/cache.md b/docs/zh-hk/components/cache.md index 9c4a550ca..23f9eec2a 100644 --- a/docs/zh-hk/components/cache.md +++ b/docs/zh-hk/components/cache.md @@ -3,8 +3,8 @@ ## 簡介 `friendsofhyperf/cache` 使用 Laravel 風格的倉庫 API 封裝 `hyperf/cache` -提供的驅動。它支援 PSR-16 操作、命名儲存、門面存取、快取事件、巨集以及 -stale-while-revalidate 快取。 +提供的驅動。它支持 PSR-16 操作、命名存儲、門面訪問、緩存事件、宏以及 +stale-while-revalidate 緩存。 ## 安裝 @@ -12,21 +12,21 @@ stale-while-revalidate 快取。 composer require friendsofhyperf/cache ``` -該元件要求 Hyperf 3.2。其 `ConfigProvider` 會在容器中註冊 +該組件要求 Hyperf 3.2。其 `ConfigProvider` 會在容器中註冊 `FriendsOfHyperf\Cache\Contract\Factory` 和 `FriendsOfHyperf\Cache\Contract\Repository`。 ## 配置 -該元件不會發佈獨立的配置檔案。請透過 `hyperf/cache` 配置驅動和命名儲存； -`CacheManager::store($name)` 會將名稱傳給 Hyperf 的快取管理器。預設倉庫解析 -`default` 儲存。 +該組件不會發布獨立的配置文件。請通過 `hyperf/cache` 配置驅動和命名存儲； +`CacheManager::store($name)` 會將名稱傳給 Hyperf 的緩存管理器。默認倉庫解析 +`default` 存儲。 -## 取得倉庫 +## 獲取倉庫 ### 依賴注入 -注入 `Contract\Repository` 以使用預設儲存： +注入 `Contract\Repository` 以使用默認存儲： ```php namespace App\Controller; @@ -48,7 +48,7 @@ class IndexController } ``` -需要命名儲存時注入 `Contract\Factory`： +需要命名存儲時注入 `Contract\Factory`： ```php use FriendsOfHyperf\Cache\Contract\Factory; @@ -69,42 +69,42 @@ $users = Cache::store('redis')->get('users'); ``` `Cache::driver($name)` 是 `Cache::store($name)` 的別名。 -`Cache::resolve($name)` 會建立新倉庫，而不是傳回管理器中快取的倉庫實例。 +`Cache::resolve($name)` 會創建新倉庫，而不是返回管理器中緩存的倉庫實例。 ## 核心操作 -倉庫實作了 `Psr\SimpleCache\CacheInterface`，因此可使用 `get()`、`set()`、 +倉庫實現了 `Psr\SimpleCache\CacheInterface`，因此可使用 `get()`、`set()`、 `delete()`、`clear()`、`getMultiple()`、`setMultiple()`、`deleteMultiple()` 和 -`has()`。此外還提供以下擴充： +`has()`。此外還提供以下擴展： | 方法 | 行為 | | --- | --- | -| `get($key, $default = null)` | 取得單個項目；未命中時會執行可呼叫的預設值。傳入陣列會轉交給 `many()`。 | -| `put($key, $value, $ttl = null)` | 儲存單個項目；`null` 表示永久儲存，非正數 TTL 會刪除該鍵。傳入關聯陣列會轉交給 `putMany()`，並將第二個參數用作其 TTL。 | -| `putMany($values, $ttl = null)` | 儲存多個項目；非正數 TTL 會刪除對應鍵。 | -| `forever($key, $value)` | 不設定 TTL 地儲存單個項目。 | -| `add($key, $value, $ttl = null)` | 僅當 `get($key)` 傳回 `null` 時儲存項目。 | -| `many($keys)` | 取得多個鍵；關聯陣列輸入可為每個鍵提供預設值。 | -| `pull($key, $default = null)` | 取得項目後將其刪除。 | -| `remember($key, $ttl, Closure $callback)` | 傳回快取值，或按 TTL 儲存回呼結果。 | -| `rememberForever($key, Closure $callback)` / `sear(...)` | 傳回快取值，或永久儲存回呼結果。 | -| `increment($key, $value = 1)` / `decrement(...)` | 讀取、調整並以無 TTL 方式儲存整數值。 | +| `get($key, $default = null)` | 獲取單個項目；未命中時會執行可調用的默認值。傳入數組會轉交給 `many()`。 | +| `put($key, $value, $ttl = null)` | 存儲單個項目；`null` 表示永久存儲，非正數 TTL 會刪除該鍵。傳入關聯數組會轉交給 `putMany()`，並將第二個參數用作其 TTL。 | +| `putMany($values, $ttl = null)` | 存儲多個項目；非正數 TTL 會刪除對應鍵。 | +| `forever($key, $value)` | 不設置 TTL 地存儲單個項目。 | +| `add($key, $value, $ttl = null)` | 僅當 `get($key)` 返回 `null` 時存儲項目。 | +| `many($keys)` | 獲取多個鍵；關聯數組輸入可為每個鍵提供默認值。 | +| `pull($key, $default = null)` | 獲取項目後將其刪除。 | +| `remember($key, $ttl, Closure $callback)` | 返回緩存值，或按 TTL 存儲回調結果。 | +| `rememberForever($key, Closure $callback)` / `sear(...)` | 返回緩存值，或永久存儲回調結果。 | +| `increment($key, $value = 1)` / `decrement(...)` | 讀取、調整並以無 TTL 方式存儲整數值。 | | `flush()` | `clear()` 的別名。 | | `missing($key)` | `has($key)` 的反向判斷。 | -| `getDriver()` / `getStore()` | 傳回底層 Hyperf `DriverInterface`。 | +| `getDriver()` / `getStore()` | 返回底層 Hyperf `DriverInterface`。 | -擴充倉庫方法接受的 TTL 可以是秒數、`DateInterval` 或 `DateTimeInterface`。 +擴展倉庫方法接受的 TTL 可以是秒數、`DateInterval` 或 `DateTimeInterface`。 ::: warning 行為邊界 -倉庫會將已快取的 `null` 視為未命中。`add()`、`pull()` 和遞增/遞減方法由分離的 -操作實作，因此不是原子操作。雖然 `pull()` 接受 `$default` 參數，但目前實作不會 -將它傳給 `get()`，鍵不存在時傳回 `null`。 +倉庫會將已緩存的 `null` 視為未命中。`add()`、`pull()` 和遞增/遞減方法由分離的 +操作實現，因此不是原子操作。雖然 `pull()` 接受 `$default` 參數，但當前實現不會 +將它傳給 `get()`，鍵不存在時返回 `null`。 ::: ## Stale-While-Revalidate -`flexible()` 接受包含兩個 TTL 的陣列：第一個值是新鮮期，第二個值是快取值及其 -內部建立時間戳使用的儲存 TTL。 +`flexible()` 接受包含兩個 TTL 的數組：第一個值是新鮮期，第二個值是緩存值及其 +內部創建時間戳使用的存儲 TTL。 ```php use FriendsOfHyperf\Cache\Facade\Cache; @@ -117,9 +117,8 @@ $users = Cache::flexible('users', [30, 300], function () { ]); ``` -快取未命中時，回呼立即執行。在新鮮期內直接傳回快取值；新鮮期結束後傳回舊值， -並透過延遲回呼嘗試在鎖內重新整理快取。如果其他進程已更新建立時間戳，則跳過 -重新整理。 +緩存未命中時，回調立即執行。在新鮮期內直接返回緩存值；新鮮期結束後返回舊值， +並通過延遲迴調嘗試在鎖內刷新緩存。如果其他進程已更新創建時間戳，則跳過刷新。 使用 `flexible()` 前需要安裝兩個可選依賴： @@ -127,22 +126,22 @@ $users = Cache::flexible('users', [30, 300], function () { composer require friendsofhyperf/lock hyperf/coroutine ``` -可選的鎖陣列接受 `seconds` 和 `owner`，預設值分別為 `0` 和 `null`。 +可選的鎖數組接受 `seconds` 和 `owner`，默認值分別為 `0` 和 `null`。 ## 事件 當容器提供 `Psr\EventDispatcher\EventDispatcherInterface` 時，倉庫會為讀取、 -寫入、刪除和清空操作分派事件： +寫入、刪除和清空操作分發事件： - `CacheHit`、`CacheMissed`、`RetrievingKey`、`RetrievingManyKeys` - `WritingKey`、`WritingManyKeys`、`KeyWritten`、`KeyWriteFailed` - `ForgettingKey`、`KeyForgotten`、`KeyForgetFailed` - `CacheFlushing`、`CacheFlushed` -每個事件都包含儲存名稱。單鍵事件還包含鍵；適用時，寫入事件會公開值和 TTL， -批次事件會公開鍵，`WritingManyKeys` 還會公開值。批次讀取還會為每個傳回的鍵分派 +每個事件都包含存儲名稱。單鍵事件還包含鍵；適用時，寫入事件會公開值和 TTL， +批量事件會公開鍵，`WritingManyKeys` 還會公開值。批量讀取還會為每個返回的鍵分發 `CacheHit` 或 `CacheMissed`。 ## 參考 -該 API 的設計受 Laravel Cache 啟發，但具體行為應以本元件的契約和實作為準。 +該 API 的設計受 Laravel Cache 啓發，但具體行為應以本組件的契約和實現為準。 diff --git a/docs/zh-hk/components/co-phpunit.md b/docs/zh-hk/components/co-phpunit.md index 7c4031799..2ea71cddd 100644 --- a/docs/zh-hk/components/co-phpunit.md +++ b/docs/zh-hk/components/co-phpunit.md @@ -11,8 +11,8 @@ Co-PHPUnit 讓 PHPUnit 測試在 Swoole 協程中運行，適用於測試依賴 composer require friendsofhyperf/co-phpunit --dev ``` -組件依賴 `hyperf/coordinator` `~3.2.0`，並支援 PHPUnit 10、11 和 12。它沒有將 Swoole -擴展聲明為 Composer 依賴；未載入該擴展時，測試會回退到 PHPUnit 的普通執行方式。 +組件依賴 `hyperf/coordinator` `~3.2.0`，並支持 PHPUnit 10、11 和 12。它沒有將 Swoole +擴展聲明為 Composer 依賴；未加載該擴展時，測試會回退到 PHPUnit 的普通執行方式。 ## 使用 @@ -40,11 +40,11 @@ class ServiceTest extends TestCase } ``` -安裝組件後，不需要額外配置 PHPUnit 或 Composer 自動載入。 +安裝組件後，不需要額外配置 PHPUnit 或 Composer 自動加載。 ### 退出協程執行 -將 `NonCoroutine` 應用於單個測試方法，可以讓該方法在不建立協程的情況下運行： +將 `NonCoroutine` 應用於單個測試方法，可以讓該方法在不創建協程的情況下運行： ```php = 4.6.0` 或 `ext-swow >= 0.1.0`，但沒有將 +實現通過 Hyperf Engine 處理信號，並調用 `posix_getpid()` 和 `posix_kill()`。請在支持 +POSIX 信號且可運行協程的 Swoole 或 Swow 環境中使用。PHP POSIX 擴展必須提供上述兩個 +函數。Composer 建議安裝 `ext-swoole >= 4.6.0` 或 `ext-swow >= 0.1.0`，但沒有將 POSIX 擴展聲明為依賴。 ## 使用 -在指令中引入 `InteractsWithSignals`，然後調用 `trap()` 並傳入一個訊號編號或訊號編號陣列。 -回調會接收到訊號編號。 +在命令中引入 `InteractsWithSignals`，然後調用 `trap()` 並傳入一個信號編號或信號編號數組。 +回調會接收到信號編號。 ```php namespace App\Command; @@ -58,14 +58,14 @@ class FooCommand extends HyperfCommand } ``` -首次調用 `trap()` 時，它會透過容器建立 `SignalRegistry`，並在目前協程結束時自動清空回調。 -同一個訊號可以註冊多個回調；收到該訊號時，這些回調會並行執行。 +首次調用 `trap()` 時，它會通過容器創建 `SignalRegistry`，並在當前協程結束時自動清空回調。 +同一個信號可以註冊多個回調；收到該信號時，這些回調會併發執行。 -每個已註冊訊號只會被處理一次。回調執行完成後，註冊器會停止等待，並再次向目前程序發送同一 -訊號，因此作業系統通常會執行該訊號的預設動作。 +每個已註冊信號只會被處理一次。回調執行完成後，註冊器會停止等待，並再次向當前進程發送同一 +信號，因此操作系統通常會執行該信號的默認動作。 -使用 `untrap()` 清空一個訊號、多個訊號或全部訊號的回調。它不會取消已經啟動的等待協程； -如果之後收到該訊號，註冊器仍會在不執行回調後再次向程序發送該訊號。 +使用 `untrap()` 清空一個信號、多個信號或全部信號的回調。它不會取消已經啓動的等待協程； +如果之後收到該信號，註冊器仍會在不執行回調後再次向進程發送該信號。 ```php $this->untrap(SIGINT); @@ -75,20 +75,20 @@ $this->untrap(); ## API -Trait 向指令提供以下受保護方法： +Trait 向命令提供以下受保護方法： - `trap(array|int $signo, callable $callback): void` - `untrap(null|array|int $signo = null): void` -`SignalRegistry` 也是公開類別。其建構函式為 +`SignalRegistry` 也是公開類。其構造函數為 `__construct(int $timeout = 1, int $concurrentLimit = 0)`；`timeout` 是每次等待嘗試的 -逾時秒數，`concurrentLimit` 用於限制並行執行的回調數量，值為 `0` 表示不限制並行數。它 +超時秒數，`concurrentLimit` 用於限制併發執行的回調數量，值為 `0` 表示不限制併發數。它 提供以下方法： - `register(int|array $signo, callable $signalHandler): void` - `unregister(null|int|array $signo = null): void` -`unregister()` 會清空所選訊號的回調；傳入 `null` 會清空全部回調。 +`unregister()` 會清空所選信號的回調；傳入 `null` 會清空全部回調。 ## 運行 diff --git a/docs/zh-hk/components/command-validation.md b/docs/zh-hk/components/command-validation.md index 89e00a9dd..f2458a0b2 100644 --- a/docs/zh-hk/components/command-validation.md +++ b/docs/zh-hk/components/command-validation.md @@ -1,6 +1,6 @@ # Command Validation -在 Hyperf 命令執行前驗證其參數和選項。 +在 Hyperf 命令運行前驗證其參數和選項。 ## 安裝 @@ -13,8 +13,8 @@ Hyperf 會自動發現該組件的空 `ConfigProvider`，因此該組件沒有 ## 使用 -在命令中引入 `ValidatesInput` trait 並覆寫 `rules()`。也可以覆寫 -`messages()` 和 `attributes()` 來自訂驗證錯誤。 +在命令中引入 `ValidatesInput` trait 並重寫 `rules()`。也可以重寫 +`messages()` 和 `attributes()` 來自定義驗證錯誤。 ```php team_id` 是 `null`。 +Eloquent 風格的關係通常只會把一個外鍵列匹配到一個本地鍵或擁有者鍵列。在關係中 +額外添加 `where` 子句並不能替代複合鍵關係，因為預加載會在單個模型實例可用之前 +構造關係查詢。下面的示例中，準備預加載約束時 `$this->team_id` 是 `null`。 ```php namespace App; @@ -27,18 +27,18 @@ class User extends Model ## 安裝 -透過 Composer 安裝組件： +通過 Composer 安裝組件： ```shell composer require friendsofhyperf/compoships ``` -此組件面向 Hyperf 3.2，並依賴組件聲明的 `hyperf/database` 及相關 Hyperf 支援包。 -`composer.json` 中的建議包是可選第三方包，並不是 Compoships 關聯所必需的依賴。 +該組件面向 Hyperf 3.2，並依賴組件聲明的 `hyperf/database` 及相關 Hyperf 支撐包。 +`composer.json` 中的建議包是可選第三方包，並不是 Compoships 關係所必需的依賴。 ## 配置 -無需發布配置檔案。組件提供了 Hyperf `ConfigProvider`，但目前返回的是空配置陣列。 +無需發佈配置文件。組件提供了 Hyperf `ConfigProvider`，但當前返回的是空配置數組。 ## 使用 @@ -75,24 +75,24 @@ class User extends Model } ``` -當關聯使用鍵名陣列時，被關聯模型也必須接入 Compoships：要麼繼承 +當關系使用鍵名數組時，被關聯模型也必須接入 Compoships：要麼繼承 `FriendsOfHyperf\Compoships\Database\Eloquent\Model`，要麼使用 -`FriendsOfHyperf\Compoships\Compoships` trait。否則定義關聯時會拋出 +`FriendsOfHyperf\Compoships\Compoships` trait。否則定義關係時會拋出 `FriendsOfHyperf\Compoships\Exceptions\InvalidUsageException`。 -## 關聯語法 +## 關係語法 -Compoships 支援在以下關聯方法中使用複合鍵： +Compoships 支持在以下關係方法中使用複合鍵： - `hasOne($related, $foreignKey = null, $localKey = null)` - `hasMany($related, $foreignKey = null, $localKey = null)` - `belongsTo($related, $foreignKey = null, $ownerKey = null, $relation = null)` -將鍵參數由字串改為陣列即可。陣列順序和元素數量應保持一致，因為值會按陣列下標 +將鍵參數從字符串改為數組即可。數組順序和元素數量應保持一致，因為值會按數組下標 逐項匹配。 -對 `hasOne` 和 `hasMany` 來說，外鍵陣列表示被關聯模型上的欄位，本地鍵陣列表示目前 -模型上的欄位： +對 `hasOne` 和 `hasMany` 來説，外鍵數組表示被關聯模型上的列，本地鍵數組表示當前 +模型上的列： ```php namespace App; @@ -116,8 +116,8 @@ class Team extends Model } ``` -對 `belongsTo` 來說，外鍵陣列表示目前模型上的欄位，擁有者鍵陣列表示被關聯模型上的 -欄位： +對 `belongsTo` 來説，外鍵數組表示當前模型上的列，擁有者鍵數組表示被關聯模型上的 +列： ```php namespace App; @@ -136,17 +136,17 @@ class Task extends Model } ``` -## 例子 +## 示例 -假設一個任務清單由多個團隊管理，並且每個團隊中每個任務分類都有一名負責用戶： +假設一個任務列表由多個團隊管理，並且每個團隊中每個任務分類都有一名負責用户： - 一個任務屬於一個分類。 - 一個任務被分配給一個團隊。 -- 一個團隊有多個用戶。 -- 一個用戶屬於一個團隊。 -- 一個用戶負責一個分類下的任務。 +- 一個團隊有多個用户。 +- 一個用户屬於一個團隊。 +- 一個用户負責一個分類下的任務。 -某個任務的負責用戶，就是該任務所屬團隊中負責該任務分類的用戶。 +某個任務的負責用户，就是該任務所屬團隊中負責該任務分類的用户。 ```php namespace App; @@ -165,7 +165,7 @@ class User extends Model } ``` -反向關聯使用同一組欄位： +反向關係使用同一組列： ```php namespace App; @@ -188,11 +188,11 @@ class Task extends Model } ``` -## 行為說明 +## 行為説明 -Compoships 使用自訂查詢構造器，因此預載入可以應用多欄位 `whereIn` 約束，關聯存在性 -查詢也可以透過 `whereColumn` 比較多欄位。 +Compoships 使用自定義查詢構造器，因此預加載可以應用多列 `whereIn` 約束，關係存在性 +查詢也可以通過 `whereColumn` 比較多列。 -對 `hasOne` 和 `hasMany` 來說，`save()` 和 `create()` 會把父模型本地鍵的值按順序 -寫入被關聯模型的各個外鍵欄位。對 `belongsTo` 來說，`associate()` 會把擁有者鍵的值 -按順序寫入目前模型的各個外鍵欄位。 +對 `hasOne` 和 `hasMany` 來説，`save()` 和 `create()` 會把父模型本地鍵的值按順序 +寫入被關聯模型的各個外鍵列。對 `belongsTo` 來説，`associate()` 會把擁有者鍵的值 +按順序寫入當前模型的各個外鍵列。 diff --git a/docs/zh-hk/components/confd.md b/docs/zh-hk/components/confd.md index ee9967090..3a19dd664 100644 --- a/docs/zh-hk/components/confd.md +++ b/docs/zh-hk/components/confd.md @@ -1,11 +1,11 @@ # Confd -Confd 組件從 Etcd 或 Nacos 取得配置，將遠端值映射為環境變數名稱，並可將其寫入 -已有的 `.env` 檔案或監聽變更。 +Confd 組件從 Etcd 或 Nacos 獲取配置，將遠程值映射為環境變量名，並可將其寫入 +已有的 `.env` 文件或監聽變更。 ## 安裝 -安裝組件以及所用驅動需要的套件： +安裝組件以及所用驅動需要的包： ```shell composer require friendsofhyperf/confd @@ -15,9 +15,9 @@ composer require hyperf/nacos ``` Etcd 和 Nacos 是可選驅動依賴。Nacos v2 gRPC API 還需要 `google/protobuf`、`hyperf/grpc` -和 `hyperf/http2-client`。解碼 YAML 值需要 PHP YAML 擴充功能。 +和 `hyperf/http2-client`。解碼 YAML 值需要 PHP YAML 擴展。 -發布配置檔案： +發佈配置文件： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/confd @@ -25,22 +25,22 @@ php bin/hyperf.php vendor:publish friendsofhyperf/confd ## 配置 -發布的檔案為 `config/autoload/confd.php`，主要選項如下： +發佈的文件為 `config/autoload/confd.php`，主要選項如下： -| 選項 | 說明 | +| 選項 | 説明 | | --- | --- | -| `default` | 驅動名稱。預設為 `etcd`，可透過 `CONFD_DRIVER` 設定。 | -| `drivers..driver` | 實作 `DriverInterface` 的驅動類別。 | -| `drivers..mapping` | 將遠端配置路徑映射到環境變數名稱。 | -| `env_path` | `confd:env` 更新的已有 `.env` 檔案。 | -| `watch` | 在伺服器啟動時開始監聽。預設為 `true`，可透過 `CONFD_WATCH` 設定。 | -| `watches` | 會觸發 `WatchDispatched` 的環境變數名稱。 | -| `interval` | 輪詢間隔秒數。預設為 `1`，可透過 `CONFD_INTERVAL` 設定。 | +| `default` | 驅動名稱。默認為 `etcd`，可通過 `CONFD_DRIVER` 設置。 | +| `drivers..driver` | 實現 `DriverInterface` 的驅動類。 | +| `drivers..mapping` | 將遠程配置路徑映射到環境變量名。 | +| `env_path` | `confd:env` 更新的已有 `.env` 文件。 | +| `watch` | 在服務器啓動時開始監聽。默認為 `true`，可通過 `CONFD_WATCH` 設置。 | +| `watches` | 會觸發 `WatchDispatched` 的環境變量名。 | +| `interval` | 輪詢間隔秒數。默認為 `1`，可通過 `CONFD_INTERVAL` 設置。 | ### Etcd -Etcd 驅動取得 `namespace` 下的鍵，並只回傳 `mapping` 中列出的鍵。每個映射鍵是 Etcd -鍵，每個映射值是 `fetch()` 回傳的環境變數名稱。 +Etcd 驅動獲取 `namespace` 下的鍵，並只返回 `mapping` 中列出的鍵。每個映射鍵是 Etcd +鍵，每個映射值是 `fetch()` 返回的環境變量名。 ```php 'etcd' => [ @@ -60,9 +60,9 @@ Etcd 驅動取得 `namespace` 下的鍵，並只回傳 `mapping` 中列出的鍵 ### Nacos -Nacos 驅動讀取 `listener_config` 中的每個項目，根據 `type` 解碼，再從 `mapping` -解析點號路徑。支援的類型為 `json`、`yml`/`yaml` 和 `xml`；其他類型或未指定類型時 -保留為字串。 +Nacos 驅動讀取 `listener_config` 中的每個條目，根據 `type` 解碼，再從 `mapping` +解析點號路徑。支持的類型為 `json`、`yml`/`yaml` 和 `xml`；其他類型或未指定類型時 +保留為字符串。 ```php 'nacos' => [ @@ -96,11 +96,11 @@ Nacos 驅動讀取 `listener_config` 中的每個項目，根據 `type` 解碼 ``` 當 `client.grpc.enable` 為 `false` 時，Nacos 按 `interval` 輪詢；為 `true` 時，驅動為 -`listener_config` 中的項目註冊 gRPC 監聽。 +`listener_config` 中的條目註冊 gRPC 監聽。 -## 更新環境檔案 +## 更新環境文件 -從選定驅動取得映射值，並更新配置的已有 `.env` 檔案： +從選定驅動獲取映射值，並更新配置的已有 `.env` 文件： ```shell php bin/hyperf.php confd:env @@ -112,26 +112,26 @@ php bin/hyperf.php confd:env php bin/hyperf.php confd:env --env-path=/path/to/.env ``` -檔案不存在或取得/寫入失敗時，命令回傳結束碼 `1`。 +文件不存在或獲取/寫入失敗時，命令返回退出碼 `1`。 ## 公開 API `FriendsOfHyperf\Confd\Confd` 提供： -- `fetch(): array`：從選定驅動取得映射後的環境變數值。 -- `watch(): void`：執行首次取得並啟動選定驅動的監聽迴圈。 +- `fetch(): array`：從選定驅動獲取映射後的環境變量值。 +- `watch(): void`：執行首次獲取並啓動選定驅動的監聽循環。 -自訂驅動必須實作 `FriendsOfHyperf\Confd\Driver\DriverInterface`，其中宣告了 -`fetch(): array` 和 `loop(callable $callback): void`。內建 `Noop` 驅動不回傳值， -也不啟動迴圈。 +自定義驅動必須實現 `FriendsOfHyperf\Confd\Driver\DriverInterface`，其中聲明瞭 +`fetch(): array` 和 `loop(callable $callback): void`。內置 `Noop` 驅動不返回值， +也不啓動循環。 ## 監聽與事件 -啟用 `confd.watch` 時，`WatchOnBootListener` 會在 `MainWorkerStart` 或 -`MainCoroutineServerStart` 時呼叫 `Confd::watch()`。 +啓用 `confd.watch` 時，`WatchOnBootListener` 會在 `MainWorkerStart` 或 +`MainCoroutineServerStart` 時調用 `Confd::watch()`。 -監聽迴圈中，已有值發生變更時會派發 `ConfigChanged`。如果變更的環境變數名稱也列在 -`confd.watches` 中，還會派發 `WatchDispatched`。兩個事件都提供公開陣列屬性： +監聽循環中，已有值發生變更時會派發 `ConfigChanged`。如果變更的環境變量名也列在 +`confd.watches` 中，還會派發 `WatchDispatched`。兩個事件都提供公開數組屬性： - `ConfigChanged`：`$current`、`$previous` 和 `$changes`。 - `WatchDispatched`：`$changes`。 @@ -162,7 +162,7 @@ class ConfigChangedListener implements ListenerInterface } ``` -## 支援的驅動 +## 支持的驅動 - Etcd - Nacos diff --git a/docs/zh-hk/components/config-consul.md b/docs/zh-hk/components/config-consul.md index 757ae0d54..09bf02ab7 100644 --- a/docs/zh-hk/components/config-consul.md +++ b/docs/zh-hk/components/config-consul.md @@ -8,7 +8,7 @@ composer require friendsofhyperf/config-consul ``` -該套件會自動安裝所需的 Hyperf 配置中心、Consul、編解碼和字串處理依賴。 +該包會自動安裝所需的 Hyperf 配置中心、Consul、編解碼和字符串處理依賴。 ## 配置 @@ -39,26 +39,26 @@ return [ ]; ``` -| 配置項 | 說明 | +| 配置項 | 説明 | | --- | --- | -| `enable` | 啟用 Hyperf 配置中心。 | +| `enable` | 啓用 Hyperf 配置中心。 | | `driver` | 選擇 `consul` 驅動配置。 | -| `drivers.consul.driver` | 驅動類別，應使用 `ConsulDriver::class`。 | -| `drivers.consul.packer` | 解包每個映射值，預設為 `JsonPacker::class`。 | -| `drivers.consul.client` | 可選的 Consul 用戶端配置，支援 `uri` 和 `token`。 | -| `drivers.consul.namespaces` | 要遞迴拉取的 Consul KV 前綴陣列。 | -| `drivers.consul.mapping` | 將規範化後的 Consul 鍵映射到 Hyperf 配置鍵；只有已映射的鍵會被套用。 | -| `drivers.consul.interval` | 拉取間隔，單位為秒，預設為 `5`。 | +| `drivers.consul.driver` | 驅動類，應使用 `ConsulDriver::class`。 | +| `drivers.consul.packer` | 解包每個映射值，默認為 `JsonPacker::class`。 | +| `drivers.consul.client` | 可選的 Consul 客户端配置，支持 `uri` 和 `token`。 | +| `drivers.consul.namespaces` | 要遞歸拉取的 Consul KV 前綴數組。 | +| `drivers.consul.mapping` | 將規範化後的 Consul 鍵映射到 Hyperf 配置鍵；只有已映射的鍵會被應用。 | +| `drivers.consul.interval` | 拉取間隔，單位為秒，默認為 `5`。 | -省略 `client` 或將其設為空時，元件會重用 Hyperf 容器中綁定的 -`Hyperf\Consul\KVInterface` 用戶端。配置 `client` 時，`uri` 預設為 -`http://127.0.0.1:8500`；非空 `token` 會透過 `X-Consul-Token` 請求標頭傳送；HTTP 逾時時間為 +省略 `client` 或將其設為空時，組件會複用 Hyperf 容器中綁定的 +`Hyperf\Consul\KVInterface` 客户端。配置 `client` 時，`uri` 默認為 +`http://127.0.0.1:8500`；非空 `token` 會通過 `X-Consul-Token` 請求頭髮送；HTTP 超時時間為 2 秒。 ## 行為 -- 每個命名空間都會使用 Consul 的遞迴選項請求。如果多個命名空間傳回相同的鍵，映射前以後一個命名空間的值為準。 -- Consul KV 值會先進行 Base64 解碼，再交給配置的 packer。使用 `JsonPacker` 時，Base64 解碼後的儲存值必須是有效 JSON。 +- 每個命名空間都會使用 Consul 的遞歸選項請求。如果多個命名空間返回相同的鍵，映射前以後一個命名空間的值為準。 +- Consul KV 值會先進行 Base64 解碼，再交給配置的 packer。使用 `JsonPacker` 時，Base64 解碼後的存儲值必須是有效 JSON。 - Consul 鍵在 `mapping` 查找前會被規範化為以 `/` 開頭。 -- 該套件會在容器中註冊 `FriendsOfHyperf\ConfigConsul\ClientInterface` 和 +- 該包會在容器中註冊 `FriendsOfHyperf\ConfigConsul\ClientInterface` 和 `FriendsOfHyperf\ConfigConsul\Consul\KVInterface`；`ConsulDriver` 是配置中心驅動入口。 diff --git a/docs/zh-hk/components/console-spinner.md b/docs/zh-hk/components/console-spinner.md index ed6de9f0f..579e234f8 100644 --- a/docs/zh-hk/components/console-spinner.md +++ b/docs/zh-hk/components/console-spinner.md @@ -1,7 +1,7 @@ # Console Spinner -用於 Hyperf 命令的控制台 Spinner 元件。它封裝了 Symfony `ProgressBar`，並在每次推進時切換 -進度字元。 +用於 Hyperf 命令的控制枱 Spinner 組件。它封裝了 Symfony `ProgressBar`，並在每次推進時切換 +進度字符。 ## 安裝 @@ -11,13 +11,13 @@ composer require friendsofhyperf/console-spinner ## 可選配置 -僅在需要自訂 Spinner 字元時發佈配置檔案： +僅在需要自定義 Spinner 字符時發佈配置文件： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/console-spinner ``` -發佈後的 `config/autoload/console_spinner.php` 檔案包含： +發佈後的 `config/autoload/console_spinner.php` 文件包含： ```php return [ @@ -25,11 +25,11 @@ return [ ]; ``` -請確保 `chars` 是非空陣列，因為 Spinner 每次推進時都會從中選擇一個字元。 +請確保 `chars` 是非空數組，因為 Spinner 每次推進時都會從中選擇一個字符。 ## 使用 -在 Hyperf 命令中使用 `Spinnerable` Trait。它的受保護輔助方法 `spinner(int $max = 0)` 會建立 +在 Hyperf 命令中使用 `Spinnerable` Trait。它的受保護輔助方法 `spinner(int $max = 0)` 會創建 一個具有指定最大步數的 Spinner： ```php @@ -57,15 +57,15 @@ class FooCommand extends Command } ``` -`Spinner::advance(int $step = 1)` 會切換 Spinner 字元並推進封裝的進度條。呼叫其他方法時，會將 -呼叫轉發給 Symfony `ProgressBar`；需要直接存取底層實例時，可使用 `getOriginalProgressBar()`。 +`Spinner::advance(int $step = 1)` 會切換 Spinner 字符並推進封裝的進度條。調用其他方法時，會將 +調用轉發給 Symfony `ProgressBar`；需要直接訪問底層實例時，可使用 `getOriginalProgressBar()`。 ## 使用 `withSpinner` 處理步驟 -受保護輔助方法 `withSpinner($totalSteps, Closure $callback, string $message = '')` 會自動啟動 +受保護輔助方法 `withSpinner($totalSteps, Closure $callback, string $message = '')` 會自動啓動 和結束 Spinner。 -當 `$totalSteps` 是陣列等可計數的可迭代物件時，回呼會接收目前元素和 Spinner，並在處理每個 +當 `$totalSteps` 是數組等可計數的可迭代對象時，回調會接收當前元素和 Spinner，並在處理每個 元素後自動推進 Spinner： ```php @@ -74,7 +74,7 @@ $this->withSpinner(User::all(), function ($user, $spinner): void { }, 'Loading...'); ``` -當 `$totalSteps` 是整數時，回呼只接收 Spinner，並負責推進它： +當 `$totalSteps` 是整數時，回調只接收 Spinner，並負責推進它： ```php $this->withSpinner(10, function ($spinner): void { diff --git a/docs/zh-hk/components/elasticsearch.md b/docs/zh-hk/components/elasticsearch.md index 012ac722c..44d4ea110 100644 --- a/docs/zh-hk/components/elasticsearch.md +++ b/docs/zh-hk/components/elasticsearch.md @@ -1,11 +1,11 @@ # Elasticsearch -此組件將 Elasticsearch 官方 PHP 客戶端與 Hyperf 的 Guzzle 客戶端整合，並為已配置的連線提供靜態 +此組件將 Elasticsearch 官方 PHP 客户端與 Hyperf 的 Guzzle 客户端集成，併為已配置的連接提供靜態 Facade。 ## 要求 -此套件適用於 Hyperf 3.2，並依賴 8 或 9 版本的 `elasticsearch/elasticsearch`、`hyperf/config`、 +此包適用於 Hyperf 3.2，並依賴 8 或 9 版本的 `elasticsearch/elasticsearch`、`hyperf/config`、 `hyperf/context` 和 `hyperf/guzzle`。它沒有聲明可選依賴。 ## 安裝 @@ -15,12 +15,12 @@ composer require friendsofhyperf/elasticsearch php bin/hyperf.php vendor:publish friendsofhyperf/elasticsearch ``` -發佈命令會建立 `config/autoload/elasticsearch.php`。 +發佈命令會創建 `config/autoload/elasticsearch.php`。 ## 配置 -發佈的配置定義了 `default` 連線。`ELASTICSEARCH_HOST` 會按逗號拆分，因此可以包含多個主機。可以在 -`elasticsearch` 下加入其他命名連線： +發佈的配置定義了 `default` 連接。`ELASTICSEARCH_HOST` 會按逗號拆分，因此可以包含多個主機。可以在 +`elasticsearch` 下添加其他命名連接： ```php return [ @@ -33,15 +33,15 @@ return [ ]; ``` -對於 Facade 連線，`hosts` 可以是陣列或逗號分隔的字串。Facade 只讀取 `hosts` 鍵；其他客戶端行為 -需要透過 `ClientBuilderFactory` 和上游 Builder 配置。 +對於 Facade 連接，`hosts` 可以是數組或逗號分隔的字符串。Facade 只讀取 `hosts` 鍵；其他客户端行為 +需要通過 `ClientBuilderFactory` 和上游 Builder 配置。 ## 使用 -### 客戶端 Builder 工廠 +### 客户端 Builder 工廠 `ClientBuilderFactory::create(array $options = [])` 會將 `$options` 傳給 Hyperf 的 -`GuzzleClientFactory`，並傳回尚未構建的上游 `ClientBuilder`。請先配置 Builder，再呼叫 `build()`： +`GuzzleClientFactory`，並返回尚未構建的上游 `ClientBuilder`。請先配置 Builder，再調用 `build()`： ```php use FriendsOfHyperf\Elasticsearch\ClientBuilderFactory; @@ -64,11 +64,11 @@ class Foo } ``` -此工廠不會讀取 `config/autoload/elasticsearch.php`；必須明確設定主機和其他 Builder 選項。 +此工廠不會讀取 `config/autoload/elasticsearch.php`；必須顯式設置主機和其他 Builder 選項。 ### Facade -Facade 靜態呼叫使用 `default` 連線。使用 `connection()` 選擇命名連線： +Facade 靜態調用使用 `default` 連接。使用 `connection()` 選擇命名連接： ```php use FriendsOfHyperf\Elasticsearch\Facade\Elasticsearch; @@ -84,10 +84,10 @@ $results = Elasticsearch::connection('analytics')->search([ ]); ``` -每次 Facade 呼叫都會構建一個新客戶端。如果所選連線缺失或為 `null`，組件會拋出包含連線名稱的 +每次 Facade 調用都會構建一個新客户端。如果所選連接缺失或為 `null`，組件會拋出包含連接名稱的 `InvalidArgumentException`。 ## 上游 API -客戶端方法、請求參數、回應物件、身份驗證和其他 Builder 選項由已安裝的 -`elasticsearch/elasticsearch` 版本提供。使用這些功能時，請查閱對應版本的上游客戶端文件。 +客户端方法、請求參數、響應對象、身份驗證和其他 Builder 選項由已安裝的 +`elasticsearch/elasticsearch` 版本提供。使用這些功能時，請查閲對應版本的上游客户端文檔。 diff --git a/docs/zh-hk/components/encryption.md b/docs/zh-hk/components/encryption.md index ab7f31f4c..03dbc97b3 100644 --- a/docs/zh-hk/components/encryption.md +++ b/docs/zh-hk/components/encryption.md @@ -1,6 +1,6 @@ # Encryption -加密組件為 Hyperf 中的值和字串提供帶認證的加密。 +加密組件為 Hyperf 中的值和字符串提供帶認證的加密。 ## 安裝 @@ -8,7 +8,7 @@ composer require friendsofhyperf/encryption ``` -此套件面向 Hyperf 3.2。僅在需要為加密閉包簽名時安裝可選的 `opis/closure` 套件： +此包面向 Hyperf 3.2。僅在需要為加密閉包簽名時安裝可選的 `opis/closure` 包： ```shell composer require opis/closure @@ -16,42 +16,42 @@ composer require opis/closure ## 配置 -發佈配置檔案： +發佈配置文件： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/encryption ``` -此命令會建立 `config/autoload/encryption.php`，其中包含以下設定： +此命令會創建 `config/autoload/encryption.php`，其中包含以下設置： -| 配置鍵 | 環境變數 | 預設值 | +| 配置鍵 | 環境變量 | 默認值 | | --- | --- | --- | -| `encryption.key` | `APP_KEY` | 內置的範例 `base64:` 密鑰 | +| `encryption.key` | `APP_KEY` | 內置的示例 `base64:` 密鑰 | | `encryption.cipher` | `APP_CIPHER` | `AES-256-CBC` | -使用組件前請替換內置範例密鑰。`base64:` 前綴表示組件會先對其後的內容進行 Base64 解碼， -再校驗密鑰長度。可使用以下命令為預設 cipher 產生新密鑰： +使用組件前請替換內置示例密鑰。`base64:` 前綴表示組件會先對其後的內容進行 Base64 解碼， +再校驗密鑰長度。可使用以下命令為默認 cipher 生成新密鑰： ```shell php -r "echo 'base64:'.base64_encode(random_bytes(32)).PHP_EOL;" ``` -支援的 cipher 及原始密鑰長度如下： +支持的 cipher 及原始密鑰長度如下： | Cipher | 密鑰長度 | | --- | --- | -| `AES-128-CBC` | 16 位元組 | -| `AES-256-CBC` | 32 位元組 | -| `AES-128-GCM` | 16 位元組 | -| `AES-256-GCM` | 32 位元組 | +| `AES-128-CBC` | 16 字節 | +| `AES-256-CBC` | 32 字節 | +| `AES-128-GCM` | 16 字節 | +| `AES-256-GCM` | 32 字節 | Cipher 名稱不區分大小寫。缺少密鑰時會拋出 -`FriendsOfHyperf\Encryption\Exception\MissingKeyException`；不支援的 cipher 或錯誤的密鑰長度會拋出 +`FriendsOfHyperf\Encryption\Exception\MissingKeyException`；不支持的 cipher 或錯誤的密鑰長度會拋出 `RuntimeException`。 -## 輔助函數 +## 助手函數 -此套件會自動載入帶命名空間的 `encrypt()` 和 `decrypt()` 函數。使用前請先匯入： +此包會自動加載帶命名空間的 `encrypt()` 和 `decrypt()` 函數。使用前請先導入： ```php use function FriendsOfHyperf\Encryption\decrypt; @@ -61,8 +61,8 @@ $payload = encrypt(['id' => 1]); $value = decrypt($payload); ``` -`encrypt(mixed $value, bool $serialize = true)` 預設會序列化值， -`decrypt(string $payload, bool $unserialize = true)` 會執行對應的反向操作。處理不需要序列化的原始字串時， +`encrypt(mixed $value, bool $serialize = true)` 默認會序列化值， +`decrypt(string $payload, bool $unserialize = true)` 會執行對應的反向操作。處理不需要序列化的原始字符串時， 請將兩個函數的第二個參數都設為 `false`。 ## Encrypter API @@ -87,12 +87,12 @@ class TokenService } ``` -具體類別 `Encrypter` 還公開 `encrypt()`、`decrypt()`、`getKey()`、`getAllKeys()`、 +具體類 `Encrypter` 還公開 `encrypt()`、`decrypt()`、`getKey()`、`getAllKeys()`、 `getPreviousKeys()`、`previousKeys()`，以及靜態方法 `supported()` 和 `generateKey()`。 ## 密鑰輪換 -輪換目前密鑰後，可在具體加密器上配置舊的原始密鑰，以解密已有 payload。新 payload 始終使用目前密鑰。 +輪換當前密鑰後，可在具體加密器上配置舊的原始密鑰，以解密已有 payload。新 payload 始終使用當前密鑰。 ```php use FriendsOfHyperf\Encryption\Encrypter; @@ -102,13 +102,13 @@ $encrypter->previousKeys([ ]); ``` -每個舊密鑰的長度都必須符合目前 cipher 的要求。 +每個舊密鑰的長度都必須符合當前 cipher 的要求。 ## 失敗與可選閉包簽名 加密失敗會拋出 `FriendsOfHyperf\Encryption\Contract\EncryptException`。無效、被篡改或無法解密的 payload 會拋出 `FriendsOfHyperf\Encryption\Contract\DecryptException`。 -安裝 `opis/closure` 且已配置 `encryption.key` 時，啟動監聽器會向 -`Opis\Closure\SerializableClosure` 註冊同一個解析後的密鑰，用於閉包簽名。正常的值或字串加密不依賴 +安裝 `opis/closure` 且已配置 `encryption.key` 時，啓動監聽器會向 +`Opis\Closure\SerializableClosure` 註冊同一個解析後的密鑰，用於閉包簽名。正常的值或字符串加密不依賴 `opis/closure`。 diff --git a/docs/zh-hk/components/exception-event.md b/docs/zh-hk/components/exception-event.md index daa1011f6..822e3c168 100644 --- a/docs/zh-hk/components/exception-event.md +++ b/docs/zh-hk/components/exception-event.md @@ -1,6 +1,6 @@ # Exception Event -此元件會在 Hyperf 的異常處理器調度器處理異常後派發 `ExceptionDispatched` 事件，並提供輔助函數， +此組件會在 Hyperf 的異常處理器調度器處理異常後派發 `ExceptionDispatched` 事件，並提供輔助函數， 用於在不拋出異常的情況下手動報告異常。 ## 安裝 @@ -9,14 +9,14 @@ composer require friendsofhyperf/exception-event ``` -元件的 `ConfigProvider` 會透過 Composer 套件發現機制自動註冊切面。切面和監聽器依賴 Hyperf 的 AOP -及事件調度器支援，標準 Hyperf 應用程式已提供這些支援；在最小化安裝中，請確保 +組件的 `ConfigProvider` 會通過 Composer 包發現機制自動註冊切面。切面和監聽器依賴 Hyperf 的 AOP +及事件調度器支持，標準 Hyperf 應用已提供這些支持；在最小化安裝中，請確保 `hyperf/di` 和 `hyperf/event` 可用。 ## 自動派發 -已註冊的切面會攔截 `Hyperf\ExceptionHandler\ExceptionHandlerDispatcher::dispatch()`。調度器正常返回後， -元件會派發 `ExceptionDispatched` 事件，其中包含已處理的異常，以及上下文中的目前請求和回應。 +註冊的切面會攔截 `Hyperf\ExceptionHandler\ExceptionHandlerDispatcher::dispatch()`。調度器正常返回後， +組件會派發 `ExceptionDispatched` 事件，其中包含已處理的異常，以及上下文中的當前請求和響應。 ## 定義監聽器 @@ -68,12 +68,12 @@ class ExceptionEventListener implements ListenerInterface `FriendsOfHyperf\ExceptionEvent\Event\ExceptionDispatched` 公開以下屬性： - `Throwable $throwable`：已處理或手動報告的異常。 -- `?ServerRequestInterface $request`：目前請求；不在請求上下文中時為 `null`。 -- `?ResponseInterface $response`：目前回應；不在回應上下文中時為 `null`。 +- `?ServerRequestInterface $request`：當前請求；不在請求上下文中時為 `null`。 +- `?ResponseInterface $response`：當前響應；不在響應上下文中時為 `null`。 ## 手動報告 -元件會自動載入三個命名空間輔助函數： +組件會自動加載三個命名空間輔助函數： - `report(string|Throwable $exception = 'RuntimeException', ...$parameters)`：報告異常。 - `report_if($condition, string|Throwable $exception = 'RuntimeException', ...$parameters)`： @@ -89,14 +89,14 @@ use function FriendsOfHyperf\ExceptionEvent\report_if; use function FriendsOfHyperf\ExceptionEvent\report_unless; report(new DomainException('The operation failed.')); -report('The operation failed.'); // 使用此訊息報告 RuntimeException。 +report('The operation failed.'); // 使用此消息報告 RuntimeException。 report(DomainException::class, 'The operation failed.'); report_if($shouldReport, 'The operation failed.'); report_unless($operationSucceeded, 'The operation failed.'); ``` -`report()` 會直接派發 `ExceptionDispatched`，不會拋出異常。當第一個參數是已存在的異常類別名稱時， -其餘參數會傳給該異常的建構函數；其他字串會成為 `RuntimeException` 的訊息。 +`report()` 會直接派發 `ExceptionDispatched`，不會拋出異常。當第一個參數是已存在的異常類名時， +其餘參數會傳給該異常的構造函數；其他字符串會成為 `RuntimeException` 的消息。 `report_if()` 在條件為真值時報告，`report_unless()` 在條件為假值時報告。兩個函數都會返回原始條件。 diff --git a/docs/zh-hk/components/facade.md b/docs/zh-hk/components/facade.md index b0cff33a4..f676da450 100644 --- a/docs/zh-hk/components/facade.md +++ b/docs/zh-hk/components/facade.md @@ -8,16 +8,16 @@ Facade 組件為常用的 Hyperf 服務提供靜態代理。 composer require friendsofhyperf/facade ``` -基礎套件依賴 `friendsofhyperf/support`、`hyperf/context` 和 `hyperf/di`。大多數 -Facade 還需要可選依賴，請只安裝應用程式實際使用的 Facade 所需套件，例如： +基礎包依賴 `friendsofhyperf/support`、`hyperf/context` 和 `hyperf/di`。大多數 +Facade 還需要可選依賴，請僅安裝應用實際使用的 Facade 所需的包，例如： ```shell composer require hyperf/config hyperf/logger ``` -## 支援的 Facade +## 支持的 Facade -| Facade | 容器存取器 | 額外依賴 | +| Facade | 容器訪問器 | 額外依賴 | | --- | --- | --- | | `AMQP` | `Hyperf\Amqp\Producer` | `hyperf/amqp` | | `App`, `DI` | `Psr\Container\ContainerInterface` | 已包含（`hyperf/di`） | @@ -43,15 +43,15 @@ composer require hyperf/config hyperf/logger ## 配置與解析 -Hyperf 會自動發現此組件，但它的 `ConfigProvider` 不會發佈或合併任何配置。請按各 +Hyperf 會自動發現此組件，但它的 `ConfigProvider` 不發佈或合併任何配置。請按各 Hyperf 組件的正常方式配置底層服務。 除下方列出的組件特有方法外，對 Facade 的靜態調用會轉發給 -`ApplicationContext` 根據上表存取器解析出的物件。Facade 基類會快取首次解析的 -物件。如果容器中不存在對應存取器，將拋出 +`ApplicationContext` 根據上表訪問器解析出的對象。Facade 基類會緩存首次解析的 +對象。如果容器中不存在對應訪問器，將拋出 `Hyperf\Di\Exception\NotFoundException`。 -需要底層物件本身時，可以調用 `getFacadeRoot()`： +需要底層對象本身時，可以調用 `getFacadeRoot()`： ```php use FriendsOfHyperf\Facade\Config; @@ -60,23 +60,23 @@ $config = Config::getFacadeRoot(); $name = Config::get('app_name', 'hyperf'); ``` -每個代理可接受的方法是其底層存取器的公開方法。具體簽名請參考相應組件文檔。 +每個代理可接受的方法是其底層訪問器的公開方法。具體簽名請參考相應組件文檔。 ## 組件特有方法 -以下公開方法由 Facade 類別自身實作： +以下公開方法由 Facade 類自身實現： | Facade | 方法 | 行為 | | --- | --- | --- | -| `AMQP` | `dispatch(ProducerMessageInterface $producerMessage): PendingAmqpProducerMessageDispatch` | 建立 AMQP 待調度物件的實例方法。 | -| `AsyncQueue` | `dispatch(Closure\|JobInterface $job): PendingAsyncQueueDispatch` | 建立非同步佇列待調度物件的實例方法。 | -| `AsyncQueue` | `push(JobInterface $job, int $delay = 0, ?string $pool = null)` | 使用指定佇列池推送；當 `$pool` 為 `null` 時使用 `$job->getPoolName()`；文檔返回類型為 `bool`。 | -| `Cookie` | `has($key)` | 檢查目前請求中的 Cookie，而不是 CookieJar；文檔參數類型為 `string`，返回類型為 `bool`。 | -| `Cookie` | `get($key, $default = null)` | 讀取目前請求中的 Cookie；文檔鍵類型為 `string`，返回類型為 `mixed`。 | -| `Kafka` | `dispatch(ProduceMessage $produceMessage): PendingKafkaProducerMessageDispatch` | 建立 Kafka 待調度物件的實例方法。 | -| `Kafka` | `send(ProduceMessage $produceMessage, ?string $pool = null): void` | 以單元素批次發送訊息；未指定池時使用 `default`。 | -| `Kafka` | `sendBatch($produceMessages, ?string $pool = null): void` | 發送文檔類型為 `ProduceMessage[]` 的訊息批次；未指定池時使用 `default`。 | -| `Log` | `channel(string $name = 'hyperf', string $channel = 'default')` | 從 `LoggerFactory` 取得 `LoggerInterface`；其他 `Log` 靜態調用使用這兩個預設值。 | +| `AMQP` | `dispatch(ProducerMessageInterface $producerMessage): PendingAmqpProducerMessageDispatch` | 創建 AMQP 待調度對象的實例方法。 | +| `AsyncQueue` | `dispatch(Closure\|JobInterface $job): PendingAsyncQueueDispatch` | 創建異步隊列待調度對象的實例方法。 | +| `AsyncQueue` | `push(JobInterface $job, int $delay = 0, ?string $pool = null)` | 使用指定隊列池推送；當 `$pool` 為 `null` 時使用 `$job->getPoolName()`；文檔返回類型為 `bool`。 | +| `Cookie` | `has($key)` | 檢查當前請求中的 Cookie，而不是 CookieJar；文檔參數類型為 `string`，返回類型為 `bool`。 | +| `Cookie` | `get($key, $default = null)` | 讀取當前請求中的 Cookie；文檔鍵類型為 `string`，返回類型為 `mixed`。 | +| `Kafka` | `dispatch(ProduceMessage $produceMessage): PendingKafkaProducerMessageDispatch` | 創建 Kafka 待調度對象的實例方法。 | +| `Kafka` | `send(ProduceMessage $produceMessage, ?string $pool = null): void` | 以單元素批次發送消息；未指定隊列池時使用 `default`。 | +| `Kafka` | `sendBatch($produceMessages, ?string $pool = null): void` | 發送文檔類型為 `ProduceMessage[]` 的消息批次；未指定隊列池時使用 `default`。 | +| `Log` | `channel(string $name = 'hyperf', string $channel = 'default')` | 從 `LoggerFactory` 獲取 `LoggerInterface`；其他 `Log` 靜態調用使用這兩個默認值。 | `AMQP::dispatch`、`AsyncQueue::dispatch` 和 `Kafka::dispatch` 被聲明為實例方法。 它們不是靜態 Facade 代理方法。 diff --git a/docs/zh-hk/components/fast-paginate.md b/docs/zh-hk/components/fast-paginate.md index 5cc27fc9b..0dcf4c749 100644 --- a/docs/zh-hk/components/fast-paginate.md +++ b/docs/zh-hk/components/fast-paginate.md @@ -5,9 +5,9 @@ ## 關於 Fast Paginate 為 Hyperf 模型查詢構造器和關係提供更快的 `limit`/`offset` 分頁宏。它最適合偏移量較大的 -查詢，但實際效能取決於數據和索引，請在應用中與標準分頁器進行基準測試。 +查詢，但實際性能取決於數據和索引，請在應用中與標準分頁器進行基準測試。 -該組件使用類似延遲連接的方式。它首先對僅選擇模型主鍵以及排序所需已選別名的查詢進行分頁，然後通過第二次 +該組件使用類似延遲連接的方式。它首先對僅選擇模型主鍵以及排序所需選中別名的查詢進行分頁，然後通過第二次 查詢獲取當前頁主鍵對應的完整數據。兩次數據查詢的概念形式如下： ```sql @@ -24,7 +24,7 @@ select * from contacts where contacts.id in (...); composer require friendsofhyperf/fast-paginate ``` -該組件依賴 Hyperf 3.2 系列軟件包。無需配置：Hyperf 會發現組件的 `ConfigProvider`，並在應用啟動時註冊 +該組件依賴 Hyperf 3.2 系列軟件包。無需配置：Hyperf 會發現組件的 `ConfigProvider`，並在應用啓動時註冊 分頁宏。 ## 使用 @@ -49,12 +49,12 @@ simpleFastPaginate($perPage = null, $columns = ['*'], $pageName = 'page', $page ``` - `$perPage`：每頁條目數；`null` 使用模型配置的每頁條目數。 -- `$columns`：獲取完整數據時查詢的欄位。 -- `$pageName`：用於解析當前頁的查詢字串參數名。 +- `$columns`：獲取完整數據時查詢的列。 +- `$pageName`：用於解析當前頁的查詢字符串參數名。 - `$page`：明確指定的頁碼；`null` 時從當前請求解析。 `fastPaginate()` 返回包含總數的長度感知分頁器。`simpleFastPaginate()` 返回僅判斷是否還有下一頁的簡單 -分頁器。`BelongsToMany` 關係會保留已填充的中間表數據，同時也支援 `HasManyThrough` 關係。 +分頁器。`BelongsToMany` 關係會保留已填充的中間表數據，同時也支持 `HasManyThrough` 關係。 ### Scout 查詢構造器 @@ -74,6 +74,6 @@ Scout 的標準 `paginate()` 方法，不使用數據庫兩次查詢優化。本 - 查詢包含 `having`、`group by` 或 `union` 子句； - `$perPage` 為 `-1`； -- 排序所需的已選表達式包含 `?` 綁定佔位符。 +- 排序所需的選中表達式包含 `?` 綁定佔位符。 這些回退會保留分頁行為，但不會獲得快速分頁優化。 diff --git a/docs/zh-hk/components/grpc-validation.md b/docs/zh-hk/components/grpc-validation.md index 6d70046ad..45d1d54ea 100644 --- a/docs/zh-hk/components/grpc-validation.md +++ b/docs/zh-hk/components/grpc-validation.md @@ -8,13 +8,13 @@ composer require friendsofhyperf/grpc-validation ``` -此組件面向 Hyperf 3.2，並依賴 `hyperf/context`、`hyperf/di`、`hyperf/grpc-server` -和 `hyperf/validation`。Composer 會安裝這些依賴，套件內的 `ConfigProvider` 會自動註冊驗證切面， -毋須發佈組件設定檔。 +該組件面向 Hyperf 3.2，並依賴 `hyperf/context`、`hyperf/di`、`hyperf/grpc-server` +和 `hyperf/validation`。Composer 會安裝這些依賴，包內的 `ConfigProvider` 會自動註冊驗證切面， +無需發佈組件配置文件。 ## 基本用法 -在 gRPC 服務方法上加入 `Validation`，並為 protobuf 訊息欄位定義 Hyperf 驗證規則： +在 gRPC 服務方法上添加 `Validation`，併為 protobuf 消息字段定義 Hyperf 驗證規則： ```php 'value'], 60); ``` -控制台命令使用單獨的命名空間： +控制枱命令使用單獨的命名空間： ```php use function FriendsOfHyperf\Helpers\Command\call; diff --git a/docs/zh-hk/components/http-client.md b/docs/zh-hk/components/http-client.md index e073cfef8..1d7d44b61 100644 --- a/docs/zh-hk/components/http-client.md +++ b/docs/zh-hk/components/http-client.md @@ -1,6 +1,6 @@ # HTTP Client -適用於 Hyperf 的 HTTP 客戶端組件，移植自 Laravel，並由 Guzzle 提供底層支援。 +適用於 Hyperf 的 HTTP 客户端組件，移植自 Laravel，並由 Guzzle 提供底層支持。 ## 安裝 @@ -8,12 +8,12 @@ composer require friendsofhyperf/http-client guzzlehttp/guzzle:^7.6 ``` -`guzzlehttp/guzzle` 是本套件建議安裝的依賴，傳送請求時必須可用。無需發佈設定檔。 +`guzzlehttp/guzzle` 是本包建議安裝的依賴，發送請求時必須可用。無需發佈配置文件。 -## 傳送請求 +## 發送請求 -使用 `Http` 門面傳送 `GET`、`HEAD`、`POST`、`PUT`、`PATCH` 和 `DELETE` -請求。請求內容預設以 JSON 格式傳送。 +使用 `Http` 門面發送 `GET`、`HEAD`、`POST`、`PUT`、`PATCH` 和 `DELETE` +請求。請求體默認以 JSON 格式發送。 ```php use FriendsOfHyperf\Http\Client\Http; @@ -27,7 +27,7 @@ $response = Http::post('https://example.com/users', [ ]); ``` -在 HTTP 方法前以鏈式方法設定待傳送請求： +在 HTTP 方法前鏈式調用方法以配置待發送請求： ```php $response = Http::baseUrl('https://example.com') @@ -40,8 +40,8 @@ $response = Http::baseUrl('https://example.com') ->get('/users/{user}', ['active' => true]); ``` -使用 `withUrlParameters()` 展開 URI 範本佔位符。使用 `asForm()`、`attach()` -或 `withBody()` 分別傳送表單、多部分或原始請求內容： +使用 `withUrlParameters()` 展開 URI 模板佔位符。使用 `asForm()`、`attach()` +或 `withBody()` 分別發送表單、多部分或原始請求體： ```php $response = Http::withUrlParameters(['user' => 1]) @@ -55,13 +55,13 @@ $response = Http::attach('avatar', fopen('/path/to/avatar.jpg', 'r'), 'avatar.jp ->post('https://example.com/users/1/avatar'); ``` -預設連線逾時為 10 秒，請求總逾時為 30 秒。可使用 `withOptions()` 傳入其他 -Guzzle 請求選項。只應在確實需要停用 TLS 憑證驗證時使用 `withoutVerifying()`。 +默認連接超時為 10 秒，請求總超時為 30 秒。可使用 `withOptions()` 傳入其他 +Guzzle 請求選項。僅在確實需要禁用 TLS 證書驗證時使用 `withoutVerifying()`。 ## 重試 -`retry()` 的第一個參數可以是總嘗試次數，也可以是以毫秒為單位的退避延遲陣列。 -第二個參數可以是固定延遲或閉包。可選的第三個參數決定是否重試失敗回應或連線例外。 +`retry()` 的第一個參數可以是總嘗試次數，也可以是以毫秒為單位的退避延遲數組。 +第二個參數可以是固定延遲或閉包。可選的第三個參數決定是否重試失敗響應或連接異常。 ```php use FriendsOfHyperf\Http\Client\PendingRequest; @@ -74,11 +74,11 @@ $response = Http::retry( )->get('https://example.com'); ``` -預設情況下，重試耗盡後會拋出例外。將第四個參數設為 `false` 可回傳最終失敗回應。 +默認情況下，重試耗盡後會拋出異常。將第四個參數設為 `false` 可返回最終失敗響應。 -## 回應與例外 +## 響應與異常 -請求回傳 `FriendsOfHyperf\Http\Client\Response`。常用回應方法包括： +請求返回 `FriendsOfHyperf\Http\Client\Response`。常用響應方法包括： ```php $response->body(); @@ -99,8 +99,8 @@ $response->clientError(); $response->serverError(); ``` -HTTP 4xx 和 5xx 回應預設不會拋出例外。在待傳送請求或回應上呼叫 `throw()` 可拋出 -`RequestException`。連線失敗會拋出 `ConnectionException`。 +HTTP 4xx 和 5xx 響應默認不會拋出異常。在待發送請求或響應上調用 `throw()` 可拋出 +`RequestException`。連接失敗會拋出 `ConnectionException`。 ```php use FriendsOfHyperf\Http\Client\RequestException; @@ -112,9 +112,9 @@ try { } ``` -## 並行請求 +## 併發請求 -使用 `pool()` 並行傳送請求。使用 `as()` 為回應指定鍵名。 +使用 `pool()` 併發發送請求。使用 `as()` 為響應指定鍵名。 ```php use FriendsOfHyperf\Http\Client\Http; @@ -132,8 +132,8 @@ $responses['user']->status(); ## 測試 -`fake()` 會攔截符合的請求，並記錄請求以供斷言。呼叫 `preventStrayRequests()` -可拒絕沒有符合假回應的請求。 +`fake()` 會攔截匹配的請求，並記錄請求以供斷言。調用 `preventStrayRequests()` +可拒絕沒有匹配假響應的請求。 ```php use FriendsOfHyperf\Http\Client\Http; @@ -150,8 +150,8 @@ Http::assertSent(fn (Request $request) => $request->url() === 'https://example.c Http::assertSentCount(1); ``` -重複請求需要回傳不同回應時，可使用回應序列。序列耗盡後預設拋出 -`OutOfBoundsException`，除非設定了 `whenEmpty()` 或 `dontFailWhenEmpty()`。 +重複請求需要返回不同響應時，可使用響應序列。序列耗盡後默認拋出 +`OutOfBoundsException`，除非配置了 `whenEmpty()` 或 `dontFailWhenEmpty()`。 ```php Http::fakeSequence('example.com/*') @@ -162,17 +162,17 @@ Http::fakeSequence('example.com/*') 其他可用斷言包括 `assertNotSent()`、`assertNothingSent()`、`assertSentInOrder()` 和 `assertSequencesAreEmpty()`。 -## 中介軟件與事件 +## 中間件與事件 使用 `withMiddleware()`、`withRequestMiddleware()` 或 `withResponseMiddleware()` -加入單次請求中介軟件。`Factory` 還提供 `globalMiddleware()`、 +添加單次請求中間件。`Factory` 還提供 `globalMiddleware()`、 `globalRequestMiddleware()` 和 `globalResponseMiddleware()`。 -使用 PSR 事件分派器建立 `Factory` 時，組件會分派 `RequestSending`、 +使用 PSR 事件分發器創建 `Factory` 時，組件會分發 `RequestSending`、 `ResponseReceived` 和 `ConnectionFailed` 事件。 -## Laravel 相容性 +## Laravel 兼容性 -本組件 API 基於 Laravel HTTP 客戶端，但實際可用 API 和行為以本組件源碼為準。 -可參閱 [Laravel HTTP Client 文件](https://laravel.com/docs/9.x/http-client) -了解更多背景，並在使用前對照本組件確認 API。 +本組件 API 基於 Laravel HTTP 客户端，但實際可用 API 和行為以本組件源碼為準。 +可參閲 [Laravel HTTP Client 文檔](https://laravel.com/docs/9.x/http-client) +瞭解更多背景，並在使用前對照本組件確認 API。 diff --git a/docs/zh-hk/components/ide-helper.md b/docs/zh-hk/components/ide-helper.md index 3c8307780..d55f708ca 100644 --- a/docs/zh-hk/components/ide-helper.md +++ b/docs/zh-hk/components/ide-helper.md @@ -1,6 +1,6 @@ # IDE Helper -IDE Helper 組件為 Hyperf 模型及使用 `Hyperf\Macroable\Macroable` 的類別生成 PHP 助手檔案。 +IDE Helper 組件為 Hyperf 模型及使用 `Hyperf\Macroable\Macroable` 的類生成 PHP 助手文件。 ## 安裝 @@ -9,44 +9,44 @@ composer require friendsofhyperf/ide-helper ``` Hyperf 會發現組件的 `ConfigProvider`，並自動註冊 `ide-helper:model` 和 -`ide-helper:macro` 命令。組件不會發佈配置檔案。 +`ide-helper:macro` 命令。組件不會發布配置文件。 ## 模型助手 -為應用程式 `app` 目錄下找到的具體模型類別生成助手： +為應用 `app` 目錄下找到的具體模型類生成助手： ```shell php ./bin/hyperf.php ide-helper:model ``` 命令會在當前目錄寫入 `_ide_helper_models.php`。它會生成 `Eloquent` 助手，並根據類型轉換、 -存取器、關聯關係和軟刪除推斷模型屬性及方法。 +訪問器、關聯關係和軟刪除推斷模型屬性及方法。 -使用 `--name`（`-N`）修改輸出檔案；使用 `--ignore`（`-I`）排除以逗號分隔的完整模型類別名稱： +使用 `--name`（`-N`）修改輸出文件；使用 `--ignore`（`-I`）排除以逗號分隔的完整模型類名： ```shell php ./bin/hyperf.php ide-helper:model --name=storage/ide-models.php \ --ignore='App\Model\InternalModel,App\Model\LegacyModel' ``` -安裝建議依賴 `doctrine/dbal` 後，還可從資料庫資料表欄位推斷屬性： +安裝建議依賴 `doctrine/dbal` 後，還可從數據庫表字段推斷屬性： ```shell composer require --dev doctrine/dbal ``` -## 巨集助手 +## 宏助手 -為已載入的巨集生成助手： +為已加載的宏生成助手： ```shell php ./bin/hyperf.php ide-helper:macro ``` -掃描 Composer 優化類別映射前，命令會執行 `composer dump-autoload -o --no-scripts`。預設會在 +掃描 Composer 優化類映射前，命令會運行 `composer dump-autoload -o --no-scripts`。默認會在 當前目錄寫入 `_ide_helper_macros.php`。 -使用 `--name`（`-N`）修改輸出檔案： +使用 `--name`（`-N`）修改輸出文件： ```shell php ./bin/hyperf.php ide-helper:macro --name=storage/ide-macros.php @@ -54,7 +54,7 @@ php ./bin/hyperf.php ide-helper:macro --name=storage/ide-macros.php ## 配置 -需要自訂生成行為時，請建立 `config/autoload/ide-helper.php`： +需要自定義生成行為時，請創建 `config/autoload/ide-helper.php`： ```php `：將自訂資料庫類型映射為 Doctrine 類型。 -- `macro.namespaces`：只掃描類別名稱以其中任一前綴開頭的類別映射條目；空陣列會掃描全部條目。 -- `macro.rejects`：巨集生成時排除的完整類別名稱。 +- `model.custom_db_types.`：將自定義數據庫類型映射為 Doctrine 類型。 +- `macro.namespaces`：只掃描類名以其中任一前綴開頭的類映射條目；空數組會掃描全部條目。 +- `macro.rejects`：宏生成時排除的完整類名。 diff --git a/docs/zh-hk/components/index.md b/docs/zh-hk/components/index.md index bd1d687c3..74fa2d3d1 100644 --- a/docs/zh-hk/components/index.md +++ b/docs/zh-hk/components/index.md @@ -5,74 +5,74 @@ ## 開發與診斷 -- [Telescope](telescope.md)：檢查請求、異常、查詢、Redis 指令等執行資訊。 -- [Tinker](tinker.md)：在 Hyperf 應用程式中執行互動式 REPL。 -- [Web Tinker](web-tinker.md)：透過瀏覽器使用 Tinker。 -- [IDE Helper](ide-helper.md)：為應用程式類別產生 IDE 元資料。 -- [Pretty Console](pretty-console.md)：格式化命令列輸出。 -- [Command Benchmark](command-benchmark.md)：測量指令執行過程。 +- [Telescope](telescope.md)：檢查請求、異常、查詢、Redis 命令等運行信息。 +- [Tinker](tinker.md)：在 Hyperf 應用中運行交互式 REPL。 +- [Web Tinker](web-tinker.md)：通過瀏覽器使用 Tinker。 +- [IDE Helper](ide-helper.md)：為應用類生成 IDE 元數據。 +- [Pretty Console](pretty-console.md)：格式化命令行輸出。 +- [Command Benchmark](command-benchmark.md)：測量命令執行過程。 -## 資料庫與模型 +## 數據庫與模型 -- [Model Factory](model-factory.md)：為測試和種子資料建立模型工廠。 +- [Model Factory](model-factory.md)：為測試和種子數據創建模型工廠。 - [Model Observer](model-observer.md)：註冊模型觀察者。 -- [Model Scope](model-scope.md)：定義可重用的模型查詢作用域。 -- [Model Hashids](model-hashids.md)：對外提供編碼後的模型識別碼。 -- [Model Morph Addon](model-morph-addon.md)：擴充多型模型關聯。 -- [Compoships](compoships.md)：使用多欄定義模型關聯。 -- [Fast Paginate](fast-paginate.md)：最佳化大型資料集分頁。 -- [MySQL Grammar Addon](mysql-grammar-addon.md)：擴充 MySQL 查詢語法。 +- [Model Scope](model-scope.md)：定義可複用的模型查詢作用域。 +- [Model Hashids](model-hashids.md)：對外提供編碼後的模型標識。 +- [Model Morph Addon](model-morph-addon.md)：擴展多態模型關聯。 +- [Compoships](compoships.md)：使用多列定義模型關聯。 +- [Fast Paginate](fast-paginate.md)：優化大數據集分頁。 +- [MySQL Grammar Addon](mysql-grammar-addon.md)：擴展 MySQL 查詢語法。 - [Trigger](trigger.md)：消費 MySQL binlog 事件。 -## 快取與協調 +## 緩存與協調 -- [Cache](cache.md)：使用表達力更強的快取 API。 -- [Lock](lock.md)：透過分散式鎖協調工作。 -- [Redis Subscriber](redis-subscriber.md)：消費 Redis Pub/Sub 訊息。 +- [Cache](cache.md)：使用表達力更強的緩存 API。 +- [Lock](lock.md)：通過分佈式鎖協調任務。 +- [Redis Subscriber](redis-subscriber.md)：消費 Redis Pub/Sub 消息。 ## HTTP 與外部服務 -- [HTTP Client](http-client.md)：使用便捷的 HTTP 用戶端。 -- [OAuth2 Server](oauth2-server.md)：建立 OAuth 2.0 授權伺服器。 -- [OpenAI Client](openai-client.md)：整合 OpenAI PHP 用戶端。 -- [Elasticsearch](elasticsearch.md)：設定 Elasticsearch 用戶端。 -- [reCAPTCHA](recaptcha.md)：驗證 Google reCAPTCHA 回應。 +- [HTTP Client](http-client.md)：使用便捷的 HTTP 客户端。 +- [OAuth2 Server](oauth2-server.md)：構建 OAuth 2.0 授權服務器。 +- [OpenAI Client](openai-client.md)：集成 OpenAI PHP 客户端。 +- [Elasticsearch](elasticsearch.md)：配置 Elasticsearch 客户端。 +- [reCAPTCHA](recaptcha.md)：驗證 Google reCAPTCHA 響應。 -## 訊息與通知 +## 消息與通知 -- [AMQP Job](amqp-job.md)：將 AMQP 訊息作為工作派發。 -- [Mail](mail.md)：使用 Symfony Mailer 傳送郵件。 -- [Notification](notification.md)：透過多個管道傳送通知。 -- [Notification Mail](notification-mail.md)：透過郵件傳送通知。 -- [Notification EasySms](notification-easysms.md)：透過短訊傳送通知。 -- [TCP Sender](tcp-sender.md)：向 TCP 服務傳送訊息。 +- [AMQP Job](amqp-job.md)：將 AMQP 消息作為任務派發。 +- [Mail](mail.md)：使用 Symfony Mailer 發送郵件。 +- [Notification](notification.md)：通過多個渠道發送通知。 +- [Notification Mail](notification-mail.md)：通過郵件發送通知。 +- [Notification EasySms](notification-easysms.md)：通過短信發送通知。 +- [TCP Sender](tcp-sender.md)：向 TCP 服務發送消息。 -## 設定與基礎設施 +## 配置與基礎設施 -- [Confd](confd.md)：使用 confd 管理設定。 -- [Config Consul](config-consul.md)：從 Consul 載入設定。 -- [IPC Broadcaster](ipc-broadcaster.md)：在 Worker 程序之間廣播訊息。 -- [Telescope Elasticsearch](telescope-elasticsearch.md)：將 Telescope 記錄儲存到 Elasticsearch。 +- [Confd](confd.md)：使用 confd 管理配置。 +- [Config Consul](config-consul.md)：從 Consul 加載配置。 +- [IPC Broadcaster](ipc-broadcaster.md)：在 Worker 進程之間廣播消息。 +- [Telescope Elasticsearch](telescope-elasticsearch.md)：將 Telescope 記錄存儲到 Elasticsearch。 ## 安全與驗證 -- [Encryption](encryption.md)：加密和解密應用程式資料。 +- [Encryption](encryption.md)：加密和解密應用數據。 - [Purifier](purifier.md)：清理 HTML 輸入。 -- [Validated DTO](validated-dto.md)：驗證並填入資料傳輸物件。 -- [Command Validation](command-validation.md)：驗證主控台指令輸入。 +- [Validated DTO](validated-dto.md)：驗證並填充數據傳輸對象。 +- [Command Validation](command-validation.md)：驗證控制枱命令輸入。 - [gRPC Validation](grpc-validation.md)：驗證 gRPC 請求。 -- [Rate Limit](rate-limit.md)：套用可設定的速率限制演算法。 +- [Rate Limit](rate-limit.md)：應用可配置的限流算法。 -## 框架擴充 +## 框架擴展 - [Facade](facade.md)：定義 Laravel 風格的 Facade。 -- [Macros](macros.md)：為框架類別加入巨集。 +- [Macros](macros.md)：為框架類添加宏。 - [Helpers](helpers.md)：使用額外的輔助函數。 -- [Support](support.md)：使用共用工具、流暢派發和退避策略。 +- [Support](support.md)：使用共享工具、流式派發和退避策略。 - [Exception Event](exception-event.md)：為異常派發事件。 -## 指令與執行環境 +## 命令與運行時 -- [Command Signals](command-signals.md)：在指令中處理程序訊號。 +- [Command Signals](command-signals.md)：在命令中處理進程信號。 - [Console Spinner](console-spinner.md)：顯示進度 Spinner。 -- [Co-PHPUnit](co-phpunit.md)：在協程中執行 PHPUnit 測試。 +- [Co-PHPUnit](co-phpunit.md)：在協程中運行 PHPUnit 測試。 diff --git a/docs/zh-hk/components/ipc-broadcaster.md b/docs/zh-hk/components/ipc-broadcaster.md index fd7cc6968..932f27490 100644 --- a/docs/zh-hk/components/ipc-broadcaster.md +++ b/docs/zh-hk/components/ipc-broadcaster.md @@ -1,6 +1,6 @@ # Ipc Broadcaster -在 Hyperf Server Worker 和用戶進程之間廣播可序列化訊息。 +在 Hyperf Server Worker 和用户進程之間廣播可序列化消息。 ## 安裝 @@ -8,22 +8,22 @@ composer require friendsofhyperf/ipc-broadcaster ``` -該套件會自動註冊 `ConfigProvider`，將 `BroadcasterInterface` 綁定到 -`AllProcessesBroadcaster`，並註冊 Server Worker 接收訊息所需的監聽器。該組件沒有需要發佈的配置檔案。 +該包會自動註冊 `ConfigProvider`，將 `BroadcasterInterface` 綁定到 +`AllProcessesBroadcaster`，並註冊 Server Worker 接收消息所需的監聽器。該組件沒有需要發佈的配置文件。 -該套件的 `composer.json` 僅聲明了 `hyperf/event ~3.2.0`，且沒有聲明可選依賴。請在提供廣播器所需 +該包的 `composer.json` 僅聲明瞭 `hyperf/event ~3.2.0`，且沒有聲明可選依賴。請在提供廣播器所需 Server、Process、容器和 DI 運行時類的 Hyperf Server 應用中使用。 -## 廣播訊息 +## 廣播消息 `broadcast()` 函數接受 `IpcMessageInterface` 實例或閉包。默認通過 -`AllProcessesBroadcaster` 將訊息發送到其他所有 Server Worker 和所有已註冊的協程用戶進程。 +`AllProcessesBroadcaster` 將消息發送到其他所有 Server Worker 和所有已註冊的協程用户進程。 -### 類訊息 +### 類消息 繼承 `IpcMessage` 並實現 `handle()`。`IpcMessage` 還通過 `InteractsWithFromWorkerId` 提供 `getFromWorkerId()` 和 `setFromWorkerId()`。Server Worker -收到訊息時，`getFromWorkerId()` 包含發送方的 Worker ID。 +收到消息時，`getFromWorkerId()` 包含發送方的 Worker ID。 ```php broadcast($message); Server Worker。`UserProcessesBroadcaster` 接受可選的進程名稱和進程 ID；兩者均未傳時，會發送到 Hyperf `ProcessCollector` 收集的所有已註冊進程。 -## 在用戶進程中處理訊息 +## 在用户進程中處理消息 -組件會為 Server Worker 收到的訊息自動調用 `handle()`。在用戶進程中，Hyperf 會派發 -`Hyperf\Process\Event\PipeMessage`，組件不會自動調用其中訊息的 `handle()` 方法。需要讓用戶進程 -執行訊息時，請註冊監聽器： +組件會為 Server Worker 收到的消息自動調用 `handle()`。在用户進程中，Hyperf 會派發 +`Hyperf\Process\Event\PipeMessage`，組件不會自動調用其中消息的 `handle()` 方法。需要讓用户進程 +執行消息時，請註冊監聽器： ```php use FriendsOfHyperf\IpcBroadcaster\Contract\IpcMessageInterface; @@ -112,7 +112,7 @@ class UserProcessPipeMessageListener implements ListenerInterface ## 在當前 Worker 中運行 -廣播默認不會在當前 Server Worker 中執行。給訊息添加 `RunsInCurrentWorker` 後，會先在當前 Worker +廣播默認不會在當前 Server Worker 中執行。給消息添加 `RunsInCurrentWorker` 後，會先在當前 Worker 中調用一次 `handle()`，再發送到所選目標： ```php @@ -130,7 +130,7 @@ class RefreshMessage extends IpcMessage } ``` -## 協程伺服器限制 +## 協程服務器限制 -觸發 `MainCoroutineServerStart` 後，跨進程廣播會被禁用，廣播器調用不會發送訊息便直接返回。使用 -`RunsInCurrentWorker` 的訊息仍會在廣播器返回前在本地執行一次。 +觸發 `MainCoroutineServerStart` 後，跨進程廣播會被禁用，廣播器調用不會發送消息便直接返回。使用 +`RunsInCurrentWorker` 的消息仍會在廣播器返回前在本地執行一次。 diff --git a/docs/zh-hk/components/lock.md b/docs/zh-hk/components/lock.md index 8707d3415..bffe0e627 100644 --- a/docs/zh-hk/components/lock.md +++ b/docs/zh-hk/components/lock.md @@ -8,7 +8,7 @@ Hyperf 原子鎖組件。 composer require friendsofhyperf/lock ``` -預設驅動使用 Redis。請根據使用的驅動安裝對應的可選依賴： +默認驅動使用 Redis。請根據使用的驅動安裝對應的可選依賴： | 驅動 | 配置名稱 | 可選依賴 | | --- | --- | --- | @@ -18,34 +18,34 @@ composer require friendsofhyperf/lock | `CoroutineLock` | `co` | 無 | | `CacheLock` | 未發佈 | `hyperf/cache` | -發佈配置檔案： +發佈配置文件： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/lock -i config ``` -使用資料庫驅動時，還需要發佈並執行鎖遷移： +使用數據庫驅動時，還需要發佈並執行鎖遷移： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/lock -i migrations php bin/hyperf.php migrate ``` -執行發佈的遷移前，請將其中的 `value` 欄位改為 `owner`。目前 `DatabaseLock` 實作讀寫的是 -`owner` 欄位。 +運行發佈的遷移前，請將其中的 `value` 列改為 `owner`。當前 `DatabaseLock` 實現讀寫的是 +`owner` 列。 ## 配置 發佈的 `config/autoload/lock.php` 包含 `default`、`file`、`database` 和 `co` 配置。每項配置 -用於選擇驅動類別，並將其中的 `constructor` 選項傳給驅動。`lock()` 和 -`LockFactory::make()` 的第四個參數是配置名稱，而不是驅動類別名稱。 +用於選擇驅動類，並將其中的 `constructor` 選項傳給驅動。`lock()` 和 +`LockFactory::make()` 的第四個參數是配置名稱，而不是驅動類名。 所選的 `lock.` 配置不存在時，工廠會拋出 `InvalidArgumentException`。你也可以新增 -自訂配置，其驅動須實作 `FriendsOfHyperf\Lock\Driver\LockInterface`。 +自定義配置，其驅動須實現 `FriendsOfHyperf\Lock\Driver\LockInterface`。 -## 建立鎖 +## 創建鎖 -匯入並呼叫帶命名空間的輔助函式： +導入並調用帶命名空間的輔助函數： ```php use function FriendsOfHyperf\Lock\lock; @@ -61,14 +61,14 @@ if ($lock->get()) { } ``` -不傳名稱呼叫 `lock()` 時返回 `LockFactory`，否則返回 `LockInterface` 實例。參數如下： +不傳名稱調用 `lock()` 時返回 `LockFactory`，否則返回 `LockInterface` 實例。參數如下： - `name`：鎖名稱。 -- `seconds`：請求的鎖有效期秒數，預設為 `0`。 -- `owner`：可選的擁有者識別；省略時會隨機產生。 -- `driver`：`lock` 下的配置名稱，預設為 `default`。 +- `seconds`：請求的鎖有效期秒數，默認為 `0`。 +- `owner`：可選的所有者標識；省略時會隨機生成。 +- `driver`：`lock` 下的配置名稱，默認為 `default`。 -TTL 行為取決於驅動。特別是當 `seconds` 為 `0` 或負數時，`DatabaseLock` 會儲存一天的 +TTL 行為取決於驅動。特別是當 `seconds` 為 `0` 或負數時，`DatabaseLock` 會存儲一天的 過期時間。 ## 鎖操作 @@ -76,8 +76,8 @@ TTL 行為取決於驅動。特別是當 `seconds` 為 `0` 或負數時，`Datab `LockInterface` 公開 `get()`、`block()`、`release()`、`owner()`、`forceRelease()`、 `refresh()`、`isExpired()` 和 `getRemainingLifetime()`。 -`get()` 只嘗試取得一次；未傳回呼時返回布林值。傳入回呼時，它會返回回呼結果，並在 -`finally` 區塊中釋放鎖： +`get()` 只嘗試獲取一次；未傳回調時返回布爾值。傳入回調時，它會返回回調結果，並在 +`finally` 塊中釋放鎖： ```php $result = lock('foo', 10)->get(function () { @@ -85,7 +85,7 @@ $result = lock('foo', 10)->get(function () { }); ``` -`block()` 會重試，直到取得鎖或達到等待時限；逾時時拋出 `LockTimeoutException`。傳入回呼 +`block()` 會重試，直到獲取鎖或達到等待時限；超時時拋出 `LockTimeoutException`。傳入回調 時也會自動釋放鎖： ```php @@ -100,15 +100,15 @@ try { } ``` -`release()` 只釋放目前擁有者持有的鎖，`forceRelease()` 會忽略擁有權。僅當驅動支援時， -`refresh($ttl)` 才能重新整理過期時間；TTL 不為正數時返回 `false`。`isExpired()` 和 -`getRemainingLifetime()` 返回鎖實例追蹤的過期狀態。 +`release()` 只釋放當前所有者持有的鎖，`forceRelease()` 會忽略所有權。僅當驅動支持時， +`refresh($ttl)` 才能刷新過期時間；TTL 不為正數時返回 `false`。`isExpired()` 和 +`getRemainingLifetime()` 返回鎖實例跟蹤的過期狀態。 ## 註解 ### 屬性注入 -`#[Lock]` 用於屬性，並在應用程式啟動時注入鎖實例。參數為 `name`、`seconds`、`owner` 和 +`#[Lock]` 用於屬性，並在應用啓動時注入鎖實例。參數為 `name`、`seconds`、`owner` 和 `driver`。 ```php @@ -124,8 +124,8 @@ class Foo ### 阻塞方法 -`#[Blockable]` 用於方法。當 `seconds` 大於 `0` 時，它會建立鎖並最多等待 `seconds` 秒取得 -鎖，然後在方法返回或拋出例外後自動釋放。`ttl` 是鎖有效期，`driver` 用於選擇鎖配置。 +`#[Blockable]` 用於方法。當 `seconds` 大於 `0` 時，它會創建鎖並最多等待 `seconds` 秒獲取 +鎖，然後在方法返回或拋出異常後自動釋放。`ttl` 是鎖有效期，`driver` 用於選擇鎖配置。 `prefix` 和 `value` 會結合方法參數格式化為鎖名稱。 `Blockable` 使用 `Hyperf\Cache\Helper\StringHelper`，因此使用此註解前需安裝 diff --git a/docs/zh-hk/components/macros.md b/docs/zh-hk/components/macros.md index 93377d10f..50b944dc5 100644 --- a/docs/zh-hk/components/macros.md +++ b/docs/zh-hk/components/macros.md @@ -1,7 +1,7 @@ # Macros -此組件為 Hyperf 的集合、上下文、請求和字串類別加入常用宏。組件的 `ConfigProvider` 會在應用程式 -啟動時自動註冊 mixin，無需發佈設定檔。 +該組件為 Hyperf 的集合、上下文、請求和字符串類添加常用宏。組件的 `ConfigProvider` 會在應用啓動時 +自動註冊 mixin，無需發佈配置文件。 ## 安裝 @@ -11,18 +11,18 @@ composer require friendsofhyperf/macros ## 可選依賴 -已註冊的宏會直接使用以下可選套件： +已註冊的宏會直接使用以下可選包： - `hyperf/http-server`：所有 `Request` 宏。 - `league/commonmark`：`Str::markdown`、`Str::inlineMarkdown` 及對應的 `Stringable` 方法。 - `voku/portable-ascii`：`Str::transliterate`。 -- `friendsofhyperf/encryption`：`Stringable::encrypt` 和 `Stringable::decrypt`；同時需要設定 +- `friendsofhyperf/encryption`：`Stringable::encrypt` 和 `Stringable::decrypt`；同時需要配置 encryption 組件。 -`composer.json` 還建議安裝用於產生 UUID 的 `ramsey/uuid`、用於產生 ULID 的 `symfony/uid` 和 -`opis/closure`。目前 mixin 原始碼不會直接呼叫這三個套件。 +`composer.json` 還建議安裝用於生成 UUID 的 `ramsey/uuid`、用於生成 ULID 的 `symfony/uid` 和 +`opis/closure`。當前 mixin 源碼不會直接調用這三個包。 -## 支援方法 +## 支持方法 ### Hyperf\Collection\Arr @@ -38,9 +38,9 @@ composer require friendsofhyperf/macros - `Arr::sortByMany($array, $comparisons = [])` - `Arr::string(ArrayAccess|array $array, null|string|int $key, ?string $default = null)` -帶類型的讀取方法支援點號路徑；解析出的值不符合目標類型時會拋出 `InvalidArgumentException`。 -`Arr::from` 可將支援的陣列、Enumerable/Arrayable 物件、可遍歷物件、支援 JSON 的物件和一般物件 -轉換為陣列，但拒絕純量值。 +帶類型的讀取方法支持點號路徑；解析出的值不符合目標類型時會拋出 `InvalidArgumentException`。 +`Arr::from` 可將受支持的數組、Enumerable/Arrayable 對象、可遍歷對象、支持 JSON 的對象和普通對象 +轉換為數組，但拒絕標量值。 ### Hyperf\Collection\Collection @@ -50,7 +50,7 @@ composer require friendsofhyperf/macros - `LazyCollection::collapseWithKeys()` -`collapseWithKeys` 在保留鍵的同時展平巢狀陣列或集合。非陣列和非集合值會被忽略，後出現的重複鍵會 +`collapseWithKeys` 在保留鍵的同時展平嵌套數組或集合。非數組和非集合值會被忽略，後出現的重複鍵會 覆蓋先前的值。 ### Hyperf\Context\Context @@ -58,7 +58,7 @@ composer require friendsofhyperf/macros - `Context::decrement(string $id, int $step = 1, ?int $coroutineId = null)` - `Context::increment(string $id, int $step = 1, ?int $coroutineId = null)` -兩個方法都透過 `Context::override` 更新所選上下文中的值。缺少的值會先按零處理，再套用步長。 +兩個方法都通過 `Context::override` 更新選定上下文中的值。缺失的值會先按零處理，再應用步長。 ### Hyperf\HttpServer\Request @@ -102,8 +102,8 @@ composer require friendsofhyperf/macros - `Request::whenFilled($key, callable $callback, ?callable $default = null)` - `Request::whenHas($key, callable $callback, ?callable $default = null)` -`Request::fake` 建立獨立的 PSR-7 `ServerRequest`，並可選擇將其傳給回呼。`merge` 和 -`mergeIfMissing` 會更新目前上下文中儲存的解析後輸入。`validate` 和 `validateWithBag` 會從容器 +`Request::fake` 創建獨立的 PSR-7 `ServerRequest`，並可選擇將其傳給回調。`merge` 和 +`mergeIfMissing` 會更新當前上下文中存儲的解析後輸入。`validate` 和 `validateWithBag` 會從容器 解析 Hyperf 的 `ValidatorFactoryInterface`。 ### Hyperf\Stringable\Str @@ -130,10 +130,10 @@ composer require friendsofhyperf/macros - `Stringable::toHtmlString()` - `Stringable::whenIsAscii($callback, $default = null)` -多數 `Stringable` 轉換宏會傳回新的 `Stringable` 實例，因此可以鏈式呼叫。兩個 `doesnt*` 方法傳回 -布林值，`toHtmlString` 傳回 `FriendsOfHyperf\Support\HtmlString`。 +多數 `Stringable` 轉換宏返回新的 `Stringable` 實例，因此可以鏈式調用。兩個 `doesnt*` 方法返回 +布爾值，`toHtmlString` 返回 `FriendsOfHyperf\Support\HtmlString`。 -## 範例 +## 示例 ```php use Hyperf\Collection\Arr; diff --git a/docs/zh-hk/components/mail.md b/docs/zh-hk/components/mail.md index 8a02e6c2a..85d828882 100644 --- a/docs/zh-hk/components/mail.md +++ b/docs/zh-hk/components/mail.md @@ -1,6 +1,6 @@ # Mail -Mail 組件透過 Symfony Mailer 傳輸發送視圖、Markdown、HTML 和純文字郵件。 +Mail 組件通過 Symfony Mailer 傳輸發送視圖、Markdown、HTML 和純文本郵件。 ## 安裝 @@ -9,7 +9,7 @@ composer require friendsofhyperf/mail php bin/hyperf.php vendor:publish friendsofhyperf/mail ``` -發佈組件會建立 `config/autoload/mail.php`，並將郵件視圖組件複製到 `storage/views/mail`。 +發佈組件會創建 `config/autoload/mail.php`，並將郵件視圖組件複製到 `storage/views/mail`。 如果應用尚無 Hyperf 視圖配置，請另行發佈： ```shell @@ -25,9 +25,9 @@ php bin/hyperf.php vendor:publish hyperf/view ## 配置 -發佈的配置預設使用 `log` mailer。透過 `MAIL_MAILER` 選擇 mailer，並在 `mail.mailers` 下配置。 -支援的傳輸包括 `smtp`、`sendmail`、`mail`、`mailgun`、`ses`、`ses-v2`、`postmark`、`log`、 -`array`、`failover` 和 `roundrobin`。可使用 `Mail::extend()` 註冊自訂傳輸。 +發佈的配置默認使用 `log` mailer。通過 `MAIL_MAILER` 選擇 mailer，並在 `mail.mailers` 下配置。 +支持的傳輸包括 `smtp`、`sendmail`、`mail`、`mailgun`、`ses`、`ses-v2`、`postmark`、`log`、 +`array`、`failover` 和 `roundrobin`。可使用 `Mail::extend()` 註冊自定義傳輸。 ```php // config/autoload/mail.php @@ -67,19 +67,19 @@ return [ ]; ``` -mailer 專屬的 `from`、`reply_to`、`to` 或 `return_path` 會覆蓋對應全域地址。全域 `to` 地址還會在 +mailer 專屬的 `from`、`reply_to`、`to` 或 `return_path` 會覆蓋對應全局地址。全局 `to` 地址還會在 發送前移除原始 To、Cc 和 Bcc 收件人，適合開發環境使用。 -## 建立 Mailable +## 創建 Mailable -安裝 `hyperf/devtool` 後，可生成基於視圖的 mailable；使用 `--markdown` 會同時建立 Markdown 模板： +安裝 `hyperf/devtool` 後，可生成基於視圖的 mailable；使用 `--markdown` 會同時創建 Markdown 模板： ```shell php bin/hyperf.php gen:mail TestMail php bin/hyperf.php gen:mail TestMail --markdown ``` -`Envelope` 定義地址、主題、標籤、元數據和 Symfony 訊息回調。`Content` 接受 `view`（或其 `html` +`Envelope` 定義地址、主題、標籤、元數據和 Symfony 消息回調。`Content` 接受 `view`（或其 `html` 別名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中聲明的 public 屬性也會暴露給視圖。 ```php @@ -120,13 +120,13 @@ class TestMail extends Mailable } ``` -附件還可透過 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 建立。可重用的附件 -物件可以實現 `FriendsOfHyperf\Mail\Contract\Attachable`。 +附件還可通過 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 創建。可複用的附件 +對象可以實現 `FriendsOfHyperf\Mail\Contract\Attachable`。 ## 發送郵件 `Mail::mailer()` 選擇已配置的 mailer；省略參數時使用 `mail.default`。`to()`、`cc()` 和 `bcc()` -返回待發送郵件物件，其 `send()` 接受 `FriendsOfHyperf\Mail\Contract\Mailable`。發送成功時返回 +返回待發送郵件對象，其 `send()` 接受 `FriendsOfHyperf\Mail\Contract\Mailable`。發送成功時返回 `SentMessage`；當 `MessageSending` 監聽器中止發送時返回 `null`。 ```php @@ -139,7 +139,7 @@ Mail::mailer('smtp') ->send(new TestMail('Hyperf')); ``` -對於無需 mailable 類的郵件，mailer 還提供 `html()`、`raw()`、`plain()`，以及接受視圖名或視圖陣列的 +對於無需 mailable 類的郵件，mailer 還提供 `html()`、`raw()`、`plain()`，以及接受視圖名或視圖數組的 `send()`。回調會收到 `FriendsOfHyperf\Mail\Message`，其未知方法會轉發給底層 Symfony `Email`。 ```php diff --git a/docs/zh-hk/components/model-factory.md b/docs/zh-hk/components/model-factory.md index 3a288bb91..27c27850b 100644 --- a/docs/zh-hk/components/model-factory.md +++ b/docs/zh-hk/components/model-factory.md @@ -1,6 +1,6 @@ # Model Factory -此元件用於載入 Hyperf 模型工廠定義，並提供 +此組件用於加載 Hyperf 模型工廠定義，並提供 `FriendsOfHyperf\ModelFactory\factory()` 輔助函數。 ## 安裝 @@ -9,18 +9,18 @@ composer require friendsofhyperf/model-factory --dev ``` -此套件要求 PHP `^8.0`、Faker，以及 Hyperf 的 config、database 和 stringable 元件， -沒有宣告可選依賴。 +此包要求 PHP `^8.0`、Faker，以及 Hyperf 的 config、database 和 stringable 組件， +沒有聲明可選依賴。 -發佈設定和範例工廠檔案： +發佈配置和示例工廠文件： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/model-factory ``` -該命令會建立 `config/autoload/model_factory.php` 和 `factories/model_factory.php`。 +該命令會創建 `config/autoload/model_factory.php` 和 `factories/model_factory.php`。 -## 設定 +## 配置 ```php define(User::class, function (Generator $faker) { }); ``` -可以向 `define()` 傳入第三個參數來定義具名工廠： +可以向 `define()` 傳入第三個參數來定義命名工廠： ```php $factory->define(User::class, function (Generator $faker) { @@ -67,7 +67,7 @@ $factory->state(User::class, 'suspended', ['active' => false]); ## 使用輔助函數 -使用前先匯入輔助函數： +使用前先導入輔助函數： ```php use App\Model\User; @@ -81,20 +81,20 @@ factory(User::class, 'admin')->create(); factory(User::class, 'admin', 5)->create(); ``` -輔助函數接收模型類別，之後可以傳入數量，或傳入具名工廠及可選數量。 -第二個參數為字串時，它會選擇具名工廠，而不是套用工廠狀態。 -應在傳回的建構器上套用已註冊的狀態： +輔助函數接收模型類，之後可以傳入數量，或傳入命名工廠及可選數量。 +第二個參數為字符串時，它會選擇命名工廠，而不是應用工廠狀態。 +應在返回的構建器上應用已註冊的狀態： ```php factory(User::class)->state('suspended')->create(); ``` -輔助函數傳回 `Hyperf\Database\Model\FactoryBuilder`。常用的終止方法包括： +輔助函數返回 `Hyperf\Database\Model\FactoryBuilder`。常用的終止方法包括： -- `make()`：建構模型但不持久化。 -- `create()`：建構並持久化模型。 -- `raw()`：傳回產生的屬性陣列。 +- `make()`：構建模型但不持久化。 +- `create()`：構建並持久化模型。 +- `raw()`：返回生成的屬性數組。 -未指定數量時，這些方法傳回單個結果；指定數量時，傳回模型集合或原始屬性陣列清單。 -傳給這些方法的屬性陣列會覆蓋產生的值。如果應用程式容器不可用， -`factory()` 傳回 `null`。 +未指定數量時，這些方法返回單個結果；指定數量時，返回模型集合或原始屬性數組列表。 +傳給這些方法的屬性數組會覆蓋生成的值。如果應用容器不可用， +`factory()` 返回 `null`。 diff --git a/docs/zh-hk/components/model-hashids.md b/docs/zh-hk/components/model-hashids.md index 99469a91f..79bb75bec 100644 --- a/docs/zh-hk/components/model-hashids.md +++ b/docs/zh-hk/components/model-hashids.md @@ -1,6 +1,6 @@ # Model Hashids -Model Hashids 按需編碼和解碼模型主鍵。hashid 不會儲存到資料庫中，因此查詢仍然使用模型的主鍵欄位。 +Model Hashids 按需編碼和解碼模型主鍵。hashid 不會存儲到數據庫中，因此查詢仍然使用模型的主鍵列。 ## 安裝 @@ -8,16 +8,16 @@ Model Hashids 按需編碼和解碼模型主鍵。hashid 不會儲存到資料 composer require friendsofhyperf/model-hashids ``` -此元件依賴 `hashids/hashids`，以及 Hyperf 3.2 的 config、database 和 stringable 元件。僅在需要 -自訂 hashid 設定時發佈配置檔案： +此組件依賴 `hashids/hashids`，以及 Hyperf 3.2 的 config、database 和 stringable 組件。僅在需要 +自定義 hashid 設置時發佈配置文件： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/model-hashids ``` -## 設定 +## 設置 -在模型中使用 `HasHashid`。如果隱式路由綁定也需要使用 hashid，再新增 `HashidRouting`： +在模型中使用 `HasHashid`。如果隱式路由綁定也需要使用 hashid，再添加 `HashidRouting`： ```php use FriendsOfHyperf\ModelHashids\Concerns\HasHashid; @@ -33,7 +33,7 @@ class Item extends Model ## 配置 -發佈後的檔案為 `config/autoload/hashids.php`。`default` 用於選擇連線，每個連線可設定 `salt`、 +發佈後的文件為 `config/autoload/hashids.php`。`default` 用於選擇連接，每個連接可設置 `salt`、 `length` 和 `alphabet`： ```php @@ -49,9 +49,9 @@ return [ ]; ``` -未發佈配置時，元件使用 `main` 連線、空 salt、最小長度 `0` 和上面顯示的字元表。 +未發佈配置時，組件使用 `main` 連接、空 salt、最小長度 `0` 和上面顯示的字符表。 -如需為某個模型選擇其他連線，請覆寫受保護的 `getHashidsConnection()` 方法： +如需為某個模型選擇其他連接，請覆寫受保護的 `getHashidsConnection()` 方法： ```php class Item extends Model @@ -88,12 +88,12 @@ Item::findByHashid($hashid); Item::findByHashidOrFail($hashid); ``` -`hashidToId()` 返回 `hashids/hashids` 解碼出的第一個 ID；請傳入使用相同連線設定產生的有效 +`hashidToId()` 返回 `hashids/hashids` 解碼出的第一個 ID；請傳入使用相同連接設置生成的有效 hashid。 ### 序列化 Hashid -`hashid` 存取器不會自動附加。可將它新增到模型的 `$appends` 屬性： +`hashid` 訪問器不會自動追加。可將它添加到模型的 `$appends` 屬性： ```php class Item extends Model @@ -104,7 +104,7 @@ class Item extends Model } ``` -也可以僅在需要時附加： +也可以僅在需要時追加： ```php return $item->append('hashid')->toJson(); @@ -112,7 +112,7 @@ return $item->append('hashid')->toJson(); ### 隱式路由綁定 -`HashidRouting` 將模型的 hashid 作為預設路由鍵，並透過 `byHashid` 解析： +`HashidRouting` 將模型的 hashid 作為默認路由鍵，並通過 `byHashid` 解析： ```php Route::get('/items/{item}', function (Item $item) { @@ -120,7 +120,7 @@ Route::get('/items/{item}', function (Item $item) { }); ``` -當路由明確指定其他欄位時，解析會交給模型的父類別實作： +當路由明確指定其他字段時，解析會交給模型的父類實現： ```php Route::get('/items/{item:slug}', function (Item $item) { @@ -128,7 +128,7 @@ Route::get('/items/{item:slug}', function (Item $item) { }); ``` -也可以將其他欄位設為預設路由鍵，同時在特定路由中指定 `hashid`： +也可以將其他字段設為默認路由鍵，同時在特定路由中指定 `hashid`： ```php class Item extends Model diff --git a/docs/zh-hk/components/model-morph-addon.md b/docs/zh-hk/components/model-morph-addon.md index dc8ba3bf5..f075e4427 100644 --- a/docs/zh-hk/components/model-morph-addon.md +++ b/docs/zh-hk/components/model-morph-addon.md @@ -1,6 +1,6 @@ # Model Morph Addon -Model Morph Addon 允許宣告 `morphTo` 關聯的模型自行解析多態別名，而不必只依賴全域多態映射。 +Model Morph Addon 允許聲明 `morphTo` 關聯的模型自行解析多態別名，而不必只依賴全局多態映射。 ## 要求 @@ -14,12 +14,12 @@ Model Morph Addon 允許宣告 `morphTo` 關聯的模型自行解析多態別名 composer require friendsofhyperf/model-morph-addon ``` -套件的 `ConfigProvider` 會自動註冊兩個 AOP 切面。它沒有需要發佈的設定檔，也沒有可選的整合依賴。 +包的 `ConfigProvider` 會自動註冊兩個 AOP 切面。它沒有需要發佈的配置文件，也沒有可選的集成依賴。 ## 定義模型局部多態映射 -在宣告 `morphTo()` 的模型上覆寫 `getActualClassNameForMorph()`。每個關聯模型應透過 -`getMorphClass()` 傳回資料庫中儲存的別名。 +在聲明 `morphTo()` 的模型上重寫 `getActualClassNameForMorph()`。每個關聯模型應通過 +`getMorphClass()` 返回數據庫中存儲的別名。 ```php namespace App\Model; @@ -71,11 +71,11 @@ class User extends Model } ``` -解析器應為每個輸入傳回有效的模型類別。未知別名傳回原值，可以保留 Hyperf 的預設回退行為。 +解析器應為每個輸入返回有效的模型類。未知別名返回原值，可以保留 Hyperf 的默認回退行為。 ## 查詢所有多態類型 -當 `hasMorph()` 接收到萬用字元類型列表 `['*']` 時，組件也會套用模型局部解析器。委派給 +當 `hasMorph()` 接收到通配符類型列表 `['*']` 時，組件也會應用模型局部解析器。委託給 `hasMorph()` 的方法（例如 `whereHasMorph()` 和 `doesntHaveMorph()`）具有相同行為。 ```php @@ -84,12 +84,12 @@ $images = Image::query() ->get(); ``` -對於 `['*']`，Hyperf 會找出模型資料表中儲存的不同且非空多態類型值。組件會先透過 -`Image::getActualClassNameForMorph()` 解析每個值，再由 Hyperf 建立關聯查詢。 +對於 `['*']`，Hyperf 會發現模型表中存儲的不同且非空的多態類型值。組件會先通過 +`Image::getActualClassNameForMorph()` 解析每個值，再由 Hyperf 構建關聯查詢。 ## 行為 -- 載入 `Image::imageable` 關聯時，會透過 `Image::getActualClassNameForMorph()` 解析其儲存類型。 -- 多態別名屬於宣告 `morphTo()` 的模型；不同模型可以用不同方式解析同一別名。 -- 傳給多態查詢方法的明確類型列表維持 Hyperf 的預設行為。查詢切面只改變完全符合的萬用字元列表 +- 加載 `Image::imageable` 關聯時，會通過 `Image::getActualClassNameForMorph()` 解析其存儲類型。 +- 多態別名屬於聲明 `morphTo()` 的模型；不同模型可以用不同方式解析同一別名。 +- 傳給多態查詢方法的顯式類型列表保持 Hyperf 的默認行為。查詢切面只改變完全匹配的通配符列表 `['*']`。 diff --git a/docs/zh-hk/components/model-observer.md b/docs/zh-hk/components/model-observer.md index 488d51737..96d3d4e71 100644 --- a/docs/zh-hk/components/model-observer.md +++ b/docs/zh-hk/components/model-observer.md @@ -1,6 +1,6 @@ # Model Observer -Model Observer 組件用於註冊處理 Hyperf 模型事件的類別。觀察者可以在觀察者類別上綁定，也可以在模型類別上綁定。 +Model Observer 組件用於註冊處理 Hyperf 模型事件的類。觀察者可以在觀察者類上綁定，也可以在模型類上綁定。 ## 安裝 @@ -8,7 +8,7 @@ Model Observer 組件用於註冊處理 Hyperf 模型事件的類別。觀察者 composer require friendsofhyperf/model-observer ``` -組件會透過 ConfigProvider 自動註冊。與 Hyperf 模型一起使用時需要安裝 `hyperf/database`： +組件會通過 ConfigProvider 自動註冊。與 Hyperf 模型一起使用時需要安裝 `hyperf/database`： ```shell composer require hyperf/database @@ -16,13 +16,13 @@ composer require hyperf/database ## 生成觀察者 -向 `gen:observer` 傳入模型類別，可在預設的 `App\Observer` 命名空間中生成觀察者： +向 `gen:observer` 傳入模型類，可在默認的 `App\Observer` 命名空間中生成觀察者： ```shell php bin/hyperf.php gen:observer UserObserver --model="App\\Model\\User" ``` -該命令還支援： +該命令還支持： ```shell php bin/hyperf.php gen:observer UserObserver \ @@ -31,11 +31,11 @@ php bin/hyperf.php gen:observer UserObserver \ --force ``` -- `--model`、`-M`：用於生成屬性和方法簽名的模型類別。 +- `--model`、`-M`：用於生成屬性和方法簽名的模型類。 - `--namespace`、`-N`：生成的觀察者命名空間。 -- `--force`、`-f`：覆蓋已存在的觀察者檔案。 +- `--force`、`-f`：覆蓋已存在的觀察者文件。 -可以在 `config/autoload/devtool.php` 中修改預設命名空間或範本： +可以在 `config/autoload/devtool.php` 中修改默認命名空間或模板： ```php return [ @@ -50,7 +50,7 @@ return [ ## 從觀察者綁定 -在觀察者類別上使用 `#[Observer]`。`model` 參數接受一個模型類別或模型類別陣列： +在觀察者類上使用 `#[Observer]`。`model` 參數接受一個模型類或模型類數組： ```php namespace App\Observer; @@ -63,12 +63,12 @@ class UserObserver { public function creating(User $model): void { - // 建立用戶前執行。 + // 創建用户前執行。 } public function created(User $model): void { - // 建立用戶後執行。 + // 創建用户後執行。 } } ``` @@ -86,7 +86,7 @@ class SearchIndexObserver { public function saved(Model $model): void { - // 更新搜尋索引。 + // 更新搜索索引。 } } ``` @@ -104,7 +104,7 @@ class AuditObserver ## 從模型綁定 -使用 `#[ObservedBy]` 在模型上聲明觀察者。它的 `classes` 參數接受一個觀察者類別或觀察者類別陣列， +使用 `#[ObservedBy]` 在模型上聲明觀察者。它的 `classes` 參數接受一個觀察者類或觀察者類數組， 並且該屬性可以重複聲明： ```php @@ -122,7 +122,7 @@ class User extends Model } ``` -來自 `#[Observer]` 和 `#[ObservedBy]` 的綁定會合併。同一模型的重複觀察者類別只會調用一次。 +來自 `#[Observer]` 和 `#[ObservedBy]` 的綁定會合並。同一模型的重複觀察者類只會調用一次。 ## 在協程中運行觀察者 @@ -140,14 +140,14 @@ class UserObserver implements ShouldCoroutine { public function created(User $model): void { - // 在新建立的協程中運行。 + // 在新創建的協程中運行。 } } ``` -協程觀察者非同步運行，不要依賴它們在模型操作返回前執行完畢。 +協程觀察者異步運行，不要依賴它們在模型操作返回前執行完畢。 -## 支援的事件 +## 支持的事件 觀察者只需定義需要的方法。每個可調用方法都會接收模型實例： @@ -166,4 +166,4 @@ class UserObserver implements ShouldCoroutine - `deleted` - `forceDeleted` -組件透過 Hyperf 事件分發這些方法。觀察者方法的返回值會被忽略，不能用於取消模型操作。 +組件通過 Hyperf 事件分發這些方法。觀察者方法的返回值會被忽略，不能用於取消模型操作。 diff --git a/docs/zh-hk/components/model-scope.md b/docs/zh-hk/components/model-scope.md index 97cdcefb6..da410a892 100644 --- a/docs/zh-hk/components/model-scope.md +++ b/docs/zh-hk/components/model-scope.md @@ -1,6 +1,6 @@ # Model Scope -Model Scope 組件透過可重複使用的 `#[ScopedBy]` 註解註冊 Hyperf 模型全域 +Model Scope 組件通過可重複使用的 `#[ScopedBy]` 註解註冊 Hyperf 模型全局 Scope。 ## 使用要求 @@ -15,7 +15,7 @@ Scope。 composer require friendsofhyperf/model-scope ``` -組件的 `ConfigProvider` 會自動註冊 Scope 監聽器，無需發佈配置檔案。 +組件的 `ConfigProvider` 會自動註冊 Scope 監聽器，無需發佈配置文件。 ## 定義 Scope @@ -39,8 +39,7 @@ class AncientScope implements Scope ## 將 Scope 綁定到模型 -在模型類別上加入 `#[ScopedBy]`。應用程式啟動時，該 Scope 會被註冊為全域 -Scope。 +在模型類上添加 `#[ScopedBy]`。應用啓動時，該 Scope 會被註冊為全局 Scope。 ```php namespace App\Model; @@ -57,9 +56,9 @@ class User extends Model ## 註冊多個 Scope -`classes` 參數可以接收單個 Scope 類別或 Scope 類別陣列，該註解也可以重複 -使用。`priority` 預設為 `0`；優先級越高的 Scope 越先註冊。同一個註解中 -傳入的所有類別共用一個優先級。 +`classes` 參數可以接收單個 Scope 類或 Scope 類數組，該註解也可以重複使用。 +`priority` 默認為 `0`；優先級越高的 Scope 越先註冊。同一個註解中傳入的所有 +類共用一個優先級。 ```php namespace App\Model; @@ -79,12 +78,12 @@ class User extends Model ## 註冊行為 -觸發 `BootApplication` 時，組件會讀取所有帶有 `#[ScopedBy]` 註解的模型類別。 -對於每個聲明的 Scope 類別，組件會： +觸發 `BootApplication` 時，組件會讀取所有帶有 `#[ScopedBy]` 註解的模型類。 +對於每個聲明的 Scope 類，組件會： -1. 驗證類別存在並實現 `Hyperf\Database\Model\Scope`； -2. 檢查容器中是否存在該類別； +1. 驗證類存在並實現 `Hyperf\Database\Model\Scope`； +2. 檢查容器中是否存在該類； 3. 從容器解析實例，並將其傳給 `Model::addGlobalScope()`。 -未通過任一檢查的 Scope 項目會被略過。Scope 建構函式可以使用容器能夠解析的 +未通過任一檢查的 Scope 條目會被跳過。Scope 構造函數可以使用容器能夠解析的 依賴。相同優先級的 Scope 之間不保證註冊順序。 diff --git a/docs/zh-hk/components/mysql-grammar-addon.md b/docs/zh-hk/components/mysql-grammar-addon.md index 99b63e63c..a365c4497 100644 --- a/docs/zh-hk/components/mysql-grammar-addon.md +++ b/docs/zh-hk/components/mysql-grammar-addon.md @@ -1,6 +1,6 @@ # MySQL Grammar Addon -此組件用於避免 Hyperf 讀取 MySQL 資料表結構元數據時，非 ASCII 欄位註釋出現亂碼。 +該組件用於避免 Hyperf 讀取 MySQL 表結構元數據時，非 ASCII 字段註釋出現亂碼。 ## 安裝 @@ -8,28 +8,28 @@ composer require friendsofhyperf/mysql-grammar-addon --dev ``` -此套件要求 `hyperf/database` 和 `hyperf/di` 的版本為 `~3.2.0`，且未聲明可選依賴。Hyperf -套件自動發現會自動註冊此組件的切面，無需額外設定。 +該包要求 `hyperf/database` 和 `hyperf/di` 的版本為 `~3.2.0`，且未聲明可選依賴。Hyperf 包 +自動發現會自動註冊該組件的切面，無需額外配置。 ## 行為 -此切面會攔截以下 MySQL 資料表結構語法方法： +該切面會攔截以下 MySQL 表結構語法方法： - `Hyperf\Database\Schema\Grammars\MySqlGrammar::compileColumnListing()` - `Hyperf\Database\Schema\Grammars\MySqlGrammar::compileColumns()` -它會修改產生的元數據查詢，以二進制形式讀取欄位註釋： +它會修改生成的元數據查詢，以二進制形式讀取字段註釋： ```sql binary `column_comment` ``` -這樣，讀取 MySQL 資料表結構元數據的程式碼可以保留註釋的原始位元組。此組件不會新增查詢建構器 -方法，也沒有需要應用程式碼呼叫的公開 API。 +這樣，讀取 MySQL 表結構元數據的代碼可以保留註釋的原始字節。該組件不會添加查詢構造器方法， +也沒有需要應用代碼調用的公開 API。 -## 範例 +## 示例 -安裝此組件之前，產生的模型註解可能包含亂碼： +安裝該組件之前，生成的模型註解可能包含亂碼： ```php /** @@ -38,11 +38,11 @@ binary `column_comment` */ ``` -安裝此組件之後，可以保留原始註釋： +安裝該組件之後，可以保留原始註釋： ```php /** * @property int $user_id 用户id - * @property string $event_name 事件名称 + * @property string $event_name 事件名稱 */ ``` diff --git a/docs/zh-hk/components/notification-easysms.md b/docs/zh-hk/components/notification-easysms.md index b8a9e4af8..0d3746458 100644 --- a/docs/zh-hk/components/notification-easysms.md +++ b/docs/zh-hk/components/notification-easysms.md @@ -1,6 +1,6 @@ # Notification EasySms Channel -此元件透過 [EasySms](https://github.com/overtrue/easy-sms) 傳送通知。 +此組件通過 [EasySms](https://github.com/overtrue/easy-sms) 發送通知。 ## 安裝 @@ -8,25 +8,25 @@ composer require friendsofhyperf/notification-easysms ``` -元件依賴 `friendsofhyperf/notification` 和 `overtrue/easy-sms:^3.0`，Composer 會自動安裝。 +組件依賴 `friendsofhyperf/notification` 和 `overtrue/easy-sms:^3.0`，Composer 會自動安裝。 -## 設定 +## 配置 -發佈 `config/autoload/easy_sms.php`，然後參照 EasySms 文件設定預設策略、預設閘道和閘道憑證： +發佈 `config/autoload/easy_sms.php`，然後參照 EasySms 文檔配置默認策略、默認網關和網關憑據： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/notification-easysms ``` -元件會使用完整的 `easy_sms` 設定陣列建立 `EasySms` 實例。 +組件會使用完整的 `easy_sms` 配置數組創建 `EasySms` 實例。 ## 使用 -應用程式啟動時，元件會以 `easy-sms` 通道名稱註冊 `EasySmsChannel`。 +應用啓動時，組件會以 `easy-sms` 通道名註冊 `EasySmsChannel`。 ### 定義通知路由 -在接收者中使用 `Notifiable` trait，並定義 `routeNotificationForSms()`。此方法應傳回電話號碼字串。 +在接收者中使用 `Notifiable` trait，並定義 `routeNotificationForSms()`。該方法應返回手機號碼字符串。 ```php "你的驗證碼是 {$this->code}。", + 'content' => "您的驗證碼是 {$this->code}。", 'template' => 'SMS_123456789', 'data' => [ 'code' => $this->code, @@ -92,8 +92,8 @@ class VerificationCodeNotification extends Notification implements Smsable } ``` -EasySms 會將陣列載荷轉換為 `Message`。支援的訊息屬性包括 `content`、`template`、`data`、`type` -和 `gateways`。需要透過 `setGateways()` 等方法設定訊息時，可直接傳回 `Message`： +EasySms 會將數組載荷轉換為 `Message`。支持的消息屬性包括 `content`、`template`、`data`、`type` +和 `gateways`。需要通過 `setGateways()` 等方法配置消息時，可直接返回 `Message`： ```php public function toSms(mixed $notifiable): array|Message @@ -105,6 +105,6 @@ public function toSms(mixed $notifiable): array|Message } ``` -訊息未指定閘道時，EasySms 會使用 `config/autoload/easy_sms.php` 中的 `default.gateways`。傳送結果是 -EasySms 傳回的閘道結果陣列，並會傳給通知調度器。如果通知未實作 `Smsable`，通道會拋出 +消息未指定網關時，EasySms 會使用 `config/autoload/easy_sms.php` 中的 `default.gateways`。發送結果是 +EasySms 返回的網關結果數組，並會傳給通知調度器。如果通知未實現 `Smsable`，通道會拋出 `RuntimeException`。 diff --git a/docs/zh-hk/components/notification-mail.md b/docs/zh-hk/components/notification-mail.md index 2400bf497..778150c34 100644 --- a/docs/zh-hk/components/notification-mail.md +++ b/docs/zh-hk/components/notification-mail.md @@ -36,7 +36,7 @@ class User extends Model - // 通知信箱 + // 通知郵箱 public function routeNotificationForMail(): string { return $this->mail; diff --git a/docs/zh-hk/components/oauth2-server.md b/docs/zh-hk/components/oauth2-server.md index 58aa547cb..d27606a89 100644 --- a/docs/zh-hk/components/oauth2-server.md +++ b/docs/zh-hk/components/oauth2-server.md @@ -1,6 +1,6 @@ # OAuth2 Server -使用 `league/oauth2-server` 為 Hyperf 建立 OAuth 2.0 授權伺服器。 +使用 `league/oauth2-server` 為 Hyperf 構建 OAuth 2.0 授權服務器。 ## 安裝 @@ -10,45 +10,45 @@ php bin/hyperf.php vendor:publish friendsofhyperf/oauth2-server php bin/hyperf.php migrate ``` -發佈命令會建立 `config/autoload/oauth2-server.php`。在該檔案中設定私鑰、公鑰、加密金鑰、 -權杖有效期、啟用的授權類型和 scopes。 +發佈命令會創建 `config/autoload/oauth2-server.php`。在該文件中配置私鑰、公鑰、加密密鑰、 +令牌有效期、啓用的授權類型和 scopes。 -設定私鑰和公鑰路徑後產生密鑰對： +配置私鑰和公鑰路徑後生成密鑰對： ```shell php bin/hyperf.php oauth2-server:generate-keypair ``` -## 設定 +## 配置 -常用設定項包括： +常用配置項包括： -| 設定項 | 說明 | +| 配置項 | 説明 | | --- | --- | -| `authorization_server.private_key` | 用於簽發權杖的私鑰路徑。 | +| `authorization_server.private_key` | 用於簽發令牌的私鑰路徑。 | | `authorization_server.private_key_passphrase` | 可選的私鑰密碼。 | -| `authorization_server.encryption_key` | 授權伺服器使用的加密金鑰。 | -| `authorization_server.encryption_key_type` | `plain` 或其他支援的 `EncryptionKeyType`。 | +| `authorization_server.encryption_key` | 授權服務器使用的加密密鑰。 | +| `authorization_server.encryption_key_type` | `plain` 或其他支持的 `EncryptionKeyType`。 | | `authorization_server.access_token_ttl` | Access token 有效期，類型為 `DateInterval`。 | | `authorization_server.refresh_token_ttl` | Refresh token 有效期，類型為 `DateInterval`。 | | `authorization_server.persist_access_token` | 是否持久化已簽發的 access token。 | -| `resource_server.public_key` | 用於驗證權杖的公鑰路徑。 | +| `resource_server.public_key` | 用於驗證令牌的公鑰路徑。 | | `resource_server.jwt_leeway` | 可選的 JWT 時鐘偏移寬限時間。 | | `scopes.available` | 允許請求的 scopes。 | -| `scopes.default` | 未請求 scope 時預設分配的 scopes。 | +| `scopes.default` | 未請求 scope 時默認分配的 scopes。 | ## 命令 -| 命令 | 說明 | +| 命令 | 説明 | | --- | --- | | `oauth2-server:clear-expired-tokens` | 清理過期的 access token 和 refresh token。 | -| `oauth2-server:create-client` | 建立 OAuth2 用戶端。 | -| `oauth2-server:delete-client` | 刪除 OAuth2 用戶端。 | -| `oauth2-server:generate-keypair` | 產生私鑰/公鑰密鑰對。 | -| `oauth2-server:list-clients` | 列出 OAuth2 用戶端。 | -| `oauth2-server:update-client` | 更新 OAuth2 用戶端。 | +| `oauth2-server:create-client` | 創建 OAuth2 客户端。 | +| `oauth2-server:delete-client` | 刪除 OAuth2 客户端。 | +| `oauth2-server:generate-keypair` | 生成私鑰/公鑰密鑰對。 | +| `oauth2-server:list-clients` | 列出 OAuth2 客户端。 | +| `oauth2-server:update-client` | 更新 OAuth2 客户端。 | -按應用需要建立用戶端： +按應用需要創建客户端： ```shell php bin/hyperf.php oauth2-server:create-client "My App" \ @@ -59,7 +59,7 @@ php bin/hyperf.php oauth2-server:create-client "My App" \ ## Token Endpoint -元件提供授權伺服器工廠。可以在自己的控制器或路由處理器中處理 token 請求： +組件提供授權服務器工廠。可以在自己的控制器或路由處理器中處理 token 請求： ```php use FriendsOfHyperf\Oauth2\Server\Factory\AuthorizationServerFactory; @@ -94,5 +94,5 @@ Router::addGroup('/api', function () { ]); ``` -如果需要直接驗證請求，可以透過 `ResourceServerFactory` 建立 resource server 並呼叫 +如果需要直接驗證請求，可以通過 `ResourceServerFactory` 構建 resource server 並調用 `validateAuthenticatedRequest()`。 diff --git a/docs/zh-hk/components/openai-client.md b/docs/zh-hk/components/openai-client.md index ca690a568..454a323da 100644 --- a/docs/zh-hk/components/openai-client.md +++ b/docs/zh-hk/components/openai-client.md @@ -1,12 +1,12 @@ # OpenAI Client -此組件將 [openai-php/client](https://github.com/openai-php/client) 整合至 Hyperf， -向依賴注入容器註冊上游客戶端，並提供靜態門面。 +此組件將 [openai-php/client](https://github.com/openai-php/client) 集成到 Hyperf， +向依賴注入容器註冊上游客户端，並提供靜態門面。 ## 依賴要求 -此套件適用於 Hyperf 3.2，依賴 `hyperf/config`、`hyperf/di`、`hyperf/guzzle` 和 -0.10.0 或以上版本的 `openai-php/client`，並未聲明可選依賴。 +此包面向 Hyperf 3.2，依賴 `hyperf/config`、`hyperf/di`、`hyperf/guzzle` 和 0.10.0 或更高版本的 +`openai-php/client`，未聲明可選依賴。 ## 安裝 @@ -20,11 +20,11 @@ composer require friendsofhyperf/openai-client php bin/hyperf.php vendor:publish friendsofhyperf/openai-client ``` -此指令會建立 `config/autoload/openai.php`。 +此命令會創建 `config/autoload/openai.php`。 ## 配置 -發佈的配置文件會讀取以下環境變數： +發佈的配置文件會讀取以下環境變量： ```env OPENAI_BASE_URI=api.openai.com/v1 @@ -33,31 +33,31 @@ OPENAI_ORGANIZATION= OPENAI_REQUEST_TIMEOUT=30 ``` -| 配置項 | 預設值 | 說明 | +| 配置項 | 默認值 | 説明 | | --- | --- | --- | -| `openai.base_uri` | `api.openai.com/v1` | 傳給上游客戶端工廠的基礎 URI。 | -| `openai.api_key` | 空字串 | 用於 Bearer 身份驗證的 API 密鑰。 | -| `openai.organization` | `null` | 可選的 OpenAI 組織識別碼。 | -| `openai.request_timeout` | `30` | 傳給 Hyperf Guzzle 客戶端的逾時時間，單位為秒。 | +| `openai.base_uri` | `api.openai.com/v1` | 傳給上游客户端工廠的基礎 URI。 | +| `openai.api_key` | 空字符串 | 用於 Bearer 身份驗證的 API 密鑰。 | +| `openai.organization` | `null` | 可選的 OpenAI 組織標識。 | +| `openai.request_timeout` | `30` | 傳給 Hyperf Guzzle 客户端的超時時間，單位為秒。 | ## 容器綁定與運行行為 -組件會將 `OpenAI\Client` 和 `OpenAI\Contracts\ClientContract` 綁定至同一個 -客戶端實例。工廠會： +組件會將 `OpenAI\Client` 和 `OpenAI\Contracts\ClientContract` 綁定到同一個 +客户端實例。工廠會： -- 透過 `Hyperf\Guzzle\ClientFactory` 建立 HTTP 客戶端； -- 套用配置的基礎 URI、API 密鑰、組織和請求逾時時間； -- 傳送 `OpenAI-Beta: assistants=v2` 請求標頭。 +- 通過 `Hyperf\Guzzle\ClientFactory` 創建 HTTP 客户端； +- 應用配置的基礎 URI、API 密鑰、組織和請求超時時間； +- 發送 `OpenAI-Beta: assistants=v2` 請求頭。 -API 密鑰必須是字串，組織必須是 `null` 或字串。類型不正確時會拋出 -`FriendsOfHyperf\OpenAi\Exception\ApiKeyIsMissing`。空 API 密鑰仍是字串，因此不會 -觸發此例外；API 請求會改為因身份驗證失敗而報錯。 +API 密鑰必須是字符串，組織必須是 `null` 或字符串。類型不正確時會拋出 +`FriendsOfHyperf\OpenAi\Exception\ApiKeyIsMissing`。空 API 密鑰仍是字符串，因此不會 +觸發此異常；API 請求會改為因身份驗證失敗而報錯。 ## 使用 ### 容器 -可以從容器解析契約或具體客戶端。資源方法、請求參數和回應物件由已安裝的 +可以從容器解析契約或具體客户端。資源方法、請求參數和響應對象由已安裝的 `openai-php/client` 版本提供。 ```php @@ -83,11 +83,11 @@ use FriendsOfHyperf\OpenAi\Facade\OpenAI; $models = OpenAI::models()->list(); ``` -## Azure 與自訂客戶端 +## Azure 與自定義客户端 -組件工廠會固定配置 Bearer 身份驗證，且未提供自訂請求標頭或查詢參數的配置。 -Azure OpenAI 等需要 `api-key` 請求標頭和 `api-version` 查詢參數的服務，必須使用 -上游工廠手動建立客戶端： +組件工廠始終配置 Bearer 身份驗證，且未提供自定義請求頭或查詢參數的配置。 +Azure OpenAI 等需要 `api-key` 請求頭和 `api-version` 查詢參數的服務，必須使用 +上游工廠手動創建客户端： ```php use OpenAI; @@ -99,10 +99,10 @@ $client = OpenAI::factory() ->make(); ``` -手動建立的客戶端不會自動註冊至 Hyperf 容器。由於 Azure 基礎 URI 已包含部署， -因此針對該部署的調用毋須傳入 `model` 參數。 +手動創建的客户端不會自動註冊到 Hyperf 容器。由於 Azure 基礎 URI 已包含部署， +因此針對該部署的調用無需傳入 `model` 參數。 ## 上游 API 指南 -有關支援的資源和使用示例，請參閱與已安裝版本相符的 -[openai-php/client 文件](https://github.com/openai-php/client)。 +有關支持的資源和使用示例，請參閲與已安裝版本匹配的 +[openai-php/client 文檔](https://github.com/openai-php/client)。 diff --git a/docs/zh-hk/components/recaptcha.md b/docs/zh-hk/components/recaptcha.md index ddfb5e3e3..e70537bf6 100644 --- a/docs/zh-hk/components/recaptcha.md +++ b/docs/zh-hk/components/recaptcha.md @@ -8,17 +8,17 @@ composer require friendsofhyperf/recaptcha ``` -## 設定 +## 配置 -使用中介軟體或驗證規則前，先發佈 `config/autoload/recaptcha.php`： +使用中間件或驗證規則前，先發布 `config/autoload/recaptcha.php`： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/recaptcha ``` -透過 `RECAPTCHA_SECRET_V2_KEY` 設定 reCAPTCHA v2 金鑰，透過 `RECAPTCHA_SECRET_V3_KEY` -設定 reCAPTCHA v3 金鑰，也可以直接修改發佈檔案中的 `v2.secret_key` 與 `v3.secret_key`。 -`default` 用於選擇未明確傳入版本時使用的版本。 +通過 `RECAPTCHA_SECRET_V2_KEY` 配置 reCAPTCHA v2 密鑰，通過 `RECAPTCHA_SECRET_V3_KEY` +配置 reCAPTCHA v3 密鑰，也可以直接修改發佈文件中的 `v2.secret_key` 與 `v3.secret_key`。 +`default` 用於選擇未顯式傳入版本時使用的版本。 ## 使用 diff --git a/docs/zh-hk/components/sentry.md b/docs/zh-hk/components/sentry.md index 113fe1ea7..0c50a11ec 100644 --- a/docs/zh-hk/components/sentry.md +++ b/docs/zh-hk/components/sentry.md @@ -9,7 +9,7 @@ Hyperf 的 Sentry 組件。它將 Sentry PHP SDK 接入 Hyperf 應用生命週 composer require friendsofhyperf/sentry ``` -可選集成需要安裝對應的 Hyperf 或客戶端包，例如 `hyperf/amqp`、`hyperf/crontab`、 +可選集成需要安裝對應的 Hyperf 或客户端包，例如 `hyperf/amqp`、`hyperf/crontab`、 `hyperf/database`、`hyperf/rpc-multiplex`、`elasticsearch/elasticsearch`、 `phpmyadmin/sql-parser` 或 `hyperf/engine`。 @@ -19,7 +19,7 @@ composer require friendsofhyperf/sentry php bin/hyperf.php vendor:publish friendsofhyperf/sentry ``` -該命令會發佈 `config/autoload/sentry.php`。核心配置如下： +該命令會發布 `config/autoload/sentry.php`。核心配置如下： ```php setMaxAttempts(3); ``` -閉包支援依賴注入。待派發物件會在銷毀時派發工作。 +閉包支持依賴注入。待派發對象會在銷燬時派發任務。 ### AMQP 與 Kafka @@ -48,9 +48,9 @@ dispatch($amqpMessage) dispatch($kafkaMessage)->onPool('default'); ``` -### 條件設定 +### 條件配置 -所有待派發物件都支援 `when()` 和 `unless()`： +所有待派發對象都支持 `when()` 和 `unless()`： ```php dispatch($job) @@ -58,9 +58,9 @@ dispatch($job) ->unless($canRunNow, fn ($pending) => $pending->delay(60)); ``` -## 閉包工作 +## 閉包任務 -需要將閉包工作傳遞給其他 API 時，可以直接建立可序列化的非同步佇列工作： +需要將閉包任務傳遞給其他 API 時，可以直接創建可序列化的異步隊列任務： ```php use FriendsOfHyperf\Support\CallQueuedClosure; @@ -73,10 +73,10 @@ $job->setMaxAttempts(3); ## 退避策略 -退避策略實作會傳回下一次等待的毫秒數，並提供 `next()`、`reset()`、`getAttempt()` 和 +退避策略實現會返回下一次等待的毫秒數，並提供 `next()`、`reset()`、`getAttempt()` 和 `sleep()` 方法。 -### 陣列退避 +### 數組退避 ```php use FriendsOfHyperf\Support\Backoff\ArrayBackoff; @@ -86,7 +86,7 @@ $short = ArrayBackoff::fromPattern('short'); $fromString = ArrayBackoff::fromString('100, 500, 1000'); ``` -如果希望陣列耗盡後傳回 `0`，而不是重複最後一個值，請將建構函數第二個參數設為 `false`。 +如果希望數組耗盡後返回 `0`，而不是重複最後一個值，請將構造函數第二個參數設為 `false`。 ### 可用策略 @@ -94,13 +94,13 @@ $fromString = ArrayBackoff::fromString('100, 500, 1000'); - `LinearBackoff`：按固定步長增加等待時間。 - `ExponentialBackoff`：指數增長，可選抖動。 - `FibonacciBackoff`：使用斐波那契數列等待時間。 -- `PoissonBackoff`：基於泊松分佈產生等待時間。 -- `DecorrelatedJitterBackoff`：為分散式重試提供去相關抖動。 -- `ArrayBackoff`：使用呼叫方定義的等待序列。 +- `PoissonBackoff`：基於泊松分佈生成等待時間。 +- `DecorrelatedJitterBackoff`：為分佈式重試提供去相關抖動。 +- `ArrayBackoff`：使用調用方定義的等待序列。 ## 其他工具 此組件還包含 `retry()` 和 `once()` 輔助函數，以及 `ConfigurationUrlParser`、`Env`、 `HtmlString`、`Number`、`Once`、`Sleep`、`Timebox`、`UuidContainer`、`RedisCommand`、 -管道輔助功能和可重用 Trait。在其他組件新增重複工具前，請先檢查 -`FriendsOfHyperf\Support` 下已有的類別。 +管道輔助功能和可複用 Trait。在其他組件新增重複工具前，請先檢查 +`FriendsOfHyperf\Support` 下已有的類。 diff --git a/docs/zh-hk/components/validated-dto.md b/docs/zh-hk/components/validated-dto.md index 4185aa59f..0ff6de413 100644 --- a/docs/zh-hk/components/validated-dto.md +++ b/docs/zh-hk/components/validated-dto.md @@ -176,16 +176,16 @@ class CreateUserCommand extends Command } ``` -## 匯出 DTO 型別 +## 導出 DTO 類型 -使用 `dto:export` 可以將 DTO 類別匯出為 TypeScript。傳入完整 DTO 類別名稱，也可以指定輸出檔案： +使用 `dto:export` 可以將 DTO 類導出為 TypeScript。傳入完整 DTO 類名，也可以指定輸出文件： ```shell php bin/hyperf.php dto:export 'App\DTO\UserDTO' php bin/hyperf.php dto:export 'App\DTO\UserDTO' --output=resources/types/user.dto.ts --force ``` -`--lang` 選項支援 `typescript` 或 `ts`。 +`--lang` 選項支持 `typescript` 或 `ts`。 ## 訪問 DTO 數據 diff --git a/docs/zh-hk/faq/about.md b/docs/zh-hk/faq/about.md index a79be6153..937b668d7 100644 --- a/docs/zh-hk/faq/about.md +++ b/docs/zh-hk/faq/about.md @@ -1,20 +1,20 @@ # 關於 FriendsOfHyperf -## FriendsOfHyperf 是甚麼？ +## FriendsOfHyperf 是什麼？ -FriendsOfHyperf 是維護 Hyperf 可重用組件的社群專案。組件集涵蓋開發工具、資料庫輔助功能、 -訊息通訊、資料驗證、監控以及外部服務整合。 +FriendsOfHyperf 是維護 Hyperf 可複用組件的社區項目。組件集涵蓋開發工具、數據庫輔助功能、 +消息通信、數據驗證、監控以及外部服務集成。 ## 倉庫如何組織？ -`components` 倉庫是唯一事實來源。`src/` 下的每個目錄都是可獨立安裝的 Composer 套件， +`components` 倉庫是唯一事實來源。`src/` 下的每個目錄都是可獨立安裝的 Composer 包， 而 `friendsofhyperf/components` 會安裝完整組件集。 ## 組件如何發佈？ -發佈流程會將 monorepo 拆分為唯讀的獨立組件倉庫。Issue 和 Pull Request 都應提交到 monorepo。 +發佈流程會將 monorepo 拆分為只讀的獨立組件倉庫。Issue 和 Pull Request 都應提交到 monorepo。 -## 文件如何維護？ +## 文檔如何維護？ -文件站點使用 VitePress，並為四種語言維護路徑一致的頁面。提交文件變更前，請在倉庫根目錄執行 +文檔站點使用 VitePress，併為四種語言維護路徑一致的頁面。提交文檔變更前，請在倉庫根目錄運行 `npm run docs:check`。 diff --git a/docs/zh-hk/faq/how-to-use.md b/docs/zh-hk/faq/how-to-use.md index 1b510a8a3..7b994f7b6 100644 --- a/docs/zh-hk/faq/how-to-use.md +++ b/docs/zh-hk/faq/how-to-use.md @@ -1,6 +1,6 @@ # 如何使用組件 -## 安裝組件套件 +## 安裝組件包 從[組件目錄](../components/index.md)選擇組件，然後使用 Composer 安裝： @@ -10,19 +10,19 @@ composer require friendsofhyperf/cache ## 檢查可選依賴 -閱讀組件的 `composer.json` 和文件。可選功能可能需要 Composer `suggest` 段中列出的套件。 +閲讀組件的 `composer.json` 和文檔。可選功能可能需要 Composer `suggest` 段中列出的包。 -## 發佈設定 +## 發佈配置 -組件提供可發佈設定時，請使用文件說明的指令： +組件提供可發佈配置時，請使用文檔説明的命令： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/cache ``` -不要直接對所有組件執行此指令，並非每個組件都有可發佈設定。 +不要直接對所有組件運行此命令，並非每個組件都有可發佈配置。 -## 驗證整合 +## 驗證集成 -啟動應用程式並實際使用整合功能，同時加入應用程式層級測試。排查問題時，請在 Issue 中提供 -組件版本和 Hyperf 版本。 +啓動應用並實際使用集成功能，同時添加應用級測試。排查問題時，請在 Issue 中提供組件版本和 +Hyperf 版本。 diff --git a/docs/zh-hk/faq/index.md b/docs/zh-hk/faq/index.md index 00f02360c..32f069501 100644 --- a/docs/zh-hk/faq/index.md +++ b/docs/zh-hk/faq/index.md @@ -3,32 +3,32 @@ ## 應該在哪裏報告問題？ 請在 [components monorepo](https://github.com/friendsofhyperf/components/issues) 提交 Issue， -並提供組件名稱、已安裝版本、最小重現範例和完整異常堆疊。 +並提供組件名稱、已安裝版本、最小復現示例和完整異常堆棧。 -## 應該安裝聚合套件還是單個組件？ +## 應該安裝聚合包還是單個組件？ -明確需要完整組件集時安裝 `friendsofhyperf/components`。大多數應用程式更適合按需安裝獨立的 -`friendsofhyperf/*` 套件，以減少依賴並只啟用需要的服務提供者。 +明確需要完整組件集時安裝 `friendsofhyperf/components`。大多數應用更適合按需安裝獨立的 +`friendsofhyperf/*` 包，以減少依賴並只啓用需要的服務提供者。 ## 組件會自動註冊嗎？ -大多數組件提供 Hyperf `ConfigProvider`，並透過組件發現機制自動註冊。需要設定檔或資料庫 -遷移的組件會在對應頁面說明發佈指令。 +大多數組件提供 Hyperf `ConfigProvider`，並通過組件發現機制自動註冊。需要配置文件或數據庫 +遷移的組件會在對應頁面説明發布命令。 -## 支援哪些版本？ +## 支持哪些版本？ -目前分支要求 PHP 8.2 或更高版本，並面向 Hyperf 3.2。準確的必要依賴和建議依賴請查看所選 +當前分支要求 PHP 8.2 或更高版本，並面向 Hyperf 3.2。準確的必需依賴和建議依賴請查看所選 組件的 `composer.json`。 -## 為甚麼範例還需要其他套件？ +## 為什麼示例還需要其他包？ -部分功能會整合 AMQP、Kafka、非同步佇列、Elasticsearch 或外部服務等可選依賴。Composer 的 -`suggest` 段和組件文件會標明這些依賴。 +部分功能會集成 AMQP、Kafka、異步隊列、Elasticsearch 或外部服務等可選依賴。Composer 的 +`suggest` 段和組件文檔會標明這些依賴。 ## 應該向哪裏提交 Pull Request？ 所有 Pull Request 都應提交到 [components monorepo](https://github.com/friendsofhyperf/components)。獨立組件倉庫由自動拆分 -產生，不接收貢獻。 +生成，不接收貢獻。 -更多資訊請閱讀[關於 FriendsOfHyperf](about.md)和[如何使用組件](how-to-use.md)。 +更多信息請閲讀[關於 FriendsOfHyperf](about.md)和[如何使用組件](how-to-use.md)。 diff --git a/docs/zh-hk/guide/index.md b/docs/zh-hk/guide/index.md index 7a96e4b57..8dff67071 100644 --- a/docs/zh-hk/guide/index.md +++ b/docs/zh-hk/guide/index.md @@ -1,13 +1,13 @@ # 入門 FriendsOfHyperf Components 是一組面向 Hyperf 3.2 的獨立組件，採用 monorepo 統一維護。 -你可以安裝完整組件集，也可以只安裝應用程式需要的單個組件。 +你可以安裝完整組件集，也可以只安裝應用需要的單個組件。 ## 環境要求 - PHP 8.2 或更高版本 - Hyperf 3.2 -- 根據 Hyperf 應用程式選擇 Swoole 或 Swow +- 根據 Hyperf 應用選擇 Swoole 或 Swow ## 安裝完整組件集 @@ -15,7 +15,7 @@ FriendsOfHyperf Components 是一組面向 Hyperf 3.2 的獨立組件，採用 m composer require friendsofhyperf/components ``` -聚合套件會取代所有獨立組件套件，並註冊其中可用的 `ConfigProvider`。 +聚合包會替代所有獨立組件包，並註冊其中可用的 `ConfigProvider`。 ## 安裝單個組件 @@ -23,22 +23,22 @@ composer require friendsofhyperf/components composer require friendsofhyperf/cache ``` -將 `cache` 替換為[組件目錄](../components/index.md)中的套件名稱。大多數組件會透過 Hyperf -組件發現機制自動註冊；如果組件提供設定檔，請按對應組件頁面的說明發佈設定。 +將 `cache` 替換為[組件目錄](../components/index.md)中的包名。大多數組件會通過 Hyperf +組件發現機制自動註冊；如果組件提供配置文件，請按對應組件頁面的説明發布配置。 ## 選擇組件 - 開發與診斷：Telescope、Tinker、Web Tinker、IDE Helper -- 資料庫與模型：Model Factory、Model Observer、Compoships、Fast Paginate +- 數據庫與模型：Model Factory、Model Observer、Compoships、Fast Paginate - 基礎設施：Cache、Lock、Config Consul、Redis Subscriber - 安全與驗證：Encryption、Purifier、reCAPTCHA、Validated DTO -- 通訊與訊息：Mail、Notification、EasySms、AMQP Job、TCP Sender +- 通信與消息：Mail、Notification、EasySms、AMQP Job、TCP Sender 完整分類請查看[組件目錄](../components/index.md)。 ## 後續步驟 -1. 開啟組件頁面，確認依賴和環境要求。 -2. 安裝對應的獨立組件套件。 -3. 在組件要求時發佈設定。 -4. 為應用程式中的整合行為加入針對性測試。 +1. 打開組件頁面，確認依賴和環境要求。 +2. 安裝對應的獨立組件包。 +3. 在組件要求時發佈配置。 +4. 為應用中的集成行為添加有針對性的測試。 diff --git a/docs/zh-hk/guide/introduce/about.md b/docs/zh-hk/guide/introduce/about.md index 735d0972b..0b373ff1a 100644 --- a/docs/zh-hk/guide/introduce/about.md +++ b/docs/zh-hk/guide/introduce/about.md @@ -1,25 +1,25 @@ # 關於 Hyperf Fans -FriendsOfHyperf 是由社群維護的 Hyperf 擴充組件集合，提供面向生產環境的整合能力， -並帶來部分受 Laravel 啟發的開發體驗。 +FriendsOfHyperf 是由社區維護的 Hyperf 擴展組件集合，提供面向生產環境的集成能力， +並帶來部分受 Laravel 啓發的開發體驗。 ## 倉庫模式 -原始碼統一維護在 +源代碼統一維護在 [friendsofhyperf/components](https://github.com/friendsofhyperf/components) monorepo 中。 -`src/` 下的每個目錄也會作為可獨立安裝的 Composer 套件發佈。請向 monorepo 提交變更， -不要向自動拆分產生的獨立倉庫提交。 +`src/` 下的每個目錄也會作為可獨立安裝的 Composer 包發佈。請向 monorepo 提交變更， +不要向自動拆分生成的獨立倉庫提交。 -## 相容性 +## 兼容性 -目前分支面向 PHP 8.2 或更高版本以及 Hyperf 3.2。各組件頁面會說明可選整合和額外依賴。 +當前分支面向 PHP 8.2 或更高版本以及 Hyperf 3.2。各組件頁面會説明可選集成和額外依賴。 -## 文件語言 +## 文檔語言 -文件同時維護英文、簡體中文、香港繁體中文和台灣繁體中文。每次文件變更都必須保持四種語言 +文檔同時維護英文、簡體中文、香港繁體中文和台灣繁體中文。每次文檔變更都必須保持四種語言 的頁面路徑與標題結構一致。 ## 參與貢獻 請在 monorepo 中提交 Issue 和 Pull Request。行為變更應在同一個 Pull Request 中更新組件測試 -以及全部四種語言的文件。 +以及全部四種語言的文檔。 diff --git a/docs/zh-tw/components/amqp-job.md b/docs/zh-tw/components/amqp-job.md index c02d73c61..8fe03f54d 100644 --- a/docs/zh-tw/components/amqp-job.md +++ b/docs/zh-tw/components/amqp-job.md @@ -3,9 +3,9 @@ ## 簡介 `friendsofhyperf/amqp-job` 透過 `hyperf/amqp` 分發 PHP 任務物件。任務使用 `AmqpJob` -註解宣告 AMQP 綁定，服務啟動時，元件會為每個已啟用且帶有該註解的任務自動註冊消費者。 +註解宣告 AMQP 繫結，服務啟動時，元件會為每個已啟用且帶有該註解的任務自動註冊消費者。 -元件預設使用 PHP 序列化，因此只應分發可信的任務物件，並確保消費者可以載入對應的類別。 +元件預設使用 PHP 序列化，因此只應分發可信的任務物件，並確保消費者可以載入對應的類。 ## 安裝 @@ -13,9 +13,9 @@ composer require friendsofhyperf/amqp-job ``` -Hyperf 會自動發現套件中的 `ConfigProvider`。它會註冊消費者監聽器，並將重試次數儲存綁定到 -Redis，將訊息封裝器綁定到 `PhpSerializerPacker`。分發任務前，請先設定 `hyperf/amqp` -及所選的 AMQP 連線池。將 `amqp.enable` 設定為 `false` 會略過所有任務消費者的自動註冊。 +Hyperf 會自動發現包中的 `ConfigProvider`。它會註冊消費者監聽器，並將重試次數儲存繫結到 +Redis，將訊息打包器繫結到 `PhpSerializerPacker`。分發任務前，請先配置 `hyperf/amqp` +及所選的 AMQP 連線池。將 `amqp.enable` 設定為 `false` 會跳過所有任務消費者的自動註冊。 ## 定義並分發任務 @@ -60,42 +60,42 @@ function dispatchFoo(Producer $producer, int $id): bool ``` `dispatch(JobInterface $payload, ?bool $confirm = null, ?int $timeout = null): bool` -是建立並發布 `JobMessage` 的便捷函式。如果任務尚無任務 ID，它會為其分配唯一 ID。可選的 -`confirm` 和 `timeout` 參數會覆寫本次分發使用的任務值。 +是建立併發布 `JobMessage` 的便捷函式。如果任務尚無任務 ID，它會為其分配唯一 ID。可選的 +`confirm` 和 `timeout` 引數會覆蓋本次分發使用的任務值。 -目前 `dispatch()` 不會將任務的交換器、路由鍵或連線池複製到 `JobMessage`。因此產生的生產者 -訊息會使用空交換器、空路由鍵和 Hyperf 的 `default` AMQP 連線池。若要發布到 `AmqpJob` -宣告的綁定，請像上例一樣建立 `JobMessage`、設定目的地，再交給 `Hyperf\Amqp\Producer`。 +當前 `dispatch()` 不會將任務的交換機、路由鍵或連線池複製到 `JobMessage`。因此生成的生產者 +訊息會使用空交換機、空路由鍵和 Hyperf 的 `default` AMQP 連線池。若要釋出到 `AmqpJob` +宣告的繫結，請像上例一樣建立 `JobMessage`、設定目的地，再交給 `Hyperf\Amqp\Producer`。 ## 註解選項 -| 選項 | 類型 | 預設值 | 行為 | +| 選項 | 型別 | 預設值 | 行為 | | --- | --- | --- | --- | -| `exchange` | `string` | 必填 | 自動消費者使用的交換器，也是 `Job::getExchange()` 的回傳值。 | -| `routingKey` | `string` | 必填 | 自動消費者使用的路由鍵，也是 `Job::getRoutingKey()` 的回傳值。 | -| `pool` | `?string` | `null` | 自動消費者連線池，也是 `Job::getPoolName()` 的回傳值。 | +| `exchange` | `string` | 必填 | 自動消費者使用的交換機，也是 `Job::getExchange()` 的返回值。 | +| `routingKey` | `string` | 必填 | 自動消費者使用的路由鍵，也是 `Job::getRoutingKey()` 的返回值。 | +| `pool` | `?string` | `null` | 自動消費者連線池，也是 `Job::getPoolName()` 的返回值。 | | `queue` | `?string` | `null` | 消費者佇列；省略時保持未設定。 | | `maxAttempts` | `int` | `0` | 處理失敗的最大嘗試次數；`0` 表示不重試。 | | `maxConsumption` | `int` | `0` | 消費者退出前最多消費的訊息數。 | -| `confirm` | `bool` | `false` | `Job::getConfirm()` 的回傳值，由 `dispatch()` 使用。 | +| `confirm` | `bool` | `false` | `Job::getConfirm()` 的返回值，由 `dispatch()` 使用。 | | `enable` | `bool` | `true` | 控制是否自動註冊消費者。 | | `nums` | `int` | `1` | 消費者程序數。 | | `name` | `?string` | `null` | 消費者程序名稱。 | -如果任務未使用該註解，其 getter 預設回傳交換器 `hyperf`、路由鍵 `hyperf.job`、無指定 -連線池、關閉發布確認、5 秒發布逾時和不重試。子類別可以提供 `$exchange`、`$routingKey`、 -`$poolName`、`$confirm`、`$timeout` 或 `$maxAttempts` 等受保護屬性來覆寫這些 getter 值。 -如上所述，`dispatch()` 只使用確認和逾時 getter。 +如果任務未使用該註解，其 getter 預設返回交換機 `hyperf`、路由鍵 `hyperf.job`、無指定 +連線池、關閉釋出確認、5 秒釋出超時和不重試。子類可以提供 `$exchange`、`$routingKey`、 +`$poolName`、`$confirm`、`$timeout` 或 `$maxAttempts` 等受保護屬性來覆蓋這些 getter 值。 +如上所述，`dispatch()` 只使用確認和超時 getter。 ## 消費與重試 -當 `handle()` 沒有回傳值或回傳無法識別的字串時，`JobConsumer` 會確認任務。回傳 +當 `handle()` 沒有返回值或返回無法識別的字串時，`JobConsumer` 會確認任務。返回 `Hyperf\Amqp\Result` 或其字串值可以直接控制消費結果。 -當 `handle()` 擲回例外時，如果存在相容的日誌記錄器，消費者會記錄例外。設定 -`maxAttempts > 0` 後，基於 Redis 的次數計數器會重新入列任務，直到達到設定的總嘗試次數。 +當 `handle()` 丟擲異常時，如果存在相容的日誌記錄器，消費者會記錄異常。設定 +`maxAttempts > 0` 後，基於 Redis 的次數計數器會重新入隊任務，直到達到配置的總嘗試次數。 隨後消費者會呼叫 `fail(Throwable $e)` 並丟棄訊息。預設 `fail()` 方法不執行任何操作， -可以覆寫它： +可以覆蓋它： ```php use Throwable; @@ -106,13 +106,13 @@ public function fail(Throwable $e): void } ``` -預設 Redis 次數鍵使用 `hyperf:amqp-job:attempts:` 前綴，並在 86,400 秒後過期，因此啟用 -重試時必須可用 Redis。綁定 `FriendsOfHyperf\AmqpJob\Contract\Attempt` 或 -`FriendsOfHyperf\AmqpJob\Contract\Packer` 可以取代預設實作。記錄例外時，消費者會依序 +預設 Redis 次數鍵使用 `hyperf:amqp-job:attempts:` 字首，並在 86,400 秒後過期，因此啟用 +重試時必須可用 Redis。繫結 `FriendsOfHyperf\AmqpJob\Contract\Attempt` 或 +`FriendsOfHyperf\AmqpJob\Contract\Packer` 可以替換預設實現。記錄異常時，消費者會依次 解析 `FriendsOfHyperf\AmqpJob\Contract\LoggerInterface` 和 -`Hyperf\Contract\StdoutLoggerInterface`；兩者都不可用時會略過日誌記錄。 +`Hyperf\Contract\StdoutLoggerInterface`；兩者都不可用時會跳過日誌記錄。 -## 註冊自訂消費者 +## 註冊自定義消費者 通常使用自動註冊的消費者即可。若要透過手動宣告的消費者消費相容的序列化任務，請繼承 `JobConsumer` 並使用 Hyperf 的 `Consumer` 註解： diff --git a/docs/zh-tw/components/cache.md b/docs/zh-tw/components/cache.md index 31c40a0d4..718db3264 100644 --- a/docs/zh-tw/components/cache.md +++ b/docs/zh-tw/components/cache.md @@ -2,8 +2,8 @@ ## 簡介 -`friendsofhyperf/cache` 使用 Laravel 風格的儲存庫 API 封裝 `hyperf/cache` -提供的驅動程式。它支援 PSR-16 操作、具名儲存、Facade 存取、快取事件、巨集以及 +`friendsofhyperf/cache` 使用 Laravel 風格的倉庫 API 封裝 `hyperf/cache` +提供的驅動。它支援 PSR-16 操作、命名儲存、門面訪問、快取事件、宏以及 stale-while-revalidate 快取。 ## 安裝 @@ -16,15 +16,15 @@ composer require friendsofhyperf/cache `FriendsOfHyperf\Cache\Contract\Factory` 和 `FriendsOfHyperf\Cache\Contract\Repository`。 -## 設定 +## 配置 -該元件不會發布獨立的設定檔。請透過 `hyperf/cache` 設定驅動程式和具名儲存； -`CacheManager::store($name)` 會將名稱傳給 Hyperf 的快取管理器。預設儲存庫解析 +該元件不會發布獨立的配置檔案。請透過 `hyperf/cache` 配置驅動和命名儲存； +`CacheManager::store($name)` 會將名稱傳給 Hyperf 的快取管理器。預設倉庫解析 `default` 儲存。 -## 取得儲存庫 +## 獲取倉庫 -### 相依性注入 +### 依賴注入 注入 `Contract\Repository` 以使用預設儲存： @@ -48,7 +48,7 @@ class IndexController } ``` -需要具名儲存時注入 `Contract\Factory`： +需要命名儲存時注入 `Contract\Factory`： ```php use FriendsOfHyperf\Cache\Contract\Factory; @@ -56,7 +56,7 @@ use FriendsOfHyperf\Cache\Contract\Factory; $cache = $factory->store('redis'); ``` -### Facade +### 門面 ```php use FriendsOfHyperf\Cache\Facade\Cache; @@ -69,36 +69,36 @@ $users = Cache::store('redis')->get('users'); ``` `Cache::driver($name)` 是 `Cache::store($name)` 的別名。 -`Cache::resolve($name)` 會建立新儲存庫，而不是傳回管理器中快取的儲存庫執行個體。 +`Cache::resolve($name)` 會建立新倉庫，而不是返回管理器中快取的倉庫例項。 ## 核心操作 -儲存庫實作了 `Psr\SimpleCache\CacheInterface`，因此可使用 `get()`、`set()`、 +倉庫實現了 `Psr\SimpleCache\CacheInterface`，因此可使用 `get()`、`set()`、 `delete()`、`clear()`、`getMultiple()`、`setMultiple()`、`deleteMultiple()` 和 -`has()`。此外還提供以下擴充： +`has()`。此外還提供以下擴充套件： | 方法 | 行為 | | --- | --- | -| `get($key, $default = null)` | 取得單一項目；未命中時會執行可呼叫的預設值。傳入陣列會轉交給 `many()`。 | -| `put($key, $value, $ttl = null)` | 儲存單一項目；`null` 表示永久儲存，非正數 TTL 會刪除該鍵。傳入關聯陣列會轉交給 `putMany()`，並將第二個參數用作其 TTL。 | -| `putMany($values, $ttl = null)` | 儲存多個項目；非正數 TTL 會刪除對應鍵。 | -| `forever($key, $value)` | 不設定 TTL 地儲存單一項目。 | -| `add($key, $value, $ttl = null)` | 僅當 `get($key)` 傳回 `null` 時儲存項目。 | -| `many($keys)` | 取得多個鍵；關聯陣列輸入可為每個鍵提供預設值。 | -| `pull($key, $default = null)` | 取得項目後將其刪除。 | -| `remember($key, $ttl, Closure $callback)` | 傳回快取值，或按 TTL 儲存回呼結果。 | -| `rememberForever($key, Closure $callback)` / `sear(...)` | 傳回快取值，或永久儲存回呼結果。 | +| `get($key, $default = null)` | 獲取單個專案；未命中時會執行可呼叫的預設值。傳入陣列會轉交給 `many()`。 | +| `put($key, $value, $ttl = null)` | 儲存單個專案；`null` 表示永久儲存，非正數 TTL 會刪除該鍵。傳入關聯陣列會轉交給 `putMany()`，並將第二個引數用作其 TTL。 | +| `putMany($values, $ttl = null)` | 儲存多個專案；非正數 TTL 會刪除對應鍵。 | +| `forever($key, $value)` | 不設定 TTL 地儲存單個專案。 | +| `add($key, $value, $ttl = null)` | 僅當 `get($key)` 返回 `null` 時儲存專案。 | +| `many($keys)` | 獲取多個鍵；關聯陣列輸入可為每個鍵提供預設值。 | +| `pull($key, $default = null)` | 獲取專案後將其刪除。 | +| `remember($key, $ttl, Closure $callback)` | 返回快取值，或按 TTL 儲存回撥結果。 | +| `rememberForever($key, Closure $callback)` / `sear(...)` | 返回快取值，或永久儲存回撥結果。 | | `increment($key, $value = 1)` / `decrement(...)` | 讀取、調整並以無 TTL 方式儲存整數值。 | | `flush()` | `clear()` 的別名。 | | `missing($key)` | `has($key)` 的反向判斷。 | -| `getDriver()` / `getStore()` | 傳回底層 Hyperf `DriverInterface`。 | +| `getDriver()` / `getStore()` | 返回底層 Hyperf `DriverInterface`。 | -擴充儲存庫方法接受的 TTL 可以是秒數、`DateInterval` 或 `DateTimeInterface`。 +擴充套件倉庫方法接受的 TTL 可以是秒數、`DateInterval` 或 `DateTimeInterface`。 ::: warning 行為邊界 -儲存庫會將已快取的 `null` 視為未命中。`add()`、`pull()` 和遞增/遞減方法由分離的 -操作實作，因此不具原子性。雖然 `pull()` 接受 `$default` 參數，但目前實作不會 -將它傳給 `get()`，鍵不存在時傳回 `null`。 +倉庫會將已快取的 `null` 視為未命中。`add()`、`pull()` 和遞增/遞減方法由分離的 +操作實現，因此不是原子操作。雖然 `pull()` 接受 `$default` 引數，但當前實現不會 +將它傳給 `get()`，鍵不存在時返回 `null`。 ::: ## Stale-While-Revalidate @@ -117,22 +117,21 @@ $users = Cache::flexible('users', [30, 300], function () { ]); ``` -快取未命中時，回呼立即執行。在新鮮期內直接傳回快取值；新鮮期結束後傳回舊值， -並透過延遲回呼嘗試在鎖內重新整理快取。如果其他處理程序已更新建立時間戳，則 -跳過重新整理。 +快取未命中時，回撥立即執行。在新鮮期內直接返回快取值；新鮮期結束後返回舊值， +並透過延遲迴調嘗試在鎖內重新整理快取。如果其他程序已更新建立時間戳，則跳過重新整理。 -使用 `flexible()` 前需要安裝兩個選用相依套件： +使用 `flexible()` 前需要安裝兩個可選依賴： ```shell composer require friendsofhyperf/lock hyperf/coroutine ``` -選用的鎖陣列接受 `seconds` 和 `owner`，預設值分別為 `0` 和 `null`。 +可選的鎖陣列接受 `seconds` 和 `owner`，預設值分別為 `0` 和 `null`。 ## 事件 -當容器提供 `Psr\EventDispatcher\EventDispatcherInterface` 時，儲存庫會為讀取、 -寫入、刪除和清空操作分派事件： +當容器提供 `Psr\EventDispatcher\EventDispatcherInterface` 時，倉庫會為讀取、 +寫入、刪除和清空操作分發事件： - `CacheHit`、`CacheMissed`、`RetrievingKey`、`RetrievingManyKeys` - `WritingKey`、`WritingManyKeys`、`KeyWritten`、`KeyWriteFailed` @@ -140,9 +139,9 @@ composer require friendsofhyperf/lock hyperf/coroutine - `CacheFlushing`、`CacheFlushed` 每個事件都包含儲存名稱。單鍵事件還包含鍵；適用時，寫入事件會公開值和 TTL， -批次事件會公開鍵，`WritingManyKeys` 還會公開值。批次讀取還會為每個傳回的鍵分派 +批次事件會公開鍵，`WritingManyKeys` 還會公開值。批次讀取還會為每個返回的鍵分發 `CacheHit` 或 `CacheMissed`。 ## 參考 -該 API 的設計受 Laravel Cache 啟發，但具體行為應以本元件的契約和實作為準。 +該 API 的設計受 Laravel Cache 啟發，但具體行為應以本元件的契約和實現為準。 diff --git a/docs/zh-tw/components/co-phpunit.md b/docs/zh-tw/components/co-phpunit.md index 2cec665bc..e2227e9b2 100644 --- a/docs/zh-tw/components/co-phpunit.md +++ b/docs/zh-tw/components/co-phpunit.md @@ -12,13 +12,13 @@ composer require friendsofhyperf/co-phpunit --dev ``` 元件依賴 `hyperf/coordinator` `~3.2.0`，並支援 PHPUnit 10、11 和 12。它沒有將 Swoole -擴充套件宣告為 Composer 依賴；未載入該擴充套件時，測試會退回到 PHPUnit 的一般執行方式。 +擴充套件宣告為 Composer 依賴；未載入該擴充套件時，測試會回退到 PHPUnit 的普通執行方式。 ## 使用 ### 在協程中執行測試 -在測試類別或共用的測試基底類別中使用 `RunTestsInCoroutine`： +在測試類或共享的測試基類中使用 `RunTestsInCoroutine`： ```php = 4.6.0` 或 `ext-swow >= 0.1.0`，但沒有將 -POSIX 擴充套件宣告為相依套件。 +實現透過 Hyperf Engine 處理訊號，並呼叫 `posix_getpid()` 和 `posix_kill()`。請在支援 +POSIX 訊號且可執行協程的 Swoole 或 Swow 環境中使用。PHP POSIX 擴充套件必須提供上述兩個 +函式。Composer 建議安裝 `ext-swoole >= 4.6.0` 或 `ext-swow >= 0.1.0`，但沒有將 +POSIX 擴充套件宣告為依賴。 ## 使用 -在指令中引入 `InteractsWithSignals`，然後呼叫 `trap()` 並傳入一個訊號編號或訊號編號陣列。 -回呼會接收到訊號編號。 +在命令中引入 `InteractsWithSignals`，然後呼叫 `trap()` 並傳入一個訊號編號或訊號編號陣列。 +回撥會接收到訊號編號。 ```php namespace App\Command; @@ -58,14 +58,14 @@ class FooCommand extends HyperfCommand } ``` -首次呼叫 `trap()` 時，它會透過容器建立 `SignalRegistry`，並在目前協程結束時自動清空回呼。 -同一個訊號可以註冊多個回呼；收到該訊號時，這些回呼會平行執行。 +首次呼叫 `trap()` 時，它會透過容器建立 `SignalRegistry`，並在當前協程結束時自動清空回撥。 +同一個訊號可以註冊多個回撥；收到該訊號時，這些回撥會併發執行。 -每個已註冊訊號只會被處理一次。回呼執行完成後，註冊器會停止等待，並再次向目前行程傳送同一 +每個已註冊訊號只會被處理一次。回撥執行完成後，註冊器會停止等待，並再次向當前程序傳送同一 訊號，因此作業系統通常會執行該訊號的預設動作。 -使用 `untrap()` 清空一個訊號、多個訊號或全部訊號的回呼。它不會取消已經啟動的等待協程； -如果之後收到該訊號，註冊器仍會在不執行回呼後再次向行程傳送該訊號。 +使用 `untrap()` 清空一個訊號、多個訊號或全部訊號的回撥。它不會取消已經啟動的等待協程； +如果之後收到該訊號，註冊器仍會在不執行回撥後再次向程序傳送該訊號。 ```php $this->untrap(SIGINT); @@ -75,20 +75,20 @@ $this->untrap(); ## API -Trait 向指令提供以下受保護方法： +Trait 向命令提供以下受保護方法： - `trap(array|int $signo, callable $callback): void` - `untrap(null|array|int $signo = null): void` -`SignalRegistry` 也是公開類別。其建構函式為 +`SignalRegistry` 也是公開類。其建構函式為 `__construct(int $timeout = 1, int $concurrentLimit = 0)`；`timeout` 是每次等待嘗試的 -逾時秒數，`concurrentLimit` 用於限制平行執行的回呼數量，值為 `0` 表示不限制平行數。它 +超時秒數，`concurrentLimit` 用於限制併發執行的回撥數量，值為 `0` 表示不限制併發數。它 提供以下方法： - `register(int|array $signo, callable $signalHandler): void` - `unregister(null|int|array $signo = null): void` -`unregister()` 會清空所選訊號的回呼；傳入 `null` 會清空全部回呼。 +`unregister()` 會清空所選訊號的回撥；傳入 `null` 會清空全部回撥。 ## 執行 diff --git a/docs/zh-tw/components/command-validation.md b/docs/zh-tw/components/command-validation.md index 759209e78..e58ef3a46 100644 --- a/docs/zh-tw/components/command-validation.md +++ b/docs/zh-tw/components/command-validation.md @@ -1,6 +1,6 @@ # Command Validation -在 Hyperf 命令執行前驗證其參數和選項。 +在 Hyperf 命令執行前驗證其引數和選項。 ## 安裝 @@ -8,13 +8,13 @@ composer require friendsofhyperf/command-validation ``` -該元件要求 Hyperf `~3.2.0`（包括 `hyperf/validation`），且未宣告選用依賴。 -Hyperf 會自動探索該元件的空 `ConfigProvider`，因此該元件沒有需要發布的設定。 +該元件要求 Hyperf `~3.2.0`（包括 `hyperf/validation`），且未宣告可選依賴。 +Hyperf 會自動發現該元件的空 `ConfigProvider`，因此該元件沒有需要釋出的配置。 ## 使用 -在命令中引入 `ValidatesInput` trait 並覆寫 `rules()`。也可以覆寫 -`messages()` 和 `attributes()` 來自訂驗證錯誤。 +在命令中引入 `ValidatesInput` trait 並重寫 `rules()`。也可以重寫 +`messages()` 和 `attributes()` 來自定義驗證錯誤。 ```php team_id` 是 `null`。 +Eloquent 風格的關係通常只會把一個外來鍵列匹配到一個本地鍵或擁有者鍵列。在關係中 +額外新增 `where` 子句並不能替代複合鍵關係，因為預載入會在單個模型例項可用之前 +構造關係查詢。下面的示例中，準備預載入約束時 `$this->team_id` 是 `null`。 ```php namespace App; @@ -33,16 +33,16 @@ class User extends Model composer require friendsofhyperf/compoships ``` -此元件面向 Hyperf 3.2，並依賴元件宣告的 `hyperf/database` 及相關 Hyperf 支援套件。 -`composer.json` 中的建議套件是可選第三方套件，並不是 Compoships 關聯所必需的依賴。 +該元件面向 Hyperf 3.2，並依賴元件宣告的 `hyperf/database` 及相關 Hyperf 支撐包。 +`composer.json` 中的建議包是可選第三方包，並不是 Compoships 關係所必需的依賴。 ## 配置 -無需發布設定檔。元件提供了 Hyperf `ConfigProvider`，但目前回傳的是空設定陣列。 +無需釋出配置檔案。元件提供了 Hyperf `ConfigProvider`，但當前返回的是空配置陣列。 ## 使用 -### 使用 `FriendsOfHyperf\Compoships\Database\Eloquent\Model` 類別 +### 使用 `FriendsOfHyperf\Compoships\Database\Eloquent\Model` 類 讓模型繼承 `FriendsOfHyperf\Compoships\Database\Eloquent\Model`，而不是直接繼承 `Hyperf\Database\Model\Model`。這個基礎模型使用了 Compoships trait，同時保留正常 @@ -60,7 +60,7 @@ class User extends Model ### 使用 `FriendsOfHyperf\Compoships\Compoships` Trait -如果模型必須繼承其他基礎類別，可以在模型中使用 +如果模型必須繼承其他基礎類，可以在模型中使用 `FriendsOfHyperf\Compoships\Compoships` trait。 ```php @@ -75,24 +75,24 @@ class User extends Model } ``` -當關聯使用鍵名陣列時，被關聯模型也必須接入 Compoships：要麼繼承 +當關系使用鍵名陣列時，被關聯模型也必須接入 Compoships：要麼繼承 `FriendsOfHyperf\Compoships\Database\Eloquent\Model`，要麼使用 -`FriendsOfHyperf\Compoships\Compoships` trait。否則定義關聯時會拋出 +`FriendsOfHyperf\Compoships\Compoships` trait。否則定義關係時會丟擲 `FriendsOfHyperf\Compoships\Exceptions\InvalidUsageException`。 -## 關聯語法 +## 關係語法 -Compoships 支援在以下關聯方法中使用複合鍵： +Compoships 支援在以下關係方法中使用複合鍵： - `hasOne($related, $foreignKey = null, $localKey = null)` - `hasMany($related, $foreignKey = null, $localKey = null)` - `belongsTo($related, $foreignKey = null, $ownerKey = null, $relation = null)` -將鍵參數由字串改為陣列即可。陣列順序和元素數量應保持一致，因為值會按陣列索引 +將鍵引數從字串改為陣列即可。陣列順序和元素數量應保持一致，因為值會按陣列下標 逐項匹配。 -對 `hasOne` 和 `hasMany` 來說，外鍵陣列表示被關聯模型上的欄位，本地鍵陣列表示目前 -模型上的欄位： +對 `hasOne` 和 `hasMany` 來說，外來鍵陣列表示被關聯模型上的列，本地鍵陣列表示當前 +模型上的列： ```php namespace App; @@ -116,8 +116,8 @@ class Team extends Model } ``` -對 `belongsTo` 來說，外鍵陣列表示目前模型上的欄位，擁有者鍵陣列表示被關聯模型上的 -欄位： +對 `belongsTo` 來說，外來鍵陣列表示當前模型上的列，擁有者鍵陣列表示被關聯模型上的 +列： ```php namespace App; @@ -136,9 +136,9 @@ class Task extends Model } ``` -## 範例 +## 示例 -假設一個任務清單由多個團隊管理，並且每個團隊中每個任務分類都有一名負責使用者： +假設一個任務列表由多個團隊管理，並且每個團隊中每個任務分類都有一名負責使用者： - 一個任務屬於一個分類。 - 一個任務被分配給一個團隊。 @@ -165,7 +165,7 @@ class User extends Model } ``` -反向關聯使用同一組欄位： +反向關係使用同一組列： ```php namespace App; @@ -190,9 +190,9 @@ class Task extends Model ## 行為說明 -Compoships 使用自訂查詢建構器，因此預載入可以套用多欄位 `whereIn` 約束，關聯存在性 -查詢也可以透過 `whereColumn` 比較多欄位。 +Compoships 使用自定義查詢構造器，因此預載入可以應用多列 `whereIn` 約束，關係存在性 +查詢也可以透過 `whereColumn` 比較多列。 對 `hasOne` 和 `hasMany` 來說，`save()` 和 `create()` 會把父模型本地鍵的值按順序 -寫入被關聯模型的各個外鍵欄位。對 `belongsTo` 來說，`associate()` 會把擁有者鍵的值 -按順序寫入目前模型的各個外鍵欄位。 +寫入被關聯模型的各個外來鍵列。對 `belongsTo` 來說，`associate()` 會把擁有者鍵的值 +按順序寫入當前模型的各個外來鍵列。 diff --git a/docs/zh-tw/components/confd.md b/docs/zh-tw/components/confd.md index 2d43ef9b0..bcbc40c3c 100644 --- a/docs/zh-tw/components/confd.md +++ b/docs/zh-tw/components/confd.md @@ -1,11 +1,11 @@ # Confd -Confd 元件從 Etcd 或 Nacos 取得設定，將遠端值映射為環境變數名稱，並可將其寫入 +Confd 元件從 Etcd 或 Nacos 獲取配置，將遠端值對映為環境變數名，並可將其寫入 已有的 `.env` 檔案或監聽變更。 ## 安裝 -安裝元件以及所用驅動需要的套件： +安裝元件以及所用驅動需要的包： ```shell composer require friendsofhyperf/confd @@ -14,33 +14,33 @@ composer require hyperf/etcd composer require hyperf/nacos ``` -Etcd 和 Nacos 是選用驅動相依套件。Nacos v2 gRPC API 還需要 `google/protobuf`、 -`hyperf/grpc` 和 `hyperf/http2-client`。解碼 YAML 值需要 PHP YAML 擴充功能。 +Etcd 和 Nacos 是可選驅動依賴。Nacos v2 gRPC API 還需要 `google/protobuf`、`hyperf/grpc` +和 `hyperf/http2-client`。解碼 YAML 值需要 PHP YAML 擴充套件。 -發布設定檔案： +釋出配置檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/confd ``` -## 設定 +## 配置 -發布的檔案為 `config/autoload/confd.php`，主要選項如下： +釋出的檔案為 `config/autoload/confd.php`，主要選項如下： | 選項 | 說明 | | --- | --- | | `default` | 驅動名稱。預設為 `etcd`，可透過 `CONFD_DRIVER` 設定。 | -| `drivers..driver` | 實作 `DriverInterface` 的驅動類別。 | -| `drivers..mapping` | 將遠端設定路徑映射到環境變數名稱。 | +| `drivers..driver` | 實現 `DriverInterface` 的驅動類。 | +| `drivers..mapping` | 將遠端配置路徑對映到環境變數名。 | | `env_path` | `confd:env` 更新的已有 `.env` 檔案。 | | `watch` | 在伺服器啟動時開始監聽。預設為 `true`，可透過 `CONFD_WATCH` 設定。 | -| `watches` | 會觸發 `WatchDispatched` 的環境變數名稱。 | +| `watches` | 會觸發 `WatchDispatched` 的環境變數名。 | | `interval` | 輪詢間隔秒數。預設為 `1`，可透過 `CONFD_INTERVAL` 設定。 | ### Etcd -Etcd 驅動取得 `namespace` 下的鍵，並只回傳 `mapping` 中列出的鍵。每個映射鍵是 Etcd -鍵，每個映射值是 `fetch()` 回傳的環境變數名稱。 +Etcd 驅動獲取 `namespace` 下的鍵，並只返回 `mapping` 中列出的鍵。每個對映鍵是 Etcd +鍵，每個對映值是 `fetch()` 返回的環境變數名。 ```php 'etcd' => [ @@ -60,8 +60,8 @@ Etcd 驅動取得 `namespace` 下的鍵，並只回傳 `mapping` 中列出的鍵 ### Nacos -Nacos 驅動讀取 `listener_config` 中的每個項目，根據 `type` 解碼，再從 `mapping` -解析點號路徑。支援的類型為 `json`、`yml`/`yaml` 和 `xml`；其他類型或未指定類型時 +Nacos 驅動讀取 `listener_config` 中的每個條目，根據 `type` 解碼，再從 `mapping` +解析點號路徑。支援的型別為 `json`、`yml`/`yaml` 和 `xml`；其他型別或未指定型別時 保留為字串。 ```php @@ -96,33 +96,33 @@ Nacos 驅動讀取 `listener_config` 中的每個項目，根據 `type` 解碼 ``` 當 `client.grpc.enable` 為 `false` 時，Nacos 按 `interval` 輪詢；為 `true` 時，驅動為 -`listener_config` 中的項目註冊 gRPC 監聽。 +`listener_config` 中的條目註冊 gRPC 監聽。 ## 更新環境檔案 -從選定驅動取得映射值，並更新設定的已有 `.env` 檔案： +從選定驅動獲取對映值，並更新配置的已有 `.env` 檔案： ```shell php bin/hyperf.php confd:env ``` -使用 `--env-path`（或 `-E`）覆寫 `confd.env_path`： +使用 `--env-path`（或 `-E`）覆蓋 `confd.env_path`： ```shell php bin/hyperf.php confd:env --env-path=/path/to/.env ``` -檔案不存在或取得/寫入失敗時，命令回傳結束碼 `1`。 +檔案不存在或獲取/寫入失敗時，命令返回退出碼 `1`。 ## 公開 API `FriendsOfHyperf\Confd\Confd` 提供： -- `fetch(): array`：從選定驅動取得映射後的環境變數值。 -- `watch(): void`：執行首次取得並啟動選定驅動的監聽迴圈。 +- `fetch(): array`：從選定驅動獲取對映後的環境變數值。 +- `watch(): void`：執行首次獲取並啟動選定驅動的監聽迴圈。 -自訂驅動必須實作 `FriendsOfHyperf\Confd\Driver\DriverInterface`，其中宣告了 -`fetch(): array` 和 `loop(callable $callback): void`。內建 `Noop` 驅動不回傳值， +自定義驅動必須實現 `FriendsOfHyperf\Confd\Driver\DriverInterface`，其中聲明瞭 +`fetch(): array` 和 `loop(callable $callback): void`。內建 `Noop` 驅動不返回值， 也不啟動迴圈。 ## 監聽與事件 @@ -130,7 +130,7 @@ php bin/hyperf.php confd:env --env-path=/path/to/.env 啟用 `confd.watch` 時，`WatchOnBootListener` 會在 `MainWorkerStart` 或 `MainCoroutineServerStart` 時呼叫 `Confd::watch()`。 -監聽迴圈中，已有值發生變更時會派發 `ConfigChanged`。如果變更的環境變數名稱也列在 +監聽迴圈中，已有值發生變更時會派發 `ConfigChanged`。如果變更的環境變數名也列在 `confd.watches` 中，還會派發 `WatchDispatched`。兩個事件都提供公開陣列屬性： - `ConfigChanged`：`$current`、`$previous` 和 `$changes`。 diff --git a/docs/zh-tw/components/config-consul.md b/docs/zh-tw/components/config-consul.md index 1aa746efd..7c44da527 100644 --- a/docs/zh-tw/components/config-consul.md +++ b/docs/zh-tw/components/config-consul.md @@ -8,7 +8,7 @@ composer require friendsofhyperf/config-consul ``` -該套件會自動安裝所需的 Hyperf 設定中心、Consul、編解碼和字串處理依賴。 +該包會自動安裝所需的 Hyperf 配置中心、Consul、編解碼和字串處理依賴。 ## 配置 @@ -39,26 +39,26 @@ return [ ]; ``` -| 設定項 | 說明 | +| 配置項 | 說明 | | --- | --- | -| `enable` | 啟用 Hyperf 設定中心。 | -| `driver` | 選擇 `consul` 驅動設定。 | -| `drivers.consul.driver` | 驅動類別，應使用 `ConsulDriver::class`。 | -| `drivers.consul.packer` | 解包每個映射值，預設為 `JsonPacker::class`。 | -| `drivers.consul.client` | 選用的 Consul 用戶端設定，支援 `uri` 和 `token`。 | -| `drivers.consul.namespaces` | 要遞迴拉取的 Consul KV 前綴陣列。 | -| `drivers.consul.mapping` | 將正規化後的 Consul 鍵映射到 Hyperf 設定鍵；只有已映射的鍵會被套用。 | +| `enable` | 啟用 Hyperf 配置中心。 | +| `driver` | 選擇 `consul` 驅動配置。 | +| `drivers.consul.driver` | 驅動類，應使用 `ConsulDriver::class`。 | +| `drivers.consul.packer` | 解包每個對映值，預設為 `JsonPacker::class`。 | +| `drivers.consul.client` | 可選的 Consul 客戶端配置，支援 `uri` 和 `token`。 | +| `drivers.consul.namespaces` | 要遞迴拉取的 Consul KV 字首陣列。 | +| `drivers.consul.mapping` | 將規範化後的 Consul 鍵對映到 Hyperf 配置鍵；只有已對映的鍵會被應用。 | | `drivers.consul.interval` | 拉取間隔，單位為秒，預設為 `5`。 | -省略 `client` 或將其設為空時，元件會重用 Hyperf 容器中綁定的 -`Hyperf\Consul\KVInterface` 用戶端。設定 `client` 時，`uri` 預設為 -`http://127.0.0.1:8500`；非空 `token` 會透過 `X-Consul-Token` 請求標頭傳送；HTTP 逾時時間為 +省略 `client` 或將其設為空時，元件會複用 Hyperf 容器中繫結的 +`Hyperf\Consul\KVInterface` 客戶端。配置 `client` 時，`uri` 預設為 +`http://127.0.0.1:8500`；非空 `token` 會透過 `X-Consul-Token` 請求頭髮送；HTTP 超時時間為 2 秒。 ## 行為 -- 每個命名空間都會使用 Consul 的遞迴選項請求。如果多個命名空間傳回相同的鍵，映射前以後一個命名空間的值為準。 -- Consul KV 值會先進行 Base64 解碼，再交給設定的 packer。使用 `JsonPacker` 時，Base64 解碼後的儲存值必須是有效 JSON。 -- Consul 鍵在 `mapping` 查找前會被正規化為以 `/` 開頭。 -- 該套件會在容器中註冊 `FriendsOfHyperf\ConfigConsul\ClientInterface` 和 - `FriendsOfHyperf\ConfigConsul\Consul\KVInterface`；`ConsulDriver` 是設定中心驅動入口。 +- 每個名稱空間都會使用 Consul 的遞迴選項請求。如果多個名稱空間返回相同的鍵，對映前以後一個名稱空間的值為準。 +- Consul KV 值會先進行 Base64 解碼，再交給配置的 packer。使用 `JsonPacker` 時，Base64 解碼後的儲存值必須是有效 JSON。 +- Consul 鍵在 `mapping` 查詢前會被規範化為以 `/` 開頭。 +- 該包會在容器中註冊 `FriendsOfHyperf\ConfigConsul\ClientInterface` 和 + `FriendsOfHyperf\ConfigConsul\Consul\KVInterface`；`ConsulDriver` 是配置中心驅動入口。 diff --git a/docs/zh-tw/components/console-spinner.md b/docs/zh-tw/components/console-spinner.md index 7838ba108..a6c512cdf 100644 --- a/docs/zh-tw/components/console-spinner.md +++ b/docs/zh-tw/components/console-spinner.md @@ -1,6 +1,6 @@ # Console Spinner -用於 Hyperf 命令的主控台 Spinner 元件。它封裝了 Symfony `ProgressBar`，並在每次推進時切換 +用於 Hyperf 命令的控制檯 Spinner 元件。它封裝了 Symfony `ProgressBar`，並在每次推進時切換 進度字元。 ## 安裝 @@ -9,15 +9,15 @@ composer require friendsofhyperf/console-spinner ``` -## 選用設定 +## 可選配置 -僅在需要自訂 Spinner 字元時發佈設定檔： +僅在需要自定義 Spinner 字元時釋出配置檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/console-spinner ``` -發佈後的 `config/autoload/console_spinner.php` 檔案包含： +釋出後的 `config/autoload/console_spinner.php` 檔案包含： ```php return [ @@ -57,16 +57,15 @@ class FooCommand extends Command } ``` -`Spinner::advance(int $step = 1)` 會切換 Spinner 字元並推進封裝的進度列。呼叫其他方法時，會將 -呼叫轉送給 Symfony `ProgressBar`；需要直接存取底層執行個體時，可使用 -`getOriginalProgressBar()`。 +`Spinner::advance(int $step = 1)` 會切換 Spinner 字元並推進封裝的進度條。呼叫其他方法時，會將 +呼叫轉發給 Symfony `ProgressBar`；需要直接訪問底層例項時，可使用 `getOriginalProgressBar()`。 ## 使用 `withSpinner` 處理步驟 受保護輔助方法 `withSpinner($totalSteps, Closure $callback, string $message = '')` 會自動啟動 和結束 Spinner。 -當 `$totalSteps` 是陣列等可計數的可迭代物件時，回呼會接收目前元素和 Spinner，並在處理每個 +當 `$totalSteps` 是陣列等可計數的可迭代物件時，回撥會接收當前元素和 Spinner，並在處理每個 元素後自動推進 Spinner： ```php @@ -75,7 +74,7 @@ $this->withSpinner(User::all(), function ($user, $spinner): void { }, 'Loading...'); ``` -當 `$totalSteps` 是整數時，回呼只接收 Spinner，並負責推進它： +當 `$totalSteps` 是整數時，回撥只接收 Spinner，並負責推進它： ```php $this->withSpinner(10, function ($spinner): void { diff --git a/docs/zh-tw/components/elasticsearch.md b/docs/zh-tw/components/elasticsearch.md index 680bd4dc5..1684c6645 100644 --- a/docs/zh-tw/components/elasticsearch.md +++ b/docs/zh-tw/components/elasticsearch.md @@ -1,12 +1,12 @@ # Elasticsearch -此元件將 Elasticsearch 官方 PHP 用戶端與 Hyperf 的 Guzzle 用戶端整合，並為已設定的連線提供靜態 +此元件將 Elasticsearch 官方 PHP 客戶端與 Hyperf 的 Guzzle 客戶端整合，併為已配置的連線提供靜態 Facade。 ## 要求 -此套件適用於 Hyperf 3.2，並依賴 8 或 9 版本的 `elasticsearch/elasticsearch`、`hyperf/config`、 -`hyperf/context` 和 `hyperf/guzzle`。它沒有宣告選用依賴。 +此包適用於 Hyperf 3.2，並依賴 8 或 9 版本的 `elasticsearch/elasticsearch`、`hyperf/config`、 +`hyperf/context` 和 `hyperf/guzzle`。它沒有宣告可選依賴。 ## 安裝 @@ -15,12 +15,12 @@ composer require friendsofhyperf/elasticsearch php bin/hyperf.php vendor:publish friendsofhyperf/elasticsearch ``` -發佈命令會建立 `config/autoload/elasticsearch.php`。 +釋出命令會建立 `config/autoload/elasticsearch.php`。 -## 設定 +## 配置 -發佈的設定定義了 `default` 連線。`ELASTICSEARCH_HOST` 會按逗號拆分，因此可以包含多個主機。可以在 -`elasticsearch` 下加入其他命名連線： +釋出的配置定義了 `default` 連線。`ELASTICSEARCH_HOST` 會按逗號拆分，因此可以包含多個主機。可以在 +`elasticsearch` 下新增其他命名連線： ```php return [ @@ -33,15 +33,15 @@ return [ ]; ``` -對於 Facade 連線，`hosts` 可以是陣列或逗號分隔的字串。Facade 只讀取 `hosts` 鍵；其他用戶端行為 -需要透過 `ClientBuilderFactory` 和上游 Builder 設定。 +對於 Facade 連線，`hosts` 可以是陣列或逗號分隔的字串。Facade 只讀取 `hosts` 鍵；其他客戶端行為 +需要透過 `ClientBuilderFactory` 和上游 Builder 配置。 ## 使用 -### 用戶端 Builder 工廠 +### 客戶端 Builder 工廠 `ClientBuilderFactory::create(array $options = [])` 會將 `$options` 傳給 Hyperf 的 -`GuzzleClientFactory`，並傳回尚未建構的上游 `ClientBuilder`。請先設定 Builder，再呼叫 `build()`： +`GuzzleClientFactory`，並返回尚未構建的上游 `ClientBuilder`。請先配置 Builder，再呼叫 `build()`： ```php use FriendsOfHyperf\Elasticsearch\ClientBuilderFactory; @@ -64,7 +64,7 @@ class Foo } ``` -此工廠不會讀取 `config/autoload/elasticsearch.php`；必須明確設定主機和其他 Builder 選項。 +此工廠不會讀取 `config/autoload/elasticsearch.php`；必須顯式設定主機和其他 Builder 選項。 ### Facade @@ -84,10 +84,10 @@ $results = Elasticsearch::connection('analytics')->search([ ]); ``` -每次 Facade 呼叫都會建構一個新用戶端。如果所選連線缺失或為 `null`，元件會擲回包含連線名稱的 +每次 Facade 呼叫都會構建一個新客戶端。如果所選連線缺失或為 `null`，元件會丟擲包含連線名稱的 `InvalidArgumentException`。 ## 上游 API -用戶端方法、請求參數、回應物件、身分驗證和其他 Builder 選項由已安裝的 -`elasticsearch/elasticsearch` 版本提供。使用這些功能時，請查閱對應版本的上游用戶端文件。 +客戶端方法、請求引數、響應物件、身份驗證和其他 Builder 選項由已安裝的 +`elasticsearch/elasticsearch` 版本提供。使用這些功能時，請查閱對應版本的上游客戶端文件。 diff --git a/docs/zh-tw/components/encryption.md b/docs/zh-tw/components/encryption.md index 9c936219c..645a3f208 100644 --- a/docs/zh-tw/components/encryption.md +++ b/docs/zh-tw/components/encryption.md @@ -1,6 +1,6 @@ # Encryption -加密元件為 Hyperf 中的值和字串提供帶驗證的加密。 +加密元件為 Hyperf 中的值和字串提供帶認證的加密。 ## 安裝 @@ -8,15 +8,15 @@ composer require friendsofhyperf/encryption ``` -此套件面向 Hyperf 3.2。僅在需要為加密閉包簽章時安裝選用的 `opis/closure` 套件： +此包面向 Hyperf 3.2。僅在需要為加密閉包簽名時安裝可選的 `opis/closure` 包： ```shell composer require opis/closure ``` -## 設定 +## 配置 -釋出設定檔： +釋出配置檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/encryption @@ -24,13 +24,13 @@ php bin/hyperf.php vendor:publish friendsofhyperf/encryption 此命令會建立 `config/autoload/encryption.php`，其中包含以下設定： -| 設定鍵 | 環境變數 | 預設值 | +| 配置鍵 | 環境變數 | 預設值 | | --- | --- | --- | -| `encryption.key` | `APP_KEY` | 內建的範例 `base64:` 金鑰 | +| `encryption.key` | `APP_KEY` | 內建的示例 `base64:` 金鑰 | | `encryption.cipher` | `APP_CIPHER` | `AES-256-CBC` | -使用元件前請替換內建範例金鑰。`base64:` 前綴表示元件會先對其後的內容進行 Base64 解碼， -再驗證金鑰長度。可使用以下命令為預設 cipher 產生新金鑰： +使用元件前請替換內建示例金鑰。`base64:` 字首表示元件會先對其後的內容進行 Base64 解碼， +再校驗金鑰長度。可使用以下命令為預設 cipher 生成新金鑰： ```shell php -r "echo 'base64:'.base64_encode(random_bytes(32)).PHP_EOL;" @@ -45,13 +45,13 @@ php -r "echo 'base64:'.base64_encode(random_bytes(32)).PHP_EOL;" | `AES-128-GCM` | 16 位元組 | | `AES-256-GCM` | 32 位元組 | -Cipher 名稱不區分大小寫。缺少金鑰時會擲出 -`FriendsOfHyperf\Encryption\Exception\MissingKeyException`；不支援的 cipher 或錯誤的金鑰長度會擲出 +Cipher 名稱不區分大小寫。缺少金鑰時會丟擲 +`FriendsOfHyperf\Encryption\Exception\MissingKeyException`；不支援的 cipher 或錯誤的金鑰長度會丟擲 `RuntimeException`。 -## 輔助函式 +## 助手函式 -此套件會自動載入帶命名空間的 `encrypt()` 和 `decrypt()` 函式。使用前請先匯入： +此包會自動載入帶名稱空間的 `encrypt()` 和 `decrypt()` 函式。使用前請先匯入： ```php use function FriendsOfHyperf\Encryption\decrypt; @@ -63,13 +63,13 @@ $value = decrypt($payload); `encrypt(mixed $value, bool $serialize = true)` 預設會序列化值， `decrypt(string $payload, bool $unserialize = true)` 會執行對應的反向操作。處理不需要序列化的原始字串時， -請將兩個函式的第二個參數都設為 `false`。 +請將兩個函式的第二個引數都設為 `false`。 ## Encrypter API 容器會將 `FriendsOfHyperf\Encryption\Encrypter`、 `FriendsOfHyperf\Encryption\Contract\Encrypter` 和 -`FriendsOfHyperf\Encryption\Contract\StringEncrypter` 綁定到已設定的加密器。 +`FriendsOfHyperf\Encryption\Contract\StringEncrypter` 繫結到已配置的加密器。 ```php use FriendsOfHyperf\Encryption\Contract\StringEncrypter; @@ -87,12 +87,12 @@ class TokenService } ``` -具體類別 `Encrypter` 還公開 `encrypt()`、`decrypt()`、`getKey()`、`getAllKeys()`、 +具體類 `Encrypter` 還公開 `encrypt()`、`decrypt()`、`getKey()`、`getAllKeys()`、 `getPreviousKeys()`、`previousKeys()`，以及靜態方法 `supported()` 和 `generateKey()`。 -## 金鑰輪替 +## 金鑰輪換 -輪替目前金鑰後，可在具體加密器上設定舊的原始金鑰，以解密已有 payload。新 payload 始終使用目前金鑰。 +輪換當前金鑰後，可在具體加密器上配置舊的原始金鑰，以解密已有 payload。新 payload 始終使用當前金鑰。 ```php use FriendsOfHyperf\Encryption\Encrypter; @@ -102,13 +102,13 @@ $encrypter->previousKeys([ ]); ``` -每個舊金鑰的長度都必須符合目前 cipher 的要求。 +每個舊金鑰的長度都必須符合當前 cipher 的要求。 -## 失敗與選用閉包簽章 +## 失敗與可選閉包簽名 -加密失敗會擲出 `FriendsOfHyperf\Encryption\Contract\EncryptException`。無效、遭竄改或無法解密的 -payload 會擲出 `FriendsOfHyperf\Encryption\Contract\DecryptException`。 +加密失敗會丟擲 `FriendsOfHyperf\Encryption\Contract\EncryptException`。無效、被篡改或無法解密的 +payload 會丟擲 `FriendsOfHyperf\Encryption\Contract\DecryptException`。 -安裝 `opis/closure` 且已設定 `encryption.key` 時，啟動監聽器會向 -`Opis\Closure\SerializableClosure` 註冊同一個解析後的金鑰，用於閉包簽章。正常的值或字串加密不依賴 +安裝 `opis/closure` 且已配置 `encryption.key` 時，啟動監聽器會向 +`Opis\Closure\SerializableClosure` 註冊同一個解析後的金鑰，用於閉包簽名。正常的值或字串加密不依賴 `opis/closure`。 diff --git a/docs/zh-tw/components/exception-event.md b/docs/zh-tw/components/exception-event.md index 6743f1a19..cca179b36 100644 --- a/docs/zh-tw/components/exception-event.md +++ b/docs/zh-tw/components/exception-event.md @@ -1,7 +1,7 @@ # Exception Event -此元件會在 Hyperf 的例外處理器派送器處理例外後派送 `ExceptionDispatched` 事件，並提供輔助函式， -用於在不擲回例外的情況下手動回報例外。 +此元件會在 Hyperf 的異常處理器排程器處理異常後派發 `ExceptionDispatched` 事件，並提供輔助函式， +用於在不丟擲異常的情況下手動報告異常。 ## 安裝 @@ -9,14 +9,14 @@ composer require friendsofhyperf/exception-event ``` -元件的 `ConfigProvider` 會透過 Composer 套件探索機制自動註冊切面。切面和監聽器依賴 Hyperf 的 AOP -及事件派送器支援，標準 Hyperf 應用程式已提供這些支援；在最小化安裝中，請確保 +元件的 `ConfigProvider` 會透過 Composer 包發現機制自動註冊切面。切面和監聽器依賴 Hyperf 的 AOP +及事件排程器支援，標準 Hyperf 應用已提供這些支援；在最小化安裝中，請確保 `hyperf/di` 和 `hyperf/event` 可用。 -## 自動派送 +## 自動派發 -已註冊的切面會攔截 `Hyperf\ExceptionHandler\ExceptionHandlerDispatcher::dispatch()`。派送器正常返回後， -元件會派送 `ExceptionDispatched` 事件，其中包含已處理的例外，以及上下文中的目前請求和回應。 +註冊的切面會攔截 `Hyperf\ExceptionHandler\ExceptionHandlerDispatcher::dispatch()`。排程器正常返回後， +元件會派發 `ExceptionDispatched` 事件，其中包含已處理的異常，以及上下文中的當前請求和響應。 ## 定義監聽器 @@ -67,19 +67,19 @@ class ExceptionEventListener implements ListenerInterface `FriendsOfHyperf\ExceptionEvent\Event\ExceptionDispatched` 公開以下屬性： -- `Throwable $throwable`：已處理或手動回報的例外。 -- `?ServerRequestInterface $request`：目前請求；不在請求上下文中時為 `null`。 -- `?ResponseInterface $response`：目前回應；不在回應上下文中時為 `null`。 +- `Throwable $throwable`：已處理或手動報告的異常。 +- `?ServerRequestInterface $request`：當前請求；不在請求上下文中時為 `null`。 +- `?ResponseInterface $response`：當前響應；不在響應上下文中時為 `null`。 -## 手動回報 +## 手動報告 -元件會自動載入三個命名空間輔助函式： +元件會自動載入三個名稱空間輔助函式： -- `report(string|Throwable $exception = 'RuntimeException', ...$parameters)`：回報例外。 +- `report(string|Throwable $exception = 'RuntimeException', ...$parameters)`：報告異常。 - `report_if($condition, string|Throwable $exception = 'RuntimeException', ...$parameters)`： - 條件為真值時回報。 + 條件為真值時報告。 - `report_unless($condition, string|Throwable $exception = 'RuntimeException', ...$parameters)`： - 條件為假值時回報。 + 條件為假值時報告。 ```php use DomainException; @@ -89,14 +89,14 @@ use function FriendsOfHyperf\ExceptionEvent\report_if; use function FriendsOfHyperf\ExceptionEvent\report_unless; report(new DomainException('The operation failed.')); -report('The operation failed.'); // 使用此訊息回報 RuntimeException。 +report('The operation failed.'); // 使用此訊息報告 RuntimeException。 report(DomainException::class, 'The operation failed.'); report_if($shouldReport, 'The operation failed.'); report_unless($operationSucceeded, 'The operation failed.'); ``` -`report()` 會直接派送 `ExceptionDispatched`，不會擲回例外。當第一個參數是已存在的例外類別名稱時， -其餘參數會傳給該例外的建構函式；其他字串會成為 `RuntimeException` 的訊息。 +`report()` 會直接派發 `ExceptionDispatched`，不會丟擲異常。當第一個引數是已存在的異常類名時， +其餘引數會傳給該異常的建構函式；其他字串會成為 `RuntimeException` 的訊息。 -`report_if()` 在條件為真值時回報，`report_unless()` 在條件為假值時回報。兩個函式都會傳回原始條件。 +`report_if()` 在條件為真值時報告，`report_unless()` 在條件為假值時報告。兩個函式都會返回原始條件。 diff --git a/docs/zh-tw/components/facade.md b/docs/zh-tw/components/facade.md index a0d3abfa0..6a7b22465 100644 --- a/docs/zh-tw/components/facade.md +++ b/docs/zh-tw/components/facade.md @@ -8,8 +8,8 @@ Facade 元件為常用的 Hyperf 服務提供靜態代理。 composer require friendsofhyperf/facade ``` -基礎套件依賴 `friendsofhyperf/support`、`hyperf/context` 和 `hyperf/di`。大多數 -Facade 還需要選用依賴，請只安裝應用程式實際使用的 Facade 所需套件，例如： +基礎包依賴 `friendsofhyperf/support`、`hyperf/context` 和 `hyperf/di`。大多數 +Facade 還需要可選依賴，請僅安裝應用實際使用的 Facade 所需的包，例如： ```shell composer require hyperf/config hyperf/logger @@ -17,7 +17,7 @@ composer require hyperf/config hyperf/logger ## 支援的 Facade -| Facade | 容器存取器 | 額外依賴 | +| Facade | 容器訪問器 | 額外依賴 | | --- | --- | --- | | `AMQP` | `Hyperf\Amqp\Producer` | `hyperf/amqp` | | `App`, `DI` | `Psr\Container\ContainerInterface` | 已包含（`hyperf/di`） | @@ -41,14 +41,14 @@ composer require hyperf/config hyperf/logger `App` 是 `DI` 的別名，`File` 是 `Filesystem` 的別名。 -## 設定與解析 +## 配置與解析 -Hyperf 會自動探索此元件，但它的 `ConfigProvider` 不會發佈或合併任何設定。請按各 -Hyperf 元件的正常方式設定底層服務。 +Hyperf 會自動發現此元件，但它的 `ConfigProvider` 不釋出或合併任何配置。請按各 +Hyperf 元件的正常方式配置底層服務。 -除下方列出的元件特有方法外，對 Facade 的靜態呼叫會轉送給 -`ApplicationContext` 根據上表存取器解析出的物件。Facade 基底類別會快取首次解析 -的物件。如果容器中不存在對應存取器，將擲出 +除下方列出的元件特有方法外，對 Facade 的靜態呼叫會轉發給 +`ApplicationContext` 根據上表訪問器解析出的物件。Facade 基類會快取首次解析的 +物件。如果容器中不存在對應訪問器，將丟擲 `Hyperf\Di\Exception\NotFoundException`。 需要底層物件本身時，可以呼叫 `getFacadeRoot()`： @@ -60,25 +60,25 @@ $config = Config::getFacadeRoot(); $name = Config::get('app_name', 'hyperf'); ``` -每個代理可接受的方法是其底層存取器的公開方法。具體簽章請參考相應元件文件。 +每個代理可接受的方法是其底層訪問器的公開方法。具體簽名請參考相應元件文件。 ## 元件特有方法 -以下公開方法由 Facade 類別自身實作： +以下公開方法由 Facade 類自身實現： | Facade | 方法 | 行為 | | --- | --- | --- | -| `AMQP` | `dispatch(ProducerMessageInterface $producerMessage): PendingAmqpProducerMessageDispatch` | 建立 AMQP 待調度物件的實例方法。 | -| `AsyncQueue` | `dispatch(Closure\|JobInterface $job): PendingAsyncQueueDispatch` | 建立非同步佇列待調度物件的實例方法。 | -| `AsyncQueue` | `push(JobInterface $job, int $delay = 0, ?string $pool = null)` | 使用指定佇列池推送；當 `$pool` 為 `null` 時使用 `$job->getPoolName()`；文件回傳型別為 `bool`。 | -| `Cookie` | `has($key)` | 檢查目前請求中的 Cookie，而不是 CookieJar；文件參數型別為 `string`，回傳型別為 `bool`。 | -| `Cookie` | `get($key, $default = null)` | 讀取目前請求中的 Cookie；文件鍵型別為 `string`，回傳型別為 `mixed`。 | -| `Kafka` | `dispatch(ProduceMessage $produceMessage): PendingKafkaProducerMessageDispatch` | 建立 Kafka 待調度物件的實例方法。 | -| `Kafka` | `send(ProduceMessage $produceMessage, ?string $pool = null): void` | 以單元素批次傳送訊息；未指定池時使用 `default`。 | -| `Kafka` | `sendBatch($produceMessages, ?string $pool = null): void` | 傳送文件型別為 `ProduceMessage[]` 的訊息批次；未指定池時使用 `default`。 | -| `Log` | `channel(string $name = 'hyperf', string $channel = 'default')` | 從 `LoggerFactory` 取得 `LoggerInterface`；其他 `Log` 靜態呼叫使用這兩個預設值。 | - -`AMQP::dispatch`、`AsyncQueue::dispatch` 和 `Kafka::dispatch` 被宣告為實例方法。 +| `AMQP` | `dispatch(ProducerMessageInterface $producerMessage): PendingAmqpProducerMessageDispatch` | 建立 AMQP 待排程物件的例項方法。 | +| `AsyncQueue` | `dispatch(Closure\|JobInterface $job): PendingAsyncQueueDispatch` | 建立非同步佇列待排程物件的例項方法。 | +| `AsyncQueue` | `push(JobInterface $job, int $delay = 0, ?string $pool = null)` | 使用指定佇列池推送；當 `$pool` 為 `null` 時使用 `$job->getPoolName()`；文件返回型別為 `bool`。 | +| `Cookie` | `has($key)` | 檢查當前請求中的 Cookie，而不是 CookieJar；文件引數型別為 `string`，返回型別為 `bool`。 | +| `Cookie` | `get($key, $default = null)` | 讀取當前請求中的 Cookie；文件鍵型別為 `string`，返回型別為 `mixed`。 | +| `Kafka` | `dispatch(ProduceMessage $produceMessage): PendingKafkaProducerMessageDispatch` | 建立 Kafka 待排程物件的例項方法。 | +| `Kafka` | `send(ProduceMessage $produceMessage, ?string $pool = null): void` | 以單元素批次傳送訊息；未指定佇列池時使用 `default`。 | +| `Kafka` | `sendBatch($produceMessages, ?string $pool = null): void` | 傳送文件型別為 `ProduceMessage[]` 的訊息批次；未指定佇列池時使用 `default`。 | +| `Log` | `channel(string $name = 'hyperf', string $channel = 'default')` | 從 `LoggerFactory` 獲取 `LoggerInterface`；其他 `Log` 靜態呼叫使用這兩個預設值。 | + +`AMQP::dispatch`、`AsyncQueue::dispatch` 和 `Kafka::dispatch` 被宣告為例項方法。 它們不是靜態 Facade 代理方法。 ```php diff --git a/docs/zh-tw/components/fast-paginate.md b/docs/zh-tw/components/fast-paginate.md index 082ec0a7c..643fe7277 100644 --- a/docs/zh-tw/components/fast-paginate.md +++ b/docs/zh-tw/components/fast-paginate.md @@ -4,11 +4,11 @@ ## 關於 -Fast Paginate 為 Hyperf 模型查詢建構器和關聯提供更快的 `limit`/`offset` 分頁巨集。它最適合偏移量較大的 -查詢，但實際效能取決於資料和索引，請在應用程式中與標準分頁器進行基準測試。 +Fast Paginate 為 Hyperf 模型查詢構造器和關係提供更快的 `limit`/`offset` 分頁宏。它最適合偏移量較大的 +查詢，但實際效能取決於資料和索引，請在應用中與標準分頁器進行基準測試。 -該元件使用類似延遲連線的方式。它首先對僅選擇模型主鍵以及排序所需已選別名的查詢進行分頁，然後透過第二次 -查詢取得目前頁面主鍵對應的完整資料。兩次資料查詢的概念形式如下： +該元件使用類似延遲連線的方式。它首先對僅選擇模型主鍵以及排序所需選中別名的查詢進行分頁，然後透過第二次 +查詢獲取當前頁主鍵對應的完整資料。兩次資料查詢的概念形式如下： ```sql select contacts.id from contacts limit 15 offset 150000; @@ -24,14 +24,14 @@ select * from contacts where contacts.id in (...); composer require friendsofhyperf/fast-paginate ``` -該元件依賴 Hyperf 3.2 系列套件。無需設定：Hyperf 會發現元件的 `ConfigProvider`，並在應用程式啟動時註冊 -分頁巨集。 +該元件依賴 Hyperf 3.2 系列軟體包。無需配置：Hyperf 會發現元件的 `ConfigProvider`，並在應用啟動時註冊 +分頁宏。 ## 使用 -### 模型查詢建構器和關聯 +### 模型查詢構造器和關係 -模型查詢建構器和關聯均提供以下兩個巨集： +模型查詢構造器和關係均提供以下兩個宏： ```php User::query()->fastPaginate(); @@ -41,22 +41,22 @@ User::first()->posts()->fastPaginate(); User::first()->posts()->simpleFastPaginate(); ``` -它們的簽章與對應的 Hyperf 模型查詢建構器分頁方法一致： +它們的簽名與對應的 Hyperf 模型查詢構造器分頁方法一致： ```php fastPaginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null); simpleFastPaginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null); ``` -- `$perPage`：每頁項目數；`null` 使用模型設定的每頁項目數。 -- `$columns`：取得完整資料時查詢的欄位。 -- `$pageName`：用於解析目前頁面的查詢字串參數名稱。 -- `$page`：明確指定的頁碼；`null` 時從目前請求解析。 +- `$perPage`：每頁條目數；`null` 使用模型配置的每頁條目數。 +- `$columns`：獲取完整資料時查詢的列。 +- `$pageName`：用於解析當前頁的查詢字串引數名。 +- `$page`：明確指定的頁碼；`null` 時從當前請求解析。 -`fastPaginate()` 回傳包含總數的長度感知分頁器。`simpleFastPaginate()` 回傳僅判斷是否還有下一頁的簡單 -分頁器。`BelongsToMany` 關聯會保留已填充的中介表資料，同時也支援 `HasManyThrough` 關聯。 +`fastPaginate()` 返回包含總數的長度感知分頁器。`simpleFastPaginate()` 返回僅判斷是否還有下一頁的簡單 +分頁器。`BelongsToMany` 關係會保留已填充的中間表資料，同時也支援 `HasManyThrough` 關係。 -### Scout 查詢建構器 +### Scout 查詢構造器 安裝 `hyperf/scout` 後，元件還會在 `Hyperf\Scout\Builder` 上註冊 `fastPaginate()`： @@ -64,7 +64,7 @@ simpleFastPaginate($perPage = null, $columns = ['*'], $pageName = 'page', $page User::search('Hyperf')->fastPaginate(); ``` -其簽章為 `fastPaginate($perPage = null, $pageName = 'page', $page = null)`。該 Scout 巨集會直接呼叫 +其簽名為 `fastPaginate($perPage = null, $pageName = 'page', $page = null)`。該 Scout 宏會直接呼叫 Scout 的標準 `paginate()` 方法，不使用資料庫兩次查詢最佳化。本元件不強制依賴 `hyperf/scout`。 ## 自動回退 @@ -74,6 +74,6 @@ Scout 的標準 `paginate()` 方法，不使用資料庫兩次查詢最佳化。 - 查詢包含 `having`、`group by` 或 `union` 子句； - `$perPage` 為 `-1`； -- 排序所需的已選運算式包含 `?` 綁定預留位置。 +- 排序所需的選中表達式包含 `?` 繫結佔位符。 這些回退會保留分頁行為，但不會獲得快速分頁最佳化。 diff --git a/docs/zh-tw/components/grpc-validation.md b/docs/zh-tw/components/grpc-validation.md index 254001c69..a26206ad8 100644 --- a/docs/zh-tw/components/grpc-validation.md +++ b/docs/zh-tw/components/grpc-validation.md @@ -8,13 +8,13 @@ composer require friendsofhyperf/grpc-validation ``` -此元件面向 Hyperf 3.2，並依賴 `hyperf/context`、`hyperf/di`、`hyperf/grpc-server` -和 `hyperf/validation`。Composer 會安裝這些依賴，套件內的 `ConfigProvider` 會自動註冊驗證切面， -不需發布元件設定檔。 +該元件面向 Hyperf 3.2，並依賴 `hyperf/context`、`hyperf/di`、`hyperf/grpc-server` +和 `hyperf/validation`。Composer 會安裝這些依賴，包內的 `ConfigProvider` 會自動註冊驗證切面， +無需釋出元件配置檔案。 ## 基本用法 -在 gRPC 服務方法上加入 `Validation`，並為 protobuf 訊息欄位定義 Hyperf 驗證規則： +在 gRPC 服務方法上新增 `Validation`，併為 protobuf 訊息欄位定義 Hyperf 驗證規則： ```php $value * 2); // 10 ``` -`cache` 會根據參數選擇行為： +`cache` 會根據引數選擇行為： ```php use function FriendsOfHyperf\Helpers\cache; @@ -90,7 +90,7 @@ $value = cache('key', 'default'); cache(['key' => 'value'], 60); ``` -主控台命令使用單獨的命名空間： +控制檯命令使用單獨的名稱空間： ```php use function FriendsOfHyperf\Helpers\Command\call; diff --git a/docs/zh-tw/components/http-client.md b/docs/zh-tw/components/http-client.md index c7f3d82ce..414a38714 100644 --- a/docs/zh-tw/components/http-client.md +++ b/docs/zh-tw/components/http-client.md @@ -8,12 +8,12 @@ composer require friendsofhyperf/http-client guzzlehttp/guzzle:^7.6 ``` -`guzzlehttp/guzzle` 是本套件建議安裝的依賴，傳送請求時必須可用。無需發佈設定檔。 +`guzzlehttp/guzzle` 是本包建議安裝的依賴，傳送請求時必須可用。無需釋出配置檔案。 ## 傳送請求 使用 `Http` 門面傳送 `GET`、`HEAD`、`POST`、`PUT`、`PATCH` 和 `DELETE` -請求。請求內容預設以 JSON 格式傳送。 +請求。請求體預設以 JSON 格式傳送。 ```php use FriendsOfHyperf\Http\Client\Http; @@ -27,7 +27,7 @@ $response = Http::post('https://example.com/users', [ ]); ``` -在 HTTP 方法前以鏈式方法設定待傳送請求： +在 HTTP 方法前鏈式呼叫方法以配置待發送請求： ```php $response = Http::baseUrl('https://example.com') @@ -40,8 +40,8 @@ $response = Http::baseUrl('https://example.com') ->get('/users/{user}', ['active' => true]); ``` -使用 `withUrlParameters()` 展開 URI 範本佔位符。使用 `asForm()`、`attach()` -或 `withBody()` 分別傳送表單、多部分或原始請求內容： +使用 `withUrlParameters()` 展開 URI 模板佔位符。使用 `asForm()`、`attach()` +或 `withBody()` 分別傳送表單、多部分或原始請求體： ```php $response = Http::withUrlParameters(['user' => 1]) @@ -55,13 +55,13 @@ $response = Http::attach('avatar', fopen('/path/to/avatar.jpg', 'r'), 'avatar.jp ->post('https://example.com/users/1/avatar'); ``` -預設連線逾時為 10 秒，請求總逾時為 30 秒。可使用 `withOptions()` 傳入其他 -Guzzle 請求選項。只應在確實需要停用 TLS 憑證驗證時使用 `withoutVerifying()`。 +預設連線超時為 10 秒，請求總超時為 30 秒。可使用 `withOptions()` 傳入其他 +Guzzle 請求選項。僅在確實需要停用 TLS 證書驗證時使用 `withoutVerifying()`。 ## 重試 -`retry()` 的第一個參數可以是總嘗試次數，也可以是以毫秒為單位的退避延遲陣列。 -第二個參數可以是固定延遲或閉包。可選的第三個參數決定是否重試失敗回應或連線例外。 +`retry()` 的第一個引數可以是總嘗試次數，也可以是以毫秒為單位的退避延遲陣列。 +第二個引數可以是固定延遲或閉包。可選的第三個引數決定是否重試失敗響應或連線異常。 ```php use FriendsOfHyperf\Http\Client\PendingRequest; @@ -74,11 +74,11 @@ $response = Http::retry( )->get('https://example.com'); ``` -預設情況下，重試耗盡後會擲回例外。將第四個參數設為 `false` 可回傳最終失敗回應。 +預設情況下，重試耗盡後會丟擲異常。將第四個引數設為 `false` 可返回最終失敗響應。 -## 回應與例外 +## 響應與異常 -請求回傳 `FriendsOfHyperf\Http\Client\Response`。常用回應方法包括： +請求返回 `FriendsOfHyperf\Http\Client\Response`。常用響應方法包括： ```php $response->body(); @@ -99,8 +99,8 @@ $response->clientError(); $response->serverError(); ``` -HTTP 4xx 和 5xx 回應預設不會擲回例外。在待傳送請求或回應上呼叫 `throw()` 可擲回 -`RequestException`。連線失敗會擲回 `ConnectionException`。 +HTTP 4xx 和 5xx 響應預設不會丟擲異常。在待發送請求或響應上呼叫 `throw()` 可丟擲 +`RequestException`。連線失敗會丟擲 `ConnectionException`。 ```php use FriendsOfHyperf\Http\Client\RequestException; @@ -112,9 +112,9 @@ try { } ``` -## 並行請求 +## 併發請求 -使用 `pool()` 並行傳送請求。使用 `as()` 為回應指定鍵名。 +使用 `pool()` 併發傳送請求。使用 `as()` 為響應指定鍵名。 ```php use FriendsOfHyperf\Http\Client\Http; @@ -132,8 +132,8 @@ $responses['user']->status(); ## 測試 -`fake()` 會攔截符合的請求，並記錄請求以供斷言。呼叫 `preventStrayRequests()` -可拒絕沒有符合假回應的請求。 +`fake()` 會攔截匹配的請求，並記錄請求以供斷言。呼叫 `preventStrayRequests()` +可拒絕沒有匹配假響應的請求。 ```php use FriendsOfHyperf\Http\Client\Http; @@ -150,8 +150,8 @@ Http::assertSent(fn (Request $request) => $request->url() === 'https://example.c Http::assertSentCount(1); ``` -重複請求需要回傳不同回應時，可使用回應序列。序列耗盡後預設擲回 -`OutOfBoundsException`，除非設定了 `whenEmpty()` 或 `dontFailWhenEmpty()`。 +重複請求需要返回不同響應時，可使用響應序列。序列耗盡後預設丟擲 +`OutOfBoundsException`，除非配置了 `whenEmpty()` 或 `dontFailWhenEmpty()`。 ```php Http::fakeSequence('example.com/*') @@ -165,14 +165,14 @@ Http::fakeSequence('example.com/*') ## 中介軟體與事件 使用 `withMiddleware()`、`withRequestMiddleware()` 或 `withResponseMiddleware()` -加入單次請求中介軟體。`Factory` 還提供 `globalMiddleware()`、 +新增單次請求中介軟體。`Factory` 還提供 `globalMiddleware()`、 `globalRequestMiddleware()` 和 `globalResponseMiddleware()`。 -使用 PSR 事件分派器建立 `Factory` 時，元件會分派 `RequestSending`、 +使用 PSR 事件分發器建立 `Factory` 時，元件會分發 `RequestSending`、 `ResponseReceived` 和 `ConnectionFailed` 事件。 ## Laravel 相容性 本元件 API 基於 Laravel HTTP 客戶端，但實際可用 API 和行為以本元件原始碼為準。 可參閱 [Laravel HTTP Client 文件](https://laravel.com/docs/9.x/http-client) -了解更多背景，並在使用前對照本元件確認 API。 +瞭解更多背景，並在使用前對照本元件確認 API。 diff --git a/docs/zh-tw/components/ide-helper.md b/docs/zh-tw/components/ide-helper.md index 53e022f05..eaa460888 100644 --- a/docs/zh-tw/components/ide-helper.md +++ b/docs/zh-tw/components/ide-helper.md @@ -1,6 +1,6 @@ # IDE Helper -IDE Helper 元件為 Hyperf 模型及使用 `Hyperf\Macroable\Macroable` 的類別產生 PHP 助手檔案。 +IDE Helper 元件為 Hyperf 模型及使用 `Hyperf\Macroable\Macroable` 的類生成 PHP 助手檔案。 ## 安裝 @@ -9,42 +9,42 @@ composer require friendsofhyperf/ide-helper ``` Hyperf 會發現元件的 `ConfigProvider`，並自動註冊 `ide-helper:model` 和 -`ide-helper:macro` 命令。元件不會發布設定檔。 +`ide-helper:macro` 命令。元件不會發布配置檔案。 ## 模型助手 -為應用程式 `app` 目錄下找到的具體模型類別產生助手： +為應用 `app` 目錄下找到的具體模型類生成助手： ```shell php ./bin/hyperf.php ide-helper:model ``` -命令會在目前目錄寫入 `_ide_helper_models.php`。它會產生 `Eloquent` 助手，並根據型別轉換、 -存取器、關聯關係和軟刪除推斷模型屬性及方法。 +命令會在當前目錄寫入 `_ide_helper_models.php`。它會生成 `Eloquent` 助手，並根據型別轉換、 +訪問器、關聯關係和軟刪除推斷模型屬性及方法。 -使用 `--name`（`-N`）修改輸出檔案；使用 `--ignore`（`-I`）排除以逗號分隔的完整模型類別名稱： +使用 `--name`（`-N`）修改輸出檔案；使用 `--ignore`（`-I`）排除以逗號分隔的完整模型類名： ```shell php ./bin/hyperf.php ide-helper:model --name=storage/ide-models.php \ --ignore='App\Model\InternalModel,App\Model\LegacyModel' ``` -安裝建議依賴 `doctrine/dbal` 後，還可從資料庫資料表欄位推斷屬性： +安裝建議依賴 `doctrine/dbal` 後，還可從資料庫表字段推斷屬性： ```shell composer require --dev doctrine/dbal ``` -## 巨集助手 +## 宏助手 -為已載入的巨集產生助手： +為已載入的宏生成助手： ```shell php ./bin/hyperf.php ide-helper:macro ``` -掃描 Composer 最佳化類別映射前，命令會執行 `composer dump-autoload -o --no-scripts`。預設會在 -目前目錄寫入 `_ide_helper_macros.php`。 +掃描 Composer 最佳化類對映前，命令會執行 `composer dump-autoload -o --no-scripts`。預設會在 +當前目錄寫入 `_ide_helper_macros.php`。 使用 `--name`（`-N`）修改輸出檔案： @@ -52,9 +52,9 @@ php ./bin/hyperf.php ide-helper:macro php ./bin/hyperf.php ide-helper:macro --name=storage/ide-macros.php ``` -## 設定 +## 配置 -需要自訂產生行為時，請建立 `config/autoload/ide-helper.php`： +需要自定義生成行為時，請建立 `config/autoload/ide-helper.php`： ```php `：將自訂資料庫型別映射為 Doctrine 型別。 -- `macro.namespaces`：只掃描類別名稱以其中任一前綴開頭的類別映射項目；空陣列會掃描全部項目。 -- `macro.rejects`：巨集產生時排除的完整類別名稱。 +- `model.ignores`：模型生成時排除的完整模型類名。 +- `model.camel_case_properties`：將生成的屬性名轉換為駝峰格式，預設為 `false`。 +- `model.type_overrides`：將推斷出的模型屬性型別對映為替代型別。 +- `model.custom_db_types.`：將自定義資料庫型別對映為 Doctrine 型別。 +- `macro.namespaces`：只掃描類名以其中任一字首開頭的類對映條目；空陣列會掃描全部條目。 +- `macro.rejects`：宏生成時排除的完整類名。 diff --git a/docs/zh-tw/components/index.md b/docs/zh-tw/components/index.md index 1dac20fc7..da8a3cdc4 100644 --- a/docs/zh-tw/components/index.md +++ b/docs/zh-tw/components/index.md @@ -5,74 +5,74 @@ ## 開發與診斷 -- [Telescope](telescope.md)：檢查請求、例外、查詢、Redis 指令等執行資訊。 -- [Tinker](tinker.md)：在 Hyperf 應用程式中執行互動式 REPL。 +- [Telescope](telescope.md)：檢查請求、異常、查詢、Redis 命令等執行資訊。 +- [Tinker](tinker.md)：在 Hyperf 應用中執行互動式 REPL。 - [Web Tinker](web-tinker.md)：透過瀏覽器使用 Tinker。 -- [IDE Helper](ide-helper.md)：為應用程式類別產生 IDE 中繼資料。 +- [IDE Helper](ide-helper.md)：為應用類生成 IDE 元資料。 - [Pretty Console](pretty-console.md)：格式化命令列輸出。 -- [Command Benchmark](command-benchmark.md)：測量指令執行過程。 +- [Command Benchmark](command-benchmark.md)：測量命令執行過程。 ## 資料庫與模型 - [Model Factory](model-factory.md)：為測試和種子資料建立模型工廠。 - [Model Observer](model-observer.md)：註冊模型觀察者。 -- [Model Scope](model-scope.md)：定義可重用的模型查詢範圍。 -- [Model Hashids](model-hashids.md)：對外提供編碼後的模型識別碼。 -- [Model Morph Addon](model-morph-addon.md)：擴充多型模型關聯。 -- [Compoships](compoships.md)：使用多欄定義模型關聯。 -- [Fast Paginate](fast-paginate.md)：最佳化大型資料集分頁。 -- [MySQL Grammar Addon](mysql-grammar-addon.md)：擴充 MySQL 查詢語法。 +- [Model Scope](model-scope.md)：定義可複用的模型查詢作用域。 +- [Model Hashids](model-hashids.md)：對外提供編碼後的模型標識。 +- [Model Morph Addon](model-morph-addon.md)：擴充套件多型模型關聯。 +- [Compoships](compoships.md)：使用多列定義模型關聯。 +- [Fast Paginate](fast-paginate.md)：最佳化大資料集分頁。 +- [MySQL Grammar Addon](mysql-grammar-addon.md)：擴充套件 MySQL 查詢語法。 - [Trigger](trigger.md)：消費 MySQL binlog 事件。 ## 快取與協調 - [Cache](cache.md)：使用表達力更強的快取 API。 -- [Lock](lock.md)：透過分散式鎖協調工作。 +- [Lock](lock.md)：透過分散式鎖協調任務。 - [Redis Subscriber](redis-subscriber.md)：消費 Redis Pub/Sub 訊息。 ## HTTP 與外部服務 -- [HTTP Client](http-client.md)：使用便利的 HTTP 用戶端。 -- [OAuth2 Server](oauth2-server.md)：建立 OAuth 2.0 授權伺服器。 -- [OpenAI Client](openai-client.md)：整合 OpenAI PHP 用戶端。 -- [Elasticsearch](elasticsearch.md)：設定 Elasticsearch 用戶端。 -- [reCAPTCHA](recaptcha.md)：驗證 Google reCAPTCHA 回應。 +- [HTTP Client](http-client.md)：使用便捷的 HTTP 客戶端。 +- [OAuth2 Server](oauth2-server.md)：構建 OAuth 2.0 授權伺服器。 +- [OpenAI Client](openai-client.md)：整合 OpenAI PHP 客戶端。 +- [Elasticsearch](elasticsearch.md)：配置 Elasticsearch 客戶端。 +- [reCAPTCHA](recaptcha.md)：驗證 Google reCAPTCHA 響應。 ## 訊息與通知 -- [AMQP Job](amqp-job.md)：將 AMQP 訊息作為工作派送。 +- [AMQP Job](amqp-job.md)：將 AMQP 訊息作為任務派發。 - [Mail](mail.md)：使用 Symfony Mailer 傳送郵件。 -- [Notification](notification.md)：透過多個管道傳送通知。 +- [Notification](notification.md)：透過多個渠道傳送通知。 - [Notification Mail](notification-mail.md)：透過郵件傳送通知。 - [Notification EasySms](notification-easysms.md)：透過簡訊傳送通知。 - [TCP Sender](tcp-sender.md)：向 TCP 服務傳送訊息。 -## 設定與基礎設施 +## 配置與基礎設施 -- [Confd](confd.md)：使用 confd 管理設定。 -- [Config Consul](config-consul.md)：從 Consul 載入設定。 -- [IPC Broadcaster](ipc-broadcaster.md)：在 Worker 行程之間廣播訊息。 +- [Confd](confd.md)：使用 confd 管理配置。 +- [Config Consul](config-consul.md)：從 Consul 載入配置。 +- [IPC Broadcaster](ipc-broadcaster.md)：在 Worker 程序之間廣播訊息。 - [Telescope Elasticsearch](telescope-elasticsearch.md)：將 Telescope 記錄儲存到 Elasticsearch。 ## 安全與驗證 -- [Encryption](encryption.md)：加密和解密應用程式資料。 +- [Encryption](encryption.md)：加密和解密應用資料。 - [Purifier](purifier.md)：清理 HTML 輸入。 -- [Validated DTO](validated-dto.md)：驗證並填入資料傳輸物件。 -- [Command Validation](command-validation.md)：驗證主控台指令輸入。 +- [Validated DTO](validated-dto.md)：驗證並填充資料傳輸物件。 +- [Command Validation](command-validation.md)：驗證控制檯命令輸入。 - [gRPC Validation](grpc-validation.md)：驗證 gRPC 請求。 -- [Rate Limit](rate-limit.md)：套用可設定的速率限制演算法。 +- [Rate Limit](rate-limit.md)：應用可配置的限流演算法。 -## 框架擴充 +## 框架擴充套件 - [Facade](facade.md)：定義 Laravel 風格的 Facade。 -- [Macros](macros.md)：為框架類別加入巨集。 +- [Macros](macros.md)：為框架類新增宏。 - [Helpers](helpers.md)：使用額外的輔助函式。 -- [Support](support.md)：使用共用工具、流暢派送和退避策略。 -- [Exception Event](exception-event.md)：為例外派送事件。 +- [Support](support.md)：使用共享工具、流式派發和退避策略。 +- [Exception Event](exception-event.md)：為異常派發事件。 -## 指令與執行環境 +## 命令與執行時 -- [Command Signals](command-signals.md)：在指令中處理行程訊號。 +- [Command Signals](command-signals.md)：在命令中處理程序訊號。 - [Console Spinner](console-spinner.md)：顯示進度 Spinner。 - [Co-PHPUnit](co-phpunit.md)：在協程中執行 PHPUnit 測試。 diff --git a/docs/zh-tw/components/ipc-broadcaster.md b/docs/zh-tw/components/ipc-broadcaster.md index ab010023b..456180efb 100644 --- a/docs/zh-tw/components/ipc-broadcaster.md +++ b/docs/zh-tw/components/ipc-broadcaster.md @@ -8,20 +8,20 @@ composer require friendsofhyperf/ipc-broadcaster ``` -該套件會自動註冊 `ConfigProvider`，將 `BroadcasterInterface` 綁定到 -`AllProcessesBroadcaster`，並註冊 Server Worker 接收訊息所需的監聽器。該元件沒有需要發佈的設定檔。 +該包會自動註冊 `ConfigProvider`，將 `BroadcasterInterface` 繫結到 +`AllProcessesBroadcaster`，並註冊 Server Worker 接收訊息所需的監聽器。該元件沒有需要釋出的配置檔案。 -該套件的 `composer.json` 僅宣告了 `hyperf/event ~3.2.0`，且沒有宣告可選依賴。請在提供廣播器所需 -Server、Process、容器和 DI 執行階段類別的 Hyperf Server 應用中使用。 +該包的 `composer.json` 僅聲明瞭 `hyperf/event ~3.2.0`，且沒有宣告可選依賴。請在提供廣播器所需 +Server、Process、容器和 DI 執行時類的 Hyperf Server 應用中使用。 ## 廣播訊息 -`broadcast()` 函式接受 `IpcMessageInterface` 實例或閉包。預設透過 +`broadcast()` 函式接受 `IpcMessageInterface` 例項或閉包。預設透過 `AllProcessesBroadcaster` 將訊息傳送到其他所有 Server Worker 和所有已註冊的協程使用者程序。 -### 類別訊息 +### 類訊息 -繼承 `IpcMessage` 並實作 `handle()`。`IpcMessage` 還透過 +繼承 `IpcMessage` 並實現 `handle()`。`IpcMessage` 還透過 `InteractsWithFromWorkerId` 提供 `getFromWorkerId()` 和 `setFromWorkerId()`。Server Worker 收到訊息時，`getFromWorkerId()` 包含傳送方的 Worker ID。 @@ -53,8 +53,8 @@ broadcast(new FooMessage('bar')); ### 閉包訊息 -閉包在廣播前會包裝為 `ClosureIpcMessage` 並進行序列化，因此閉包擷取的值也必須可序列化。在一般 -Hyperf DI 環境中，有型別宣告的閉包參數可從容器解析。 +閉包在廣播前會包裝為 `ClosureIpcMessage` 並進行序列化，因此閉包捕獲的值也必須可序列化。在常規 +Hyperf DI 環境中，有型別宣告的閉包引數可從容器解析。 ```php use function FriendsOfHyperf\IpcBroadcaster\broadcast; @@ -66,7 +66,7 @@ broadcast(function () { ## 選擇目標 -注入 `BroadcasterInterface` 可使用預設的全程序廣播行為，也可以建構特定廣播器來選擇目標： +注入 `BroadcasterInterface` 可使用預設的全程序廣播行為，也可以構造特定廣播器來選擇目標： ```php use FriendsOfHyperf\IpcBroadcaster\ServerBroadcaster; @@ -79,8 +79,8 @@ $userProcessBroadcaster = new UserProcessesBroadcaster(name: 'reporting', id: 0) $userProcessBroadcaster->broadcast($message); ``` -`ServerBroadcaster` 接受容器和可選的 Worker ID；未傳 ID 時，會傳送到目前 Worker 之外的所有 -Server Worker。`UserProcessesBroadcaster` 接受可選的程序名稱和程序 ID；兩者均未傳時，會傳送到 +`ServerBroadcaster` 接受容器和可選的 Worker ID；未傳 ID 時，會發送到當前 Worker 之外的所有 +Server Worker。`UserProcessesBroadcaster` 接受可選的程序名稱和程序 ID；兩者均未傳時，會發送到 Hyperf `ProcessCollector` 收集的所有已註冊程序。 ## 在使用者程序中處理訊息 @@ -110,10 +110,10 @@ class UserProcessPipeMessageListener implements ListenerInterface } ``` -## 在目前 Worker 中執行 +## 在當前 Worker 中執行 -廣播預設不會在目前 Server Worker 中執行。給訊息加入 `RunsInCurrentWorker` 後，會先在目前 Worker -中呼叫一次 `handle()`，再傳送到所選目標： +廣播預設不會在當前 Server Worker 中執行。給訊息新增 `RunsInCurrentWorker` 後，會先在當前 Worker +中呼叫一次 `handle()`，再發送到所選目標： ```php use FriendsOfHyperf\IpcBroadcaster\IpcMessage; @@ -132,5 +132,5 @@ class RefreshMessage extends IpcMessage ## 協程伺服器限制 -觸發 `MainCoroutineServerStart` 後，跨程序廣播會被停用，廣播器呼叫不會傳送訊息便直接返回。使用 -`RunsInCurrentWorker` 的訊息仍會在廣播器返回前於本機執行一次。 +觸發 `MainCoroutineServerStart` 後，跨程序廣播會被停用，廣播器呼叫不會發送訊息便直接返回。使用 +`RunsInCurrentWorker` 的訊息仍會在廣播器返回前在本地執行一次。 diff --git a/docs/zh-tw/components/lock.md b/docs/zh-tw/components/lock.md index c06695270..f2371216b 100644 --- a/docs/zh-tw/components/lock.md +++ b/docs/zh-tw/components/lock.md @@ -8,44 +8,44 @@ Hyperf 原子鎖元件。 composer require friendsofhyperf/lock ``` -預設驅動使用 Redis。請依照使用的驅動安裝對應的選用依賴： +預設驅動使用 Redis。請根據使用的驅動安裝對應的可選依賴： -| 驅動 | 設定名稱 | 選用依賴 | +| 驅動 | 配置名稱 | 可選依賴 | | --- | --- | --- | | `RedisLock` | `default` | `hyperf/redis` | | `FileSystemLock` | `file` | `hyperf/cache` | | `DatabaseLock` | `database` | `hyperf/db-connection` | | `CoroutineLock` | `co` | 無 | -| `CacheLock` | 未發布 | `hyperf/cache` | +| `CacheLock` | 未釋出 | `hyperf/cache` | -發布設定檔： +釋出配置檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/lock -i config ``` -使用資料庫驅動時，還需要發布並執行鎖遷移： +使用資料庫驅動時，還需要釋出並執行鎖遷移： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/lock -i migrations php bin/hyperf.php migrate ``` -執行發布的遷移前，請將其中的 `value` 欄位改為 `owner`。目前 `DatabaseLock` 實作讀寫的是 -`owner` 欄位。 +執行釋出的遷移前，請將其中的 `value` 列改為 `owner`。當前 `DatabaseLock` 實現讀寫的是 +`owner` 列。 -## 設定 +## 配置 -發布的 `config/autoload/lock.php` 包含 `default`、`file`、`database` 和 `co` 設定。每項設定 -用於選擇驅動類別，並將其中的 `constructor` 選項傳給驅動。`lock()` 和 -`LockFactory::make()` 的第四個參數是設定名稱，而不是驅動類別名稱。 +釋出的 `config/autoload/lock.php` 包含 `default`、`file`、`database` 和 `co` 配置。每項配置 +用於選擇驅動類，並將其中的 `constructor` 選項傳給驅動。`lock()` 和 +`LockFactory::make()` 的第四個引數是配置名稱，而不是驅動類名。 -所選的 `lock.` 設定不存在時，工廠會擲出 `InvalidArgumentException`。你也可以新增 -自訂設定，其驅動須實作 `FriendsOfHyperf\Lock\Driver\LockInterface`。 +所選的 `lock.` 配置不存在時，工廠會丟擲 `InvalidArgumentException`。你也可以新增 +自定義配置，其驅動須實現 `FriendsOfHyperf\Lock\Driver\LockInterface`。 ## 建立鎖 -匯入並呼叫帶命名空間的輔助函式： +匯入並呼叫帶名稱空間的輔助函式： ```php use function FriendsOfHyperf\Lock\lock; @@ -61,12 +61,12 @@ if ($lock->get()) { } ``` -不傳名稱呼叫 `lock()` 時回傳 `LockFactory`，否則回傳 `LockInterface` 實例。參數如下： +不傳名稱呼叫 `lock()` 時返回 `LockFactory`，否則返回 `LockInterface` 例項。引數如下： - `name`：鎖名稱。 - `seconds`：請求的鎖有效期秒數，預設為 `0`。 -- `owner`：選用的擁有者識別；省略時會隨機產生。 -- `driver`：`lock` 下的設定名稱，預設為 `default`。 +- `owner`：可選的所有者標識；省略時會隨機生成。 +- `driver`：`lock` 下的配置名稱，預設為 `default`。 TTL 行為取決於驅動。特別是當 `seconds` 為 `0` 或負數時，`DatabaseLock` 會儲存一天的 過期時間。 @@ -76,8 +76,8 @@ TTL 行為取決於驅動。特別是當 `seconds` 為 `0` 或負數時，`Datab `LockInterface` 公開 `get()`、`block()`、`release()`、`owner()`、`forceRelease()`、 `refresh()`、`isExpired()` 和 `getRemainingLifetime()`。 -`get()` 只嘗試取得一次；未傳回呼時回傳布林值。傳入回呼時，它會回傳回呼結果，並在 -`finally` 區塊中釋放鎖： +`get()` 只嘗試獲取一次；未傳回調時返回布林值。傳入回撥時，它會返回回撥結果，並在 +`finally` 塊中釋放鎖： ```php $result = lock('foo', 10)->get(function () { @@ -85,7 +85,7 @@ $result = lock('foo', 10)->get(function () { }); ``` -`block()` 會重試，直到取得鎖或達到等待時限；逾時時擲出 `LockTimeoutException`。傳入回呼 +`block()` 會重試，直到獲取鎖或達到等待時限；超時時丟擲 `LockTimeoutException`。傳入回撥 時也會自動釋放鎖： ```php @@ -100,15 +100,15 @@ try { } ``` -`release()` 只釋放目前擁有者持有的鎖，`forceRelease()` 會忽略擁有權。僅當驅動支援時， -`refresh($ttl)` 才能重新整理過期時間；TTL 不為正數時回傳 `false`。`isExpired()` 和 -`getRemainingLifetime()` 回傳鎖實例追蹤的過期狀態。 +`release()` 只釋放當前所有者持有的鎖，`forceRelease()` 會忽略所有權。僅當驅動支援時， +`refresh($ttl)` 才能重新整理過期時間；TTL 不為正數時返回 `false`。`isExpired()` 和 +`getRemainingLifetime()` 返回鎖例項跟蹤的過期狀態。 ## 註解 ### 屬性注入 -`#[Lock]` 用於屬性，並在應用程式啟動時注入鎖實例。參數為 `name`、`seconds`、`owner` 和 +`#[Lock]` 用於屬性，並在應用啟動時注入鎖例項。引數為 `name`、`seconds`、`owner` 和 `driver`。 ```php @@ -124,9 +124,9 @@ class Foo ### 阻塞方法 -`#[Blockable]` 用於方法。當 `seconds` 大於 `0` 時，它會建立鎖並最多等待 `seconds` 秒取得 -鎖，然後在方法回傳或擲出例外後自動釋放。`ttl` 是鎖有效期，`driver` 用於選擇鎖設定。 -`prefix` 和 `value` 會結合方法參數格式化為鎖名稱。 +`#[Blockable]` 用於方法。當 `seconds` 大於 `0` 時，它會建立鎖並最多等待 `seconds` 秒獲取 +鎖，然後在方法返回或丟擲異常後自動釋放。`ttl` 是鎖有效期，`driver` 用於選擇鎖配置。 +`prefix` 和 `value` 會結合方法引數格式化為鎖名稱。 `Blockable` 使用 `Hyperf\Cache\Helper\StringHelper`，因此使用此註解前需安裝 `hyperf/cache`。 diff --git a/docs/zh-tw/components/macros.md b/docs/zh-tw/components/macros.md index d37f0feba..cf1a60c30 100644 --- a/docs/zh-tw/components/macros.md +++ b/docs/zh-tw/components/macros.md @@ -1,7 +1,7 @@ # Macros -此元件為 Hyperf 的集合、上下文、請求和字串類別加入常用巨集。元件的 `ConfigProvider` 會在應用程式 -啟動時自動註冊 mixin，無需發布設定檔。 +該元件為 Hyperf 的集合、上下文、請求和字串類新增常用宏。元件的 `ConfigProvider` 會在應用啟動時 +自動註冊 mixin，無需釋出配置檔案。 ## 安裝 @@ -11,16 +11,16 @@ composer require friendsofhyperf/macros ## 可選依賴 -已註冊的巨集會直接使用以下可選套件： +已註冊的宏會直接使用以下可選包： -- `hyperf/http-server`：所有 `Request` 巨集。 +- `hyperf/http-server`：所有 `Request` 宏。 - `league/commonmark`：`Str::markdown`、`Str::inlineMarkdown` 及對應的 `Stringable` 方法。 - `voku/portable-ascii`：`Str::transliterate`。 -- `friendsofhyperf/encryption`：`Stringable::encrypt` 和 `Stringable::decrypt`；同時需要設定 +- `friendsofhyperf/encryption`：`Stringable::encrypt` 和 `Stringable::decrypt`；同時需要配置 encryption 元件。 -`composer.json` 還建議安裝用於產生 UUID 的 `ramsey/uuid`、用於產生 ULID 的 `symfony/uid` 和 -`opis/closure`。目前 mixin 原始碼不會直接呼叫這三個套件。 +`composer.json` 還建議安裝用於生成 UUID 的 `ramsey/uuid`、用於生成 ULID 的 `symfony/uid` 和 +`opis/closure`。當前 mixin 原始碼不會直接呼叫這三個包。 ## 支援方法 @@ -38,9 +38,9 @@ composer require friendsofhyperf/macros - `Arr::sortByMany($array, $comparisons = [])` - `Arr::string(ArrayAccess|array $array, null|string|int $key, ?string $default = null)` -帶型別的讀取方法支援點號路徑；解析出的值不符合目標型別時會擲回 `InvalidArgumentException`。 -`Arr::from` 可將支援的陣列、Enumerable/Arrayable 物件、可迭代物件、支援 JSON 的物件和一般物件 -轉換為陣列，但拒絕純量值。 +帶型別的讀取方法支援點號路徑；解析出的值不符合目標型別時會丟擲 `InvalidArgumentException`。 +`Arr::from` 可將受支援的陣列、Enumerable/Arrayable 物件、可遍歷物件、支援 JSON 的物件和普通物件 +轉換為陣列，但拒絕標量值。 ### Hyperf\Collection\Collection @@ -51,14 +51,14 @@ composer require friendsofhyperf/macros - `LazyCollection::collapseWithKeys()` `collapseWithKeys` 在保留鍵的同時展平巢狀陣列或集合。非陣列和非集合值會被忽略，後出現的重複鍵會 -覆寫先前的值。 +覆蓋先前的值。 ### Hyperf\Context\Context - `Context::decrement(string $id, int $step = 1, ?int $coroutineId = null)` - `Context::increment(string $id, int $step = 1, ?int $coroutineId = null)` -兩個方法都透過 `Context::override` 更新所選上下文中的值。缺少的值會先按零處理，再套用步長。 +兩個方法都透過 `Context::override` 更新選定上下文中的值。缺失的值會先按零處理，再應用步長。 ### Hyperf\HttpServer\Request @@ -102,8 +102,8 @@ composer require friendsofhyperf/macros - `Request::whenFilled($key, callable $callback, ?callable $default = null)` - `Request::whenHas($key, callable $callback, ?callable $default = null)` -`Request::fake` 建立獨立的 PSR-7 `ServerRequest`，並可選擇將其傳給回呼。`merge` 和 -`mergeIfMissing` 會更新目前上下文中儲存的解析後輸入。`validate` 和 `validateWithBag` 會從容器 +`Request::fake` 建立獨立的 PSR-7 `ServerRequest`，並可選擇將其傳給回撥。`merge` 和 +`mergeIfMissing` 會更新當前上下文中儲存的解析後輸入。`validate` 和 `validateWithBag` 會從容器 解析 Hyperf 的 `ValidatorFactoryInterface`。 ### Hyperf\Stringable\Str @@ -130,10 +130,10 @@ composer require friendsofhyperf/macros - `Stringable::toHtmlString()` - `Stringable::whenIsAscii($callback, $default = null)` -多數 `Stringable` 轉換巨集會傳回新的 `Stringable` 執行個體，因此可以鏈式呼叫。兩個 `doesnt*` -方法傳回布林值，`toHtmlString` 傳回 `FriendsOfHyperf\Support\HtmlString`。 +多數 `Stringable` 轉換宏返回新的 `Stringable` 例項，因此可以鏈式呼叫。兩個 `doesnt*` 方法返回 +布林值，`toHtmlString` 返回 `FriendsOfHyperf\Support\HtmlString`。 -## 範例 +## 示例 ```php use Hyperf\Collection\Arr; diff --git a/docs/zh-tw/components/mail.md b/docs/zh-tw/components/mail.md index 58e0f62fb..82cc33e29 100644 --- a/docs/zh-tw/components/mail.md +++ b/docs/zh-tw/components/mail.md @@ -9,25 +9,25 @@ composer require friendsofhyperf/mail php bin/hyperf.php vendor:publish friendsofhyperf/mail ``` -發布元件會建立 `config/autoload/mail.php`，並將郵件檢視元件複製到 `storage/views/mail`。 -如果應用尚無 Hyperf 檢視設定，請另行發布： +釋出元件會建立 `config/autoload/mail.php`，並將郵件檢視元件複製到 `storage/views/mail`。 +如果應用尚無 Hyperf 檢視配置，請另行釋出： ```shell php bin/hyperf.php vendor:publish hyperf/view ``` -元件要求 PHP 8.1 或更高版本。部分功能需要可選相依套件： +元件要求 PHP 8.1 或更高版本。部分功能需要可選依賴： -- `hyperf/devtool` 提供 `gen:mail` 指令。 -- `aws/aws-sdk-php` 是 `ses` 和 `ses-v2` 傳輸的必要相依套件。 +- `hyperf/devtool` 提供 `gen:mail` 命令。 +- `aws/aws-sdk-php` 是 `ses` 和 `ses-v2` 傳輸的必要依賴。 - Symfony API 郵件傳輸需要 `symfony/http-client`。 - `symfony/mailgun-mailer` 和 `symfony/postmark-mailer` 提供對應傳輸。 -## 設定 +## 配置 -發布的設定預設使用 `log` mailer。透過 `MAIL_MAILER` 選擇 mailer，並在 `mail.mailers` 下設定。 +釋出的配置預設使用 `log` mailer。透過 `MAIL_MAILER` 選擇 mailer，並在 `mail.mailers` 下配置。 支援的傳輸包括 `smtp`、`sendmail`、`mail`、`mailgun`、`ses`、`ses-v2`、`postmark`、`log`、 -`array`、`failover` 和 `roundrobin`。可使用 `Mail::extend()` 註冊自訂傳輸。 +`array`、`failover` 和 `roundrobin`。可使用 `Mail::extend()` 註冊自定義傳輸。 ```php // config/autoload/mail.php @@ -67,20 +67,20 @@ return [ ]; ``` -mailer 專屬的 `from`、`reply_to`、`to` 或 `return_path` 會覆寫對應全域地址。全域 `to` 地址還會在 -傳送前移除原始 To、Cc 和 Bcc 收件者，適合開發環境使用。 +mailer 專屬的 `from`、`reply_to`、`to` 或 `return_path` 會覆蓋對應全域性地址。全域性 `to` 地址還會在 +傳送前移除原始 To、Cc 和 Bcc 收件人，適合開發環境使用。 ## 建立 Mailable -安裝 `hyperf/devtool` 後，可產生基於檢視的 mailable；使用 `--markdown` 會同時建立 Markdown 範本： +安裝 `hyperf/devtool` 後，可生成基於檢視的 mailable；使用 `--markdown` 會同時建立 Markdown 模板： ```shell php bin/hyperf.php gen:mail TestMail php bin/hyperf.php gen:mail TestMail --markdown ``` -`Envelope` 定義地址、主旨、標籤、中繼資料和 Symfony 訊息回呼。`Content` 接受 `view`（或其 `html` -別名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中宣告的 public 屬性也會公開給檢視。 +`Envelope` 定義地址、主題、標籤、元資料和 Symfony 訊息回撥。`Content` 接受 `view`（或其 `html` +別名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中宣告的 public 屬性也會暴露給檢視。 ```php namespace App\Mail; @@ -120,14 +120,14 @@ class TestMail extends Mailable } ``` -附件還可透過 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 建立。可重複使用的附件 -物件可以實作 `FriendsOfHyperf\Mail\Contract\Attachable`。 +附件還可透過 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 建立。可複用的附件 +物件可以實現 `FriendsOfHyperf\Mail\Contract\Attachable`。 ## 傳送郵件 -`Mail::mailer()` 選擇已設定的 mailer；省略參數時使用 `mail.default`。`to()`、`cc()` 和 `bcc()` -傳回待傳送郵件物件，其 `send()` 接受 `FriendsOfHyperf\Mail\Contract\Mailable`。傳送成功時傳回 -`SentMessage`；當 `MessageSending` 監聽器中止傳送時傳回 `null`。 +`Mail::mailer()` 選擇已配置的 mailer；省略引數時使用 `mail.default`。`to()`、`cc()` 和 `bcc()` +返回待發送郵件物件，其 `send()` 接受 `FriendsOfHyperf\Mail\Contract\Mailable`。傳送成功時返回 +`SentMessage`；當 `MessageSending` 監聽器中止傳送時返回 `null`。 ```php use App\Mail\TestMail; @@ -139,8 +139,8 @@ Mail::mailer('smtp') ->send(new TestMail('Hyperf')); ``` -對於無需 mailable 類別的郵件，mailer 還提供 `html()`、`raw()`、`plain()`，以及接受檢視名稱或檢視陣列的 -`send()`。回呼會收到 `FriendsOfHyperf\Mail\Message`，其未知方法會轉送給底層 Symfony `Email`。 +對於無需 mailable 類的郵件，mailer 還提供 `html()`、`raw()`、`plain()`，以及接受檢視名或檢視陣列的 +`send()`。回撥會收到 `FriendsOfHyperf\Mail\Message`，其未知方法會轉發給底層 Symfony `Email`。 ```php use FriendsOfHyperf\Mail\Facade\Mail; diff --git a/docs/zh-tw/components/model-factory.md b/docs/zh-tw/components/model-factory.md index 694eb8a76..ad20d2ae1 100644 --- a/docs/zh-tw/components/model-factory.md +++ b/docs/zh-tw/components/model-factory.md @@ -9,10 +9,10 @@ composer require friendsofhyperf/model-factory --dev ``` -此套件要求 PHP `^8.0`、Faker，以及 Hyperf 的 config、database 和 stringable 元件， -沒有宣告選用依賴。 +此包要求 PHP `^8.0`、Faker，以及 Hyperf 的 config、database 和 stringable 元件， +沒有宣告可選依賴。 -發布設定和範例工廠檔案： +釋出配置和示例工廠檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/model-factory @@ -20,7 +20,7 @@ php bin/hyperf.php vendor:publish friendsofhyperf/model-factory 該命令會建立 `config/autoload/model_factory.php` 和 `factories/model_factory.php`。 -## 設定 +## 配置 ```php define(User::class, function (Generator $faker) { }); ``` -可以向 `define()` 傳入第三個參數來定義具名工廠： +可以向 `define()` 傳入第三個引數來定義命名工廠： ```php $factory->define(User::class, function (Generator $faker) { @@ -81,20 +81,20 @@ factory(User::class, 'admin')->create(); factory(User::class, 'admin', 5)->create(); ``` -輔助函式接收模型類別，之後可以傳入數量，或傳入具名工廠及選用數量。 -第二個參數為字串時，它會選擇具名工廠，而不是套用工廠狀態。 -應在傳回的建構器上套用已註冊的狀態： +輔助函式接收模型類，之後可以傳入數量，或傳入命名工廠及可選數量。 +第二個引數為字串時，它會選擇命名工廠，而不是應用工廠狀態。 +應在返回的構建器上應用已註冊的狀態： ```php factory(User::class)->state('suspended')->create(); ``` -輔助函式傳回 `Hyperf\Database\Model\FactoryBuilder`。常用的終止方法包括： +輔助函式返回 `Hyperf\Database\Model\FactoryBuilder`。常用的終止方法包括： -- `make()`：建構模型但不持久化。 -- `create()`：建構並持久化模型。 -- `raw()`：傳回產生的屬性陣列。 +- `make()`：構建模型但不持久化。 +- `create()`：構建並持久化模型。 +- `raw()`：返回生成的屬性陣列。 -未指定數量時，這些方法傳回單一結果；指定數量時，傳回模型集合或原始屬性陣列清單。 -傳給這些方法的屬性陣列會覆寫產生的值。如果應用程式容器不可用， -`factory()` 傳回 `null`。 +未指定數量時，這些方法返回單個結果；指定數量時，返回模型集合或原始屬性陣列列表。 +傳給這些方法的屬性陣列會覆蓋生成的值。如果應用容器不可用， +`factory()` 返回 `null`。 diff --git a/docs/zh-tw/components/model-hashids.md b/docs/zh-tw/components/model-hashids.md index 8f0a8e59f..90fc0655d 100644 --- a/docs/zh-tw/components/model-hashids.md +++ b/docs/zh-tw/components/model-hashids.md @@ -1,6 +1,6 @@ # Model Hashids -Model Hashids 按需編碼和解碼模型主鍵。hashid 不會儲存到資料庫中，因此查詢仍然使用模型的主鍵欄位。 +Model Hashids 按需編碼和解碼模型主鍵。hashid 不會儲存到資料庫中，因此查詢仍然使用模型的主鍵列。 ## 安裝 @@ -9,7 +9,7 @@ composer require friendsofhyperf/model-hashids ``` 此元件依賴 `hashids/hashids`，以及 Hyperf 3.2 的 config、database 和 stringable 元件。僅在需要 -自訂 hashid 設定時發布設定檔： +自定義 hashid 設定時釋出配置檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/model-hashids @@ -33,7 +33,7 @@ class Item extends Model ## 配置 -發布後的檔案為 `config/autoload/hashids.php`。`default` 用於選擇連線，每個連線可設定 `salt`、 +釋出後的檔案為 `config/autoload/hashids.php`。`default` 用於選擇連線，每個連線可設定 `salt`、 `length` 和 `alphabet`： ```php @@ -49,7 +49,7 @@ return [ ]; ``` -未發布設定時，元件使用 `main` 連線、空 salt、最小長度 `0` 和上面顯示的字元表。 +未釋出配置時，元件使用 `main` 連線、空 salt、最小長度 `0` 和上面顯示的字元表。 如需為某個模型選擇其他連線，請覆寫受保護的 `getHashidsConnection()` 方法： @@ -88,12 +88,12 @@ Item::findByHashid($hashid); Item::findByHashidOrFail($hashid); ``` -`hashidToId()` 回傳 `hashids/hashids` 解碼出的第一個 ID；請傳入使用相同連線設定產生的有效 +`hashidToId()` 返回 `hashids/hashids` 解碼出的第一個 ID；請傳入使用相同連線設定生成的有效 hashid。 ### 序列化 Hashid -`hashid` 存取器不會自動附加。可將它新增到模型的 `$appends` 屬性： +`hashid` 訪問器不會自動追加。可將它新增到模型的 `$appends` 屬性： ```php class Item extends Model @@ -104,7 +104,7 @@ class Item extends Model } ``` -也可以僅在需要時附加： +也可以僅在需要時追加： ```php return $item->append('hashid')->toJson(); @@ -120,7 +120,7 @@ Route::get('/items/{item}', function (Item $item) { }); ``` -當路由明確指定其他欄位時，解析會交給模型的父類別實作： +當路由明確指定其他欄位時，解析會交給模型的父類實現： ```php Route::get('/items/{item:slug}', function (Item $item) { diff --git a/docs/zh-tw/components/model-morph-addon.md b/docs/zh-tw/components/model-morph-addon.md index 62b20a42b..59f615aa8 100644 --- a/docs/zh-tw/components/model-morph-addon.md +++ b/docs/zh-tw/components/model-morph-addon.md @@ -1,6 +1,6 @@ # Model Morph Addon -Model Morph Addon 允許宣告 `morphTo` 關聯的模型自行解析多型別名，而不必只依賴全域多型映射。 +Model Morph Addon 允許宣告 `morphTo` 關聯的模型自行解析多型別名，而不必只依賴全域性多型對映。 ## 要求 @@ -14,12 +14,12 @@ Model Morph Addon 允許宣告 `morphTo` 關聯的模型自行解析多型別名 composer require friendsofhyperf/model-morph-addon ``` -套件的 `ConfigProvider` 會自動註冊兩個 AOP 切面。它沒有需要發布的設定檔，也沒有選用的整合依賴。 +包的 `ConfigProvider` 會自動註冊兩個 AOP 切面。它沒有需要釋出的配置檔案，也沒有可選的整合依賴。 -## 定義模型局部多型映射 +## 定義模型區域性多型對映 -在宣告 `morphTo()` 的模型上覆寫 `getActualClassNameForMorph()`。每個關聯模型應透過 -`getMorphClass()` 回傳資料庫中儲存的別名。 +在宣告 `morphTo()` 的模型上重寫 `getActualClassNameForMorph()`。每個關聯模型應透過 +`getMorphClass()` 返回資料庫中儲存的別名。 ```php namespace App\Model; @@ -71,11 +71,11 @@ class User extends Model } ``` -解析器應為每個輸入回傳有效的模型類別。未知別名回傳原值，可以保留 Hyperf 的預設回退行為。 +解析器應為每個輸入返回有效的模型類。未知別名返回原值，可以保留 Hyperf 的預設回退行為。 -## 查詢所有多型類型 +## 查詢所有多型型別 -當 `hasMorph()` 接收到萬用字元類型清單 `['*']` 時，元件也會套用模型局部解析器。委派給 +當 `hasMorph()` 接收到萬用字元型別列表 `['*']` 時，元件也會應用模型區域性解析器。委託給 `hasMorph()` 的方法（例如 `whereHasMorph()` 和 `doesntHaveMorph()`）具有相同行為。 ```php @@ -84,12 +84,12 @@ $images = Image::query() ->get(); ``` -對於 `['*']`，Hyperf 會找出模型資料表中儲存的不同且非空多型類型值。元件會先透過 -`Image::getActualClassNameForMorph()` 解析每個值，再由 Hyperf 建立關聯查詢。 +對於 `['*']`，Hyperf 會發現模型表中儲存的不同且非空的多型型別值。元件會先透過 +`Image::getActualClassNameForMorph()` 解析每個值，再由 Hyperf 構建關聯查詢。 ## 行為 -- 載入 `Image::imageable` 關聯時，會透過 `Image::getActualClassNameForMorph()` 解析其儲存類型。 +- 載入 `Image::imageable` 關聯時，會透過 `Image::getActualClassNameForMorph()` 解析其儲存型別。 - 多型別名屬於宣告 `morphTo()` 的模型；不同模型可以用不同方式解析同一別名。 -- 傳給多型查詢方法的明確類型清單維持 Hyperf 的預設行為。查詢切面只改變完全符合的萬用字元清單 +- 傳給多型查詢方法的顯式型別列表保持 Hyperf 的預設行為。查詢切面只改變完全匹配的萬用字元列表 `['*']`。 diff --git a/docs/zh-tw/components/model-observer.md b/docs/zh-tw/components/model-observer.md index ab2556061..5a33e0eeb 100644 --- a/docs/zh-tw/components/model-observer.md +++ b/docs/zh-tw/components/model-observer.md @@ -1,6 +1,6 @@ # Model Observer -Model Observer 元件用於註冊處理 Hyperf 模型事件的類別。觀察者可以在觀察者類別上繫結，也可以在模型類別上繫結。 +Model Observer 元件用於註冊處理 Hyperf 模型事件的類。觀察者可以在觀察者類上繫結，也可以在模型類上繫結。 ## 安裝 @@ -14,9 +14,9 @@ composer require friendsofhyperf/model-observer composer require hyperf/database ``` -## 產生觀察者 +## 生成觀察者 -向 `gen:observer` 傳入模型類別，可在預設的 `App\Observer` 命名空間中產生觀察者： +向 `gen:observer` 傳入模型類，可在預設的 `App\Observer` 名稱空間中生成觀察者： ```shell php bin/hyperf.php gen:observer UserObserver --model="App\\Model\\User" @@ -31,11 +31,11 @@ php bin/hyperf.php gen:observer UserObserver \ --force ``` -- `--model`、`-M`：用於產生屬性和方法簽章的模型類別。 -- `--namespace`、`-N`：產生的觀察者命名空間。 -- `--force`、`-f`：覆寫已存在的觀察者檔案。 +- `--model`、`-M`：用於生成屬性和方法簽名的模型類。 +- `--namespace`、`-N`：生成的觀察者名稱空間。 +- `--force`、`-f`：覆蓋已存在的觀察者檔案。 -可以在 `config/autoload/devtool.php` 中修改預設命名空間或範本： +可以在 `config/autoload/devtool.php` 中修改預設名稱空間或模板： ```php return [ @@ -50,7 +50,7 @@ return [ ## 從觀察者繫結 -在觀察者類別上使用 `#[Observer]`。`model` 參數接受一個模型類別或模型類別陣列： +在觀察者類上使用 `#[Observer]`。`model` 引數接受一個模型類或模型類陣列： ```php namespace App\Observer; @@ -104,7 +104,7 @@ class AuditObserver ## 從模型繫結 -使用 `#[ObservedBy]` 在模型上宣告觀察者。它的 `classes` 參數接受一個觀察者類別或觀察者類別陣列， +使用 `#[ObservedBy]` 在模型上宣告觀察者。它的 `classes` 引數接受一個觀察者類或觀察者類陣列， 並且該屬性可以重複宣告： ```php @@ -122,11 +122,11 @@ class User extends Model } ``` -來自 `#[Observer]` 和 `#[ObservedBy]` 的繫結會合併。同一模型的重複觀察者類別只會呼叫一次。 +來自 `#[Observer]` 和 `#[ObservedBy]` 的繫結會合並。同一模型的重複觀察者類只會呼叫一次。 ## 在協程中執行觀察者 -如果觀察者上所有可呼叫的事件方法都應在新協程中執行，請實作 `ShouldCoroutine`： +如果觀察者上所有可呼叫的事件方法都應在新協程中執行，請實現 `ShouldCoroutine`： ```php namespace App\Observer; @@ -149,7 +149,7 @@ class UserObserver implements ShouldCoroutine ## 支援的事件 -觀察者只需定義需要的方法。每個可呼叫方法都會接收模型實例： +觀察者只需定義需要的方法。每個可呼叫方法都會接收模型例項： - `booting` - `booted` @@ -166,4 +166,4 @@ class UserObserver implements ShouldCoroutine - `deleted` - `forceDeleted` -元件透過 Hyperf 事件分發這些方法。觀察者方法的回傳值會被忽略，不能用於取消模型操作。 +元件透過 Hyperf 事件分發這些方法。觀察者方法的返回值會被忽略，不能用於取消模型操作。 diff --git a/docs/zh-tw/components/model-scope.md b/docs/zh-tw/components/model-scope.md index b38222414..a7cd41100 100644 --- a/docs/zh-tw/components/model-scope.md +++ b/docs/zh-tw/components/model-scope.md @@ -1,6 +1,6 @@ # Model Scope -Model Scope 元件透過可重複使用的 `#[ScopedBy]` 註解註冊 Hyperf 模型全域 +Model Scope 元件透過可重複使用的 `#[ScopedBy]` 註解註冊 Hyperf 模型全域性 Scope。 ## 使用要求 @@ -15,11 +15,11 @@ Scope。 composer require friendsofhyperf/model-scope ``` -元件的 `ConfigProvider` 會自動註冊 Scope 監聽器，無需發布設定檔。 +元件的 `ConfigProvider` 會自動註冊 Scope 監聽器，無需釋出配置檔案。 ## 定義 Scope -每個 Scope 都必須實作 `Hyperf\Database\Model\Scope`。 +每個 Scope 都必須實現 `Hyperf\Database\Model\Scope`。 ```php namespace App\Model\Scope; @@ -39,8 +39,7 @@ class AncientScope implements Scope ## 將 Scope 繫結到模型 -在模型類別上加入 `#[ScopedBy]`。應用程式啟動時，該 Scope 會被註冊為全域 -Scope。 +在模型類上新增 `#[ScopedBy]`。應用啟動時，該 Scope 會被註冊為全域性 Scope。 ```php namespace App\Model; @@ -57,9 +56,9 @@ class User extends Model ## 註冊多個 Scope -`classes` 參數可以接收單一 Scope 類別或 Scope 類別陣列，該註解也可以重複 -使用。`priority` 預設為 `0`；優先順序越高的 Scope 越先註冊。同一個註解中 -傳入的所有類別共用一個優先順序。 +`classes` 引數可以接收單個 Scope 類或 Scope 類陣列，該註解也可以重複使用。 +`priority` 預設為 `0`；優先順序越高的 Scope 越先註冊。同一個註解中傳入的所有 +類共用一個優先順序。 ```php namespace App\Model; @@ -79,12 +78,12 @@ class User extends Model ## 註冊行為 -觸發 `BootApplication` 時，元件會讀取所有帶有 `#[ScopedBy]` 註解的模型類別。 -對於每個宣告的 Scope 類別，元件會： +觸發 `BootApplication` 時，元件會讀取所有帶有 `#[ScopedBy]` 註解的模型類。 +對於每個宣告的 Scope 類，元件會： -1. 驗證類別存在並實作 `Hyperf\Database\Model\Scope`； -2. 檢查容器中是否存在該類別； -3. 從容器解析實例，並將其傳給 `Model::addGlobalScope()`。 +1. 驗證類存在並實現 `Hyperf\Database\Model\Scope`； +2. 檢查容器中是否存在該類； +3. 從容器解析例項，並將其傳給 `Model::addGlobalScope()`。 -未通過任一檢查的 Scope 項目會被略過。Scope 建構函式可以使用容器能夠解析的 +未透過任一檢查的 Scope 條目會被跳過。Scope 建構函式可以使用容器能夠解析的 依賴。相同優先順序的 Scope 之間不保證註冊順序。 diff --git a/docs/zh-tw/components/mysql-grammar-addon.md b/docs/zh-tw/components/mysql-grammar-addon.md index 34cccd682..7de24d4b0 100644 --- a/docs/zh-tw/components/mysql-grammar-addon.md +++ b/docs/zh-tw/components/mysql-grammar-addon.md @@ -1,6 +1,6 @@ # MySQL Grammar Addon -此元件用於避免 Hyperf 讀取 MySQL 資料表結構中繼資料時，非 ASCII 欄位註解出現亂碼。 +該元件用於避免 Hyperf 讀取 MySQL 表結構元資料時，非 ASCII 欄位註釋出現亂碼。 ## 安裝 @@ -8,28 +8,28 @@ composer require friendsofhyperf/mysql-grammar-addon --dev ``` -此套件要求 `hyperf/database` 和 `hyperf/di` 的版本為 `~3.2.0`，且未宣告選用依賴。Hyperf -套件自動探索會自動註冊此元件的切面，無需額外設定。 +該包要求 `hyperf/database` 和 `hyperf/di` 的版本為 `~3.2.0`，且未宣告可選依賴。Hyperf 包 +自動發現會自動註冊該元件的切面，無需額外配置。 ## 行為 -此切面會攔截以下 MySQL 資料表結構語法方法： +該切面會攔截以下 MySQL 表結構語法方法： - `Hyperf\Database\Schema\Grammars\MySqlGrammar::compileColumnListing()` - `Hyperf\Database\Schema\Grammars\MySqlGrammar::compileColumns()` -它會修改產生的中繼資料查詢，以二進位形式讀取欄位註解： +它會修改生成的元資料查詢，以二進位制形式讀取欄位註釋： ```sql binary `column_comment` ``` -如此一來，讀取 MySQL 資料表結構中繼資料的程式碼可以保留註解的原始位元組。此元件不會新增查詢 -建構器方法，也沒有需要應用程式碼呼叫的公開 API。 +這樣，讀取 MySQL 表結構元資料的程式碼可以保留註釋的原始位元組。該元件不會新增查詢構造器方法， +也沒有需要應用程式碼呼叫的公開 API。 -## 範例 +## 示例 -安裝此元件之前，產生的模型註解可能包含亂碼： +安裝該元件之前，生成的模型註解可能包含亂碼： ```php /** @@ -38,11 +38,11 @@ binary `column_comment` */ ``` -安裝此元件之後，可以保留原始註解： +安裝該元件之後，可以保留原始註釋： ```php /** - * @property int $user_id 用户id - * @property string $event_name 事件名称 + * @property int $user_id 使用者id + * @property string $event_name 事件名稱 */ ``` diff --git a/docs/zh-tw/components/notification-easysms.md b/docs/zh-tw/components/notification-easysms.md index 60736d980..8c20bf9f9 100644 --- a/docs/zh-tw/components/notification-easysms.md +++ b/docs/zh-tw/components/notification-easysms.md @@ -10,23 +10,23 @@ composer require friendsofhyperf/notification-easysms 元件依賴 `friendsofhyperf/notification` 和 `overtrue/easy-sms:^3.0`，Composer 會自動安裝。 -## 設定 +## 配置 -發佈 `config/autoload/easy_sms.php`，然後參照 EasySms 文件設定預設策略、預設閘道和閘道憑證： +釋出 `config/autoload/easy_sms.php`，然後參照 EasySms 文件配置預設策略、預設閘道器和閘道器憑據： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/notification-easysms ``` -元件會使用完整的 `easy_sms` 設定陣列建立 `EasySms` 實例。 +元件會使用完整的 `easy_sms` 配置陣列建立 `EasySms` 例項。 ## 使用 -應用程式啟動時，元件會以 `easy-sms` 通道名稱註冊 `EasySmsChannel`。 +應用啟動時，元件會以 `easy-sms` 通道名註冊 `EasySmsChannel`。 ### 定義通知路由 -在接收者中使用 `Notifiable` trait，並定義 `routeNotificationForSms()`。此方法應回傳電話號碼字串。 +在接收者中使用 `Notifiable` trait，並定義 `routeNotificationForSms()`。該方法應返回手機號碼字串。 ```php mail; diff --git a/docs/zh-tw/components/oauth2-server.md b/docs/zh-tw/components/oauth2-server.md index 2d28f4ad8..530190041 100644 --- a/docs/zh-tw/components/oauth2-server.md +++ b/docs/zh-tw/components/oauth2-server.md @@ -1,6 +1,6 @@ # OAuth2 Server -使用 `league/oauth2-server` 為 Hyperf 建立 OAuth 2.0 授權伺服器。 +使用 `league/oauth2-server` 為 Hyperf 構建 OAuth 2.0 授權伺服器。 ## 安裝 @@ -10,29 +10,29 @@ php bin/hyperf.php vendor:publish friendsofhyperf/oauth2-server php bin/hyperf.php migrate ``` -發佈命令會建立 `config/autoload/oauth2-server.php`。在該檔案中設定私鑰、公鑰、加密金鑰、 -權杖有效期、啟用的授權類型和 scopes。 +釋出命令會建立 `config/autoload/oauth2-server.php`。在該檔案中配置私鑰、公鑰、加密金鑰、 +令牌有效期、啟用的授權型別和 scopes。 -設定私鑰和公鑰路徑後產生金鑰對： +配置私鑰和公鑰路徑後生成金鑰對： ```shell php bin/hyperf.php oauth2-server:generate-keypair ``` -## 設定 +## 配置 -常用設定項包括： +常用配置項包括： -| 設定項 | 說明 | +| 配置項 | 說明 | | --- | --- | -| `authorization_server.private_key` | 用於簽發權杖的私鑰路徑。 | +| `authorization_server.private_key` | 用於簽發令牌的私鑰路徑。 | | `authorization_server.private_key_passphrase` | 可選的私鑰密碼。 | | `authorization_server.encryption_key` | 授權伺服器使用的加密金鑰。 | | `authorization_server.encryption_key_type` | `plain` 或其他支援的 `EncryptionKeyType`。 | | `authorization_server.access_token_ttl` | Access token 有效期，型別為 `DateInterval`。 | | `authorization_server.refresh_token_ttl` | Refresh token 有效期，型別為 `DateInterval`。 | | `authorization_server.persist_access_token` | 是否持久化已簽發的 access token。 | -| `resource_server.public_key` | 用於驗證權杖的公鑰路徑。 | +| `resource_server.public_key` | 用於驗證令牌的公鑰路徑。 | | `resource_server.jwt_leeway` | 可選的 JWT 時鐘偏移寬限時間。 | | `scopes.available` | 允許請求的 scopes。 | | `scopes.default` | 未請求 scope 時預設分配的 scopes。 | @@ -42,13 +42,13 @@ php bin/hyperf.php oauth2-server:generate-keypair | 命令 | 說明 | | --- | --- | | `oauth2-server:clear-expired-tokens` | 清理過期的 access token 和 refresh token。 | -| `oauth2-server:create-client` | 建立 OAuth2 用戶端。 | -| `oauth2-server:delete-client` | 刪除 OAuth2 用戶端。 | -| `oauth2-server:generate-keypair` | 產生私鑰/公鑰金鑰對。 | -| `oauth2-server:list-clients` | 列出 OAuth2 用戶端。 | -| `oauth2-server:update-client` | 更新 OAuth2 用戶端。 | +| `oauth2-server:create-client` | 建立 OAuth2 客戶端。 | +| `oauth2-server:delete-client` | 刪除 OAuth2 客戶端。 | +| `oauth2-server:generate-keypair` | 生成私鑰/公鑰金鑰對。 | +| `oauth2-server:list-clients` | 列出 OAuth2 客戶端。 | +| `oauth2-server:update-client` | 更新 OAuth2 客戶端。 | -按應用需要建立用戶端： +按應用需要建立客戶端： ```shell php bin/hyperf.php oauth2-server:create-client "My App" \ @@ -94,5 +94,5 @@ Router::addGroup('/api', function () { ]); ``` -如果需要直接驗證請求，可以透過 `ResourceServerFactory` 建立 resource server 並呼叫 +如果需要直接驗證請求，可以透過 `ResourceServerFactory` 構建 resource server 並呼叫 `validateAuthenticatedRequest()`。 diff --git a/docs/zh-tw/components/openai-client.md b/docs/zh-tw/components/openai-client.md index 94fca1f59..22f7bba63 100644 --- a/docs/zh-tw/components/openai-client.md +++ b/docs/zh-tw/components/openai-client.md @@ -1,12 +1,12 @@ # OpenAI Client -此元件將 [openai-php/client](https://github.com/openai-php/client) 整合至 Hyperf， -向依賴注入容器註冊上游用戶端，並提供靜態門面。 +此元件將 [openai-php/client](https://github.com/openai-php/client) 整合到 Hyperf， +向依賴注入容器註冊上游客戶端，並提供靜態門面。 -## 相依需求 +## 依賴要求 -此套件適用於 Hyperf 3.2，相依於 `hyperf/config`、`hyperf/di`、`hyperf/guzzle` 和 -0.10.0 或更新版本的 `openai-php/client`，且未宣告選用相依套件。 +此包面向 Hyperf 3.2，依賴 `hyperf/config`、`hyperf/di`、`hyperf/guzzle` 和 0.10.0 或更高版本的 +`openai-php/client`，未宣告可選依賴。 ## 安裝 @@ -14,17 +14,17 @@ composer require friendsofhyperf/openai-client ``` -發布設定檔： +釋出配置檔案： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/openai-client ``` -此指令會建立 `config/autoload/openai.php`。 +此命令會建立 `config/autoload/openai.php`。 -## 設定 +## 配置 -發布的設定檔會讀取以下環境變數： +釋出的配置檔案會讀取以下環境變數： ```env OPENAI_BASE_URI=api.openai.com/v1 @@ -33,31 +33,31 @@ OPENAI_ORGANIZATION= OPENAI_REQUEST_TIMEOUT=30 ``` -| 設定項目 | 預設值 | 說明 | +| 配置項 | 預設值 | 說明 | | --- | --- | --- | -| `openai.base_uri` | `api.openai.com/v1` | 傳給上游用戶端工廠的基礎 URI。 | -| `openai.api_key` | 空字串 | 用於 Bearer 驗證的 API 金鑰。 | -| `openai.organization` | `null` | 選用的 OpenAI 組織識別碼。 | -| `openai.request_timeout` | `30` | 傳給 Hyperf Guzzle 用戶端的逾時時間，單位為秒。 | +| `openai.base_uri` | `api.openai.com/v1` | 傳給上游客戶端工廠的基礎 URI。 | +| `openai.api_key` | 空字串 | 用於 Bearer 身份驗證的 API 金鑰。 | +| `openai.organization` | `null` | 可選的 OpenAI 組織標識。 | +| `openai.request_timeout` | `30` | 傳給 Hyperf Guzzle 客戶端的超時時間，單位為秒。 | -## 容器綁定與執行行為 +## 容器繫結與執行行為 -元件會將 `OpenAI\Client` 和 `OpenAI\Contracts\ClientContract` 綁定至同一個 -用戶端實例。工廠會： +元件會將 `OpenAI\Client` 和 `OpenAI\Contracts\ClientContract` 繫結到同一個 +客戶端例項。工廠會： -- 透過 `Hyperf\Guzzle\ClientFactory` 建立 HTTP 用戶端； -- 套用設定的基礎 URI、API 金鑰、組織和請求逾時時間； -- 傳送 `OpenAI-Beta: assistants=v2` 請求標頭。 +- 透過 `Hyperf\Guzzle\ClientFactory` 建立 HTTP 客戶端； +- 應用配置的基礎 URI、API 金鑰、組織和請求超時時間； +- 傳送 `OpenAI-Beta: assistants=v2` 請求頭。 -API 金鑰必須是字串，組織必須是 `null` 或字串。型別不正確時會擲出 +API 金鑰必須是字串，組織必須是 `null` 或字串。型別不正確時會丟擲 `FriendsOfHyperf\OpenAi\Exception\ApiKeyIsMissing`。空 API 金鑰仍是字串，因此不會 -觸發此例外；API 請求會改為因驗證失敗而報錯。 +觸發此異常；API 請求會改為因身份驗證失敗而報錯。 -## 使用方式 +## 使用 ### 容器 -可以從容器解析契約或具體用戶端。資源方法、請求參數和回應物件由已安裝的 +可以從容器解析契約或具體客戶端。資源方法、請求引數和響應物件由已安裝的 `openai-php/client` 版本提供。 ```php @@ -75,7 +75,7 @@ echo $response->choices[0]->message->content; ### 門面 -`FriendsOfHyperf\OpenAi\Facade\OpenAI` 會將靜態呼叫轉發給容器綁定的 `ClientContract`。 +`FriendsOfHyperf\OpenAi\Facade\OpenAI` 會將靜態呼叫轉發給容器繫結的 `ClientContract`。 ```php use FriendsOfHyperf\OpenAi\Facade\OpenAI; @@ -83,11 +83,11 @@ use FriendsOfHyperf\OpenAi\Facade\OpenAI; $models = OpenAI::models()->list(); ``` -## Azure 與自訂用戶端 +## Azure 與自定義客戶端 -元件工廠會固定設定 Bearer 驗證，且未提供自訂請求標頭或查詢參數的設定。 -Azure OpenAI 等需要 `api-key` 請求標頭和 `api-version` 查詢參數的服務，必須使用 -上游工廠手動建立用戶端： +元件工廠始終配置 Bearer 身份驗證，且未提供自定義請求頭或查詢引數的配置。 +Azure OpenAI 等需要 `api-key` 請求頭和 `api-version` 查詢引數的服務，必須使用 +上游工廠手動建立客戶端： ```php use OpenAI; @@ -99,10 +99,10 @@ $client = OpenAI::factory() ->make(); ``` -手動建立的用戶端不會自動註冊至 Hyperf 容器。由於 Azure 基礎 URI 已包含部署， -因此針對該部署的呼叫不需傳入 `model` 參數。 +手動建立的客戶端不會自動註冊到 Hyperf 容器。由於 Azure 基礎 URI 已包含部署， +因此針對該部署的呼叫無需傳入 `model` 引數。 ## 上游 API 指南 -有關支援的資源和使用範例，請參閱與已安裝版本相符的 +有關支援的資源和使用示例，請參閱與已安裝版本匹配的 [openai-php/client 文件](https://github.com/openai-php/client)。 diff --git a/docs/zh-tw/components/recaptcha.md b/docs/zh-tw/components/recaptcha.md index f643a677a..329b5f52a 100644 --- a/docs/zh-tw/components/recaptcha.md +++ b/docs/zh-tw/components/recaptcha.md @@ -8,17 +8,17 @@ composer require friendsofhyperf/recaptcha ``` -## 設定 +## 配置 -使用中介軟體或驗證規則前，先發佈 `config/autoload/recaptcha.php`： +使用中介軟體或驗證規則前，先發布 `config/autoload/recaptcha.php`： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/recaptcha ``` -透過 `RECAPTCHA_SECRET_V2_KEY` 設定 reCAPTCHA v2 金鑰，透過 `RECAPTCHA_SECRET_V3_KEY` -設定 reCAPTCHA v3 金鑰，也可以直接修改發佈檔案中的 `v2.secret_key` 與 `v3.secret_key`。 -`default` 用於選擇未明確傳入版本時使用的版本。 +透過 `RECAPTCHA_SECRET_V2_KEY` 配置 reCAPTCHA v2 金鑰，透過 `RECAPTCHA_SECRET_V3_KEY` +配置 reCAPTCHA v3 金鑰，也可以直接修改釋出檔案中的 `v2.secret_key` 與 `v3.secret_key`。 +`default` 用於選擇未顯式傳入版本時使用的版本。 ## 使用 diff --git a/docs/zh-tw/components/sentry.md b/docs/zh-tw/components/sentry.md index dfd61139c..a9f3b9221 100644 --- a/docs/zh-tw/components/sentry.md +++ b/docs/zh-tw/components/sentry.md @@ -1,7 +1,7 @@ # Sentry Hyperf 的 Sentry 元件。它將 Sentry PHP SDK 接入 Hyperf 應用生命週期、日誌、 -鏈路追蹤、指標、排程任務和協程友善的傳輸層。 +鏈路追蹤、指標、定時任務和協程友好的傳輸層。 ## 安裝 @@ -9,7 +9,7 @@ Hyperf 的 Sentry 元件。它將 Sentry PHP SDK 接入 Hyperf 應用生命週 composer require friendsofhyperf/sentry ``` -可選整合需要安裝對應的 Hyperf 或用戶端套件，例如 `hyperf/amqp`、`hyperf/crontab`、 +可選整合需要安裝對應的 Hyperf 或客戶端包，例如 `hyperf/amqp`、`hyperf/crontab`、 `hyperf/database`、`hyperf/rpc-multiplex`、`elasticsearch/elasticsearch`、 `phpmyadmin/sql-parser` 或 `hyperf/engine`。 @@ -19,7 +19,7 @@ composer require friendsofhyperf/sentry php bin/hyperf.php vendor:publish friendsofhyperf/sentry ``` -該命令會釋出 `config/autoload/sentry.php`。核心配置如下： +該命令會發布 `config/autoload/sentry.php`。核心配置如下： ```php setMaxAttempts(3); ``` -閉包支援相依性注入。待派送物件會在銷毀時派送工作。 +閉包支援依賴注入。待派發物件會在銷燬時派發任務。 ### AMQP 與 Kafka @@ -48,9 +48,9 @@ dispatch($amqpMessage) dispatch($kafkaMessage)->onPool('default'); ``` -### 條件設定 +### 條件配置 -所有待派送物件都支援 `when()` 和 `unless()`： +所有待派發物件都支援 `when()` 和 `unless()`： ```php dispatch($job) @@ -58,9 +58,9 @@ dispatch($job) ->unless($canRunNow, fn ($pending) => $pending->delay(60)); ``` -## 閉包工作 +## 閉包任務 -需要將閉包工作傳遞給其他 API 時，可以直接建立可序列化的非同步佇列工作： +需要將閉包任務傳遞給其他 API 時，可以直接建立可序列化的非同步佇列任務： ```php use FriendsOfHyperf\Support\CallQueuedClosure; @@ -73,7 +73,7 @@ $job->setMaxAttempts(3); ## 退避策略 -退避策略實作會回傳下一次等待的毫秒數，並提供 `next()`、`reset()`、`getAttempt()` 和 +退避策略實現會返回下一次等待的毫秒數，並提供 `next()`、`reset()`、`getAttempt()` 和 `sleep()` 方法。 ### 陣列退避 @@ -86,21 +86,21 @@ $short = ArrayBackoff::fromPattern('short'); $fromString = ArrayBackoff::fromString('100, 500, 1000'); ``` -如果希望陣列用完後回傳 `0`，而不是重複最後一個值，請將建構函式第二個參數設為 `false`。 +如果希望陣列耗盡後返回 `0`，而不是重複最後一個值，請將建構函式第二個引數設為 `false`。 ### 可用策略 - `FixedBackoff`：固定等待時間。 -- `LinearBackoff`：依固定步長增加等待時間。 -- `ExponentialBackoff`：指數成長，可選用抖動。 -- `FibonacciBackoff`：使用費波那契數列等待時間。 -- `PoissonBackoff`：依泊松分布產生等待時間。 +- `LinearBackoff`：按固定步長增加等待時間。 +- `ExponentialBackoff`：指數增長，可選抖動。 +- `FibonacciBackoff`：使用斐波那契數列等待時間。 +- `PoissonBackoff`：基於泊松分佈生成等待時間。 - `DecorrelatedJitterBackoff`：為分散式重試提供去相關抖動。 -- `ArrayBackoff`：使用呼叫端定義的等待序列。 +- `ArrayBackoff`：使用呼叫方定義的等待序列。 ## 其他工具 此元件還包含 `retry()` 和 `once()` 輔助函式，以及 `ConfigurationUrlParser`、`Env`、 `HtmlString`、`Number`、`Once`、`Sleep`、`Timebox`、`UuidContainer`、`RedisCommand`、 -管線輔助功能和可重用 Trait。在其他元件新增重複工具前，請先檢查 -`FriendsOfHyperf\Support` 下已有的類別。 +管道輔助功能和可複用 Trait。在其他元件新增重複工具前，請先檢查 +`FriendsOfHyperf\Support` 下已有的類。 diff --git a/docs/zh-tw/components/validated-dto.md b/docs/zh-tw/components/validated-dto.md index afa4c3bbf..fd6de32ca 100644 --- a/docs/zh-tw/components/validated-dto.md +++ b/docs/zh-tw/components/validated-dto.md @@ -178,7 +178,7 @@ class CreateUserCommand extends Command ## 匯出 DTO 型別 -使用 `dto:export` 可以將 DTO 類別匯出為 TypeScript。傳入完整 DTO 類別名稱，也可以指定輸出檔案： +使用 `dto:export` 可以將 DTO 類匯出為 TypeScript。傳入完整 DTO 類名，也可以指定輸出檔案： ```shell php bin/hyperf.php dto:export 'App\DTO\UserDTO' diff --git a/docs/zh-tw/faq/about.md b/docs/zh-tw/faq/about.md index ec9779ab4..eea63e97d 100644 --- a/docs/zh-tw/faq/about.md +++ b/docs/zh-tw/faq/about.md @@ -2,19 +2,19 @@ ## FriendsOfHyperf 是什麼？ -FriendsOfHyperf 是維護 Hyperf 可重用元件的社群專案。元件集涵蓋開發工具、資料庫輔助功能、 +FriendsOfHyperf 是維護 Hyperf 可複用元件的社群專案。元件集涵蓋開發工具、資料庫輔助功能、 訊息通訊、資料驗證、監控以及外部服務整合。 -## 儲存庫如何組織？ +## 倉庫如何組織？ -`components` 儲存庫是唯一事實來源。`src/` 下的每個目錄都是可獨立安裝的 Composer 套件， +`components` 倉庫是唯一事實來源。`src/` 下的每個目錄都是可獨立安裝的 Composer 包， 而 `friendsofhyperf/components` 會安裝完整元件集。 -## 元件如何發布？ +## 元件如何釋出？ -發布流程會將 monorepo 拆分為唯讀的獨立元件儲存庫。Issue 和 Pull Request 都應提交到 monorepo。 +釋出流程會將 monorepo 拆分為只讀的獨立元件倉庫。Issue 和 Pull Request 都應提交到 monorepo。 ## 文件如何維護？ -文件站點使用 VitePress，並為四種語言維護路徑一致的頁面。提交文件變更前，請在儲存庫根目錄執行 +文件站點使用 VitePress，併為四種語言維護路徑一致的頁面。提交文件變更前，請在倉庫根目錄執行 `npm run docs:check`。 diff --git a/docs/zh-tw/faq/how-to-use.md b/docs/zh-tw/faq/how-to-use.md index 632ce8e30..0b7460b41 100644 --- a/docs/zh-tw/faq/how-to-use.md +++ b/docs/zh-tw/faq/how-to-use.md @@ -1,6 +1,6 @@ # 如何使用元件 -## 安裝元件套件 +## 安裝元件包 從[元件目錄](../components/index.md)選擇元件，然後使用 Composer 安裝： @@ -8,21 +8,21 @@ composer require friendsofhyperf/cache ``` -## 檢查選用相依套件 +## 檢查可選依賴 -閱讀元件的 `composer.json` 和文件。選用功能可能需要 Composer `suggest` 區段中列出的套件。 +閱讀元件的 `composer.json` 和文件。可選功能可能需要 Composer `suggest` 段中列出的包。 -## 發布設定 +## 釋出配置 -元件提供可發布設定時，請使用文件說明的指令： +元件提供可釋出配置時，請使用文件說明的命令： ```shell php bin/hyperf.php vendor:publish friendsofhyperf/cache ``` -不要直接對所有元件執行此指令，並非每個元件都有可發布設定。 +不要直接對所有元件執行此命令，並非每個元件都有可釋出配置。 ## 驗證整合 -啟動應用程式並實際使用整合功能，同時加入應用程式層級測試。排查問題時，請在 Issue 中提供 -元件版本和 Hyperf 版本。 +啟動應用並實際使用整合功能，同時新增應用級測試。排查問題時，請在 Issue 中提供元件版本和 +Hyperf 版本。 diff --git a/docs/zh-tw/faq/index.md b/docs/zh-tw/faq/index.md index d46a3a88a..8456fae56 100644 --- a/docs/zh-tw/faq/index.md +++ b/docs/zh-tw/faq/index.md @@ -1,34 +1,34 @@ # 常見問題 -## 應該在哪裡回報問題？ +## 應該在哪裡報告問題？ 請在 [components monorepo](https://github.com/friendsofhyperf/components/issues) 提交 Issue， -並提供元件名稱、已安裝版本、最小重現範例和完整例外堆疊。 +並提供元件名稱、已安裝版本、最小復現示例和完整異常堆疊。 -## 應該安裝聚合套件還是單一元件？ +## 應該安裝聚合包還是單個元件？ -明確需要完整元件集時安裝 `friendsofhyperf/components`。大多數應用程式更適合依需求安裝獨立的 -`friendsofhyperf/*` 套件，以減少相依套件並只啟用需要的服務提供者。 +明確需要完整元件集時安裝 `friendsofhyperf/components`。大多數應用更適合按需安裝獨立的 +`friendsofhyperf/*` 包，以減少依賴並只啟用需要的服務提供者。 ## 元件會自動註冊嗎？ -大多數元件提供 Hyperf `ConfigProvider`，並透過元件探索機制自動註冊。需要設定檔或資料庫 -遷移的元件會在對應頁面說明發布指令。 +大多陣列件提供 Hyperf `ConfigProvider`，並透過元件發現機制自動註冊。需要配置檔案或資料庫 +遷移的元件會在對應頁面說明發布命令。 ## 支援哪些版本？ -目前分支要求 PHP 8.2 或更新版本，並適用於 Hyperf 3.2。準確的必要相依套件和建議相依套件請查看 -所選元件的 `composer.json`。 +當前分支要求 PHP 8.2 或更高版本，並面向 Hyperf 3.2。準確的必需依賴和建議依賴請檢視所選 +元件的 `composer.json`。 -## 為什麼範例還需要其他套件？ +## 為什麼示例還需要其他包？ -部分功能會整合 AMQP、Kafka、非同步佇列、Elasticsearch 或外部服務等選用相依套件。Composer 的 -`suggest` 區段和元件文件會標明這些相依套件。 +部分功能會整合 AMQP、Kafka、非同步佇列、Elasticsearch 或外部服務等可選依賴。Composer 的 +`suggest` 段和元件文件會標明這些依賴。 ## 應該向哪裡提交 Pull Request？ 所有 Pull Request 都應提交到 -[components monorepo](https://github.com/friendsofhyperf/components)。獨立元件儲存庫由自動拆分 -產生，不接收貢獻。 +[components monorepo](https://github.com/friendsofhyperf/components)。獨立元件倉庫由自動拆分 +生成，不接收貢獻。 更多資訊請閱讀[關於 FriendsOfHyperf](about.md)和[如何使用元件](how-to-use.md)。 diff --git a/docs/zh-tw/guide/index.md b/docs/zh-tw/guide/index.md index 76f8a36e3..42aa1a8aa 100644 --- a/docs/zh-tw/guide/index.md +++ b/docs/zh-tw/guide/index.md @@ -1,13 +1,13 @@ # 入門 FriendsOfHyperf Components 是一組面向 Hyperf 3.2 的獨立元件，採用 monorepo 統一維護。 -你可以安裝完整元件集，也可以只安裝應用程式需要的單一元件。 +你可以安裝完整元件集，也可以只安裝應用需要的單個元件。 -## 環境需求 +## 環境要求 -- PHP 8.2 或更新版本 +- PHP 8.2 或更高版本 - Hyperf 3.2 -- 依照 Hyperf 應用程式選擇 Swoole 或 Swow +- 根據 Hyperf 應用選擇 Swoole 或 Swow ## 安裝完整元件集 @@ -15,16 +15,16 @@ FriendsOfHyperf Components 是一組面向 Hyperf 3.2 的獨立元件，採用 m composer require friendsofhyperf/components ``` -聚合套件會取代所有獨立元件套件，並註冊其中可用的 `ConfigProvider`。 +聚合包會替代所有獨立元件包，並註冊其中可用的 `ConfigProvider`。 -## 安裝單一元件 +## 安裝單個元件 ```shell composer require friendsofhyperf/cache ``` -將 `cache` 替換為[元件目錄](../components/index.md)中的套件名稱。大多數元件會透過 Hyperf -元件探索機制自動註冊；如果元件提供設定檔，請依照對應元件頁面的說明發布設定。 +將 `cache` 替換為[元件目錄](../components/index.md)中的包名。大多陣列件會透過 Hyperf +元件發現機制自動註冊；如果元件提供配置檔案，請按對應元件頁面的說明發布配置。 ## 選擇元件 @@ -34,11 +34,11 @@ composer require friendsofhyperf/cache - 安全與驗證：Encryption、Purifier、reCAPTCHA、Validated DTO - 通訊與訊息：Mail、Notification、EasySms、AMQP Job、TCP Sender -完整分類請查看[元件目錄](../components/index.md)。 +完整分類請檢視[元件目錄](../components/index.md)。 ## 後續步驟 -1. 開啟元件頁面，確認相依套件與環境需求。 -2. 安裝對應的獨立元件套件。 -3. 在元件要求時發布設定。 -4. 為應用程式中的整合行為加入針對性測試。 +1. 開啟元件頁面，確認依賴和環境要求。 +2. 安裝對應的獨立元件包。 +3. 在元件要求時釋出配置。 +4. 為應用中的整合行為新增有針對性的測試。 diff --git a/docs/zh-tw/guide/introduce/about.md b/docs/zh-tw/guide/introduce/about.md index aded880b6..317eed20c 100644 --- a/docs/zh-tw/guide/introduce/about.md +++ b/docs/zh-tw/guide/introduce/about.md @@ -1,22 +1,22 @@ # 關於 Hyperf Fans -FriendsOfHyperf 是由社群維護的 Hyperf 擴充元件集合，提供面向正式環境的整合能力， +FriendsOfHyperf 是由社群維護的 Hyperf 擴充套件元件集合，提供面向生產環境的整合能力， 並帶來部分受 Laravel 啟發的開發體驗。 -## 儲存庫模式 +## 倉庫模式 原始碼統一維護在 [friendsofhyperf/components](https://github.com/friendsofhyperf/components) monorepo 中。 -`src/` 下的每個目錄也會作為可獨立安裝的 Composer 套件發布。請向 monorepo 提交變更， -不要向自動拆分產生的獨立儲存庫提交。 +`src/` 下的每個目錄也會作為可獨立安裝的 Composer 包釋出。請向 monorepo 提交變更， +不要向自動拆分生成的獨立倉庫提交。 ## 相容性 -目前分支適用於 PHP 8.2 或更新版本以及 Hyperf 3.2。各元件頁面會說明選用整合和額外相依套件。 +當前分支面向 PHP 8.2 或更高版本以及 Hyperf 3.2。各元件頁面會說明可選整合和額外依賴。 ## 文件語言 -文件同時維護英文、簡體中文、香港繁體中文和台灣繁體中文。每次文件變更都必須保持四種語言 +文件同時維護英文、簡體中文、香港繁體中文和臺灣繁體中文。每次文件變更都必須保持四種語言 的頁面路徑與標題結構一致。 ## 參與貢獻 diff --git a/src/tinker/composer.json b/src/tinker/composer.json index 87bfc2a90..1eedc5f4c 100644 --- a/src/tinker/composer.json +++ b/src/tinker/composer.json @@ -32,7 +32,7 @@ "hyperf/stringable": "~3.2.0", "hyperf/support": "~3.2.0", "hyperf/tappable": "~3.2.0", - "psy/psysh": "^0.11.0 || ^0.12.0" + "psy/psysh": "^0.12.0" }, "suggest": { "hyperf/view-engine": "Suggest for using `Hyperf\\ViewEngine\\HtmlString`." diff --git a/src/tinker/src/Command/TinkerCommand.php b/src/tinker/src/Command/TinkerCommand.php index 75a075537..302289d72 100644 --- a/src/tinker/src/Command/TinkerCommand.php +++ b/src/tinker/src/Command/TinkerCommand.php @@ -16,6 +16,7 @@ use Hyperf\Contract\ConfigInterface; use Psr\Container\ContainerInterface; use Psy\Configuration; +use Psy\ManualUpdater\Checker as ManualUpdaterChecker; use Psy\Shell; use Psy\VersionUpdater\Checker; use Symfony\Component\Console\Command\Command as SymfonyCommand; @@ -56,6 +57,7 @@ public function handle() $config = Configuration::fromInput($this->input); $config->setUpdateCheck(Checker::NEVER); + $config->setUpdateManualCheck(ManualUpdaterChecker::NEVER); $config->setUsePcntl((bool) $this->config->get('tinker.usePcntl', false)); $config->getPresenter()->addCasters( $this->getCasters()