README

WordPress 设置 API 框架

此 PHP 包有助于加快您在 WordPress 管理员中设置屏幕的开发速度。该框架允许您轻松地向 WordPress 管理员添加选项、设置部分和管理页面，包括根据 WordPress 设置 API 和最佳编码标准管理注册、清理、正确添加和显示设置。

对谁有用

WPSettings 框架旨在帮助插件和主题开发者快速创建一致的 WordPress 管理界面，无论项目大小。对于将 WordPress 作为“备胎”使用且可能不太熟悉 WordPress 特性和其专有逻辑的开发者来说，它特别有用。

使用此类框架来帮助您与 WordPress 设置 API 交互是否过度？依赖您无法控制的代码是否安全？

经过10多年的深入 WordPress 开发，包括始终显示为 WordPress 本土的管理界面，我主要为了自己的使用而编写了这个框架，它已成为我在所有项目中使用的东西。简单来说，这为我节省了大量时间和麻烦！

至于安全性，该库完全开源，您可以在 GitHub 上分叉它，根据自己的喜好进行定制，甚至创建一个 pull request 以允许他人从您的新功能中受益。代码将保持公开并对所有人可用。如果您想建议功能或参与功能投票或简单地支持项目，非常欢迎您这样做。

工作原理

WPSettings 框架

使用 WPSettings 框架，只需在您的项目主文件中加载库，就可以简单地在 WordPress 管理员的常规设置中添加一个简单的文本字段，并在数据库中清理选项值的所有代码

• 一行代码来在您的项目主文件中加载库

require_once('path_to_wpsettings_folder/autoload.php');

• 实际的代码片段

//make use of the class once in your file
use \SergeLiatko\WPSettings\Setting;
//then create setting like this
$my_option = new Setting( array(
	'option' => 'option_name_in_db',
	'label'  => __( 'My option label', 'my-text-domain' )
) );

...就这样。严肃地说，这就是实现它的所有代码。

WordPress 设置 API

现在计算使用标准 WordPress 设置 API 获取相同（干净注册和适当清理）结果所需的 PHP 行数

add_action( 'admin_init', function () {
	register_setting(
		'general',
		'option_name_in_db',
		array(
			'sanitize_callback' => 'sanitize_text_field',
		)
	);
}, 10, 0 );

add_action( 'admin_menu', function () {
	add_settings_field(
		'option-name-in-db',
		__( 'My option label', 'my-text-domain' ),
		function() {
			printf(
				'<input type="%1$s" id="%2$s" name="%3$s" value="%4$s" class="%5$s">',
				'text',
				'option-name-in-db',
				'option_name_in_db',
				esc_attr( get_option( 'option_name_in_db', '' ) ),
				'regular-text code'
			);
		},
		'general',
		'default',
		array(
			'label_for' => 'option-name-in-db'
		)
	);
}, 10, 0 );

使用 WPSettings 框架需要 6 行 代码，而使用 WordPress 设置 API 需要 30 行 代码。当然，如果您添加更多选项，它们不一定都会占用 30 行，但仍然在编码速度上快了 5 倍，并且消除了学习 WordPress 设置 API 隐藏技巧和窍门的巨大任务。

最好的部分

WPSettings 框架负责

• 添加单个或多个管理页面以及/或子菜单页面以及它们的介绍性文本到 WordPress 管理区域。
• 将单个或多个设置部分添加到现有或您自定义的管理页面。
• 将设置字段添加到现有或您自定义的设置部分
  • 文本输入（所有常见类型：隐藏、文本、URL、电子邮件、密码、电话、数字、范围、日期等）。
  • 复选框（单选和多项）以及单选按钮（同样有单选和多项）。
  • 文本区域。
  • 下拉菜单（允许选项组）。
  • 您想要的任何自定义编码字段（您会发现这个框架是多么灵活）。
• 为您自定义设置部分添加描述，以及为设置字段添加帮助信息。
• 在WordPress数据库中注册您的选项。
• 对大多数选项类型进行用户数据输入的清理（在需要时，您可以使用自己的清理函数）。
• 正确处理选项默认值 - 不在数据库中保存默认值，确保在未提供值时返回，允许在用户未输入值时强制使用默认值（这对于文本选项非常有用）。

WPSettings框架允许您重写主类中的任何功能，并提供自己的扩展。

安装

使用composer

使用以下命令安装框架的最新版本

$ composer require sergeliatko/wpsettings

使用git

使用以下命令安装框架的最新版本

git clone https://github.com/sergeliatko/wpsettings wpsettings

安装所有必需的库

git clone https://github.com/sergeliatko/form-fields form-fields

git clone https://github.com/sergeliatko/html html

作为一个子模块

Git子模块是一种强大的工具，允许您轻松地包含自己的第三方项目，同时仍然将它们视为两个独立的项目。而不是提供子模块的优点和使用方法的深入解释，建议您花点时间阅读官方Git文档中的子模块页面。准备好深入时，以下命令将WPSettings作为子模块进行克隆

git submodule add https://github.com/sergeliatko/wpsettings wpsettings

不要忘记所需的库

git submodule add https://github.com/sergeliatko/form-fields form-fields

git submodule add https://github.com/sergeliatko/html html

手动

下载所有必需库的zip文件

• WPSettings
• FormFields
• HTML

并将它们提取到您的项目资源文件夹中。

加载框架类

使用composer

Composer会自动加载框架。

手动

如果手动加载类（手动安装后或使用git安装后），请确保将所有3个库中的autoload.php文件包含在您的项目中

<?php
//...
//Load WPSettings Framework
require_once ( dirname(__FILE__) . '/path_to/wpsettings/autoload.php' );
require_once ( dirname(__FILE__) . '/path_to/form-fields/autoload.php' );
require_once ( dirname(__FILE__) . '/path_to/html/autoload.php' );
//...

基本用法

添加设置

<?php
//...
//make use of the Setting class once in your file
use \SergeLiatko\WPSettings\Setting;

//...

//then create setting like this
$my_option = Setting::createInstance( array(
	'option' => 'option_name_in_db',
	'label'  => __( 'My option label', 'my-text-domain' )
) );
//...

请参阅src/Setting.php以获取更多详细信息及接受参数。

添加设置部分

<?php
//...
//make use of the Section class once in your file
use SergeLiatko\WPSettings\Section;

//...

//then create settings section like this
$my_section = Section::createInstance( array(
	'id'          => 'custom-section-id',
	'title'       => __( 'My section title', 'my-text-domain' ),
	'description' => __( 'This is section description text that appears above setting fields.', 'my-text-domain' ),
	'settings'    => array(
		array(
			'option' => 'option_1_name_in_db',
			'label'  => __( 'My option 1 label', 'my-text-domain' ),
		),
		array(
			'option' => 'option_2_name_in_db',
			'label'  => __( 'My option 2 label', 'my-text-domain' ),
		),
	),
) );
//...

请参阅src/Section.php以获取更多详细信息及接受参数。

添加管理页面

<?php
//...
//make use of the Page class once in your file
use SergeLiatko\WPSettings\Page;

//...
//then create admin page like this
$my_section = Page::createInstance( array(
	'slug'     => 'my-admin-page',
	'label'    => __( 'My Admin Page', 'my-text-domain' ),
	'sections' => array(
		array(
			'id'          => 'default',
			'title'       => __( 'My section title', 'my-text-domain' ),
			'description' => __( 'In this section my setting fields will appear', 'my-text-domain' ),
			'settings'    => array(
				array(
					'option' => 'option_1_name_in_db',
					'label'  => __( 'My option 1 label', 'my-text-domain' ),
				),
				array(
					'option' => 'option_2_name_in_db',
					'label'  => __( 'My option 2 label', 'my-text-domain' ),
				),
			),
		),
	),
) );
//...

请参阅src/Page.php以获取更多详细信息及接受参数。

扩展核心功能

以下类可以扩展

• Setting
• Section
• Page

要这样做，用您的代码扩展类，并将参数数组中的_class键与您的扩展类完全限定名作为值添加。

$my_option = Setting::createInstance( array(
	'_class' => '\\MyNameSpace\\MySettingExtension',
	'option' => 'option_name_in_db',
	'label'  => __( 'My option label', 'my-text-domain' )
) );

有关详细信息，请参阅src/Factory.php

从数据库获取选项值

请使用get_option() WordPress函数从数据库中获取选项值。框架故意不在一个选项中保存所有设置，以尽可能接近WordPress默认功能，并允许您从WordPress原生钩子和过滤器中受益于选项，从而使您的代码与其它WordPress函数的兼容性更高。

文档正在路上...

虽然完整的文档仍在开发中，但代码源有广泛的注释和参数描述，以帮助您了解可能性。

我将非常感激您通过编辑README.md文件对项目文档的贡献，以及在问题中发布您的文档建议。

财务支持WPSettings

支持WPSettings并通过GitHub赞助计划资助项目。只需一杯咖啡的价格，您就可以获取早期更新和技巧。如果您使用此框架进行商业项目，我建议您选择更大的贡献计划，以获得功能投票权以及通过聊天获得我的个人支持。

代码审查、产品指南和咨询服务也可用于帮助您的产品开发。请随时联系我讨论您的项目。

此外，所有筹集的资金都将用于支付项目文档和推广的费用。

关于

当前版本

• 0.1

要求

• PHP >= 7.3
• WordPress >= 4.7
• sergeliatko/form-fields >= 1.0.8
• sergeliatko/html >= 1.0.5（由sergeliatko/form-fields要求）

功能请求、问题、支持和错误报告

请在GitHub Issues中提交您的问题和请求。

许可

WPSettings根据GPL-3.0许可。有关详细信息，请参阅许可文件。

作者

Serge Liatko - contact(at)sergeliatko.com - https://sergeliatko.com

构建工具

• PHPStorm
• Wampserver
• WordPress