Zibll 附加插件开发指南

function yourprefix_shortcode_demo($atts, $content = null)
{
    $atts = shortcode_atts(array(
        'title' => '默认标题',
    ), $atts);

    // 注意：短代码必须 return，不能 echo
    return '<div class="zib-widget"><h4>' . esc_html($atts['title']) . '</h4></div>';
}
add_shortcode('yourprefix_demo', 'yourprefix_shortcode_demo');

function yourprefix_shortcode_demo($atts, $content = null)
{
    $atts = shortcode_atts(array(
        'title' => '默认标题',
    ), $atts);

    // 注意：短代码必须 return，不能 echo
    return '<div class="zib-widget"><h4>' . esc_html($atts['title']) . '</h4></div>';
}
add_shortcode('yourprefix_demo', 'yourprefix_shortcode_demo');

// main.js 中提供的辅助函数
function zib__(key) {
    var map = window._win && window._win.i18n;
    return map && Object.prototype.hasOwnProperty.call(map, key) ? map[key] : key;
}

// 使用示例
notyf(zib__('processing'), 'load');
console.log(zib__('confirm_delete'));

// 在插件中添加自定义i18n字符串
add_filter('zib_js_i18n_strings', function($strings) {
    $strings['my_plugin_confirm'] = __('我的插件确认提示', 'my-plugin');
    $strings['my_plugin_success'] = __('操作成功', 'my-plugin');
    $strings['my_plugin_error'] = __('操作失败', 'my-plugin');
    return $strings;
});

// 简单查询
$db = new zib_db();
$results = $db->table('posts')
    ->where(['post_status' => 'publish'])
    ->limit(10)
    ->get();

// 复杂条件查询
$results = $db->table('posts', 'p')
    ->join('postmeta', 'pm', 'p.ID = pm.post_id')
    ->where([
        'p.post_status' => 'publish',
        'pm.meta_key'   => '_thumbnail_id'
    ])
    ->select('p.ID, p.post_title, pm.meta_value')
    ->orderBy('p.post_date', 'DESC')
    ->limit(10)
    ->get();

// 插入数据
$db->table('custom_table')->insert([
    'name'  => 'test',
    'value' => 123
]);

// 更新数据
$db->table('custom_table')
    ->where(['id' => 1])
    ->update(['value' => 456]);

// 删除数据
$db->table('custom_table')
    ->where(['id' => 1])
    ->delete();

// 获取用户总数
$total = $db->table('users')->count('ID');

// 计算订单总金额
$revenue = $db->table('orders')
    ->where(['status' => 'completed'])
    ->sum('amount');

// 获取平均评分
$avg_score = $db->table('posts')->avg('rating');

// 检查文件是否存在(区分大小写)
if (ZibFile::file_exists_case($filename)) {
    // 文件存在
}

// 检查路径是否可读/可写
if (ZibFile::path_readable($path)) { }
if (ZibFile::path_writeable($path)) { }

// 获取文件信息
$info = ZibFile::getFileInfo('/path/to/file.jpg');
// 返回: ['name', 'size', 'type', 'mtime', ...]

// 创建目录(递归)
ZibFile::mkdirs('/path/to/new/dir');

// 删除目录(递归)
ZibFile::rmdirs('/path/to/dir');

// 复制文件/目录
ZibFile::copy('/source', '/dest');

// 移动文件/目录
ZibFile::move('/source', '/dest');

// 获取文件扩展名
$ext = ZibFile::getExtension('photo.jpg'); // 返回 'jpg'

// 格式化文件大小
$size = ZibFile::formatSize(1024 * 1024); // 返回 '1 MB'

// 安全写入文件
ZibFile::writeFile('/path/to/file.txt', $content);

// 读取文件内容
$content = ZibFile::readFile('/path/to/file.txt');

// 发送短信验证码
$result = ZibSMS::send('13800138000', '123456', 'ali');
// 返回: ['error' => 0, 'msg' => '发送成功'] 或 ['error' => 1, 'msg' => '错误信息']

// 验证手机号格式
if (ZibSMS::is_phonenumber('13800138000')) {
    // 格式正确
}

// 生成二维码图片
QRcode::png('https://example.com', $outfile = false, $level = QR_ECLEVEL_L, $size = 4);

// 生成二维码SVG
QRcode::svg('https://example.com', $outfile = false);

// 参数说明:
// - $text: 二维码内容
// - $outfile: 输出文件路径,false则直接输出
// - $level: 纠错级别(L/M/Q/H)
// - $size: 像素大小

// 发送邮件(封装wp_mail)
zib_send_mail($to, $subject, $message, $headers = array());

// 发送HTML邮件
zib_send_html_mail($to, $subject, $html_content);

// 前台投稿页面
'newposts_sidebar_top'    // 前台投稿-侧边栏顶部
'newposts_sidebar_bottom' // 前台投稿-侧边栏底部

// 动态页面侧边栏（根据页面设置生成）
'page_top_fluid_123'      // [页面:XXX]-顶部全宽度
'page_sidebar_123'        // [页面:XXX]-侧边栏

// 论坛相关侧边栏ID示例
'bbs_plate_sidebar'       // 版块侧边栏
'bbs_posts_sidebar'       // 帖子页侧边栏

// 商城相关侧边栏ID示例
'shop_product_sidebar'    // 商品页侧边栏
'shop_cart_sidebar'       // 购物车侧边栏

// 在你的插件中，可以直接向已有侧边栏添加小工具
add_action('widgets_init', function() {
    // 注册自定义小工具到特定侧边栏
    register_widget('YourPrefix_Custom_Widget');
});

if (is_active_sidebar('home_top_fluid')) {
    dynamic_sidebar('home_top_fluid');
}

add_action('widgets_init', function() {
    register_sidebar(array(
        'name'          => __('我的插件侧边栏', 'my-plugin'),
        'id'            => 'my_plugin_sidebar',
        'description'   => __('我的插件专用侧边栏', 'my-plugin'),
        'before_widget' => '<div class="zib-widget %2$s">',
        'after_widget'  => '</div>',
        'before_title'  => '<h3>',
        'after_title'   => '</h3>',
    ));
});

// 简单获取选项值
$value = _pz('option_name');

// 带默认值
$value = _pz('option_name', 'default_value');

// 获取嵌套数组的子项
$subvalue = _pz('parent_option', false, 'child_key');

/**
 * @param string $name     选项的名称
 * @param mixed  $default  如果未找到选项，则返回的默认值
 * @param string $subname  （可选）如果选项是嵌套数组，则为选项的子名称
 * @return mixed           选项的值，如果未找到则返回默认值
 */
function _pz($name, $default = false, $subname = '')

// 检查功能是否启用
if (_pz('pay_balance_s')) {
    // 余额功能已启用
}

// 获取配置值（带默认值）
$cache_ttl = _pz('cache_time', 3600);

// 获取嵌套配置
$wechat_config = _pz('oauth_weixin', false, 'appid');

function _pz($name, $default = false, $subname = '')
{
    static $options = null;
    if ($options === null) {
        $options = get_option('zibll_options'); // 只执行一次
    }
    
    if (isset($options[$name])) {
        if ($subname) {
            return isset($options[$name][$subname]) ? $options[$name][$subname] : $default;
        } else {
            return $options[$name];
        }
    }
    return $default;
}

// 更新单个选项
_spz('option_name', 'new_value');

// 获取缓存
$cache = wp_cache_get($key, $group, $force);

// 设置缓存
wp_cache_set($key, $data, $group, $expire);

// 删除缓存
wp_cache_delete($key, $group);

// 刷新所有缓存
wp_cache_flush();

// 获取头像（带缓存）
function zib_get_data_avatar($user_id = '', $size = '', $alt = '')
{
    $cache = wp_cache_get($user_id, 'user_avatar', true);
    if (false === $cache) {
        $avatar = zib_get_avatar(null, $user_id, $args);
        wp_cache_set($user_id, $avatar, 'user_avatar');
    } else {
        $avatar = $cache;
    }
    return $avatar;
}

// 更新头像时清除缓存
add_action('user_save_custom_avatar', function ($user_id) {
    wp_cache_delete($user_id, 'user_avatar');
    zib_get_data_avatar($user_id);
}, 10);

// 获取用户评论数（带缓存）
function get_user_comment_count($user_id, $comments_status = 'approve', $cut = true)
{
    $cache_num = wp_cache_get($user_id, 'user_comment_' . $comments_status . '_count', true);
    
    if (false === $cache_num) {
        $args = array(
            'user_id'   => $user_id,
            'status'    => $comments_status,
            'count'     => true,
            'post_type' => ['post'],
        );
        $count = get_comments($args);
        wp_cache_set($user_id, $count, 'user_comment_' . $comments_status . '_count');
    } else {
        $count = $cache_num;
    }
    
    return $cut ? _cut_count($count) : (int) $count;
}

// 评论状态变化时清除缓存
add_action('transition_comment_status', 'zib_comment_del_cache_status', 10, 3);
add_action('comment_post', 'zib_comment_del_cache', 10);

// SVG图标精灵缓存（24小时）
function zib_output_svg_sprite() {
    $cache_key = 'zib_svg_sprite_v1';
    $svg_sprite = get_transient($cache_key);
    
    if ($svg_sprite === false) {
        // 生成SVG内容...
        set_transient($cache_key, $svg_sprite, 24 * HOUR_IN_SECONDS);
    }
    
    echo $svg_sprite;
}

function myplugin_get_expensive_data($id)
{
    $cache_key = 'myplugin_data_' . $id;
    $cache_group = 'myplugin';
    
    // 尝试从缓存获取
    $data = wp_cache_get($cache_key, $cache_group);
    
    if (false === $data) {
        // 缓存未命中，执行耗时操作
        $data = expensive_database_query($id);
        
        // 存入缓存（有效期1小时）
        wp_cache_set($cache_key, $data, $cache_group, 3600);
    }
    
    return $data;
}

// 数据更新时清除缓存
add_action('myplugin_data_updated', function($id) {
    wp_cache_delete('myplugin_data_' . $id, 'myplugin');
});

// 获取缓存（带自动重建机制）
zib_cache_get($key, $group, $callback, $expire = 0);

// 设置缓存
zib_cache_set($key, $value, $group, $expire = 0);

// 删除缓存
zib_cache_delete($key, $group);

// 清除整个缓存组
zib_cache_flush_group($group);

// 获取或创建缓存（不存在时自动执行回调）
$result = zib_cache_get('my_plugin_data', 'my_plugin', function() {
    return expensive_query();
}, 3600);

// 设置缓存（有效期1小时）
zib_cache_set('my_plugin_result', $data, 'my_plugin', 3600);

// 删除指定缓存
zib_cache_delete('my_plugin_data', 'my_plugin');

// 清除整个缓存组
zib_cache_flush_group('my_plugin');

use Zib\Meilisearch\Client;

// 创建客户端
$client = new Client('http://localhost:7700', 'masterKey');

// 获取索引
$index = $client->index('posts');

// 添加文档
$index->addDocuments([
    ['id' => 1, 'title' => '文章标题', 'content' => '文章内容'],
]);

// 搜索
$results = $index->search('关键词', [
    'limit' => 20,
    'filter' => 'post_status = publish',
]);

// 删除文档
$index->deleteDocument(1);

// 清空索引
$index->deleteAllDocuments();

// 主题更新时显示插件提示
add_action('zibll_update_notices', function ($version) {
    ?>
    <div class="notice notice-info">
        <p><?php printf(__('你的插件 v%s 已就绪，请查看 %s设置页%s。', 'your-textdomain'),
            YOURPLUGIN_VERSION,
            '<a href="' . admin_url('admin.php?page=yourplugin_options') . '">',
            '</a>'
        ); ?></p>
    </div>
    <?php
});

// 主题新安装时显示
add_action('zibll_new_install_notices', function ($version) {
    // 同上格式
});

// 在插件激活或特定版本时执行升级任务
function yourprefix_upgrade_to_1_1()
{
    // 数据迁移、建表等
}
register_activation_hook(__FILE__, function () {
    $version = get_option('yourprefix_version', '0.0.0');
    if (version_compare($version, '1.1.0', '<')) {
        yourprefix_upgrade_to_1_1();
        update_option('yourprefix_version', '1.1.0');
    }
});

// 使用 switcher（主题内广泛使用，稳定可靠）
array(
    'id'      => 'enabled',
    'type'    => 'switcher',
    'title'   => __('启用功能', 'your-textdomain'),
    'default' => true,
),

// 或使用 checkbox（兼容性最佳）
array(
    'id'      => 'enabled_alt',
    'type'    => 'checkbox',
    'title'   => __('启用功能（备选）', 'your-textdomain'),
    'default' => '1', // 字符串 '1'/'0' 而非布尔值
),

function yourprefix_ajax_handler() {
    // 1. 权限检查（优先）
    if (!current_user_can('edit_posts')) {
        wp_send_json_error(array('msg' => '权限不足'), 403);
    }

    // 2. Nonce 验证
    check_ajax_referer('yourprefix_nonce', 'nonce');

    // 3. 参数验证
    if (!isset($_POST['data']) || empty($_POST['data'])) {
        wp_send_json_error(array('msg' => '参数错误'), 400);
    }

    // 4. 参数清理
    $data = sanitize_text_field(wp_unslash($_POST['data']));

    // 5. 业务逻辑
    try {
        $result = yourprefix_process_data($data);
        wp_send_json_success(array('result' => $result));
    } catch (Exception $e) {
        wp_send_json_error(array('msg' => '处理失败'), 500);
    }
}

// 注册钩子（仅登录用户访问）
add_action('wp_ajax_yourprefix_action', 'yourprefix_ajax_handler');
// add_action('wp_ajax_nopriv_yourprefix_action', 'yourprefix_ajax_handler'); // 公开接口取消注释

$data = array(
    'value' => 100,           // 变动值（正数增加，负数减少）
    'type'  => 'manual_add',  // 变动类型标识
    'desc'  => '手动增加余额', // 变动描述
);
zibpay_update_user_balance($user_id, $data);

/**
 * 获取用户余额（带兼容性封装）
 */
function yourprefix_get_user_balance($user_id) {
    if (function_exists('zibpay_get_user_balance')) {
        return zibpay_get_user_balance($user_id);
    }
    // Fallback：直接读取 meta（不推荐，仅作最后兜底）
    $balance = get_user_meta($user_id, 'balance', true);
    return floatval($balance);
}

/**
 * 更新用户余额（必须走主题统一接口）
 */
function yourprefix_update_user_balance($user_id, $amount, $type = 'add', $desc = '') {
    if (!function_exists('zibpay_update_user_balance')) {
        yourprefix_log_error('zibpay_update_user_balance 函数不存在');
        return false;
    }

    $data = array(
        'value' => $type === 'add' ? $amount : -$amount,
        'type'  => $desc,
        'desc'  => $desc,
    );

    return zibpay_update_user_balance($user_id, $data);
}

// 正确：使用 section id 作为 parent
CSF::createSection($options_key, array(
    'id'     => 'parent_section',
    'title'  => '父级设置',
    'icon'   => 'fa fa-folder',
    // 父 section 不包含 fields，仅作为容器
));

CSF::createSection($options_key, array(
    'id'     => 'child_section',
    'title'  => '子级设置',
    'parent' => 'parent_section', // 使用 id，不是 '父级设置'
    'fields' => array(
        // 字段定义
    ),
));

// 启用调试模式
define('WP_DEBUG', true);

// 记录错误到日志文件
define('WP_DEBUG_LOG', true);  // 日志位置：wp-content/debug.log

// 不在页面显示错误（生产环境建议 false）
define('WP_DEBUG_DISPLAY', false);

// 保存数据库查询（性能调试）
define('SAVEQUERIES', true);

/**
 * 记录错误日志
 */
function yourprefix_log_error($message, $data = array()) {
    if (WP_DEBUG) {
        $log_data = !empty($data) ? ' | Data: ' . print_r($data, true) : '';
        error_log('[YourPlugin] ' . $message . $log_data);
    }
}

/**
 * 调试输出（仅开发环境）
 */
function yourprefix_debug($data, $label = '') {
    if (!WP_DEBUG || !is_admin()) return;
    
    $label = $label ? "<strong>$label:</strong><br>" : '';
    echo "<pre style='background:#fff; padding:10px; border:1px solid #ccc; margin:10px;'>";
    echo $label;
    var_dump($data);
    echo "</pre>";
}

/**
 * 安全的选项读取（带默认值）
 */
function yourprefix_get_option($key, $default = false) {
    static $options = null;
    
    // 开发环境不缓存，便于调试
    if (WP_DEBUG) {
        $options = get_option('yourplugin_options');
        return isset($options[$key]) ? $options[$key] : $default;
    }
    
    if ($options === null) {
        $options = get_option('yourplugin_options');
    }
    return isset($options[$key]) ? $options[$key] : $default;
}

/**
 * 获取选项（带多层缓存）
 */
function yourprefix_get_option($key, $default = false) {
    $cache_key = 'yourplugin_option_' . $key;
    
    // 尝试从 WP 缓存获取
    if (function_exists('wp_cache_get')) {
        $cached = wp_cache_get($cache_key, 'yourplugin');
        if ($cached !== false) {
            return $cached;
        }
    }
    
    // 静态缓存作为备选
    static $options = null;
    if ($options === null) {
        $options = get_option('yourplugin_options', array());
    }
    
    $value = isset($options[$key]) ? $options[$key] : $default;
    
    // 设置 WP 缓存（有效期5分钟）
    if (function_exists('wp_cache_set')) {
        wp_cache_set($cache_key, $value, 'yourplugin', 300);
    }
    
    return $value;
}

/**
 * 更新选项（同时清理缓存）
 */
function yourprefix_update_option($key, $value) {
    $options = get_option('yourplugin_options', array());
    $options[$key] = $value;
    update_option('yourplugin_options', $options);
    
    // 清理相关缓存
    if (function_exists('wp_cache_delete')) {
        wp_cache_delete('yourplugin_option_' . $key, 'yourplugin');
        wp_cache_delete('yourplugin_options', 'yourplugin');
    }
}

/**
 * 获取帖子列表（优化版）
 */
function yourprefix_get_posts($args = array()) {
    $defaults = array(
        'post_type'              => 'post',
        'post_status'            => 'publish',
        'posts_per_page'         => 10,
        'no_found_rows'          => true,           // 不需要总条数时设置为true
        'update_post_term_cache' => false,         // 不需要分类缓存时关闭
        'update_post_meta_cache' => false,         // 不需要meta缓存时关闭
        'ignore_sticky_posts'    => true,
        'fields'                 => 'ids',         // 只需要ID时使用
    );
    
    $args = wp_parse_args($args, $defaults);
    $query = new WP_Query($args);
    
    return $query->posts;
}

function yourprefix_render_post($post) {
    if (!is_object($post)) return;
    
    ?>
    <article id="post-<?php echo esc_attr($post->ID); ?>" class="post-card">
        <h2><a href="<?php echo esc_url(get_permalink($post->ID)); ?>">
            <?php echo esc_html(get_the_title($post->ID)); ?>
        </a></h2>
        <div class="post-content">
            <?php echo wp_kses_post(get_the_content($post->ID)); ?>
        </div>
        <script>
            var postData = {
                id: <?php echo absint($post->ID); ?>,
                title: '<?php echo esc_js(get_the_title($post->ID)); ?>'
            };
        </script>
    </article>
    <?php
}

/**
 * 检查当前用户是否具有指定能力
 * 
 * @param string $capability 能力名称
 * @param mixed ...$args 额外参数（某些能力需要）
 * @return bool
 */
function zib_current_user_can($capability, ...$args)

// 常用能力示例:
if (zib_current_user_can('new_post_add')) { /* 能否发布文章 */ }
if (zib_current_user_can('comment_view', $post)) { /* 能否查看评论 */ }
if (zib_current_user_can('view_order', $order)) { /* 能否查看订单 */ }
if (zib_current_user_can('order_close', $order)) { /* 能否关闭订单 */ }

/**
 * 检查用户权限（带日志记录）
 */
function yourprefix_current_user_can($capability, $object = null) {
    // 管理员拥有所有权限
    if (current_user_can('administrator')) {
        return true;
    }
    
    // 检查标准权限
    if (current_user_can($capability)) {
        return true;
    }
    
    // 对象级权限检查（如订单、帖子等）
    if ($object && is_object($object)) {
        // 检查对象所有者
        if (isset($object->user_id) && $object->user_id == get_current_user_id()) {
            return true;
        }
    }
    
    yourprefix_log_error('权限检查失败', array(
        'capability' => $capability,
        'user_id' => get_current_user_id()
    ));
    
    return false;
}

/**
 * AJAX权限检查快捷函数
 */
function yourprefix_check_ajax_permission($capability = 'edit_posts') {
    if (!is_user_logged_in()) {
        wp_send_json_error(array('msg' => '请先登录'), 401);
    }
    
    if (!current_user_can($capability)) {
        wp_send_json_error(array('msg' => '权限不足'), 403);
    }
}

your-plugin/
├── your-plugin.php              # 入口文件（依赖检测 + 自动加载）
├── inc/
│   ├── core/
│   │   ├── bootstrap.php        # 初始化与依赖检测
│   │   ├── hooks.php            # 钩子注册中心
│   │   └── autoloader.php       # 自动加载器
│   ├── admin/
│   │   ├── options.php          # CSF 后台选项
│   │   ├── menus.php            # 后台菜单注册
│   │   └── notices.php          # 后台通知
│   ├── frontend/
│   │   ├── shortcodes.php       # 短代码注册
│   │   ├── widgets.php          # 小工具
│   │   └── templates.php        # 模板函数
│   ├── ajax/
│   │   ├── handlers.php         # AJAX 处理器
│   │   └── endpoints.php        # REST API 端点
│   └── utils/
│       ├── validators.php       # 验证工具
│       ├── sanitizers.php       # 清理工具
│       └── helpers.php          # 辅助函数
├── assets/
│   ├── css/
│   │   ├── frontend.css         # 前台样式
│   │   └── admin.css            # 后台样式
│   ├── js/
│   │   ├── frontend.js          # 前台脚本
│   │   └── admin.js             # 后台脚本
│   └── images/                  # 图片资源
├── languages/                   # 语言包
│   └── your-plugin-zh_CN.mo/po
├── templates/                   # 模板文件（可选）
└── README.md                    # 说明文档