README

简介

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

功能

1. 方法参数验证

   如果你在方法中添加了以下注释

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

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

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

2. 提取方法描述

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

3. 验证方法上下文

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

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

以下示例展示了如何提取方法 DocBlock 注释。

/** 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