# WordPress 框架指南 > 适用于：WordPress 6.0+、PHP 8.0+、插件开发、主题开发、REST API、块编辑器 (Gutenberg) 语言指南：@.claude/skills/php-guide/SKILL.md ## 概述 WordPress 是一个内容管理系统 (CMS)，为超过 40% 的网络提供支持。本指南涵盖现代 WordPress 开发，包括插件架构、主题开发、REST API 端点、块编辑器 (Gutenberg) 和安全要点。 **在以下情况下使用 WordPress：** * 需要内容管理系统 * 博客或发布平台 * 使用 WooCommerce 进行电子商务 * 具有熟悉的管理 UI 的自定义应用程序 * 利用现有生态系统进行快速原型设计 **在以下情况下考虑替代方案：** * 构建纯API后端（使用Laravel/Symfony） * 高性能要求（考虑无头） * 复杂的业务逻辑应用 * 微服务架构 ## 护栏 ### WordPress 特定规则 * 在所有 PHP 文件中使用 `declare(strict_types=1)` * 防止直接文件访问： `if (!define('ABSPATH')) { exit; }` * 对所有插件/主题类使用命名空间 * 转义所有输出：`esc_html()`、`esc_attr()`、`esc_url()`、`wp_kses_post()` * 清理所有输入：`sanitize_text_field()`、`sanitize_email()`、`absint()` * 验证所有表单提交和 AJAX 请求的随机数 * 在执行操作之前检查功能：`current_user_can()` * 对所有数据库查询使用`$wpdb->prepare()`（从不连接） * 通过`wp_enqueue_scripts`钩子注册所有脚本/样式 * 对所有面向用户的字符串使用文本域和 `__()` / `_e()` * 为需要 Gutenberg/REST 支持的帖子类型和分类设置 `show_in_rest => true` * 使用 `register_post_meta()` 在 REST API 中公开元字段 * 始终包含 `uninstall.php` 或 `register_uninstall_hook()` 进行清理 ### 反模式 * 不要使用 `query_posts()` （使用 `WP_Query` 或 `get_posts()`） * 不要修改核心文件（使用钩子和过滤器） * 不要硬编码 URL（使用 `home_url()`、`admin_url()`、`plugin_dir_url()`） * 不要将业务逻辑存储在模板文件中 * 不要跳过任何表单或 AJAX 处理程序上的随机数验证 * 不要对不受信任的数据使用`extract()` * 不要回显未经处理的用户输入 * 不要在未经清理的情况下直接使用`$_GET`/`$_POST` ## 项目结构 ### 插件结构我的插件/ ├── my-plugin.php # 主插件文件（标头、常量、引导程序） ├── 包括/ │ ├── class-plugin.php # 主插件类（单例） │ ├── class-activator.php # 激活钩子 │ ├── class-deactivator.php # 停用钩子 │ ├── 管理/ │ │ ├── class-admin.php # 管理功能 │ │ └── 部分/ # 管理模板 │ ├── 公开/ │ │ ├── class-public.php # 公共功能 │ │ └──partials/ # 公共模板 │ ├── API/ │ │ └── class-rest-api.php # REST API 端点 │ └── 积木/ │ └── my-block/ # 古腾堡块 ├── 资产/ │ ├── css/ │ ├── js/ │ └── 图片/ ├── languages/ # 翻译文件(.pot, .po, .mo) ├── templates/ # 可覆盖的模板文件 ├── 测试/phpunit/ ├── 作曲家.json ├── package.json └── readme.txt # WordPress.org 自述文件 ### 主题结构我的主题/ ├── style.css # 主题元数据（必填） ├──functions.php # 主题设置和挂钩 ├── index.php # 后备模板（必填） ├── header.php / footer.php # 页眉/页脚模板 ├── single.php / page.php # 单篇文章/页面模板 ├── archive.php / 404.php # 存档/错误模板 ├── search.php / sidebar.php # 搜索/侧边栏模板 ├── inc/ # 定制器、模板函数、钩子 ├── template-parts/ # 可重用的内容部分 ├── 资产/ # CSS、JS、图片 ├── 零件/ # 模板零件（FSE） ├── Patterns/ # 块模式 ├── templates/ # 块模板（FSE） └── theme.json # 主题配置（FSE） ## 模板层次结构 WordPress 按照从最具体到最不具体的顺序解析模板。模式：`{type}-{slug}.php -> {type}-{id}.php -> {type}.php -> index.php` * **单个** : `single-{post-type}-{slug}` -> `single-{post-type}` -> `single` -> `singular` -> `index` * **页面** : `page-{slug}` -> `page-{id}` -> `page` -> `singular` -> `index` * **存档** : `archive-{post-type}` -> `archive` -> `index` * **类别** : `category-{slug}` -> `category-{id}` -> `category` -> `archive` -> `index` * **分类法** : `taxonomy-{tax}-{term}` -> `taxonomy-{tax}` -> `taxonomy` -> `archive` * **搜索/404** : `search.php` / `404.php` -> `index.php` ## 插件基础知识 ### 主插件文件 init(); }); ### 单例插件类 30); add_filter('post_class', [$this, 'addPostClasses'], 10, 3); // 自定义钩子（用于扩展性） do_action('my_plugin_after_save', $postId, $data); $value = apply_filters('my_plugin_format_price', $price, $currency); ### 资产排队公共函数 enqueueAssets(): void { wp_enqueue_style('my-plugin-style', MY_PLUGIN_URL . 'assets/css/public.css', [], MY_PLUGIN_VERSION); wp_enqueue_script('my-plugin-script', MY_PLUGIN_URL . 'assets/js/public.js', ['jquery'], MY_PLUGIN_VERSION, true); wp_localize_script('我的插件脚本', 'MyPluginData', [ 'ajaxUrl' => admin_url('admin-ajax.php'), 'nonce' => wp_create_nonce('my_plugin_nonce'), '字符串' => [ '正在加载' => __('正在加载...', '我的插件'), 'error' => __('发生错误。', '我的插件'), ], ]); } ## 休息 API ### 自定义端点模式命名空间, '/' . $this->rest_base, [ [ '方法' => WP_REST_Server::可读， '回调' => [$this, 'getItems'], 'permission_callback' => [$this, 'getItemsPermissions'], 'args' => $this->getCollectionParams(), ], [ '方法' => WP_REST_Server::CREATABLE, '回调' => [$this, 'createItem'], 'permission_callback' => [$this, 'createItemPermissions'], ], ]); } 公共函数 getItems(WP_REST_Request $request): WP_REST_Response { $query = 新 \WP_Query([ 'post_type' => '书', 'posts_per_page' => $request->get_param('per_page') ?? 10、 '分页' => $request->get_param('page') ?? 1、 ]); $items = array_map(fn($post) => $this->formatItem($post), $query->posts); $response = new WP_REST_Response($items, 200); $response->header('X-WP-Total', $query->found_posts); $response->header('X-WP-TotalPages', $query->max_num_pages); 返回$响应； } 公共函数 getItemsPermissions(): bool { return true; } 公共函数 createItemPermissions(): bool { return current_user_can('publish_posts'); } } **REST API 约定：** * 扩展“WP_REST_Controller”以获得完整的 CRUD 端点 * 始终定义 `permission_callback` （使用 `__return_true` 来实现真正的公共） * 使用“args”中的“sanitize_callback”清理输入参数 * 返回“WP_Error”以获取具有正确状态代码的错误响应 * 使用分页标题：`X-WP-Total`、`X-WP-TotalPages` * 版本化你的命名空间：`my-plugin/v1` ## 块编辑器（古腾堡） ### 块注册 (PHP) // 从 block.json 注册（首选） register_block_type(MY_PLUGIN_PATH.'块/我的块'); // 带有服务器渲染的动态块 register_block_type('我的插件/特色项目', [ 'render_callback' => [$this, 'renderFeaturedItems'], '属性' => [ '计数' => ['类型' => '数字', '默认' => 3], ], ]); ### 块.json { "$schema": "https://schemas.wp.org/trunk/block.json", “api版本”：3， “名称”：“我的插件/我的块”， “版本”：“1.0.0”， "title": "我的区块", "类别": "小部件", "icon": "管理通用", “支持”：{ “html”：假， “对齐”：[“宽”，“全”]， “颜色”：{“背景”：true，“文本”：true }， “间距”：{“边距”：true，“填充”：true } }, “属性”：{ “内容”：{“类型”：“字符串”，“默认”：“”} }, “textdomain”：“我的插件”， "editorScript": "文件:./index.js", "editorStyle": "文件:./index.css", "style": "文件:./style-index.css", “渲染”：“文件：./render.php” } ### 阻止 JavaScript (index.js) 从'@wordpress/blocks'导入{registerBlockType}；从 '@wordpress/block-editor' 导入 { useBlockProps, InspectorControls }; 从'@wordpress/components'导入{PanelBody，ToggleControl}；从 '@wordpress/i18n' 导入 { __ }；从 '@wordpress/server-side-render' 导入 ServerSideRender； registerBlockType('我的插件/我的块', { 编辑：({ 属性，setAttributes }) => { const blockProps = useBlockProps(); 返回（ <> <检查器控件> <切换控制标签={__('显示图像', '我的插件')} 检查= {attributes.showImage} onChange={(val) => setAttributes({ showImage: val })} />

）； }, save: () => null, // 动态块：服务器端渲染 }); ## 安全要点 ### 输入清理 $title = sanitize_text_field($_POST['title']); $email = sanitize_email($_POST['email']); $url = esc_url_raw($_POST['url']); $content = wp_kses_post($_POST['content']); $filename = sanitize_file_name($_POST['filename']); $key = sanitize_key($_POST['key']); $int = absint($_POST['number']); ### 输出转义回声 esc_html($标题); // HTML 上下文回声 esc_attr($属性); // 属性上下文回声 esc_url($url); // URL 上下文回声 esc_js($script); // JS 上下文回声 wp_kses_post($内容); // 允许安全 HTML ### 随机数验证 // 在表单中生成nonce字段 wp_nonce_field('my_action', 'my_nonce'); // 提交时验证随机数 if (!wp_verify_nonce($_POST['my_nonce'], 'my_action')) { wp_die(__('安全检查失败。', '我的插件')); } // AJAX 随机数检查 check_ajax_referer('my_plugin_nonce', 'nonce'); ### 能力检查 if (!current_user_can('edit_posts')) { wp_die(__('权限不足。', '我的插件')); } // REST API权限回调 'permission_callback' => fn() => current_user_can('edit_post', $id) ## 命令参考 # 开发 npm run build # 构建块/资产 npm run start # 块的监视模式作曲家安装 # PHP 依赖项 # 测试 ./vendor/bin/phpunit # 运行测试 ./vendor/bin/phpunit --coverage-html 覆盖率 # 覆盖率报告 # 代码质量 ./vendor/bin/phpcs # PHP CodeSniffer (WPCS) ./vendor/bin/phpcbf # 自动修复编码标准 ./vendor/bin/phpstananalyze # 静态分析 # WP-CLI 要点 wp plugin activate my-plugin # 激活插件 wp plugin list --status=active # 列出活动插件 wp theme activate my-theme # 激活主题 wp db export backup.sql # 数据库备份 wp 帖子列表 --post_type=book # 列出帖子 wpcacheflush# 清除对象缓存 wp瞬态删除 --all # 清除瞬态 wp cron event run --all # 运行计划的事件 wp rewritelush #刷新重写规则 ### 自定义 WP-CLI 命令如果（定义（'WP_CLI'）&& WP_CLI）{ WP_CLI::add_command('mycommand', MyPlugin\CLI\MyCommand::class); } ## 高级主题有关详细模式和完整实现示例，请参阅： * [references/patterns.md]() \-- 自定义帖子类型、分类法、元框、古腾堡块、WooCommerce 集成、数据库操作、测试、缓存、性能 ## 外部参考 * [WordPress 开发者资源]() * [插件开发者手册]() * [主题开发者手册]() * [REST API 手册]() * [块编辑器手册]() * [WordPress 编码标准]() * [WP-CLI 文档]()

文字新闻

包含技能