johnbillion / args

Array arguments made bearable

Hi there 👋

My name is John Blackbourn. I'm one of the core committers to the WordPress open source project and I maintain several popular plugins and tools for WordPress developers, including:

• Query Monitor
• WP Crontrol
• User Switching
• WordPress Hooks Intellisense for VS Code
• Extended CPTs
• and many more...

args's Issues

Redundant type hints

	/**
	 * The number of posts to query for. Use -1 to request all posts.
	 *
	 * @var int
	 */
	public int $posts_per_page;

How about telling its type only once?

	/**
	 * The number of posts to query for. Use -1 to request all posts.
	 */
	public int $posts_per_page;

passing an `Args` instance to `WP_Query` without `toArray()` silently yields subtle bugs

I spent the past few hours trying to figure out why two nearly-identical queries in my project yielded wildly different results. Both used the same tax_query->clauses, but only one of the resulting queries actually respected the clause. It turns out that I had forgotten to call toArray() on the instance of \Args\WP_Query prior to passing it to the \WP_Query constructor. I would have expected that to cause an obvious error.

The query with new WP_Query($args->toArray()) correctly filtered posts by tax_query, while the query with new WP_Query($args) did not respect tax_query but also did not fail entirely.

Package License "GPL-2.0+" is a deprecated

just a friendly notice :)

johnbillion/extended-cpts is valid, but with a few warnings
# General warnings
- License "GPL-2.0+" is a deprecated SPDX license identifier, use "GPL-2.0-or-later" instead

ref

• https://getcomposer.org/doc/04-schema.md#license
• https://spdx.org/licenses/
• https://spdx.org/licenses/GPL-2.0+.html
• https://spdx.org/licenses/GPL-2.0-or-later.html
• johnbillion/extended-cpts#212

Add tests that detect new and changed parameters

Need a test suite that runs against WordPress nightly and detects new and changed parameters to the functions covered by this library.

"Value objects"

These are called value objects.

Please see mine
https://github.com/szepeviktor/phpstan-wordpress/tree/master/example
class*.php

PHP 8.1: PHP Deprecated: Return type of Args\Shared\Base::offsetGet($offset)

PHP deprecation notice when running PHP 8.1.

PHP Deprecated:  Return type of Args\Shared\Base::offsetGet($offset) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /usr/local/wordpress/vendor/johnbillion/args/src/Shared/Base.php on line 47

• Tested w/ johnbillion/args (1.3.0 => 1.4.0)
• WordPress 6.0
• PHP 8.1

Breeding a mule

Could we somehow inject your args into wordpress-stubs?

Test generate.php

PHPStan would approve generate.php with this diff.

diff --git a/generate.php b/generate.php
index e23d303..ff34d23 100644
--- a/generate.php
+++ b/generate.php
@@ -7,6 +7,7 @@ use phpDocumentor\Reflection\Php\Project;

 require_once __DIR__ . '/vendor/autoload.php';

+/** @var array{"file"?:string, "method"?:string, "function"?:string, "param"?:string} $options */
 $options = getopt( '', [
        'file:',
        'method::',
@@ -79,6 +80,7 @@ if ( ! empty( $options['method'] ) ) {
        $symbol = $methods[ $options['method'] ];
        $name = $oc;
 } else {
+       /** @var array{"file":string, "function":string, "param":string} $options */
        $functions = $file->getFunctions();

        if ( ! isset( $functions[ $options['function'] ] ) ) {
@@ -93,9 +95,9 @@ if ( ! empty( $options['method'] ) ) {
        $name = trim( $options['function'], '()' );
 }

+/** @var BaseTag[] $tags */
 $tags = $symbol->getDocBlock()->getTags();

-/** @var BaseTag[] $tags */
 $tags = array_values( array_filter( $tags, function( BaseTag $tag ) : bool {
        return ( $tag instanceof Param );
 } ) );

Reduce number of exported files

How about not exporting these files?

CONTRIBUTING.md

phpcs.xml.dist
phpstan.neon.dist
phpunit.xml.dist

generate.php
shape.php
shapes.php

Current state: