title: Annotation meta:

  • name: description content: Easyswoole提供了一个轻量级的注解解析工具
  • name: keywords content: swoole|swoole extension|swoole framework|EasySwoole|Annotation

Annotation

Easyswoole provides a lightweight annotation resolution tool.

The installation

  1. composer require easyswoole/annotation

Implementation principle

  • convention
    • Each annotation behavior starts with the @ character and is formatted as @METHOD(ARGS)
  • The execution process is as follows：
    • Use PHP reflection to get comment information
    • Explode and explode each line with PHP_EOL
    • Parse the data of each line. If the corresponding METHOD AnnotationTagInterface exists, pass the parsed ARGS to the assetValue METHOD in the AnnotationTagInterface. The user can perform custom parsing of the parsed values in this method.
    • In strict mode, an error is reported if the correct value cannot be resolved.

example

  1. <?php
  2. use EasySwoole\Annotation\Annotation;
  3. use EasySwoole\Annotation\AbstractAnnotationTag;
  5. /*
  6.  * Define the param rendering method
  7.  */
  9. class param extends AbstractAnnotationTag
  10. {
  12.     public function tagName(): string
  13.     {
  14.         return 'param';
  15.     }
  17.     public function assetValue(?string $raw)
  18.     {
  19.         $list = explode(',',$raw);
  20.         foreach ($list as $item){
  21.             parse_str($item,$ret);
  22.             foreach ($ret as $key => $value){
  23.                 $this->$key = trim($value," \t\n\r\0\x0B\"\'");
  24.             }
  25.         }
  26.     }
  27. }
  29. /*
  30.  * Define the timeout rendering method
  31.  */
  33. class timeout extends AbstractAnnotationTag
  34. {
  35.     public $timeout;
  37.     public function tagName(): string
  38.     {
  39.         return 'timeout';
  40.     }
  42.     public function assetValue(?string $raw)
  43.     {
  44.         $this->timeout = floatval($raw);
  45.     }
  47.     public function aliasMap(): array
  48.     {
  49.         return [
  50.             static::class,
  51.             "timeout_alias"
  52.         ];
  53.     }
  54. }
  57. class A
  58. {
  59.     protected $a;
  61.     /**
  62.      * @param(name=a,type=string,value=2)
  63.      * @param(name=b)
  64.      * @timeout_Alias(0.5)
  65.      * @fuck(easyswoole)
  66.      * 这是我的其他说明啊啊啊啊啊
  67.      */
  68.     function test()
  69.     {
  71.     }
  72. }
  74. /**
  75.  * Instantiate the renderer and register the rendering method to parse
  76.  */
  77. $annotation = new Annotation();
  78. $ref = new \ReflectionClass(A::class);
  79. //Do not register fuck parsing
  80. $annotation->addParserTag(new param());
  81. $annotation->addParserTag(new timeout());
  83. $list = $annotation->getClassMethodAnnotation($ref->getMethod('test'));
  85. foreach ($list['param'] as $item){
  86.     var_dump((array)$item);
  87. }
  89. foreach ($list['timeout'] as $item){
  90.     var_dump((array)$item);
  91. }

::: warning
If @ exists in the first three characters of each comment line, it means that this behavior needs to parse the comment line. By default, it is in non-strict mode. Unregistered tag information will not be parsed. :::

Default annotation parsing tool

Easyswoole comes with a string parsing tool calledEasyswoole \Annotation\ValueParser, which supports unit testing in the following format

The code is shown in：

  1. namespace EasySwoole\Annotation\Tests;
  4. use EasySwoole\Annotation\ValueParser;
  5. use PHPUnit\Framework\TestCase;
  7. class ValueParserTest extends TestCase
  8. {
  9.     function testNormal()
  10.     {
  11.         $str = "int=1";
  12.         $this->assertEquals([
  13.             'int'=>"1"
  14.         ],ValueParser::parser($str));
  16.         $str = "int=1,int2=2";
  17.         $this->assertEquals([
  18.             'int'=>"1",
  19.             'int2'=>"2"
  20.         ],ValueParser::parser($str));
  22.         $str = "int=1,int2='2'";
  23.         $this->assertEquals([
  24.             'int'=>"1",
  25.             'int2'=>"2"
  26.         ],ValueParser::parser($str));
  27.     }
  29.     function testArray()
  30.     {
  31.         $str = "array={1,2,3}";
  32.         $this->assertEquals([
  33.             'array'=>['1','2','3']
  34.         ],ValueParser::parser($str));
  36.         $str = "array={'1','2','3'}";
  37.         $this->assertEquals([
  38.             'array'=>['1','2','3']
  39.         ],ValueParser::parser($str));
  42.         $str = "array={'1','2 , 3'}";
  43.         $this->assertEquals([
  44.             'array'=>['1','2 , 3']
  45.         ],ValueParser::parser($str));
  47.         $str = 'array={"1","2","3"}';
  48.         $this->assertEquals([
  49.             'array'=>['1','2','3']
  50.         ],ValueParser::parser($str));
  52.         $str = "array={1,2,3} ,array2={4,5,6}";
  53.         $this->assertEquals([
  54.             'array'=>['1','2','3'],
  55.             'array2'=>['4','5','6']
  56.         ],ValueParser::parser($str));
  58.     }
  61.     function testEval()
  62.     {
  63.         $str = 'time="eval(time() + 30)"';
  64.         $this->assertEquals([
  65.             'time'=>time() + 30,
  66.         ],ValueParser::parser($str));
  68.         $str = 'time="eval(time() + 30)" , time2="eval(time() + 31)';
  69.         $this->assertEquals([
  70.             'time'=>time() + 30,
  71.             'time2'=>time() + 31
  72.         ],ValueParser::parser($str));
  74.         $str = 'list="eval([1,2,3,4])"';
  75.         $this->assertEquals([
  76.             'list'=>[1,2,3,4]
  77.         ],ValueParser::parser($str));
  78.     }
  80.     function testArrayAndEval()
  81.     {
  82.         $str = 'array="{"1","2",eval(time() + 30)}"';
  83.         $this->assertEquals([
  84.             'array'=>['1','2',time() + 30]
  85.         ],ValueParser::parser($str));
  87.         $str = 'array={"1","2",eval(time() + 30)},str="222"';
  88.         $this->assertEquals([
  89.             'array'=>['1','2',time() + 30],
  90.             "str"=>'222'
  91.         ],ValueParser::parser($str));
  93.         $str = "array={1,2,3},time=eval(time())";
  94.         $this->assertEquals([
  95.             'array'=>['1','2','3'],
  96.             'time'=>time()
  97.         ],ValueParser::parser($str));
  98.     }
  101.     function testStrMulti()
  102.     {
  103.         $str = 'mix="first|{1,2,3}|eval(time() + 3)"';
  104.         $this->assertEquals([
  105.             'mix'=>['first',['1','2','3'],time() + 3]
  106.         ],ValueParser::parser($str));
  107.     }
  108. }

IDE support

PHPStorm needs to install the “PHP Annotation” plug-in to provide Annotation autoprompt capability. The plug-in can be searched and installed directly in PHPStorm or downloaded and installed on Github

::: warning https://github.com/Haehnchen/idea-php-annotation-plugin :::

Then write one of the following Annotation prompt classes yourself, the focus is to use the @annotation class Annotation, mark this is an Annotation prompt class, PHPStorm index to this file, you can annotate the class name and class members

  2. <?php
  5. namespace EasySwoole\Validate;
  7. /**
  8.  * Annotated document
  9.  * @Annotation
  10.  * You need to use the Annotation tag up here which is an Annotation prompt class
  11.  */
  12. final class ValidateRule
  13. {
  14.     /**
  15.      * These fields are prompted in parentheses
  16.      * @var string
  17.      */
  18.     protected $name;
  20.     /**
  21.      * These fields are prompted in parentheses
  22.      * @var string
  23.      */
  24.     protected $column;
  26.     /**
  27.      * These fields are prompted in parentheses
  28.      * @var string
  29.      */
  30.     protected $alias;
  31. }

You can implement the following aaa method automatic annotation prompt

  1. <?php
  3. use EasySwoole\Validate as Validate;
  5. class a
  6. {
  7.     /**
  8.      * @Validate\ValidateRule(column="name",alias="The name of the account")
  9.      */
  10.     function aaa(){
  12.     }
  13. }