Replace _deprecated_function( 'add_filter' ) with apply_filters_deprecated()

[birgire]

Since 4.6 we have the function ​apply_filters_deprecated() for deprecated filters:

When a filter hook is deprecated, the apply_filters() call is replaced with >apply_filters_deprecated(), which triggers a deprecation notice and then fires the >original filter hook.

In ​wp-includes/class-wp-editor.php we have:

// Back-compat for the `htmledit_pre` and `richedit_pre` filters
if ( 'html' === $default_editor && has_filter( 'htmledit_pre' ) ) {
	// TODO: needs _deprecated_filter(), use _deprecated_function() as substitute for now
	_deprecated_function( 'add_filter( htmledit_pre )', '4.3.0', 'add_filter( format_for_editor )' );
	$content = apply_filters( 'htmledit_pre', $content );
} elseif ( 'tinymce' === $default_editor && has_filter( 'richedit_pre' ) ) {
	_deprecated_function( 'add_filter( richedit_pre )', '4.3.0', 'add_filter( format_for_editor )' );
	$content = apply_filters( 'richedit_pre', $content );
}

I think we can replace it with:

// Back-compat for the `htmledit_pre` and `richedit_pre` filters
if ( 'html' === $default_editor && has_filter( 'htmledit_pre' ) ) {
	$content = apply_filters_deprecated( 'htmledit_pre', array( $content ), '4.3.0', 'format_for_editor' );
} elseif ( 'tinymce' === $default_editor && has_filter( 'richedit_pre' ) ) {
	$content = apply_filters_deprecated( 'richedit_pre', array( $content ), '4.3.0', 'format_for_editor' );
}

I also wonder if the missing inline documentation should be added, for those deprecated filters.

[birgire]

Thanks for the patch @lbenicio and @sebastien@…

The patch in 44341.diff​ seems to be unrelated.

The patch in 44341.2.diff​ duplicates a comment line.

Shouldn't we also add inline documentation for the filters, including the @deprecate tag with the version when it was deprecated?

[ianbelanger]

Refreshed patch and added @deprecated documentation

[desrosj]

@ianbelanger 44341.3.diff​ looks good. A few minor changes:

• Instead of putting the inline documentation before the if() statement, can there be a docblock above each apply_filter_deprecated() call? Putting it before each filter call would make it harder to miss.
• There should be a @param string $content line in the docblocks describing the parameter.
• The empy * line after @deprecated should not be there.

[ianbelanger]

Updated patch to change docblock comments based on @desrosj suggestions

[desrosj]

Thanks, @ianbelanger. This looks good.

The only thing that I am not sure of is whether the /** This filter is documented in wp-includes/deprecated.php */ docblock should also contain a @deprecated tag.

[ocean90]

4.9.7 has been released, moving to next milestone.

[pento]

In 44341.4.diff​, the initial comment "Back-compat for the htmledit_pre and richedit_pre filters" shouldn't be changed, this is still correctly describing what this block of code does.

Otherwise, this is good to commit and backport.

[pento]

In 43464:

Editor: Use apply_filters_deprecated() for some deprecated filters.

The htmledit_pre and richedit_pre filters have been deprecated since 4.3.0, since before apply_filters_deprecated() existed. They're now correctly run using apply_filters_deprecated().

Props sebastienthivinfocom, lbenicio, ianbelanger.
Fixes #44341.

[pento]

Reopen for backport.

[SergeyBiryukov]

In 43482:

Editor: Use apply_filters_deprecated() for some deprecated filters.

The htmledit_pre and richedit_pre filters have been deprecated since 4.3.0, since before apply_filters_deprecated() existed. They're now correctly run using apply_filters_deprecated().

Props sebastienthivinfocom, lbenicio, ianbelanger.
Merges [43464] to the 4.9 branch.
Fixes #44341.