用于模块开发的 API

API 旨在编写与脚本旧版本和未来版本兼容的扩展。如果您使用 API 从数据库获取数据,就可以确信这段代码在脚本未来版本中也能正常工作,从而简化新版本发布后的代码检查与适配。此外,在使用 API 时,您无需编写自己的数据读取函数,也无需额外连接和声明与数据库交互所需的类。只需连接 API 文件并开始使用其函数,其余工作都由它自动完成。

要在自己的模块中使用 API,您需要通过以下语句进行连接:

include ('engine/api/api.class.php');

同时,您无需考虑数据库连接是否存在、所需类是否已连接。该代码既可以在 DLE 脚本自身的文件中使用,也可以直接在其他与 DLE 无关的脚本中使用。这样,您就可以把 DLE 脚本与其他脚本(例如论坛)组织为标准化集成。

API 函数列表:

$dle_api->take_user_by_id( int $id [, string $select_list] );

根据用户 ID 获取其信息数组。可选参数 $select_list 指定需要读取的数据表字段列表,或者使用 * 读取全部字段。返回包含用户信息的数组;如果找不到用户,则返回 false。

$dle_api->take_user_by_name( string $name [, string $select_list]);

根据用户名获取用户信息数组。可选参数 $select_list 指定需要读取的数据表字段列表,或者使用 * 读取全部字段。返回包含用户信息的数组;如果找不到用户,则返回 false。

$dle_api->take_user_by_email( string $email [, string $select_list]);

根据用户 E-Mail 获取用户信息数组。可选参数 $select_list 指定需要读取的数据表字段列表,或者使用 * 读取全部字段。返回包含用户信息的数组;如果找不到用户,则返回 false。

$dle_api->take_users_by_group( int $group_id [, string $select_list [, int $limit]]);

根据用户组编号获取用户信息数组。可选参数 $select_list 指定需要读取的数据表字段列表。可选参数 $limit 指定返回用户数量的限制。返回包含用户信息的数组;如果找不到用户,则返回 false。

$dle_api->take_users_by_ip( string $ip, [, bool $like [, string $select_list [, int $limit]]]);

根据 IP 获取用户列表。第二个参数 $like 用于指定搜索时使用精确匹配还是模糊匹配。可选参数 $select_list 指定需要读取的数据表字段列表。可选参数 $limit 指定返回用户数量的限制。返回包含用户信息的数组;如果找不到用户,则返回 false。

$dle_api->change_user_name( int $user_id, string $new_name);

修改用户名。第一个参数是要修改登录名的用户 ID,第二个参数是用户的新登录名。返回值:如果执行成功则为 true,如果新名称已被其他用户占用则为 false。

$dle_api->change_user_pass( int $user_id, string $new_pass);

修改用户密码。第一个参数是要修改密码的用户 ID,第二个参数是用户的新密码。

$dle_api->change_user_email( int $user_id, string $new_email);

修改用户 E-Mail。第一个参数是要修改 E-Mail 的用户 ID,第二个参数是用户的新 E-Mail。返回值:1 - 执行成功,-1 - 新 E-Mail 已存在,-2 - E-Mail 格式不正确。

$dle_api->change_user_group( int $user_id, int $new_group);

修改用户组。第一个参数是要修改所属组的用户 ID,第二个参数是新的用户组 ID。返回值:如果执行成功则为 true,如果指定的组 ID 不存在则为 false。

$dle_api->external_auth( string $login, string $password);

使用登录名和密码进行授权。返回值:true - 授权成功,false - 登录名或密码不正确。

$dle_api->external_register( string $login, string $password, string $email, int $group);

在数据库中注册用户。函数接收以下参数:登录名、密码、E-mail 以及要注册用户的用户组编号。返回值:1 - 执行成功,-1 - 新登录名已存在,-2 - 新 E-Mail 已存在,-3 - E-Mail 格式不正确,-4 - 指定了不存在的用户组。

$dle_api->send_pm_to_user ( int $user_id, string $subject, string $text, string $from);

向用户发送私人消息。$user_id 是收件人 ID。$subject 是消息主题。$text 是消息内容。$from 是发送者登录名。返回值:1 - 执行成功,-1 - 未找到收件人,0 - 数据库错误。

$dle_api->load_table ( string $table [, string $fields [, string $where [, bool $multirow [, int $start [, int $limit [, string $sort [, string $sort_order]]]]]]]);

从数据表中获取信息。

$table - 表名

$fields - 需要读取的字段列表,以逗号分隔,或者使用 * 读取全部字段

$where - 查询条件

$multirow - 读取一行还是多行

$start - 查询起始位置

$limit - 查询记录数量,0 表示读取全部

$sort - 用于排序的字段

$sort_order - 排序方向

返回包含数据的数组;如果数据库中按指定参数未找到任何内容,则返回 false。

$dle_api->save_to_cache ( string $fname, mixed $vars);

把数据写入缓存文件。参数 $fname 指定缓存文件名,不包含扩展名。$vars 是要写入缓存的数据。

$dle_api->load_from_cache ( string $fname,  [, int $timeout [, string $type]]);

从缓存文件中读取数据。参数 $fname 指定缓存文件名,不包含扩展名。可选参数 $timeout 指定缓存信息被视为有效的秒数。如果缓存文件已过期,则函数返回 false。可选参数 $type 指定缓存中存储的数据类型;如果不是 'text',则认为保存的是数组并返回数组数据。

$dle_api->clean_cache (  [string $name] );

删除缓存。可选参数 $name 指定要删除的具体文件名,不含扩展名。

$dle_api->get_cached_files();

获取包含缓存文件名的数组。

$dle_api->edit_config ( mixed $key,  [, string $new_value]);

修改并保存脚本设置。

参数 $key 为字符串或数组。如果是字符串,则表示参数名称;如果是数组,则表示参数的关联数组。

参数 $new_value - 参数值。如果 $key 为数组,则不使用该参数。

$dle_api->take_news ( string $cat,  [, string $fields [, int $start [, int $limit [, string $sort [, string $sort_order]]]]]);

获取新闻。

$cat - 新闻分类,以逗号分隔

$fields - 需要读取的新闻字段列表,或者使用 * 读取全部字段

$start - 查询起始位置

$limit - 查询新闻数量,0 表示读取全部新闻

$sort - 用于排序的字段

$sort_order - 排序方向

返回包含新闻的二维关联数组。

$dle_api->checkGroup ( int $group );

检查指定的用户组是否存在。返回值:如果该用户组存在则为 true,如果不存在则为 false。

$dle_api->install_admin_module ( string $name, string $title, string $descr, string $icon [, string $perm] );

把第三方模块安装到脚本管理面板中。

$name - 模块名称,即位于 engine/inc/ 文件夹中的 .php 文件名,但不含扩展名

$title - 模块标题

$descr - 模块说明

$icon - 模块图标名称,不含路径。

$perm - 允许显示该模块的用户组信息。该字段可以采用以下值:all 或以逗号分隔的用户组 ID,例如:1,2,3。如果指定值为 all,则模块会显示给所有有权访问管理面板的用户。

$dle_api->uninstall_admin_module ( string $name );

从脚本管理面板中卸载第三方模块。

$name - 要删除的模块名称

$dle_api->change_admin_module_perms ( string $name, string $perm );

修改允许在脚本管理面板中显示第三方模块的用户组。

$name - 模块名称

$perm - 允许显示该模块的用户组信息。该字段可以采用以下值:all 或以逗号分隔的用户组 ID,例如:1,2,3。如果指定值为 all,则模块会显示给所有有权访问管理面板的用户。