README

Args

WordPress 中许多函数和方法都接受关联数组作为参数，而您的 IDE 或代码编辑器无法像对单个函数参数那样自动完成。

$query = new WP_Query( [
	'post_type' => 'post',
	'category' => 'does this accept an ID or a slug?',
	'number_of_...errr'
] );

此库提供了经过良好文档化的类，这些类代表 WordPress 中使用的许多关联数组参数。在使用它们填充参数的地方使用它们，意味着您在代码编辑器中获得自动完成和智能感应，以及通过类型属性实现的严格类型。还包含了针对 PHPStan 的综合类型和约束。

当前状态

最后更新为 WordPress 6.6。

要求

PHP 8.0+

安装

composer require johnbillion/args

版本 2 的变化

在 Args 版本 2.0 及更高版本中

许多参数的类型严格性已提高，以增加类型安全性。
实现所有 Args 类的 Base 类不再实现 ArrayAccess、Countable 或 IteratorAggregate。更多信息请参阅此问题。
现在需要 PHP 8.0+。

用法

使用类构造函数的用法

$args = new \Args\WP_Query;

$args->tag = 'amazing';
$args->posts_per_page = 100;

$query = new \WP_Query( $args->toArray() );

使用过程式函数参数的用法

$args = new \Args\register_post_type;

$args->show_in_rest = true;
$args->taxonomies = [ 'genre', 'audience' ];

$story = register_post_type( 'story', $args->toArray() );

元查询、分类查询和日期查询

WordPress 中的查询类支持不同的 meta_query、tax_query 和 date_query 参数。这些完全受支持，您可以以结构化和强类型的方式构建它们。

创建 meta_query 参数

$args = new \Args\WP_Query;

// Create a clause
$clause = new \Args\MetaQuery\Clause;
$clause->key = 'my_meta_key';
$clause->value = 'my_meta_value';

// Add the clause
$args->meta_query->clauses[] = $clause;

$query = new \WP_Query( $args->toArray() );

创建 tax_query 参数

$args = new \Args\WP_Query;

// Create a clause
$clause = new \Args\TaxQuery\Clause;
$clause->taxonomy = 'post_tag';
$clause->terms = [ 'amazing' ];

// Add the clause
$args->tax_query->clauses[] = $clause;

$query = new \WP_Query( $args->toArray() );

创建 date_query 参数

$args = new \Args\WP_Query;

// Create a clause
$clause = new \Args\DateQuery\Clause;
$clause->year = 2000;
$clause->compare = '>=';

// Add the clause
$args->date_query->clauses[] = $clause;

$query = new \WP_Query( $args->toArray() );

或者，您可以通过调用带有与 WordPress 核心相同的嵌套数组语法的 fromArray() 静态方法来构建完整的查询对象

$args = new \Args\WP_Query;

// Set the meta query from an array
$array = [
	[
		'key' => 'my_meta_key',
		'value' => 'my_meta_value',
	]
];
$args->meta_query = $args->meta_query::fromArray( $array );

$query = new \WP_Query( $args->toArray() );

提供的内容

帖子

\Args\WP_Query
\Args\register_post_type
\Args\wp_insert_post
\Args\wp_update_post
\Args\get_posts
\Args\register_post_meta
\Args\register_post_status

分类和术语

\Args\WP_Term_Query
\Args\register_taxonomy
\Args\wp_insert_term
\Args\wp_update_term
\Args\get_terms
\Args\get_categories
\Args\get_tags
\Args\register_term_meta
\Args\wp_count_terms
\Args\wp_get_object_terms
\Args\wp_dropdown_categories

用户

\Args\WP_User_Query
\Args\wp_insert_user
\Args\wp_update_user
\Args\get_users

\Args\WP_Comment_Query
\Args\get_comments

HTTP API

\Args\wp_remote_get
\Args\wp_remote_post
\Args\wp_remote_head
\Args\wp_remote_request
\Args\wp_safe_remote_get
\Args\wp_safe_remote_post
\Args\wp_safe_remote_head
\Args\wp_safe_remote_request

区块

\Args\WP_Block_Type
\Args\register_block_type

自定义器

\Args\WP_Customize_Control
\Args\WP_Customize_Manager
\Args\WP_Customize_Panel
\Args\WP_Customize_Section
\Args\WP_Customize_Setting

其他所有内容

\Args\paginate_links
\Args\register_meta
\Args\register_rest_field
\Args\wp_get_nav_menus
\Args\wp_nav_menu
\Args\wp_die
\Args\wp_dropdown_languages
\Args\wp_generate_tag_cloud

类型检查

此库尽可能实现了类型化类属性。如果您将错误类型的值传递给已类型化的参数，只要您使用严格类型，就会得到一个致命错误。

<?php
declare( strict_types=1 );

不再因为类型不正确而出现神秘的错误。

请注意，WordPress中的许多参数接受多种类型，例如$ignore_sticky_posts参数对于\WP_Query可以是布尔值或整数。在这些情况下，我选择使用最合适的类型进行参数类型化，即使技术上可以接受其他类型。

静态分析

对于具有固定值集或其他约束的属性，使用了PHPStan特定的@phpstan-var标签。这使得通过PHPStan进行静态分析时能够进行更严格的类型和价值检查。

确保您使用的是最新版本的PHPStan，以便充分利用这些约束。

贡献

有关生成自己的Args定义或为Args库做出贡献的信息，请查看CONTRIBUTING.md。

但为什么呢？

我为这些用于传递参数的数组类型参数起了一个名字，我叫它们斯德哥尔摩参数。我们如此习惯于使用它们，以至于忘记了这是一个多么糟糕的设计模式。这个库的存在是为了解决这个问题，而不需要重构整个WordPress。

赞助商

我维护此库和其他库的时间部分由以下赞助商赞助

以及所有在我GitHub上的慷慨赞助商

点击此处了解如何支持此库以及我的其他WordPress开发工具和插件.

许可证：GPLv2

此程序是免费软件；您可以按照自由软件基金会发布的GNU通用公共许可证的条款重新分发和/或修改它；可以是许可证的版本2，也可以是（您选择的）任何后续版本。

此程序的分发是希望它会是有用的，但没有提供任何保证；甚至没有关于其适销性或适用于特定目的的暗示性保证。有关详细信息，请参阅GNU通用公共许可证。

johnbillion / args

维护者

详细信息