【进阶】模块开发规范 - APIPHP开源框架

>i 本文档的最新修订日期是： > **2023-09-29** # 综述在路径 `/lib/core/` 中，包含了框架所有自带的类（Class）。但在本框架的所有表述中，将把它称作 `模块` 。一个模块包含了一类相同的功能，例如在框架的 `Db` 模块中，就包含了数据库的增删改查功能。具体到业务代码而言，可以将某一个业务流程归属于同一各模块中，例如订单的生成、支付、扣款、订单状态的变更，就可以放在一个模块中。框架源码包中已经包含了许多常用模块，您也可以自行编写模块。 # 路径规定&命名空间所有自行编写的模块，均应当放在 `/lib/` 目录下根据命名空间创建的子目录中（即子目录路径与命名空间保持一致）。 # 命名和书写规范请遵循 `PSR-4` 。 # 模块配置项模块的配置项，均应当放在 `/config/` 目录下根据命名空间创建的子目录中（即子目录路径与命名空间保持一致），且文件名应当与模块名保持一致。配置项是一个数组，并在模块加载前注入PHP的超全局变量 `$_SERVER` 中，完整的变量名是 `$_SERVER['APIPHP']['Config']['namespace\ClassName']` 。如果你的模块是 `user\Auth`，那么配置文件应为 `/config/user/Auth.php` 且内容应为： ```php <?php $_SERVER['APIPHP']['Config']['user\Auth']=[ 'config1'=>'value', 'config2'=>['a','b','c'] ]; ``` # 方法类型及结构所有方法必须使用静态方法，如果需要传入参数，参数有且只有 `$UnionData` ，默认值为空数组 `[]` 。模块中的最后一个方法，必须为魔术方法 `__callStatic` 。参见如下示例： ```php <?php namespace app; class DemoClass { //无参数 public static function func1() { //方法代码 } //有参数 public static function func1($UnionData) { //方法代码 } //必须包含下面的魔术方法 public static function __callStatic($Method, $Parameters) { Common::unknownStaticMethod(__CLASS__, $Method); } } ``` # 参数的传递必须使用 `快捷传参` 模式，快捷传参模式无需记住参数顺序，且能够对参数进行校验，便于模块方法增添新的参数。快捷传参需要使用到 `Common` 模块的 `quickParameter()` 方法，使用方法见本文最后一节的说明。 # Common模块 ## 模块简述 Common模块属于 `内部模块` ，即该模块中的方法只会被其他模块调用，而不会出现在模板目录（`/source`）下的代码文件中，由于该模块中的方法均不支持快捷传参，因此未将此模块的使用方式列入模块说明中。 ## :: quickParameter()方法 ### 语法 **Common :: quickParameter ( <kbd>`$UnionData`</kbd> , <kbd>`$Name`</kbd> , <kbd>`$Dialect`</kbd> , <kbd>`$Must`</kbd> , <kbd>`$Value`</kbd> , <kbd>`$Default`</kbd> )** ### 说明检验参数是否符合预期。 ### 参数 * **`UnionData`** `(Array)` `<必须>`：此参数为传参数组变量。传参数组是一个数组，元素的 `键` 方为参数名，元素的 `值` 为参数名对应的参数值，参数值可以是多种数据类型中的一种，取决于模块方法的规定。 * **`Name`** `(String)` `<必须>`：传参数组中参数的名称。 * **`Dialect`** `(String)` `<必须>`：传参数组中参数的别名，用以辅助记忆，此参数可以与 `Name` 参数相同，也可以是中文等非英语语言。 >i 在调用方法时，参数 `Name` 与 `Dialect` 的值，都可以作为传参数组中元素的 `键` 使用。 * **`Must`** `(Bool)` `true`：用以指定传参数组中的参数是否为必传参数。如果本参数值为 `true` 且在调用方法时传入的传参数组中不存在指定的参数，框架将报错。 * **`Value`** `(多类型)` `null`：用以指定传参数组中参数的默认值。如果 `Must` 参数值为 `false` 且在调用方法时传入的传参数组中不存在指定的参数，将返回本参数的值。当未指定本参数时，将用 `null` 作为默认值。 * **`Default`** `(Bool)` `false`：用以指定传参数组中的参数是否为默认参数。如果本参数值为 `true`，则本参数可通过传参数组的[简写方式](doc:lVH085kz)传递。 ### 返回多种类型之一，取决于模块方法的规定。 ### 示例为方法 `app\Auth::login()` 指定一个必传的参数 `username` 和一个默认值为空字符串的参数 `channel` 。 ```php <?php namespace app; class Auth { public static function login($UnionData) { $Username = Common::quickParameter($UnionData, 'username', '用户名'); $Channel = Common::quickParameter($UnionData, 'channel', '渠道', false, ''); } } ``` 调用该方法时： ```php <?php use app\Auth; Auth::login([ 'username'=>'jack' '渠道'=>'a658gv9' ]); ``` ## :: diskPath()方法 ### 语法 **Common :: diskPath ( <kbd>`$Path`</kbd> )** ### 说明获取文件或目录的磁盘路径。 ### 参数 * **`Path`** `(String)` `<必须>`：文件夹或文件的路径。路径是相对于 `应用根目录` （即lib、source文件夹所在的目录，通常是站点根目录）的路径，以 `/` 开始。 ### 返回 `(String)` 类型。指定文件或目录的磁盘路径。 ## :: unknownStaticMethod()方法 ### 语法 **Common :: unknownStaticMethod ( <kbd>`$ModuleName`</kbd> , <kbd>`$MethodName`</kbd> )** ### 说明模块中调用了不存在的方法时，通过本方法进行报错。本方法仅供魔术方法 `__callStatic` 调用。 ### 参数 * **`ModuleName`** `(String)` `<必须>`：调用的模块名称。 * **`MethodName`** `(String)` `<必须>`：调用的方法名称。 ### 返回无。 ### 示例 ```php public static function __callStatic($Method, $Parameters) { self::unknownStaticMethod(__CLASS__, $Method); } ```