魔众SCRM私域运营系统PHP库-全局函数

modstart_version MSCore版本

获取MSCore版本

modstart_version( )

• 返回：string 版本号

modstart_admin_url Admin路径

生成Admin的路径，自动加前缀

modstart_admin_url( string, array )

• 参数：string $url 路径
• 参数：array $param 参数
• 返回：string

代码示例

// 返回 /admin/aaa/bbb
modstart_admin_url('aaa/bbb')
// 返回 /admin/aaa/bbb?x=y
modstart_admin_url('aaa/bbb',['x'=>'y'])

modstart_web_full_url 生成完整的Web路径

modstart_web_full_url( string, array )

• 参数：string $url 路径
• 参数：array $param 参数
• 返回：string 地址

代码示例

// 返回 http://www.example.com/aaa/bbb
modstart_web_full_url('aaa/bbb')
// 返回 http://www.example.com/aaa/bbb?x=y
modstart_web_full_url('aaa/bbb',['x'=>'y'])

modstart_web_url Web路径

生成Web的路径，自动加前缀

modstart_web_url( string, array )

• 参数：string $url 路径
• 参数：array $param 参数
• 返回：string 地址

代码示例

// 返回 /aaa/bbb
modstart_web_url('aaa/bbb')
// 返回 /aaa/bbb?x=y
modstart_web_url('aaa/bbb',['x'=>'y'])

modstart_api_url Api路径

生成Api的路径，自动加前缀

modstart_api_url( string, array )

• 参数：string $url 路径
• 参数：array $param 参数
• 返回：string

代码示例

// 返回 /api/aaa/bbb
modstart_api_url('aaa/bbb')
// 返回 /api/aaa/bbb?x=y
modstart_api_url('aaa/bbb',['x'=>'y'])

modstart_configs 获取多个配置中第一个非空值

modstart_configs( $keys, $default )

• 参数：$keys array 多个配置名
• 参数：$default string 默认值
• 返回：void array|bool|int|mixed|\ModStart\Core\Config\MConfig|string

modstart_config 获取配置

用于获取表 config 中的配置选项

modstart_config( $key, $default, $useCache )

• 参数：$key string 配置名称
• 参数：$default string|array|boolean|integer 默认值，不能为 null
• 参数：$useCache boolean 启用缓存，默认为true
• 返回：string|array|boolean|integer|\ModStart\Core\Config\MConfig 返回配置值或配置对象

代码示例

// 网站名称
modstart_config('siteName','[默认名称]');
// 获取一个配置数组，数组需存储成 json 格式
modstart_config()->getArray('xxx')
// 设置配置项
modstart_config()->set('xxx','aaa')

modstart_config_asset_url 获取配置资源路径

modstart_config_asset_url( $key, $default )

• 参数：$key string 配置名称
• 参数：$default string 默认值
• 返回：string

modstart_module_enabled 模块判断

判断模块是否已安装并启用

modstart_module_enabled( $module, $version )

• 参数：$module string 模块名称，如 Member
• 参数：$version string 模块版本要求，如 1.0.0， >=1.0.0
• 返回：boolean 模块是否安装并启用

代码示例

// 模块Member是否安装并启用
modstart_module_enabled('Member')
// 模块Member是否安装了 >=1.2.0 的版本
modstart_module_enabled('Member','>=1.2.0')

LM 多语言（模块）

LM( $module, $name, ...$params )

• 参数：$module string 模块名称
• 参数：$name string 多语言
• 参数：...$params string|int 多语言参数
• 返回：string 多语言翻译

代码示例

// 获取模块Member的多语言
LM('Member','Message')
// 获取模块Member的多语言，带参数
LM('Member','File Size Limit %s','10M')

L 多语言

获取多语言翻译

L( $name, ...$params )

• 参数：$name string 多语言
• 参数：...$params string|int 多语言参数
• 返回：string 多语言翻译

代码示例

// 返回 消息
L('Message');
// 返回 文件最大为10M
L('File Size Limit %s','10M');

L_locale 设置/获取当前语言环境

L_locale( $locale )

• 参数：$locale string|null 语言环境，如 zh、en
• 返回：string 当前语言环境

代码示例

// 获取当前语言环境
$locale = L_locale();
// 设置当前语言环境
L_locale('en');

L_locale_title 获取当前语言名称

L_locale_title( $locale )

• 参数：$locale string 语言环境
• 返回：string 语言名称

modstart_open_api_url OpenApi路径

生成 OpenApi 的路径，自动加前缀

modstart_open_api_url( $url )

• 参数：$url string 路径
• 返回：string

代码示例

// 返回 /open_api/aaa/bbb
modstart_open_api_url('aaa/bbb')

modstart_baseurl_active 判断当前URL是否匹配

用于菜单高亮等场景，判断当前 URL 是否匹配并返回激活样式类名

modstart_baseurl_active( $match, $output )

• 参数：$match string 匹配 URL
• 参数：$output string 匹配成功返回的内容，默认为 active
• 返回：string

代码示例

// 当前URL为 /admin/blog 时返回 active
modstart_baseurl_active('/admin/blog')

modstart_module_config 获取模块配置

获取指定模块的配置项

modstart_module_config( $module, $key, $default )

• 参数：$module string 模块名称
• 参数：$key string 配置键名
• 参数：$default mixed 默认值
• 返回：mixed

数据库 ModelUtil

model 构建模型

ModelUtil::model( $model )

• 参数：$model string 数据表
• 返回：Model|Builder 数据库模型

代码示例

// 查询
ModelUtil::model('user')->where(['id'=>1])->get()->toArray();
ModelUtil::model('user')->where('id','>',5)->get()->toArray();
// 查询-like
ModelUtil::model('user')->where('username','like','%keywords%')->get()->toArray();
// 查询-limit
ModelUtil::model('user')->limit(5)->get()->toArray();
// 查询-原生SQL
ModelUtil::model('user')->whereRaw(DB::raw('id > 0 OR id is null'))->get()->toArray();

// 删除
ModelUtil::model('user')->where(['id'=>1])->delete();

// 更新
ModelUtil::model('user')->where(['id'=>1])->update(['username'=>'aaa']);

insert 插入数据

ModelUtil::insert( $model, $data )

• 参数：$model string 数据表
• 参数：$data array 数据数组
• 返回：array 插入的数据记录

代码示例

ModelUtil::insert('user',['username'=>'aaa','nickname'=>'bbb']);

insertAll 插入多条数据

ModelUtil::insertAll( $model, $records, $updateTimestamp )

• 参数：$model string 数据表
• 参数：$records array 多条数据数组
• 参数：$updateTimestamp boolean 是否更新时间戳，默认为true
• 返回：void

代码示例

ModelUtil::insertAll('user',[ ['username'=>'aaa','nickname'=>'bbb'], ['username'=>'ccc','nickname'=>'ddd'] ]);

delete 删除记录

ModelUtil::delete( $model, $where )

• 参数：$model string 数据表
• 参数：$where array|int 条件数组或数据ID
• 返回：integer 被删除的记录数量

代码示例

// 删除ID为1的用户
ModelUtil::delete('user',1);
// 删除用户名为aaa的用户
ModelUtil::delete('user',['username'=>'aaa']);

get 获取单条记录

ModelUtil::get( $model, $where, $fields, $order )

• 参数：$model string 数据表
• 参数：$where int|array 条件
• 参数：$fields array 数据表字段
• 参数：$order array 排序，如 ['id','asc']
• 返回：array|null 数据记录

代码示例

ModelUtil::get('user',1);
ModelUtil::get('user',['username'=>'xxx']);
更复杂的数据获取可以使用 ModelUtil::model('xxx') 进行操作

业务异常 BizException

ModStart\Core\Exception\BizException 是系统中最常用的业务异常类。当业务逻辑校验不通过时，使用 BizException::throws 抛出异常，系统会自动捕获并返回友好的错误提示。

throws 抛出业务异常

BizException::throws( $msg, $param )

• 参数：$msg string 错误消息
• 参数：$param array 额外参数
• 返回：void（抛出异常）

代码示例

if (!$user) {
    BizException::throws('用户不存在');
}

throwsIf 条件抛出

BizException::throwsIf( $msg, $condition, $param )

• 参数：$msg string 错误消息
• 参数：$condition mixed 条件，为 true 时抛出
• 参数：$param array 额外参数
• 返回：void

代码示例

BizException::throwsIf('用户不存在', empty($user));

throwsIfEmpty 空值抛出

BizException::throwsIfEmpty( $msg, $object, $param )

• 参数：$msg string 错误消息
• 参数：$object mixed 值，为空时抛出
• 参数：$param array 额外参数
• 返回：void

throwsIfResponseError 接口响应错误抛出

BizException::throwsIfResponseError( $response, $prefix, $param )

• 参数：$response array 标准响应数组（含 code 字段）
• 参数：$prefix string 错误前缀
• 参数：$param array 额外参数
• 返回：void

代码示例

$ret = CurlUtil::postJSON($url, $data);
BizException::throwsIfResponseError($ret, '远程请求失败');

结果异常 ResultException

用于标准格式响应（code/msg/data）的异常处理。

throwsIfFail 判断响应是否有错误

ResultException::throwsIfFail( $ret )

• 参数：$ret array 标准响应数组
• 返回：void（code != 0 时抛出异常）

代码示例

$ret = modstart_config()->set('siteName', '新名称');
ResultException::throwsIfFail($ret);

客户端 AgentUtil

getUserAgent 获取浏览器UserAgent

AgentUtil::getUserAgent( )

• 返回：string

device 判断浏览器类型

AgentUtil::device( )

• 返回：string pc, mobile

isWechat 判断是否是微信浏览器

AgentUtil::isWechat( )

• 返回：boolean

isWechatMobile 判断是否是微信手机浏览器

AgentUtil::isWechatMobile( )

• 返回：boolean

isWechatPC 判断是否是微信PC浏览器

AgentUtil::isWechatPC( )

• 返回：boolean

isMobile 判断是否是手机浏览器

AgentUtil::isMobile( )

• 返回：boolean

isPC 判断是否是电脑浏览器

AgentUtil::isPC( )

• 返回：boolean

detectRobot 获取机器人类型

AgentUtil::detectRobot( $userAgent )

• 参数：$userAgent string|null 浏览器UserAgent，为空时自动获取
• 返回：string|null 机器人名称，非机器人时返回null

输入输出 Request / Response / InputPackage

命名空间：ModStart\Core\Input

Request HTTP请求工具

ModStart\Core\Input\Request 提供 HTTP 请求的便捷获取。

path 获取请求路径

Request::path( )

• 返回：string 无前导斜杠的路径

basePath 获取完整路径

Request::basePath( )

• 返回：string 包含前缀的完整路径

basePathWithQueries 获取完整路径及参数

Request::basePathWithQueries( )

• 返回：string 完整路径 + 查询字符串

domainUrl 获取域名URL

Request::domainUrl( )

• 返回：string 如 http://www.example.com

isAjax 是否为AJAX请求

Request::isAjax( )

• 返回：boolean

isPost 是否为POST请求

Request::isPost( )

• 返回：boolean

headerGet 获取请求头

Request::headerGet( $key, $default )

• 参数：$key string 请求头名称
• 参数：$default string|null 默认值
• 返回：string|null

Response 响应工具

ModStart\Core\Input\Response 生成标准响应结构。

generate 生成标准响应数组

Response::generate( $code, $msg, $data, $redirect )

• 参数：$code integer 状态码，0 为成功
• 参数：$msg string 提示消息
• 参数：$data mixed 数据
• 参数：$redirect string|null 重定向地址
• 返回：array

json 返回JSON响应

Response::json( $code, $msg, $data, $redirect )

• 返回：\Illuminate\Http\JsonResponse

jsonSuccess 返回成功JSON

Response::jsonSuccess( $msg, $data )

• 返回：\Illuminate\Http\JsonResponse

jsonError 返回错误JSON

Response::jsonError( $msg, $data, $redirect )

• 返回：\Illuminate\Http\JsonResponse

send 智能发送响应

自动判断：AJAX 请求返回 JSON，否则返回 HTML 重定向。

Response::send( $code, $msg, $redirect )

• 返回：mixed

sendError 发送错误响应

Response::sendError( $msg, $redirect )

• 返回：mixed

page404 返回404页面

Response::page404( )

• 返回：\Illuminate\Http\Response

page403 返回403页面

Response::page403( )

• 返回：\Illuminate\Http\Response

InputPackage 输入参数包

用于安全地获取请求参数。

// 获取请求参数包
$input = InputPackage::buildFromInput();
// 或从数组构建
$input = new InputPackage($array);

常用方法：

事件操作 EventUtil

fire 触发一个Laravel事件，兼容了不同版本

EventUtil::fire( $event )

• 参数：$event object|string
• 返回：void

listen 监听一个Laravel事件

EventUtil::listen( $eventClass, $callback )

• 参数：$eventClass string 事件类名
• 参数：$callback callable 回调函数
• 返回：void

文件 FileUtil

mime 根据文件后缀获取MIME类型字符串

FileUtil::mime( $ext )

• 参数：$ext string 文件后缀
• 返回：string|null

mimeToExt 根据MIME类型字符串获取文件后缀

FileUtil::mimeToExt( $mime )

• 参数：$mime string MIME类型字符串
• 返回：string|null

write 写入文件

FileUtil::write( $path, $content )

• 参数：$path string
• 参数：$content string
• 返回：boolean 是否写入成功

extension 获取文件后缀

FileUtil::extension( $pathname )

• 参数：$pathname string 文件路径
• 返回：string

listAllFiles 递归列出目录所有文件

FileUtil::listAllFiles( $dir, $filter )

• 参数：$dir string 目录
• 参数：$filter Closure 过滤器，为空表示不过滤
• 返回：array

listFiles 列出目录所有文件

FileUtil::listFiles( $filename, $pattern )

• 参数：$filename string
• 参数：$pattern string 后缀过滤，如 *.txt *.php 等
• 返回：array

formatByte 格式化字节

FileUtil::formatByte( $bytes, $decimals )

• 参数：$bytes integer 字节数
• 参数：$decimals integer 小数最多保留位数，默认为2
• 返回：string

代码示例

// 返回 1 MB
FileUtil::formatByte(1024*1024)
// 返回 1.5 GB
FileUtil::formatByte(1024*1024*1024*1.5)

formatByteSimple 格式化字节（简化）

FileUtil::formatByteSimple( $bytes, $decimals )

• 参数：$bytes integer 字节数
• 参数：$decimals integer 小数最多保留位数，默认为2
• 返回：string

代码示例

// 返回 1 M
FileUtil::formatByte(1024*1024)
// 返回 1.5 G
FileUtil::formatByte(1024*1024*1024*1.5)

formattedSizeToBytes 格式化的文件大小转换为字节

FileUtil::formattedSizeToBytes( $sizeString )

• 参数：$sizeString string 如 1M
• 返回：integer

copy 复制目录

FileUtil::copy( $src, $dst, $replaceExt, $callback, $filter )

• 参数：$src string 源路径，必须给出，不能为空
• 参数：$dst string 源路径，必须给出，不能为空
• 参数：$replaceExt string|null 如果文件存在需要添加的后缀名，作为备份使用，如果不传表示不备份
• 参数：$callback Closure|null 复制回调
• 参数：$filter Closure|null 复制过滤器
• 返回：null 注意：src 和 dst 如果是文件，需同时是文件，如果是目录，需同时是目录

rm 删除目录

FileUtil::rm( $dir, $removeSelf )

• 参数：$dir string 目录
• 参数：$removeSelf boolean 是否删除本身
• 返回：boolean

ID生成 IdUtil

generate 带前缀的ID

一般用于页面渲染时页面元素唯一ID

IdUtil::generate( string )

• 参数：string $group
• 返回：string 生成的ID字符串

代码示例

// 将生成 Aaa_1 Aaa_2 Aaa_3
IdUtil::generate('Aaa')

next64BitId 获取64位ID

IdUtil::next64BitId( )

• 返回：string ID字符串

generateSN 生成订单号

一个19位长的（BigInteger）

IdUtil::generateSN( )

• 返回：string

代码示例

// 生成 20210101010101+12121
IdUtil::generateSN()

图片工具类 ImageUtil

pngBase64 将图片文件转为Base64

ImageUtil::pngBase64( $path )

• 参数：$path string 图片路径
• 返回：string|null Base64字符串

toWidth 调整图片宽度

ImageUtil::toWidth( $path, $width )

• 参数：$path string 图片路径
• 参数：$width integer 目标宽度
• 返回：string 处理后的图片路径

CRUD工具 CRUDUtil

ModStart\Core\Util\CRUDUtil 提供 CRUD 开发的通用工具方法。

id 获取当前记录ID

CRUDUtil::id( )

• 返回：integer 从当前请求中获取的记录ID

ids 获取ID数组

CRUDUtil::ids( )

• 返回：array 整数ID数组，用于批量操作

copyId 获取复制源ID

CRUDUtil::copyId( )

• 返回：integer|null 复制操作时的源记录ID

scope 获取当前作用域

CRUDUtil::scope( )

• 返回：string|null 当前作用域值

registerRouteResource 注册标准CRUD路由

CRUDUtil::registerRouteResource( $prefix, $class )

• 参数：$prefix string 路由前缀
• 参数：$class string 控制器类名

代码示例

// 注册 blog 的标准 CRUD 路由
CRUDUtil::registerRouteResource('blog', 'BlogController');

jsDialogClose 关闭弹框

CRUDUtil::jsDialogClose( $flag )

• 返回：string JavaScript 代码

jsDialogCloseAndParentGridRefresh 关闭弹框并刷新父表格

CRUDUtil::jsDialogCloseAndParentGridRefresh( $flag )

• 返回：string JavaScript 代码

jsGridRefresh 刷新数据表格

CRUDUtil::jsGridRefresh( $index, $flag )

• 返回：string JavaScript 代码

adminRedirectOrTabClose 后台重定向或关闭标签页

CRUDUtil::adminRedirectOrTabClose( $url )

• 返回：string JavaScript 代码

分页渲染工具 PageHtmlUtil

nextPageUrl 渲染下一页分页链接

PageHtmlUtil::nextPageUrl( $total, $pageSize, $currentPage, $url )

• 参数：$total integer 总记录数
• 参数：$pageSize integer 每页记录数
• 参数：$currentPage integer 当前页
• 参数：$url string 分页链接，页码使用 {page} 占位
• 返回：void

prevPageUrl 渲染上一页分页链接

PageHtmlUtil::prevPageUrl( $total, $pageSize, $currentPage, $url )

• 参数：$total integer 总记录数
• 参数：$pageSize integer 每页记录数
• 参数：$currentPage integer 当前页
• 参数：$url string 分页链接，页码使用 {page} 占位
• 返回：void

render 渲染分页工具

PageHtmlUtil::render( $total, $pageSize, $currentPage, $url, $template )

• 参数：$total integer 总记录数
• 参数：$pageSize integer 每页记录数
• 参数：$currentPage integer 当前页
• 参数：$url string 分页链接，页码使用 {page} 占位
• 参数：$template string 模板
• 返回：void

二维码 QrcodeUtil

png 生成二维码

生成PNG格式的二维码图片

QrcodeUtil::png( $content, $size )

• 参数：$content string 二维码内容
• 参数：$size integer 大小，默认200
• 返回：string 图片二进制串

pngBase64String 生成二维码

生成二维码Base64串

QrcodeUtil::pngBase64String( $content, $size )

• 参数：$content string 二维码内容
• 参数：$size integer 大小，默认200
• 返回：string 二维码Base64字符串

代码示例

// 返回 data:image/png;base64,xxxxxxxx
QrcodeUtil::pngBase64String('http://www.xxx.com')

随机字符串 RandomUtil

number 随机数字

RandomUtil::number( $length )

• 参数：$length integer 长度
• 返回：string 字符串

string 随机字符串

RandomUtil::string( $length )

• 参数：$length integer 长度
• 返回：string 字符串

readableString 随机可读字符串

去掉0、O等相似字符

RandomUtil::readableString( $length )

• 参数：$length integer 长度
• 返回：string 字符串

lowerReadableString 随机可读字符串（小写）

RandomUtil::lowerReadableString( $length )

• 参数：$length integer 长度
• 返回：string 字符串

upperReadableString 随机可读字符串（大写）

RandomUtil::upperReadableString( $length )

• 参数：$length integer 长度
• 返回：string 字符串

hexString 随机Hex字符串

RandomUtil::hexString( $length )

• 参数：$length integer 长度
• 返回：string 字符串

lowerString 随机小写字符串

RandomUtil::lowerString( $length )

• 参数：$length integer 长度
• 返回：string 字符串

lowerChar 随机小写字符串

只包含字母

RandomUtil::lowerChar( $length )

• 参数：$length integer 长度
• 返回：string 字符串

upperChar 随机大写字符串

只包含字母

RandomUtil::upperChar( $length )

• 参数：$length integer 长度
• 返回：string 字符串

upperString 随机大写字符串

RandomUtil::upperString( $length )

• 参数：$length integer 长度
• 返回：string 字符串

uuid 随机UUID

使用年月日构造

RandomUtil::uuid( )

• 返回：string UUID

percent 随机概率

RandomUtil::percent( $value )

• 参数：$value integer 概率值
• 返回：boolean 是否成功

字符串处理 StrUtil

mbLimit 按照UTF8编码裁减字符串（汉字和英文都占1个宽度）

StrUtil::mbLimit( $text, $limit )

• 参数：$text string 待裁剪字符串
• 参数：$limit integer 裁剪长度
• 返回：string

mbLimitChars 按照UTF8编码裁减字符串（汉字占3个宽度、英文都占1个宽度）

StrUtil::mbLimitChars( $text, $limit )

• 参数：$text string 待裁剪字符串
• 参数：$limit integer 裁剪长度
• 返回：void

mbLength 计算UTF8字符串宽度（汉字和英文都占1个宽度）

StrUtil::mbLength( $text )

• 参数：$text string
• 返回：integer

wordSplit 中文分词，如果未安装分词模块，则使用正则表达式分词

StrUtil::wordSplit( $content )

• 参数：$content string 分词的内容
• 返回：array 分词结果

类型系统 TypeUtil / BaseType

ModStart\Core\Type\BaseType 是枚举类型接口，ModStart\Core\Type\TypeUtil 提供枚举类型工具方法。

BaseType 枚举类型接口

定义一个枚举类型类：

use ModStart\Core\Type\BaseType;

class BlogStatus implements BaseType
{
    const DRAFT = 1;
    const PUBLISHED = 2;
    const ARCHIVED = 3;

    public static function getList()
    {
        return [
            self::DRAFT => '草稿',
            self::PUBLISHED => '已发布',
            self::ARCHIVED => '已归档',
        ];
    }
}

TypeUtil::getList 获取枚举列表

TypeUtil::getList( $typeClass )

• 参数：$typeClass string 实现了 BaseType 的类名

在字段中使用枚举类型

// Select 下拉使用
$field->optionType(BlogStatus::class);

// Radio 单选使用
$field->optionType(BlogStatus::class);

// Type 字段显示（带颜色映射）
$field->type(BlogStatus::class, [
    BlogStatus::DRAFT => 'warning',
    BlogStatus::PUBLISHED => 'success',
    BlogStatus::ARCHIVED => 'default',
]);

其他常用工具类

EnvUtil 环境工具

ModStart\Core\Util\EnvUtil

CacheUtil 缓存工具

ModStart\Core\Util\CacheUtil

LogUtil 日志工具

ModStart\Core\Util\LogUtil

SessionUtil 会话工具

ModStart\Core\Util\SessionUtil

RouteUtil 路由工具

ModStart\Core\Util\RouteUtil

ConvertUtil 数据转换工具

ModStart\Core\Util\ConvertUtil

FormatUtil 格式化工具

ModStart\Core\Util\FormatUtil

TimeUtil 时间工具

ModStart\Core\Util\TimeUtil

CurlUtil 网络请求工具

ModStart\Core\Util\CurlUtil

HtmlUtil HTML工具

ModStart\Core\Util\HtmlUtil

SecureUtil 安全工具

ModStart\Core\Util\SecureUtil

IpUtil IP工具

ModStart\Core\Util\IpUtil

Tree工具 TreeUtil

itemsMergeLevel 为列表增加 _level 属性

TreeUtil::itemsMergeLevel( $items, $idName, $pidName, $sortName, $pid )

• 参数：$items array|Collection 数据记录
• 参数：$idName string ID字段名，默认为 id
• 参数：$pidName string 父级ID字段名，默认为 pid
• 参数：$sortName string 排序字段名，默认为 sort
• 参数：$pid int|string 父级ID，默认为 0
• 返回：Collection 返回带有 _level 属性的集合