TOP-framework/README.md

TOP-Framework

这是一个部分代码源自三年前毕业设计中的代码集合，后经过一系列重构，形成的一套框架。在此准备写一个文档。

模块

创建模块

1. 手动创建 在application（可更改）目录下创建home目录，再创建config、controller（必须）、model、view目录
2. 命令行自动创建 命令格式（[]为可选参数）：

php create.php 目录 模块名 [入口文件]

进入framework/create/目录，执行以下命令：

php create.php application home index

至此，已经通过简单的命令创建了home模块，浏览器输入127.0.0.1即可访问home模块（系统默认模块为home模块，可在入口文件中指定），亦可命令行访问home模块。

控制器

创建控制器

一个典型的控制器（Index.php）

<?php

namespace app\home\controller;

class Index
{
    public function index()
    {
        return [];
    }
}

其中包括了命名空间、以及一个默认的index方法，index方法返回数组或布尔值true则会显示模板，如果返回的是数字或字符串则会直接输出，返回对象直接输出[OBJECT]，关于模板部分后面会详细介绍。

如果当前控制器继承自top\library\Controller基础控制器，则会继承以下方法：

1. json($msg, $code = 1, $data = [], $ext = [])

返回json数据。

2. cache($status = true)

如果在方法中调用了此方法则会将模板做静态缓存，缓存时间在配置文件中设置。

3. param($name, $value)

将参数传递到模板文件。

4. view($file = '', $param = [], $cache = false)

显示模板（得到模板文件渲染后的内容）。

5. redirect($url)

利用header函数跳转。

6. tips($message, $url = '', $sec = 3)

如果是AJAX请求则会返回json数据（调用json方法），普通请求则返回tips模板文件渲染后的内容。

展示模板

public function index()
{
    return $this->view();
}

调用基础控制器中的view方法、并return出去，完成模板的展示。

模板传值

1. view方法

public function index()
{
    return $this->view(null, [
        'param' => 'Hello world!'
    ]);
}

2. 直接return数组

public function index()
{
    return [
        'param' => 'Hello world!'
    ];
}

以上两种方式等效。

控制器方法的前置、后置操作

public function before_index()
{
}

public function after_index()
{
}

public function index()
{
    return [
        'param' => 'Hello world!'
    ];
}

命名规范：before_方法名（前置）、after_方法名（后置），执行index方法之前会先执行before_index方法（如果存在），执行完index方法后会执行after_index方法（如果存在）。当前置方法return的值为空字符串、null、true时才会继续执行，否则前置方法的return等效于index方法的return。

模型

创建模型

一个典型的模型（Users.php）

<?php

namespace app\home\model;

use top\library\Model;

class 模型名称 extends Model
{
}

系统会根据模型名称去绑定对应同名称的数据表，例：模型名称为Users时，则绑定名为”前缀_users“的数据表。如果模型名称为UsersInfo时，则绑定名为“前缀_users_info”的数据表。

继承自top\library\Model基础模型后，模型将拥有以下方法或属性：

方法：

1. data($data = [], $notRaw = true) 获取即将操作的数据

接收两个参数，参数一：指定的数据（数组），传入空数组则为POST数据。参数二：是否返回进行数据表字段过滤的原始数据（布尔值）。

未通过验证则返回false，否则返回数组。

2. query($query) 执行一条SQL语句

成功返回true，失败抛出DatabaseException异常。

3. insert($data = []) 插入一条记录

传入数组为即将插入的记录

成功返回受影响的记录数，失败抛出DatabaseException异常。

4. update($data, [$param = false]) 更新一条记录

第一个参数为即将更新的数据，可传入第二个参数为主键。

$this->update([
    'username' => 'TOP糯米'
], 1);

除此之外，提供另一种方式，传递更多条件或更复杂的条件

$this->update([
    'username' => 'TOP糯米'
], function ($model) {
    $model->where('id', 1);
});

当然，也可以使用连贯操作

$this->where('id', 1)->update([
    'username' => 'TOP糯米'
]);

成功返回受影响的记录数，失败抛出DatabaseException异常。

5. find($param = false, $notRaw = true) 查找一条记录

可传入第一个参数为主键，第二个参数为是否按指定的规则（outReplace属性）进行处理。

一般调用

$this->find(1);

匿名函数

$this->find(function ($model) {
    $model->where('id', 1);
});

连贯操作

$this->where('id', 1)->find();

成功返回一个一维数组，失败抛出DatabaseException异常。

6. select($param = false, $notRaw = true) 查找多条记录

使用方法同find

成功返回一个二维数组，失败抛出DatabaseException异常。

7. delete 删除记录

直接传入主键

$this->delete(1);

匿名函数

$this->delete(function () {
    $model->where('id', 1);
});

连贯操作

$this->where('id', 1)->delete();

成功返回受影响的记录数，失败抛出DatabaseException异常。

8. count 返回记录数

一般调用

$this->count();

第一个参数同样可以为匿名函数、并且同样支持连贯操作

成功返回记录数，失败抛出DatabaseException异常。

9. avg 计算平均值

接收一个参数，当没有使用field方法指定字段时，可直接传入字段名，以计算平均值。

$this->avg('score');

使用field方法指定字段

$this->field('score')->avg();

匿名函数中指定字段或条件

$this->avg(function ($model) {
    $model->where('score', '>=', 60);
    $model->field('score');
});

成功返回平均值，失败抛出DatabaseException异常。

10. max 计算最大值

同avg方法

11. min 计算最小值

同avg方法

12. sum 求和

同avg方法

13. _sql 返回最后执行的SQL语句

14. tableDesc 返回表结构

接收参数为一个完整表名。

成功返回表结构，失败抛出DatabaseException异常。

15. distinct 过滤记录中的重复值

接收一个为字段名称的参数

调用

$this->distinct('sex')->select();

失败抛出DatabaseException异常。

16. effect 删除时指定表（别）名

接收一个参数，可以为字符串或数组，参数为表名或表别名

调用

$this->delete(function ($model) {
    $model->effect('s,this');
    $model->join('left', 'score', 's')->on('s.uid = this.id');
    $model->where(['this.id' => 3]);
});

17. field 指定字段

可传入字符串或数组

18. where 指定条件

最多可接收三个参数

仅传入一个参数时，可传入字符串或数组

$where = ['id' => ['>', 10], 'sex' => 1];
$where = 'id > 10 and sex = 1';
$this->where($where)->select();

两个参数，解析为“字段=值”

$this->where('sex', 1)->select();

三个参数，指定字段与字段值的连接符

$this->where('sex', '>', 1)->select();

19. order 对结果进行排序

$this->order('id desc')->select();

也可以使用匿名函数调用order方法

20. limit 查询范围

接收一个参数，可以是字符串或数组

一般调用

$this->limit('0, 5')->select();
$this->limit([0, 5])->select();

两种方式等效

21. join 加入多表进行查询，通常情况下与on方法同时使用

接收三个参数，第一个参数为连接方式（空、left、right、full），第二个参数为表名（不包含前缀），第三个参数为别名（当前表会自动将”this“作为别名）。

一般调用

$this->select(function ($model) {
    $model->join('left', 'score', 's')->on('s.uid = this.id');
});

同样也可以使用连贯操作

22. on 表字段连接关系

见join方法

属性：

1. $table 指定当前模型的表名（优先于模型名称）

protected $table = 'users';

2. $pk 指定当前模型的主键（如果不指定，程序将自动查询以当前模型命名的表的主键）

protected $pk = 'id';

3. $map 指定传入数据的键与数据库字段名称的映射关系

protected $map = [
    'name' => 'username'
];

4. $inReplace 入库时替换值

数据入库时自动格式化时间为unix时间戳

protected $inReplace = [
    'create_time' => ['formatTime', true]
];

protected function formatTime($time)
{
    return strtotime($time);
}

至此，在数据在被写入数据库之前会先调用inReplace中设定的函数、方法，并将return的值作为新的值写入数据库。

注意：当以字段为键名的数组的值为一个字符串时，则该字符串为即将调用的函数，如果值为一个数组，且无第二个值或第二个值为false、空，则该数组第一个值为即将调用的函数，如第二个值为true，则表示当前调用的方法存在于本类或父类中。

5. $outReplace 出库时替换值

protected $outReplace = [
    'sex' => ['outFormatSex', true]
];

protected function outFormatSex($sex)
{
    switch ($sex) {
        case 1:
            return '男';
            break;
        case 2:
            return '女';
            break;
        default:
            return '未知';
    }
}

注意：当以字段为键名的数组的值为一个字符串时，则该字符串为即将调用的函数，如果值为一个数组，且无第二个值或第二个值为false、空，则该数组第一个值为即将调用的函数，如第二个值为true，则表示当前调用的方法存在于本类或父类中。

6. $updateReplace 数据更新时替换值

基本类似于inReplace，但仅当执行更新操作时执行。

7. $validate 自动验证

验证不为空

protected $validate = [
    'username' => ['notNull', '用户名不能为空'],
];

验证不等于

protected $validate = [
    'username' => ['notEqual', '0', '用户名不能为0'],
];

多条件（用户名不为空且不为0）

protected $validate = [
    'username' => [
        ['notNull', '用户名不能为空'],
        ['notEqual', '0', '用户名不能为0'],
    ],
];

自定义函数验证，新建函数demo到函数库

function demo($name, $n1, $n2)
{
    if ($name == $n1 || $name == $n2) {
        return false;
    }
    return true;
}

添加到自动验证

protected $validate = [
    'username' => [
        ['notNull', '用户名不能为空'],
        ['notEqual', '0', '用户名不能为0'],
        ['demo', 'TOP糯米', '张三', '用户名不能为TOP糯米或张三'],
    ],
];

调用模型

调用模型有两种方式：

1. model函数（推荐） model函数会返回一个模型的单例，使用方式与直接new无差别。

$object = model(模型);

2. new 模型

$object = new 模型();

模板

模板继承

模板继承通过extend标签与block标签配合使用实现。 一个最简单的继承

// Base/layout.html（父级模板）

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
<block name="body"></block>
</body>
</html>

// Index/index.html

<extend file="Base/layout" />
<block name="body">
    <h3>内容主体</h3>
</block>

模板标签

内置一些常用标签

1. php

php标签。此标签为闭合标签，标签内的内容将被解析为原生php代码执行。

<php>
    echo '你好';
</php>

2. if

if标签。此标签为闭合标签，condition属性为if的条件，属性列表：condition。

<if condition="$age eq 10">
    // do something...
</if>

3. else

else标签。此标签为自闭合标签，可选属性condition，存在condition属性则被解析为elseif，属性列表：condition（可选）。

<if condition="$age eq 10">
    // do something...
<else />
    // do something...
</if>

<if condition="$age eq 10">
    // do something...
<else condition="$age eq 20" />
    // do something...
</if>

4. volist

循环标签。此标签为闭合标签，属性列表：name、id、key（可选）。

<volist name="lists" id="item">
    {$item['id']}
</volist>

<volist name="lists" id="item" key="i">
    {$i}、{$item['id']}
</volist>

5. assign

赋值标签，在模板中创建新的php变量。此标签为自闭合标签，属性列表：name、value。

<assign name="username" value="TOP糯米" />

6. raw

该标签为闭合标签。raw标签中的内容不会被编译。

<raw>
    <volist name="lists" id="item">
        {$item['id']}
    </volist>
</raw>

上例，volist标签会被原样输出。

7. 变量、函数输出

// 变量输出
{$username}

// 调用函数，左定界符后加上:表示调用函数
{:mb_substr($username, 0, 3, 'utf8')}

自定义标签

新建自定义标签库类文件/application/home/taglib/Extend.php，目录及文件名称没有要求。

闭合标签

namespace app\home\taglib;

class Extend
{
    public $tags = [
        'test' => ['attr' => 'start,length,id', 'close' => 1]
    ];

    public function _test($tag, $content)
    {
        $parse = '<?php ';
        $parse .= 'for ($' . $tag['id'] . ' = ' . $tag['start'] . '; $' . $tag['id'];
        $parse .=  ' < ' . $tag['start'] . ' + ' . $tag['length'] . '; ';
        $parse .= '$' . $tag['id'] . '++): ?>';
        $parse .= $content;
        $parse .= '<?php endfor; ?>';
        return $parse;
    }
}

类创建完成后，到配置文件config.php的view下的tagLib中添加Extend类

'view' => [
        'tagLib' => [
            \app\home\taglib\Extend::class
        ]
    ],

添加完成后即可在模板中使用

<test start="1" length="10" id="test">
    {$test}
</test>

自闭合标签

添加一个描述

'say' => ['attr' => 'what', 'close' => 0]

新建_say方法

public function _say($tag)
{
    return "<?php echo '{$tag['what']}'; ?>";
}

模板调用

<say what="Hello world!" />

自定义路由

路由配置文件位于 application 下，文件名：route.php 现有News控制器中的detail方法

public function detail($id)
{
    return [
        'id' => (int) $id
    ];
}

假设访问地址为： http://127.0.0.3/home/news/detail/id/1.html 。

必须参数

添加如下规则

'detail' => [
    '[id]',
    'home/news/detail'
]

完成后，可使用 http://127.0.0.3/detail/1.html 访问到对应位置。

可选参数

修改detail方法

public function detail($id = 0)
{
    return [
        'id' => (int) $id
    ];
}

添加路由规则

'detail' => [
    '[:id]',
    'home/news/detail'
]

完成后，可使用 http://127.0.0.3/detail.html 访问到对应位置，如果没传递id，则使用默认值。

多个参数

'detail' => [
    '[id][:type]',
    'home/news/detail'
]

其他

Request类

获取实例

1. instance方法获取单例

Request::instance();

2. request函数获取单例

request();

供调用的方法

1. isPost

判断是否是POST请求

2. isGet

判断是否是GET请求

3. isPut

判断是否是PUT请求

4. isDelete

判断是否是DELETE请求

5. isHead

判断是否是HEAD请求

6. isPatch

判断是否是PATCH请求

7. isOptions

判断是否是OPTIONS请求

8. isAjax

判断是否是AJAX请求

9. create

创建一个HTTP请求

原型：create($url, $data = [], $header = [])

第一个参数为请求的链接，第二个参数为将要POST的数据，第三个参数为指定Header参数

10. ip

返回客户端IP地址

11. module

当前请求的模型名称

12. classname

当前请求的完整控制器名称

13. controller

当前请求的不包含命名空间的控制器名称

14. method

当前请求的方法名称

15. params

当前请求所带的参数

16. get

获取get数据

原型：get($name = '*', $except = [], $filter = 'filter')

第一个参数为将要获取的变量名称（' * ' 为全部），第二个参数为过滤的变量，第三个参数为指定的过滤函数（可以为自定义函数名称或匿名函数）。

函数名称：

request()->get('id', ['type'], 'filter');

匿名函数：

request()->get('id', ['type'], function ($value) {
    return (int) $value;
});

17. post

获取post数据

使用同get方法

18. except

指定过滤的变量

取出全部get数据，但不包括type

request()->except('type')->get();

面向控制器的前置、后置方法（请求拦截）

创建application/home/filter/Auth.php测试文件

namespace app\home\filter;

use top\middleware\ifs\MiddlewareIfs;

class Auth implements MiddlewareIfs
{
    public function before()
    {
        return '拒绝请求';
    }

    public function after($data)
    {
        // TODO: Implement after() method.
    }
}

创建完成后，加入配置

'middleware' => [
    \app\home\filter\Auth::class
],

现在，访问项目则会得到 ' 拒绝请求 ' 结果。仅当before方法return的值为true时，程序才会继续执行，否则return等效于控制器方法的return。