Make WordPress Core

Opened 6 years ago

Closed 6 years ago

#44341 closed defect (bug) (fixed)

Replace _deprecated_function( 'add_filter' ) with apply_filters_deprecated()

Reported by: birgire's profile birgire Owned by: pento's profile pento
Milestone: 4.9.8 Priority: normal
Severity: normal Version: 4.3
Component: Editor Keywords: good-first-bug has-patch commit fixed-major
Focuses: docs Cc:

Description

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.

Attachments (4)

44341.diff (79.2 KB) - added by sebastien@… 6 years ago.
44341.2.diff (1.3 KB) - added by lbenicio 6 years ago.
44341.3.diff (1.3 KB) - added by ianbelanger 6 years ago.
Refreshed patch and added @deprecated documentation
44341.4.diff (1.4 KB) - added by ianbelanger 6 years ago.
Updated patch to change docblock comments based on @desrosj suggestions

Download all attachments as: .zip

Change History (18)

@sebastien@…
6 years ago

@lbenicio
6 years ago

#1 @SergeyBiryukov
6 years ago

  • Milestone changed from Awaiting Review to 4.9.7

#2 @birgire
6 years ago

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?

#3 @desrosj
6 years ago

  • Keywords has-patch needs-refresh added; needs-patch removed

@ianbelanger
6 years ago

Refreshed patch and added @deprecated documentation

#4 @ianbelanger
6 years ago

  • Keywords needs-refresh removed

#5 @desrosj
6 years ago

  • Focuses docs added
  • Keywords needs-refresh added

@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
6 years ago

Updated patch to change docblock comments based on @desrosj suggestions

#6 @desrosj
6 years ago

  • Keywords needs-refresh removed

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.

This ticket was mentioned in Slack in #core-docs by ianbelanger. View the logs.


6 years ago

#8 @birgire
6 years ago

  • Owner set to ianbelanger
  • Status changed from new to assigned

#9 @ocean90
6 years ago

  • Milestone changed from 4.9.7 to 4.9.8

4.9.7 has been released, moving to next milestone.

#10 @pento
6 years ago

  • Keywords commit added

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.

#11 @pento
6 years ago

  • Owner changed from ianbelanger to pento

#12 @pento
6 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

#13 @pento
6 years ago

  • Keywords fixed-major added
  • Resolution fixed deleted
  • Status changed from closed to reopened

Reopen for backport.

#14 @SergeyBiryukov
6 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

Note: See TracTickets for help on using tickets.