wp-plugin-hooks

To deprecate a custom WordPress filter hook safely, use apply_filters_deprecated instead of removing it. This maintains backward compatibility by notifying developers while preserving the third-party listener execution flow during plugin updates.

Document WordPress action and filter hooks using Fires or Filters tags, precise @since versions, and typed @param tags. For filters, you must also include correct @return semantics to define the expected transformed value type.

Use ref_array variants when forwarding unknown-length argument lists through WordPress plugin hooks. This respects how these functions pass args internally and maintains strict parameter contract stability for dynamic forwarding.

Adding new parameters to an existing apply_filters hook can break the API contract if it changes parameter order or count. Maintain backward compatibility by keeping existing parameter order, count, and types strictly stable across versions.

Choose a WordPress action hook when third-party listeners should react with side effects, and choose a filter hook when listeners need to transform and return values. This separates side effects from data modification cleanly.

The limitation of do_action_deprecated is that it only warns of removal; it still requires strict parameter contract stability beforehand. You must enforce plugin-prefixed naming and maintain typed @param tags to prevent silent integration failures.