PHPackages                             johnbillion/args - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. johnbillion/args

ActiveLibrary[Utility & Helpers](/categories/utility)

johnbillion/args
================

I don't want to get into an argument about this.

2.4.0(3mo ago)117992.9k—6.6%67GPL-2.0-or-laterPHPPHP >=8.0CI passing

Since Jul 9Pushed 3mo ago4 watchersCompare

[ Source](https://github.com/johnbillion/args)[ Packagist](https://packagist.org/packages/johnbillion/args)[ GitHub Sponsors](https://github.com/sponsors/johnbillion)[ RSS](/packages/johnbillion-args/feed)WikiDiscussions trunk Synced 1mo ago

READMEChangelog (10)Dependencies (11)Versions (43)Used By (7)

[![](https://camo.githubusercontent.com/6d8b87bcd278e15eadffdb32d041aad345ba025d92aa722688394838877eb1db/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a6f686e62696c6c696f6e2f617267732f74657374732e796d6c3f6272616e63683d7472756e6b267374796c653d666c61742d737175617265)](https://github.com/johnbillion/args/actions)

Args
====

[](#args)

Many functions and methods in WordPress accept arguments as an associative array which your IDE or code editor cannot autocomplete like it does for individual function parameters.

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

This library provides well-documented classes which represent many of the associative array parameters used throughout WordPress. Using them at the point where you populate the arguments means you get autocompletion and intellisense in your code editor, and strict typing thanks to typed properties. Comprehensive types and constraints for [PHPStan](https://phpstan.org/) are also included.

[![](.github/assets/screenshot.png)](.github/assets/screenshot.png)

Current status
--------------

[](#current-status)

Last updated for WordPress 6.9.

Requirements
------------

[](#requirements)

- PHP 8.0+

Installation
------------

[](#installation)

```
composer require johnbillion/args
```

Changes in version 2
--------------------

[](#changes-in-version-2)

In Args version 2.0 and higher:

- Many arguments have had their type strictness increased for added type safety.
- The `Base` class which is implemented by all of the Args classes no longer implements `ArrayAccess`, `Countable`, or `IteratorAggregate`. [See this issue for further information](https://github.com/johnbillion/args/issues/40).
- PHP 8.0+ is now required.

Usage
-----

[](#usage)

Usage with a class constructor:

```
$args = new \Args\WP_Query;

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

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

Usage with a procedural function parameter:

```
$args = new \Args\register_post_type;

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

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

Meta queries, tax queries, and date queries
-------------------------------------------

[](#meta-queries-tax-queries-and-date-queries)

The query classes in WordPress support variously `meta_query`, `tax_query`, and `date_query` arguments. These are fully supported and you can construct them in a structured and strongly typed way.

Creating a `meta_query` argument:

```
$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() );
```

Creating a `tax_query` argument:

```
$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() );
```

Creating a `date_query` argument:

```
$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() );
```

Nested queries are supported:

```
$args = new \Args\WP_Query;

// Create some clauses
$clause1 = new \Args\MetaQuery\Clause;
$clause1->key = 'my_meta_key';
$clause1->value = 'my_meta_value';

$clause2 = new \Args\MetaQuery\Clause;
$clause2->key = 'another_meta_key';
$clause2->value = '100';
$clause2->compare = '>';

// Create a nested query with a clause
$nested = new \Args\MetaQuery\Query;
$nested->addClause( $clause2 );

// Add the clause and nested query
$args->meta_query->clauses[] = $clause1;
$args->meta_query->queries[] = $nested;

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

Alternatively you can construct a complete query object by calling the `fromArray()` static method with the same nested array syntax that WordPress core uses:

```
$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() );
```

What's provided
---------------

[](#whats-provided)

### Posts

[](#posts)

- `\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`

### Taxonomies and terms

[](#taxonomies-and-terms)

- `\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`

### Users

[](#users)

- `\Args\WP_User_Query`
- `\Args\wp_insert_user`
- `\Args\wp_update_user`
- `\Args\get_users`

### Comments

[](#comments)

- `\Args\WP_Comment_Query`
- `\Args\get_comments`

### HTTP API

[](#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`

### Blocks

[](#blocks)

- `\Args\WP_Block_Type`
- `\Args\register_block_type`

### Abilities

[](#abilities)

- `\Args\wp_register_ability`
- `\Args\wp_register_ability_category`

### Customizer

[](#customizer)

- `\Args\WP_Customize_Control`
- `\Args\WP_Customize_Manager`
- `\Args\WP_Customize_Panel`
- `\Args\WP_Customize_Section`
- `\Args\WP_Customize_Setting`

### Everything else

[](#everything-else)

- `\Args\paginate_links`
- `\Args\register_meta`
- `\Args\register_rest_field`
- `\Args\register_setting`
- `\Args\wp_get_nav_menus`
- `\Args\wp_nav_menu`
- `\Args\wp_die`
- `\Args\wp_dropdown_languages`
- `\Args\wp_generate_tag_cloud`

Type checking
-------------

[](#type-checking)

Typed class properties are implemented in this library where possible. If you pass a value of the wrong type to an argument that is typed, you'll get a fatal error as long as you're using strict types:

```