Add PHPStan custom rule for get_subcribed_events() callbacks validation

[remyperona]

Description

Port the existing validations for callbacks of add_filter() and add_action() to the subscriber system and get_subscribed_events() array returnedé

Type of change

• Chore

SubscriberCallbackRule

This rule validates get_subscribed_events() method implementations in classes that implement SubscriberInterface.

Purpose

Ensures that:

• All array elements have @filter or @action annotations
• Filter callbacks return non-void values
• Action callbacks return void
• Parameter counts match accepted_args when specified

Usage

Add single-line comment annotations to each array element in get_subscribed_events():

public static function get_subscribed_events(): array {
    return [
        // @action
        'wp_ajax_imagify_get_admin_bar_profile' => 'get_admin_bar_profile_callback',
        
        // @action
        'admin_bar_menu' => [ 'add_imagify_admin_bar_menu', IMAGIFY_INT_MAX ],
        
        // @filter
        'imagify_cdn_source_url' => 'get_cdn_source',
        
        // @filter
        'imagify_settings' => [ 'modify_settings', 10, 2 ],
    ];
}

Supported Array Formats

1. Simple string method name:

   // @action
   'hook_name' => 'method_name'

2. Array with method and priority:

   // @filter
   'hook_name' => [ 'method_name', 20 ]

3. Array with method, priority, and accepted_args:

   // @action
   'hook_name' => [ 'method_name', 10, 3 ]

4. Nested arrays (multiple callbacks for same hook):

   // @action
   'hook_name' => [
       [ 'method_name_1', 10, 2 ],
       [ 'method_name_2', 20, 1 ]
   ]

   Note: Annotation on parent element applies to all nested callbacks.

5. Variable assignment:

   public static function get_subscribed_events(): array {
       $events = [
           // @action
           'hook_name' => 'method_name',
       ];
       return $events;
   }

Filter vs Action Guidelines

Filters (// @filter)

• Must return a value (cannot return void)
• Used when modifying data that flows through the hook
• Example:

  // @filter
  'the_content' => 'modify_content',
  
  public function modify_content( string $content ): string {
      return $content . ' Modified!';
  }

Actions (// @action)

• Must return void (or explicit never)
• Used when performing side effects without returning data
• Example:

  // @action
  'admin_init' => 'register_settings',
  
  public function register_settings(): void {
      register_setting( 'group', 'option' );
  }

Error Identifiers

• wpmedia.subscriber.missingAnnotation - Missing @filter or @action annotation
• wpmedia.subscriber.filter.missingReturn - Filter callback doesn't return a value
• wpmedia.subscriber.action.unexpectedReturn - Action callback returns a value
• wpmedia.subscriber.arguments.count - Parameter count mismatch with accepted_args

Skipped Validations

The rule automatically skips validation for:

• Empty array returns
• Delegated implementations (e.g., return ParentClass::get_subscribed_events())
• Complex multi-statement array building
• Conditional array modifications

Examples

Valid Implementation

class MySubscriber implements SubscriberInterface {
    public static function get_subscribed_events(): array {
        return [
            // @action
            'init' => 'initialize',
            
            // @filter
            'the_content' => [ 'filter_content', 10, 2 ],
        ];
    }
    
    public function initialize(): void {
        // Action - returns void
        register_post_type( 'my_type', [] );
    }
    
    public function filter_content( string $content, int $post_id ): string {
        // Filter - returns value
        return $content . ' Filtered';
    }
}

Invalid Implementation (Will Show Errors)

class MySubscriber implements SubscriberInterface {
    public static function get_subscribed_events(): array {
        return [
            // Error: Missing annotation
            'init' => 'initialize',
            
            // @filter
            'the_content' => 'filter_content',
        ];
    }
    
    // Error: Action returns string instead of void
    public function initialize(): string {
        return 'initialized';
    }
    
    // Error: Filter returns void instead of value
    public function filter_content( string $content ): void {
        echo $content;
    }
}

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -0.10%)	✅ ∅ (target: 50.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (467f183)	14243	48	0.34%
Head commit (8e9a9c2)	14243 (+0)	48 (+0)	0.34% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#1019)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

[wordpressfan]

@remyperona do u think it'd be better to have this annotation on the method itself not into the subscriber array item?
Because sometimes we have one method for more than one hook.
Also for WPR we will reset the baseline.

[remyperona]

One method can be on multiple hooks, but the same rules apply: a return for a method on a filter, no return for a method on an action.

So in the end, it is the hook that determines what should happen in the method, not the other way around.

[wordpressfan]

One method can be on multiple hooks, but the same rules apply: a return for a method on a filter, no return for a method on an action.

So in the end, it is the hook that determines what should happen in the method, not the other way around.

OK, thanks @remyperona
So I believe we can merge this one.