README

简介

评论管理器是一个PHP脚本，允许解析方法文档块注释。它还允许使用文档块注释中的信息验证参数值和返回值。

功能

1. 方法参数验证

   如果您在一个方法中添加了以下注释

   @param string $my_param [val1,val2,val3]
   

   那么评论管理器脚本可以用来检查参数$my_param的值是否在列表val1,val2,val3中。

   脚本可以验证数字范围、参数类型、列表、电子邮件、JSON和数组。还可以根据文档块注释中的信息验证方法返回值。

2. 提取方法描述

   评论管理器脚本可以用来提取方法文档块注释中给出的描述文本。可以提取长描述和短描述。

3. 验证方法上下文

   评论管理器脚本可以用来检查类方法是否从命令行、浏览器、作为API函数或测试函数等调用，基于@internal 标签中的信息。

4. 自定义验证

   评论管理器脚本允许使用自定义验证函数验证参数值。

5. 支持的标签

   目前，评论管理器脚本可以用来从文档块注释中提取以下标签： @param、@version>、@internal、@return 以及长方法和短方法描述。

   评论管理器脚本可以轻松扩展以从方法注释中提取其他标签。

6. 在MVC框架中使用

   评论管理器包可以在MVC（模型-视图-控制器）框架中使用，以基于方法文档块注释中的信息执行方法参数的自动验证。

7. PSR标准

   评论管理器包代码符合PSR-2编码风格。

示例使用

示例 1

以下示例展示了如何安全地调用具有参数和返回值验证的函数

/** The safe_function_caller closure is fetched from the CommentManager class */
$safe_function_caller       = CommentManager::GetClosure();
/** The parameters for the test function */
$parameters                 = array(
                                  "number1" => 30,
                                  "number2" => 10,
                                  "number3" => 10,
                                   "data" => array(
                                                 "type" => "integer",
                                                  "random_string" => "The result of adding the three integers is: ";
                                            )
                              );
                              
/** The function that provides custom validation for the test function parameters */
$validation_callback        = array($this, "CustomValidation");
                                      
/** The callback */
$callback                   = array(
                                  "class_name" => get_class(),
                                  "class_object" => $this,
                                  "function_name" => "AddNumbers", 
                                  "parameters" => $parameters, 
                                  "context" => "cli"
                              );
try {                                          
   /** The test function is called through the safe function caller */
   $result                  = $safe_function_caller($callback, $validation_callback);            
}
catch (\Error $e) {
    /** The error message is displayed and the script ends */
    die($e->getMessage());
}
     
/** The result of adding the numbers is displayed */
echo $result['random_string'] . $result['sum'];

在上面的示例中，CustomValidation是一个用户定义的函数，用于执行自定义验证。 AddNumbers是待验证的函数。它接受3个数字和一个随机字符串作为参数。它返回原始的随机字符串以及三个数字的和。自定义验证函数通过检查随机字符串的长度是否在范围内来验证返回值。参数的类型和值由评论管理器类检查。请参阅示例文件CommentManagerTest.php以获取完整示例。

示例 2

以下示例展示了如何提取方法文档块注释

/** The Parser class is included */
require("Parser.php");
/** An object of the parser class is created */
$parser = new Parser();
/** The method doc block comments are parsed */
$parsed_comments          = $parser->ParseMethodDocBlockComments($class_name, $function_name);
print_R($parsed_comments);

在上面的示例中，$class_name和$function_name是要检查的方法。以下输出被生成

Array
(
    [description] => Array
        (
            [short] => This function adds the three numbers given as parameters.
                       It returns the sum of the numbers and a random string.
                       The random string is given as the last parameter
            [long] => 
        )

    [version] => Array
        (
            [since] => 
            [version] => 
        )

    [internal] => Array
        (
            [context] => cli
        )

    [parameters] => Array
        (
            [0] => Array
                (
                    [type] => int
                    [variable_name] => number1
                    [rule] => range
                    [description] => the first number
                    [rule_data] => 1-100
                )

            [1] => Array
                (
                    [type] => int
                    [variable_name] => number2
                    [rule] => range
                    [description] => the second number
                    [rule_data] => 1-100
                )

            [2] => Array
                (
                    [type] => int
                    [variable_name] => number3
                    [rule] => range
                    [description] => the third number
                    [rule_data] => 1-100
                )

            [3] => Array
                (
                    [type] => array
                    [variable_name] => data
                    [rule] => 
                    [description] => contains the type of the numbers and a string
                    [rule_data] => 
                    [values] => Array
                        (
                            [0] => Array
                                (
                                    [variable_name] => type
                                    [type] => string
                                    [rule] => list
                                    [rule_data] => integer,float
                                    [description] => the type of number to be added
                                )

                            [1] => Array
                                (
                                    [variable_name] => random_string
                                    [type] => string
                                    [rule] => custom
                                    [rule_data] => 
                                    [description] => a random string that is returned by the function
                                )

                        )

                )

        )

    [return_value] => Array
        (
            [type] => array
            [variable_name] => result
            [rule] => 
            [description] => the result of the function
            [rule_data] => 
            [values] => Array
                (
                    [0] => Array
                        (
                            [variable_name] => sum
                            [type] => int
                            [rule] => range
                            [rule_data] => 1-50
                            [description] => the sum of the three numbers
                        )

                    [1] => Array
                        (
                            [variable_name] => random_string
                            [type] => string
                            [rule] => 
                            [rule_data] => 
                            [description] => the random string
                        )

                )

        )

    [function_name] => AddNumbers
)

文件列表

评论管理器包包括以下文件

• CommentManager.php。它提供了一个闭包函数，用于安全地调用类方法。它还提供了解析和验证方法参数以及返回值的功能。
• Parser.php。它提供了一个单一函数用于解析所有方法的 DocBlock 注释。
• DescriptionParser.php。它提供了提取长描述和短描述以及内部和版本标签的函数。
• ParameterParser.php。它提供了解析 @param 标签的函数。
• Validator.php。它提供了使用 DocBlock 中的信息验证方法参数和方法返回值的函数。
• VariableValidator.php。它提供了验证不同类型变量的函数。例如整数、字符串、布尔值和数组。

安装

1. 使用 composer 安装

   运行以下命令：composer require nadirlc/comment-manager

   或者

2. 从 Comment Manager GitHub 仓库 下载

   运行以下命令：git clone https://github.com/nadirlc/comment-manager.git