mirror of
https://gitee.com/hyperf/hyperf.git
synced 2024-11-30 02:37:58 +08:00
Upgrade docs to hyperf 3.0 (#4878)
This commit is contained in:
李铭昕
GitHub
parent
ae39272443
commit
fe19a4fb93
@ -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
|
||||
<?php
|
||||
/**
|
||||
* @ClassAnnotation
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
- 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
|
||||
<?php
|
||||
@ -68,25 +49,7 @@ class Foo {}
|
||||
|
||||
### Use method level annotation
|
||||
|
||||
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
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @MethodAnnotation()
|
||||
*/
|
||||
public function bar()
|
||||
{
|
||||
// some code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 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
|
||||
<?php
|
||||
@ -102,22 +65,7 @@ class Foo
|
||||
|
||||
### Use property level of annotation
|
||||
|
||||
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 < 8.0
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @PropertyAnnotation()
|
||||
*/
|
||||
private $bar;
|
||||
}
|
||||
```
|
||||
|
||||
- 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
|
||||
<?php
|
||||
@ -130,52 +78,16 @@ class Foo
|
||||
|
||||
### The passing of annotation parameter
|
||||
|
||||
- Pass the main single parameter `@DemoAnnotation("value")`
|
||||
- Pass the string parameter `@DemoAnnotation(key1="value1", key2="value2")`
|
||||
- Pass the array parameter `@DemoAnnotation(key={"value1", "value2"})`
|
||||
- Pass the main single parameter `#[DemoAnnotation('value')]`
|
||||
- Pass the string parameter `#[DemoAnnotation(key1: 'value1', key2: 'value2')]`
|
||||
- Pass the array parameter `#[DemoAnnotation(key: ['value1', 'value2'])]`
|
||||
|
||||
## Custom Annotation
|
||||
|
||||
### Create a Annotation class
|
||||
### Create an Annotation class
|
||||
|
||||
Create an annotation class into anywhere, as in the following code example:
|
||||
|
||||
- PHP < 8.0
|
||||
|
||||
```php
|
||||
namespace App\Annotation;
|
||||
|
||||
use Hyperf\Di\Annotation\AbstractAnnotation;
|
||||
|
||||
/**
|
||||
* @Annotation
|
||||
* @Target({"METHOD","PROPERTY"})
|
||||
*/
|
||||
class Bar extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
|
||||
/**
|
||||
* @Annotation
|
||||
* @Target("CLASS")
|
||||
*/
|
||||
class Foo extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
```
|
||||
|
||||
> 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
|
||||
<?php
|
||||
namespace App\Annotation;
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# 2.2 介绍
|
||||
# 3.0 介绍
|
||||
|
||||
Hyperf 是一个高性能、高灵活性的渐进式 PHP 协程框架，内置协程服务器及大量常用的组件，性能较传统基于 `PHP-FPM` 的框架有质的提升，提供超高性能的同时，也保持着极其灵活的可扩展性，标准组件均基于 [PSR 标准](https://www.php-fig.org/psr) 实现，基于强大的依赖注入设计，保证了绝大部分组件或类都是 `可替换` 与 `可复用` 的。
|
||||
|
||||
|
||||
@ -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
|
||||
<?php
|
||||
/**
|
||||
* @ClassAnnotation
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
- PHP 版本大于等于 8.0 时
|
||||
类注解定义是在 `class` 关键词上方的注释块内，比如常用的 `Controller` 和 `AutoController` 就是类注解的使用典范，下面的代码示例则为一个正确使用类注解的示例，表明 `ClassAnnotation` 注解应用于 `Foo` 类。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -68,25 +49,7 @@ class Foo {}
|
||||
|
||||
### 使用类方法注解
|
||||
|
||||
类方法注解定义是在方法上方的注释块内，比如常用的 `@RequestMapping` 就是类方法注解的使用典范，下面的代码示例则为一个正确使用类方法注解的示例，表明 `@MethodAnnotation` 注解应用于 `Foo::bar()` 方法。
|
||||
|
||||
- PHP 版本低于 8.0 时
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @MethodAnnotation()
|
||||
*/
|
||||
public function bar()
|
||||
{
|
||||
// some code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- PHP 版本大于等于 8.0 时
|
||||
类方法注解定义是在方法上方的注释块内，比如常用的 `RequestMapping` 就是类方法注解的使用典范，下面的代码示例则为一个正确使用类方法注解的示例，表明 `MethodAnnotation` 注解应用于 `Foo::bar()` 方法。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -102,22 +65,7 @@ class Foo
|
||||
|
||||
### 使用类属性注解
|
||||
|
||||
类属性注解定义是在属性上方的注释块内，比如常用的 `@Value` 和 `@Inject` 就是类属性注解的使用典范，下面的代码示例则为一个正确使用类属性注解的示例，表明 `@PropertyAnnotation` 注解应用于 `Foo` 类的 `$bar` 属性。
|
||||
|
||||
- PHP 版本低于 8.0 时
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @PropertyAnnotation()
|
||||
*/
|
||||
private $bar;
|
||||
}
|
||||
```
|
||||
|
||||
- PHP 版本大于等于 8.0 时
|
||||
类属性注解定义是在属性上方的注释块内，比如常用的 `Value` 和 `Inject` 就是类属性注解的使用典范，下面的代码示例则为一个正确使用类属性注解的示例，表明 `PropertyAnnotation` 注解应用于 `Foo` 类的 `$bar` 属性。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -130,46 +78,15 @@ class Foo
|
||||
|
||||
### 注释型注解参数传递
|
||||
|
||||
- 传递主要的单个参数 `@DemoAnnotation("value")`
|
||||
- 传递字符串参数 `@DemoAnnotation(key1="value1", key2="value2")`
|
||||
- 传递数组参数 `@DemoAnnotation(key={"value1", "value2"})`
|
||||
- 传递主要的单个参数 `#[DemoAnnotation('value')]`
|
||||
- 传递字符串参数 `#[DemoAnnotation(key1: 'value1', key2: 'value2')]`
|
||||
- 传递数组参数 `#[DemoAnnotation(key: ['value1', 'value2'])]`
|
||||
|
||||
## 自定义注解
|
||||
|
||||
### 创建一个注解类
|
||||
|
||||
在任意地方创建注解类，如下代码示例：
|
||||
|
||||
- PHP 版本低于 8.0 时
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace App\Annotation;
|
||||
|
||||
use Hyperf\Di\Annotation\AbstractAnnotation;
|
||||
|
||||
#[Attribute(Attribute::TARGET_PROPERTY)]
|
||||
class Bar extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
|
||||
#[Attribute(Attribute::TARGET_CLASS)]
|
||||
class Foo extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
```
|
||||
|
||||
> 注意注解类的 `@Annotation` 和 `@Target` 注解为全局注解，无需 `use`
|
||||
|
||||
其中 `@Target` 有如下参数：
|
||||
- `METHOD` 注解允许定义在类方法上
|
||||
- `PROPERTY` 注解允许定义在类属性上
|
||||
- `CLASS` 注解允许定义在类上
|
||||
- `ALL` 注解允许定义在任何地方
|
||||
|
||||
- PHP 版本大于等于 8.0 时
|
||||
在任意地方创建注解类，如下代码示例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -219,26 +136,6 @@ return [
|
||||
|
||||
```
|
||||
|
||||
### 原生注解(Attributes)
|
||||
|
||||
众所周知，在 PHP 8 增加了 `原生注解(Attributes)` 的特性，Hyperf 2.2 版本开始也支持了原生注解的写法，文档内的所有注解都可做对应的转换，如下：
|
||||
|
||||
#### PHPDoc 注解
|
||||
|
||||
```php
|
||||
/**
|
||||
* @ClassAnnotation()
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
#### PHP 原生注解
|
||||
|
||||
```php
|
||||
#[ClassAnnotation()]
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
### 利用注解数据
|
||||
|
||||
在没有自定义注解收集方法时，默认会将注解的元数据统一收集在 `Hyperf\Di\Annotation\AnnotationCollector` 类内，通过该类的静态方法可以方便的获取对应的元数据用于逻辑判断或实现。
|
||||
@ -429,11 +326,3 @@ return [
|
||||
```
|
||||
|
||||
这样 `co()` 和 `parallel()` 等方法，就可以自动拿到父协程，上下文中的数据，比如 `Request`。
|
||||
|
||||
## IDE 注解插件
|
||||
|
||||
因为 `PHP8.0` 以下并不是原生支持 `注解`，所以 `IDE` 不会默认增加注解支持。但我们可以添加第三方插件，来让 `IDE` 支持 `注解`。
|
||||
|
||||
### PhpStorm
|
||||
|
||||
我们到 `Plugins` 中搜索 `PHP Annotations`，就可以找到对应的组件 [PHP Annotations](https://github.com/Haehnchen/idea-php-annotation-plugin)。然后安装组件，重启 `PhpStorm`，就可以愉快的使用注解功能了，主要提供了为注解类增加自动跳转和代码提醒支持，使用注解时自动引用注解对应的命名空间等非常便捷有用的功能。
|
||||
|
||||
@ -8,7 +8,7 @@ Hyperf 对系统环境有一些要求，当您使用 Swoole 网络引擎驱动
|
||||
|
||||
当您不想采用 Docker 来作为运行的环境基础时，您需要确保您的运行环境达到了以下的要求：
|
||||
|
||||
- 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 镜像设置为阿里云镜像，加速国内下载速度
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# 2.2 介紹
|
||||
# 3.0 介紹
|
||||
|
||||
Hyperf 是一個高性能、高靈活性的漸進式 PHP 協程框架，內置協程服務器及大量常用的組件，性能較傳統基於 `PHP-FPM` 的框架有質的提升，提供超高性能的同時，也保持着極其靈活的可擴展性，標準組件均基於 [PSR 標準](https://www.php-fig.org/psr) 實現，基於強大的依賴注入設計，保證了絕大部分組件或類都是 `可替換` 與 `可複用` 的。
|
||||
|
||||
|
||||
@ -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
|
||||
<?php
|
||||
/**
|
||||
* @ClassAnnotation
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
類註解定義是在 `class` 關鍵詞上方的註釋塊內，比如常用的 `Controller` 和 `AutoController` 就是類註解的使用典範，下面的代碼示例則為一個正確使用類註解的示例，表明 `ClassAnnotation` 註解應用於 `Foo` 類。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -68,25 +49,7 @@ class Foo {}
|
||||
|
||||
### 使用類方法註解
|
||||
|
||||
類方法註解定義是在方法上方的註釋塊內，比如常用的 `@RequestMapping` 就是類方法註解的使用典範，下面的代碼示例則為一個正確使用類方法註解的示例，表明 `@MethodAnnotation` 註解應用於 `Foo::bar()` 方法。
|
||||
|
||||
- PHP 版本低於 8.0 時
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @MethodAnnotation()
|
||||
*/
|
||||
public function bar()
|
||||
{
|
||||
// some code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
類方法註解定義是在方法上方的註釋塊內，比如常用的 `RequestMapping` 就是類方法註解的使用典範，下面的代碼示例則為一個正確使用類方法註解的示例，表明 `MethodAnnotation` 註解應用於 `Foo::bar()` 方法。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -102,22 +65,7 @@ class Foo
|
||||
|
||||
### 使用類屬性註解
|
||||
|
||||
類屬性註解定義是在屬性上方的註釋塊內，比如常用的 `@Value` 和 `@Inject` 就是類屬性註解的使用典範，下面的代碼示例則為一個正確使用類屬性註解的示例，表明 `@PropertyAnnotation` 註解應用於 `Foo` 類的 `$bar` 屬性。
|
||||
|
||||
- PHP 版本低於 8.0 時
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @PropertyAnnotation()
|
||||
*/
|
||||
private $bar;
|
||||
}
|
||||
```
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
類屬性註解定義是在屬性上方的註釋塊內，比如常用的 `Value` 和 `Inject` 就是類屬性註解的使用典範，下面的代碼示例則為一個正確使用類屬性註解的示例，表明 `PropertyAnnotation` 註解應用於 `Foo` 類的 `$bar` 屬性。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -130,46 +78,15 @@ class Foo
|
||||
|
||||
### 註釋型註解參數傳遞
|
||||
|
||||
- 傳遞主要的單個參數 `@DemoAnnotation("value")`
|
||||
- 傳遞字符串參數 `@DemoAnnotation(key1="value1", key2="value2")`
|
||||
- 傳遞數組參數 `@DemoAnnotation(key={"value1", "value2"})`
|
||||
- 傳遞主要的單個參數 `#[DemoAnnotation('value')]`
|
||||
- 傳遞字符串參數 `#[DemoAnnotation(key1: 'value1', key2: 'value2')]`
|
||||
- 傳遞數組參數 `#[DemoAnnotation(key: ['value1', 'value2'])]`
|
||||
|
||||
## 自定義註解
|
||||
|
||||
### 創建一個註解類
|
||||
|
||||
在任意地方創建註解類，如下代碼示例：
|
||||
|
||||
- PHP 版本低於 8.0 時
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace App\Annotation;
|
||||
|
||||
use Hyperf\Di\Annotation\AbstractAnnotation;
|
||||
|
||||
#[Attribute(Attribute::TARGET_PROPERTY)]
|
||||
class Bar extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
|
||||
#[Attribute(Attribute::TARGET_CLASS)]
|
||||
class Foo extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
```
|
||||
|
||||
> 注意註解類的 `@Annotation` 和 `@Target` 註解為全局註解，無需 `use`
|
||||
|
||||
其中 `@Target` 有如下參數：
|
||||
- `METHOD` 註解允許定義在類方法上
|
||||
- `PROPERTY` 註解允許定義在類屬性上
|
||||
- `CLASS` 註解允許定義在類上
|
||||
- `ALL` 註解允許定義在任何地方
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
在任意地方創建註解類，如下代碼示例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -219,26 +136,6 @@ return [
|
||||
|
||||
```
|
||||
|
||||
### 原生註解(Attributes)
|
||||
|
||||
眾所周知，在 PHP 8 增加了 `原生註解(Attributes)` 的特性，Hyperf 2.2 版本開始也支持了原生註解的寫法，文檔內的所有註解都可做對應的轉換，如下：
|
||||
|
||||
#### PHPDoc 註解
|
||||
|
||||
```php
|
||||
/**
|
||||
* @ClassAnnotation()
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
#### PHP 原生註解
|
||||
|
||||
```php
|
||||
#[ClassAnnotation()]
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
### 利用註解數據
|
||||
|
||||
在沒有自定義註解收集方法時，默認會將註解的元數據統一收集在 `Hyperf\Di\Annotation\AnnotationCollector` 類內，通過該類的靜態方法可以方便的獲取對應的元數據用於邏輯判斷或實現。
|
||||
@ -429,11 +326,3 @@ return [
|
||||
```
|
||||
|
||||
這樣 `co()` 和 `parallel()` 等方法，就可以自動拿到父協程，上下文中的數據，比如 `Request`。
|
||||
|
||||
## IDE 註解插件
|
||||
|
||||
因為 `PHP8.0` 以下並不是原生支持 `註解`，所以 `IDE` 不會默認增加註解支持。但我們可以添加第三方插件，來讓 `IDE` 支持 `註解`。
|
||||
|
||||
### PhpStorm
|
||||
|
||||
我們到 `Plugins` 中搜索 `PHP Annotations`，就可以找到對應的組件 [PHP Annotations](https://github.com/Haehnchen/idea-php-annotation-plugin)。然後安裝組件，重啟 `PhpStorm`，就可以愉快的使用註解功能了，主要提供了為註解類增加自動跳轉和代碼提醒支持，使用註解時自動引用註解對應的命名空間等非常便捷有用的功能。
|
||||
|
||||
@ -8,7 +8,7 @@ Hyperf 對系統環境有一些要求，當您使用 Swoole 網絡引擎驅動
|
||||
|
||||
當您不想採用 Docker 來作為運行的環境基礎時，您需要確保您的運行環境達到了以下的要求：
|
||||
|
||||
- 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 鏡像設置為阿里雲鏡像，加速國內下載速度
|
||||
|
||||
@ -64,7 +64,7 @@ php bin/hyperf.php vendor:publish hyperf/validation
|
||||
|
||||
執行上面的命令會將驗證器的語言文件 `validation.php` 發佈到對應的語言文件目錄，`en` 指英文語言文件，`zh_CN` 指中文簡體的語言文件，您可以按照實際需要對 `validation.php` 文件內容進行修改和自定義。
|
||||
|
||||
```
|
||||
```shell
|
||||
/storage
|
||||
/languages
|
||||
/en
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# 2.2 介紹
|
||||
# 3.0 介紹
|
||||
|
||||
Hyperf 是一個高效能、高靈活性的漸進式 PHP 協程框架，內建協程伺服器及大量常用的元件，效能較傳統基於 `PHP-FPM` 的框架有質的提升，提供超高效能的同時，也保持著極其靈活的可擴充套件性，標準組件均基於 [PSR 標準](https://www.php-fig.org/psr) 實現，基於強大的依賴注入設計，保證了絕大部分元件或類都是 `可替換` 與 `可複用` 的。
|
||||
|
||||
|
||||
@ -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
|
||||
<?php
|
||||
/**
|
||||
* @ClassAnnotation
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
類註解定義是在 `class` 關鍵詞上方的註釋塊內，比如常用的 `Controller` 和 `AutoController` 就是類註解的使用典範，下面的程式碼示例則為一個正確使用類註解的示例，表明 `ClassAnnotation` 註解應用於 `Foo` 類。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -68,25 +49,7 @@ class Foo {}
|
||||
|
||||
### 使用類方法註解
|
||||
|
||||
類方法註解定義是在方法上方的註釋塊內，比如常用的 `@RequestMapping` 就是類方法註解的使用典範，下面的程式碼示例則為一個正確使用類方法註解的示例，表明 `@MethodAnnotation` 註解應用於 `Foo::bar()` 方法。
|
||||
|
||||
- PHP 版本低於 8.0 時
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @MethodAnnotation()
|
||||
*/
|
||||
public function bar()
|
||||
{
|
||||
// some code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
類方法註解定義是在方法上方的註釋塊內，比如常用的 `RequestMapping` 就是類方法註解的使用典範，下面的程式碼示例則為一個正確使用類方法註解的示例，表明 `MethodAnnotation` 註解應用於 `Foo::bar()` 方法。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -102,22 +65,7 @@ class Foo
|
||||
|
||||
### 使用類屬性註解
|
||||
|
||||
類屬性註解定義是在屬性上方的註釋塊內，比如常用的 `@Value` 和 `@Inject` 就是類屬性註解的使用典範，下面的程式碼示例則為一個正確使用類屬性註解的示例，表明 `@PropertyAnnotation` 註解應用於 `Foo` 類的 `$bar` 屬性。
|
||||
|
||||
- PHP 版本低於 8.0 時
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Foo
|
||||
{
|
||||
/**
|
||||
* @PropertyAnnotation()
|
||||
*/
|
||||
private $bar;
|
||||
}
|
||||
```
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
類屬性註解定義是在屬性上方的註釋塊內，比如常用的 `Value` 和 `Inject` 就是類屬性註解的使用典範，下面的程式碼示例則為一個正確使用類屬性註解的示例，表明 `PropertyAnnotation` 註解應用於 `Foo` 類的 `$bar` 屬性。
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -130,46 +78,15 @@ class Foo
|
||||
|
||||
### 註釋型註解引數傳遞
|
||||
|
||||
- 傳遞主要的單個引數 `@DemoAnnotation("value")`
|
||||
- 傳遞字串引數 `@DemoAnnotation(key1="value1", key2="value2")`
|
||||
- 傳遞陣列引數 `@DemoAnnotation(key={"value1", "value2"})`
|
||||
- 傳遞主要的單個引數 `#[DemoAnnotation('value')]`
|
||||
- 傳遞字串引數 `#[DemoAnnotation(key1: 'value1', key2: 'value2')]`
|
||||
- 傳遞陣列引數 `#[DemoAnnotation(key: ['value1', 'value2'])]`
|
||||
|
||||
## 自定義註解
|
||||
|
||||
### 建立一個註解類
|
||||
|
||||
在任意地方建立註解類，如下程式碼示例：
|
||||
|
||||
- PHP 版本低於 8.0 時
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace App\Annotation;
|
||||
|
||||
use Hyperf\Di\Annotation\AbstractAnnotation;
|
||||
|
||||
#[Attribute(Attribute::TARGET_PROPERTY)]
|
||||
class Bar extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
|
||||
#[Attribute(Attribute::TARGET_CLASS)]
|
||||
class Foo extends AbstractAnnotation
|
||||
{
|
||||
// some code
|
||||
}
|
||||
```
|
||||
|
||||
> 注意註解類的 `@Annotation` 和 `@Target` 註解為全域性註解，無需 `use`
|
||||
|
||||
其中 `@Target` 有如下引數：
|
||||
- `METHOD` 註解允許定義在類方法上
|
||||
- `PROPERTY` 註解允許定義在類屬性上
|
||||
- `CLASS` 註解允許定義在類上
|
||||
- `ALL` 註解允許定義在任何地方
|
||||
|
||||
- PHP 版本大於等於 8.0 時
|
||||
在任意地方建立註解類，如下程式碼示例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
@ -219,26 +136,6 @@ return [
|
||||
|
||||
```
|
||||
|
||||
### 原生註解(Attributes)
|
||||
|
||||
眾所周知，在 PHP 8 增加了 `原生註解(Attributes)` 的特性，Hyperf 2.2 版本開始也支援了原生註解的寫法，文件內的所有註解都可做對應的轉換，如下：
|
||||
|
||||
#### PHPDoc 註解
|
||||
|
||||
```php
|
||||
/**
|
||||
* @ClassAnnotation()
|
||||
*/
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
#### PHP 原生註解
|
||||
|
||||
```php
|
||||
#[ClassAnnotation()]
|
||||
class Foo {}
|
||||
```
|
||||
|
||||
### 利用註解資料
|
||||
|
||||
在沒有自定義註解收集方法時，預設會將註解的元資料統一收集在 `Hyperf\Di\Annotation\AnnotationCollector` 類內，通過該類的靜態方法可以方便的獲取對應的元資料用於邏輯判斷或實現。
|
||||
@ -429,11 +326,3 @@ return [
|
||||
```
|
||||
|
||||
這樣 `co()` 和 `parallel()` 等方法，就可以自動拿到父協程，上下文中的資料，比如 `Request`。
|
||||
|
||||
## IDE 註解外掛
|
||||
|
||||
因為 `PHP8.0` 以下並不是原生支援 `註解`，所以 `IDE` 不會預設增加註解支援。但我們可以新增第三方外掛，來讓 `IDE` 支援 `註解`。
|
||||
|
||||
### PhpStorm
|
||||
|
||||
我們到 `Plugins` 中搜索 `PHP Annotations`，就可以找到對應的元件 [PHP Annotations](https://github.com/Haehnchen/idea-php-annotation-plugin)。然後安裝元件，重啟 `PhpStorm`，就可以愉快的使用註解功能了，主要提供了為註解類增加自動跳轉和程式碼提醒支援，使用註解時自動引用註解對應的名稱空間等非常便捷有用的功能。
|
||||
|
||||
@ -8,7 +8,7 @@ Hyperf 對系統環境有一些要求，當您使用 Swoole 網路引擎驅動
|
||||
|
||||
當您不想採用 Docker 來作為執行的環境基礎時，您需要確保您的執行環境達到了以下的要求：
|
||||
|
||||
- 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 映象設定為阿里雲映象，加速國內下載速度
|
||||
|
||||
@ -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());
|
||||
|
||||
Loading…
Reference in New Issue
Block a user