diff --git a/docs/en/annotation.md b/docs/en/annotation.md index ab521b46e..cd1b123f8 100644 --- a/docs/en/annotation.md +++ b/docs/en/annotation.md @@ -4,22 +4,13 @@ Annotation is a very powerful feature of Hyperf that can be used to reduce a lot ## Concept -### What is annotation and what is comment? +### What is annotation? -Before interpreting the annotation, we need to define the difference between `annotation` and `comment`: -- Comment: For the programmer to see, help understand the code, explain and explain the code. -- Annotation: For the system or application to see, the definition of metadata. There is no effect when used alone, it needs to be used in conjunction with the application to use its metadata to works. +Attributes offer the ability to add structured, machine-readable metadata information on declarations in code: Classes, methods, functions, parameters, properties and class constants can be the target of an attribute. The metadata defined by attributes can then be inspected at runtime using the Reflection APIs. Attributes could therefore be thought of as a configuration language embedded directly into code. -### How it parse ? +With attributes the generic implementation of a feature and its concrete use in an application can be decoupled. In a way it is comparable to interfaces and their implementations. But where interfaces and implementations are about code, attributes are about annotating extra information and configuration. Interfaces can be implemented by classes, yet attributes can also be declared on methods, functions, parameters, properties and class constants. As such they are more flexible than interfaces. -Hyperf uses the [doctrine/annotations](https://github.com/doctrine/annotations) package to parse the annotations in the code. The annotations must be written in the standard comment block below to be parsed correctly. Other formats cannot correctly parsed. -Example: -```php -/** - * @AnnotationClass() - */ -``` -The syntax of writing `@AnnotationClass()` in the standard comment block indicates that the object (class, class method, class attribute) of the current comment block is annotated, and `AnnotationClass` corresponds to an `annotation class`. The class name of the class can be written in the namespace of the whole class, or just the class name, but the annotation class needs to be in the current class `use` to ensure that the correct annotation class can be found according to the namespace. +A simple example of attribute usage is to convert an interface that has optional methods to use attributes. Lets assume an ActionHandler interface representing an operation in an application, where some implementations of an action handler require setup and others do not. Instead of requiring all classes that implement ActionHandler to implement a method setUp(), an attribute can be used. One benefit of this approach is that we can use the attribute several times. ### How is works ? @@ -30,11 +21,13 @@ We have said that annotations are just metadata definitions that need to work wi In some cases we may wish to ignore certain annotations. For example, when we access some tools that automatically generate documents, many tools use annotations to define the relevant structural content of the document. These annotations may not be in line with how Hyperf is used, we can set the concern to be ignored by `config/autoload/annotations.php`. ```php +use JetBrains\PhpStorm\ArrayShape; + return [ 'scan' => [ // Annotations in the ignore_annotations array will be ignored by the annotation scanner 'ignore_annotations' => [ - 'mixin', + ArrayShape::class, ], ], ]; @@ -46,19 +39,7 @@ There are three apply types of annotation, `class`, `method of class` and `prope ### Use class level annotation -Class level annotation definitions are in the comment block above the `class` keyword. For example, the commonly used `@Controller` and `@AutoController` are examples of the use of class level annotation. The following code example is an example of correctly using class level annotation, indicating The `@ClassAnnotation` annotation is applied to the `Foo` class. - -- PHP < 8.0 - -```php -= 8.0 +Class level annotation definitions are in the comment block above the `class` keyword. For example, the commonly used `Controller` and `AutoController` are examples of the use of class level annotation. The following code example is an example of correctly using class level annotation, indicating The `ClassAnnotation` annotation is applied to the `Foo` class. ```php = 8.0 +Method level annotation definitions are in the comment block above the class method. For example, the commonly used `RequestMapping` is example of the use of method level annotation. The following code example is an example of correctly using method level annotation, indicating The `MethodAnnotation` annotation is applied to the `bar` method of `Foo` class. ```php = 8.0 +Property level annotation definitions are in the comment block above the property. For example, the commonly used `Value` and `Inject` are examples of the use of property level annotation. The following code example is an example of correctly using property level annotation, indicating The `PropertyAnnotation` annotation is applied to the `$bar` property of `Foo` class. ```php Notice that `@Annotation` and `@Target` annotations in Annotation Class are Global Annotation,no need fo `use` keyword to define the namespace. - -`@Target` has the following parameters: -- `METHOD` annotation means allows define on class methods -- `PROPERTY` annotation means allows define on class properties -- `CLASS` annotation means allows define on class -- `ALL` annotation means allows define in all scopes - -- PHP >= 8.0 - ```php [ // ignore_annotations 数组内的注解都会被注解扫描器忽略 'ignore_annotations' => [ - 'mixin', + ArrayShape::class, ], ], ]; @@ -46,19 +39,7 @@ return [ ### 使用类注解 -类注解定义是在 `class` 关键词上方的注释块内,比如常用的 `@Controller` 和 `@AutoController` 就是类注解的使用典范,下面的代码示例则为一个正确使用类注解的示例,表明 `@ClassAnnotation` 注解应用于 `Foo` 类。 - -- PHP 版本低于 8.0 时 - -```php - 注意注解类的 `@Annotation` 和 `@Target` 注解为全局注解,无需 `use` - -其中 `@Target` 有如下参数: -- `METHOD` 注解允许定义在类方法上 -- `PROPERTY` 注解允许定义在类属性上 -- `CLASS` 注解允许定义在类上 -- `ALL` 注解允许定义在任何地方 - -- PHP 版本大于等于 8.0 时 +在任意地方创建注解类,如下代码示例: ```php = 7.4 and <= 8.0 + - PHP >= 8.0 and <= 8.1 - 以下任一网络引擎 - Swoole PHP 扩展 >= 4.5,并关闭了 `Short Name` - Swow PHP 扩展 (Beta) @@ -56,7 +56,7 @@ docker run --name hyperf \ -p 9501:9501 -it \ --privileged -u root \ --entrypoint /bin/sh \ -hyperf/hyperf:7.4-alpine-v3.11-swoole +hyperf/hyperf:8.0-alpine-v3.15-swoole ``` - 将 Composer 镜像设置为阿里云镜像,加速国内下载速度 diff --git a/docs/zh-hk/README.md b/docs/zh-hk/README.md index 6d4210048..55fd9825f 100644 --- a/docs/zh-hk/README.md +++ b/docs/zh-hk/README.md @@ -1,4 +1,4 @@ -# 2.2 介紹 +# 3.0 介紹 Hyperf 是一個高性能、高靈活性的漸進式 PHP 協程框架,內置協程服務器及大量常用的組件,性能較傳統基於 `PHP-FPM` 的框架有質的提升,提供超高性能的同時,也保持着極其靈活的可擴展性,標準組件均基於 [PSR 標準](https://www.php-fig.org/psr) 實現,基於強大的依賴注入設計,保證了絕大部分組件或類都是 `可替換` 與 `可複用` 的。 diff --git a/docs/zh-hk/annotation.md b/docs/zh-hk/annotation.md index d233ef9ee..28faf4bfa 100644 --- a/docs/zh-hk/annotation.md +++ b/docs/zh-hk/annotation.md @@ -4,22 +4,13 @@ ## 概念 -### 什麼是註解什麼是註釋? +### 什麼是註解? -在解釋註解之前我們需要先定義一下 `註解` 與 `註釋` 的區別: -- 註釋:給程序員看,幫助理解代碼,對代碼起到解釋、説明的作用。 -- 註解:給應用程序看,用於元數據的定義,單獨使用時沒有任何作用,需配合應用程序對其元數據進行利用才有作用。 +註解功能提供了代碼中的聲明部分都可以添加結構化、機器可讀的元數據的能力, 註解的目標可以是類、方法、函數、參數、屬性、類常量。 通過 反射 API 可在運行時獲取註解所定義的元數據。 因此註解可以成為直接嵌入代碼的配置式語言。 -### 註釋型註解解析如何實現? +通過註解的使用,在應用中實現功能、使用功能可以相互解耦。 某種程度上講,它可以和接口(interface)與其實現(implementation)相比較。 但接口與實現是代碼相關的,註解則與聲明額外信息和配置相關。 接口可以通過類來實現,而註解也可以聲明到方法、函數、參數、屬性、類常量中。 因此它們比接口更靈活。 -Hyperf 使用了 [doctrine/annotations](https://github.com/doctrine/annotations) 包來對代碼內的註解進行解析,註解必須寫在下面示例的標準註釋塊才能被正確解析,其它格式均不能被正確解析。 -註釋塊示例: -```php -/** - * @AnnotationClass() - */ -``` -在標準註釋塊內通過書寫 `@AnnotationClass()` 這樣的語法即表明對當前註釋塊所在位置的對象(類、類方法、類屬性)進行了註解的定義, `AnnotationClass` 對應的是一個 `註解類` 的類名,可寫全類的命名空間,亦可只寫類名,但需要在當前類 `use` 該註解類以確保能夠根據命名空間找到正確的註解類。 +註解使用的一個簡單例子:將接口(interface)的可選方法改用註解實現。 我們假設接口 ActionHandler 代表了應用的一個操作: 部分 action handler 的實現需要 setup,部分不需要。 我們可以使用註解,而不用要求所有類必須實現 ActionHandler 接口並實現 setUp() 方法。 因此帶來一個好處——可以多次使用註解。 ### 註解是如何發揮作用的? @@ -30,11 +21,13 @@ Hyperf 使用了 [doctrine/annotations](https://github.com/doctrine/annotations) 在一些情況下我們可能希望忽略某些 註解,比如我們在接入一些自動生成文檔的工具時,有不少工具都是通過註解的形式去定義文檔的相關結構內容的,而這些註解可能並不符合 Hyperf 的使用方式,我們可以通過在 `config/autoload/annotations.php` 內將相關注解設置為忽略。 ```php +use JetBrains\PhpStorm\ArrayShape; + return [ 'scan' => [ // ignore_annotations 數組內的註解都會被註解掃描器忽略 'ignore_annotations' => [ - 'mixin', + ArrayShape::class, ], ], ]; @@ -46,19 +39,7 @@ return [ ### 使用類註解 -類註解定義是在 `class` 關鍵詞上方的註釋塊內,比如常用的 `@Controller` 和 `@AutoController` 就是類註解的使用典範,下面的代碼示例則為一個正確使用類註解的示例,表明 `@ClassAnnotation` 註解應用於 `Foo` 類。 - -- PHP 版本低於 8.0 時 - -```php - 注意註解類的 `@Annotation` 和 `@Target` 註解為全局註解,無需 `use` - -其中 `@Target` 有如下參數: -- `METHOD` 註解允許定義在類方法上 -- `PROPERTY` 註解允許定義在類屬性上 -- `CLASS` 註解允許定義在類上 -- `ALL` 註解允許定義在任何地方 - -- PHP 版本大於等於 8.0 時 +在任意地方創建註解類,如下代碼示例: ```php = 7.4 and <= 8.0 + - PHP >= 8.0 and <= 8.1 - 以下任一網絡引擎 - Swoole PHP 擴展 >= 4.5,並關閉了 `Short Name` - Swow PHP 擴展 (Beta) @@ -56,7 +56,7 @@ docker run --name hyperf \ -p 9501:9501 -it \ --privileged -u root \ --entrypoint /bin/sh \ -hyperf/hyperf:7.4-alpine-v3.11-swoole +hyperf/hyperf:8.0-alpine-v3.15-swoole ``` - 將 Composer 鏡像設置為阿里雲鏡像,加速國內下載速度 diff --git a/docs/zh-hk/validation.md b/docs/zh-hk/validation.md index de2996fca..7e314eaa5 100644 --- a/docs/zh-hk/validation.md +++ b/docs/zh-hk/validation.md @@ -64,7 +64,7 @@ php bin/hyperf.php vendor:publish hyperf/validation 執行上面的命令會將驗證器的語言文件 `validation.php` 發佈到對應的語言文件目錄,`en` 指英文語言文件,`zh_CN` 指中文簡體的語言文件,您可以按照實際需要對 `validation.php` 文件內容進行修改和自定義。 -``` +```shell /storage /languages /en diff --git a/docs/zh-tw/README.md b/docs/zh-tw/README.md index 2f1374c9b..50201822a 100644 --- a/docs/zh-tw/README.md +++ b/docs/zh-tw/README.md @@ -1,4 +1,4 @@ -# 2.2 介紹 +# 3.0 介紹 Hyperf 是一個高效能、高靈活性的漸進式 PHP 協程框架,內建協程伺服器及大量常用的元件,效能較傳統基於 `PHP-FPM` 的框架有質的提升,提供超高效能的同時,也保持著極其靈活的可擴充套件性,標準組件均基於 [PSR 標準](https://www.php-fig.org/psr) 實現,基於強大的依賴注入設計,保證了絕大部分元件或類都是 `可替換` 與 `可複用` 的。 diff --git a/docs/zh-tw/annotation.md b/docs/zh-tw/annotation.md index 937bfa0f2..7fe3c94da 100644 --- a/docs/zh-tw/annotation.md +++ b/docs/zh-tw/annotation.md @@ -4,22 +4,13 @@ ## 概念 -### 什麼是註解什麼是註釋? +### 什麼是註解? -在解釋註解之前我們需要先定義一下 `註解` 與 `註釋` 的區別: -- 註釋:給程式設計師看,幫助理解程式碼,對程式碼起到解釋、說明的作用。 -- 註解:給應用程式看,用於元資料的定義,單獨使用時沒有任何作用,需配合應用程式對其元資料進行利用才有作用。 +註解功能提供了程式碼中的宣告部分都可以新增結構化、機器可讀的元資料的能力, 註解的目標可以是類、方法、函式、引數、屬性、類常量。 通過 反射 API 可在執行時獲取註解所定義的元資料。 因此註解可以成為直接嵌入程式碼的配置式語言。 -### 註釋型註解解析如何實現? +通過註解的使用,在應用中實現功能、使用功能可以相互解耦。 某種程度上講,它可以和介面(interface)與其實現(implementation)相比較。 但介面與實現是程式碼相關的,註解則與宣告額外資訊和配置相關。 介面可以通過類來實現,而註解也可以宣告到方法、函式、引數、屬性、類常量中。 因此它們比介面更靈活。 -Hyperf 使用了 [doctrine/annotations](https://github.com/doctrine/annotations) 包來對程式碼內的註解進行解析,註解必須寫在下面示例的標準註釋塊才能被正確解析,其它格式均不能被正確解析。 -註釋塊示例: -```php -/** - * @AnnotationClass() - */ -``` -在標準註釋塊內通過書寫 `@AnnotationClass()` 這樣的語法即表明對當前註釋塊所在位置的物件(類、類方法、類屬性)進行了註解的定義, `AnnotationClass` 對應的是一個 `註解類` 的類名,可寫全類的名稱空間,亦可只寫類名,但需要在當前類 `use` 該註解類以確保能夠根據名稱空間找到正確的註解類。 +註解使用的一個簡單例子:將介面(interface)的可選方法改用註解實現。 我們假設介面 ActionHandler 代表了應用的一個操作: 部分 action handler 的實現需要 setup,部分不需要。 我們可以使用註解,而不用要求所有類必須實現 ActionHandler 介面並實現 setUp() 方法。 因此帶來一個好處——可以多次使用註解。 ### 註解是如何發揮作用的? @@ -30,11 +21,13 @@ Hyperf 使用了 [doctrine/annotations](https://github.com/doctrine/annotations) 在一些情況下我們可能希望忽略某些 註解,比如我們在接入一些自動生成文件的工具時,有不少工具都是通過註解的形式去定義文件的相關結構內容的,而這些註解可能並不符合 Hyperf 的使用方式,我們可以通過在 `config/autoload/annotations.php` 內將相關注解設定為忽略。 ```php +use JetBrains\PhpStorm\ArrayShape; + return [ 'scan' => [ // ignore_annotations 陣列內的註解都會被註解掃描器忽略 'ignore_annotations' => [ - 'mixin', + ArrayShape::class, ], ], ]; @@ -46,19 +39,7 @@ return [ ### 使用類註解 -類註解定義是在 `class` 關鍵詞上方的註釋塊內,比如常用的 `@Controller` 和 `@AutoController` 就是類註解的使用典範,下面的程式碼示例則為一個正確使用類註解的示例,表明 `@ClassAnnotation` 註解應用於 `Foo` 類。 - -- PHP 版本低於 8.0 時 - -```php - 注意註解類的 `@Annotation` 和 `@Target` 註解為全域性註解,無需 `use` - -其中 `@Target` 有如下引數: -- `METHOD` 註解允許定義在類方法上 -- `PROPERTY` 註解允許定義在類屬性上 -- `CLASS` 註解允許定義在類上 -- `ALL` 註解允許定義在任何地方 - -- PHP 版本大於等於 8.0 時 +在任意地方建立註解類,如下程式碼示例: ```php = 7.4 and <= 8.0 + - PHP >= 8.0 and <= 8.1 - 以下任一網路引擎 - Swoole PHP 擴充套件 >= 4.5,並關閉了 `Short Name` - Swow PHP 擴充套件 (Beta) @@ -56,7 +56,7 @@ docker run --name hyperf \ -p 9501:9501 -it \ --privileged -u root \ --entrypoint /bin/sh \ -hyperf/hyperf:7.4-alpine-v3.11-swoole +hyperf/hyperf:8.0-alpine-v3.15-swoole ``` - 將 Composer 映象設定為阿里雲映象,加速國內下載速度 diff --git a/docs/zh-tw/validation.md b/docs/zh-tw/validation.md index 8db8a5e5f..e9d0b0cec 100644 --- a/docs/zh-tw/validation.md +++ b/docs/zh-tw/validation.md @@ -64,7 +64,7 @@ php bin/hyperf.php vendor:publish hyperf/validation 執行上面的命令會將驗證器的語言檔案 `validation.php` 釋出到對應的語言檔案目錄,`en` 指英文語言檔案,`zh_CN` 指中文簡體的語言檔案,您可以按照實際需要對 `validation.php` 檔案內容進行修改和自定義。 -``` +```shell /storage /languages /en @@ -444,7 +444,7 @@ class FooController extends Controller } #[Scene(scene:'bar3', argument: 'request')] - #[Scene(scene:'bar3', argument: 'req')] // 支援多個參數 + #[Scene(scene:'bar3', argument: 'req')] // 支援多個引數 public function bar3(SceneRequest $request, DebugRequest $req) { return $this->response->success($request->all());