{"id":15637206,"url":"https://github.com/johnbillion/args","last_synced_at":"2025-05-16T01:05:03.695Z","repository":{"id":36997379,"uuid":"278460532","full_name":"johnbillion/args","owner":"johnbillion","description":"Array arguments made bearable","archived":false,"fork":false,"pushed_at":"2025-04-16T18:18:08.000Z","size":581,"stargazers_count":114,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"trunk","last_synced_at":"2025-04-17T02:30:12.542Z","etag":null,"topics":["phpstan","strict-types","wordpress"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/johnbillion/args","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnbillion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"johnbillion"}},"created_at":"2020-07-09T20:08:30.000Z","updated_at":"2025-04-16T18:17:56.000Z","dependencies_parsed_at":"2025-04-16T19:06:55.452Z","dependency_job_id":"17028b86-316b-4e21-9c7f-301b4e067541","html_url":"https://github.com/johnbillion/args","commit_stats":{"total_commits":335,"total_committers":6,"mean_commits":"55.833333333333336","dds":0.5074626865671642,"last_synced_commit":"464f53c1eff41eaa7e7aec9d5e03a2c8cfb2b783"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Fargs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Fargs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Fargs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Fargs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnbillion","download_url":"https://codeload.github.com/johnbillion/args/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["phpstan","strict-types","wordpress"],"created_at":"2024-10-03T11:10:46.646Z","updated_at":"2025-05-16T01:05:03.681Z","avatar_url":"https://github.com/johnbillion.png","language":"PHP","funding_links":["https://github.com/sponsors/johnbillion"],"categories":[],"sub_categories":[],"readme":"[![](https://img.shields.io/github/actions/workflow/status/johnbillion/args/tests.yml?branch=trunk\u0026style=flat-square)](https://github.com/johnbillion/args/actions)\n\n# Args\n\nMany 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.\n\n```php\n$query = new WP_Query( [\n\t'post_type' =\u003e 'post',\n\t'category' =\u003e 'does this accept an ID or a slug?',\n\t'number_of_...errr'\n] );\n```\n\nThis 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.\n\n![](.github/assets/screenshot.png)\n\n## Current status\n\nLast updated for WordPress 6.8.\n\n## Requirements\n\n* PHP 8.0+\n\n## Installation\n\n```shell\ncomposer require johnbillion/args\n```\n\n## Changes in version 2\n\nIn Args version 2.0 and higher:\n\n* Many arguments have had their type strictness increased for added type safety.\n* 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).\n* PHP 8.0+ is now required.\n\n## Usage\n\nUsage with a class constructor:\n\n```php\n$args = new \\Args\\WP_Query;\n\n$args-\u003etag = 'amazing';\n$args-\u003eposts_per_page = 100;\n\n$query = new \\WP_Query( $args-\u003etoArray() );\n```\n\nUsage with a procedural function parameter:\n\n```php\n$args = new \\Args\\register_post_type;\n\n$args-\u003eshow_in_rest = true;\n$args-\u003etaxonomies = [ 'genre', 'audience' ];\n\n$story = register_post_type( 'story', $args-\u003etoArray() );\n```\n\n## Meta queries, tax queries, and date queries\n\nThe 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.\n\nCreating a `meta_query` argument:\n\n```php\n$args = new \\Args\\WP_Query;\n\n// Create a clause\n$clause = new \\Args\\MetaQuery\\Clause;\n$clause-\u003ekey = 'my_meta_key';\n$clause-\u003evalue = 'my_meta_value';\n\n// Add the clause\n$args-\u003emeta_query-\u003eclauses[] = $clause;\n\n$query = new \\WP_Query( $args-\u003etoArray() );\n```\n\nCreating a `tax_query` argument:\n\n```php\n$args = new \\Args\\WP_Query;\n\n// Create a clause\n$clause = new \\Args\\TaxQuery\\Clause;\n$clause-\u003etaxonomy = 'post_tag';\n$clause-\u003eterms = [ 'amazing' ];\n\n// Add the clause\n$args-\u003etax_query-\u003eclauses[] = $clause;\n\n$query = new \\WP_Query( $args-\u003etoArray() );\n```\n\nCreating a `date_query` argument:\n\n```php\n$args = new \\Args\\WP_Query;\n\n// Create a clause\n$clause = new \\Args\\DateQuery\\Clause;\n$clause-\u003eyear = 2000;\n$clause-\u003ecompare = '\u003e=';\n\n// Add the clause\n$args-\u003edate_query-\u003eclauses[] = $clause;\n\n$query = new \\WP_Query( $args-\u003etoArray() );\n```\n\nAlternatively you can construct a complete query object by calling the `fromArray()` static method with the same nested array syntax that WordPress core uses:\n\n```php\n$args = new \\Args\\WP_Query;\n\n// Set the meta query from an array\n$array = [\n\t[\n\t\t'key' =\u003e 'my_meta_key',\n\t\t'value' =\u003e 'my_meta_value',\n\t]\n];\n$args-\u003emeta_query = $args-\u003emeta_query::fromArray( $array );\n\n$query = new \\WP_Query( $args-\u003etoArray() );\n```\n\n## What's provided\n\n### Posts\n\n* `\\Args\\WP_Query`\n* `\\Args\\register_post_type`\n* `\\Args\\wp_insert_post`\n* `\\Args\\wp_update_post`\n* `\\Args\\get_posts`\n* `\\Args\\register_post_meta`\n* `\\Args\\register_post_status`\n\n### Taxonomies and terms\n\n* `\\Args\\WP_Term_Query`\n* `\\Args\\register_taxonomy`\n* `\\Args\\wp_insert_term`\n* `\\Args\\wp_update_term`\n* `\\Args\\get_terms`\n* `\\Args\\get_categories`\n* `\\Args\\get_tags`\n* `\\Args\\register_term_meta`\n* `\\Args\\wp_count_terms`\n* `\\Args\\wp_get_object_terms`\n* `\\Args\\wp_dropdown_categories`\n\n### Users\n\n* `\\Args\\WP_User_Query`\n* `\\Args\\wp_insert_user`\n* `\\Args\\wp_update_user`\n* `\\Args\\get_users`\n\n### Comments\n\n* `\\Args\\WP_Comment_Query`\n* `\\Args\\get_comments`\n\n### HTTP API\n\n* `\\Args\\wp_remote_get`\n* `\\Args\\wp_remote_post`\n* `\\Args\\wp_remote_head`\n* `\\Args\\wp_remote_request`\n* `\\Args\\wp_safe_remote_get`\n* `\\Args\\wp_safe_remote_post`\n* `\\Args\\wp_safe_remote_head`\n* `\\Args\\wp_safe_remote_request`\n\n### Blocks\n\n* `\\Args\\WP_Block_Type`\n* `\\Args\\register_block_type`\n\n### Customizer\n\n* `\\Args\\WP_Customize_Control`\n* `\\Args\\WP_Customize_Manager`\n* `\\Args\\WP_Customize_Panel`\n* `\\Args\\WP_Customize_Section`\n* `\\Args\\WP_Customize_Setting`\n\n### Everything else\n\n* `\\Args\\paginate_links`\n* `\\Args\\register_meta`\n* `\\Args\\register_rest_field`\n* `\\Args\\register_setting`\n* `\\Args\\wp_get_nav_menus`\n* `\\Args\\wp_nav_menu`\n* `\\Args\\wp_die`\n* `\\Args\\wp_dropdown_languages`\n* `\\Args\\wp_generate_tag_cloud`\n\n## Type checking\n\nTyped 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:\n\n```php\n\u003c?php\ndeclare( strict_types=1 );\n```\n\nNo more mysterious bugs due to incorrect types.\n\nNote that several parameters in WordPress accept multiple types, for example the `$ignore_sticky_posts` argument for `\\WP_Query` can be a boolean or an integer. In some of these cases I've opted to type the parameter with the most appropriate type even though it can technically accept other types.\n\n## Static analysis\n\nPHPStan-specific `@phpstan-var` tags are used for properties that have a fixed set of values or other constraints. This allows for even greater type and value checking via static analysis with PHPStan.\n\nEnsure you're using a recent version of PHPStan to make the best use of these constraints.\n\n## Contributing\n\nCheck out [CONTRIBUTING.md](CONTRIBUTING.md) for information about generating your own Args definitions or contributing to the Args library.\n\n## But why?\n\nI have a name for these array-type parameters for passing arguments. I call them *Stockholm Parameters*. We've gotten so used to using them that we forget what a terrible design pattern it is. This library exists to work around the immediate issue without rearchitecting the whole of WordPress.\n\n## Sponsors\n\n\u003cp align=\"center\"\u003eThe time that I spend maintaining this library and others is in part sponsored by:\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://automattic.com\"\u003e\u003cimg src=\"https://cdn.jsdelivr.net/gh/johnbillion/johnbillion@latest/assets/sponsors/automattic.svg\" alt=\"Automattic\" width=\"50%\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://servmask.com\"\u003e\u003cimg src=\"https://cdn.jsdelivr.net/gh/johnbillion/johnbillion@latest/assets/sponsors/servmask.svg\" alt=\"ServMask\" width=\"25%\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003ePlus all my kind sponsors on GitHub:\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/sponsors/johnbillion\"\u003e\u003cimg src=\"https://cdn.jsdelivr.net/gh/johnbillion/johnbillion@latest/sponsors.svg\" alt=\"Sponsors\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/sponsors/johnbillion\"\u003eClick here to find out about supporting my open source tools and plugins\u003c/a\u003e.\u003c/p\u003e\n\n## License: GPLv2\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 2 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnbillion%2Fargs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnbillion%2Fargs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnbillion%2Fargs/lists"}