[wp-trac] [WordPress Trac] #45595: Filter 'sanitize_email' provides 2 times the same param

[WordPress Trac]

#45595: Filter 'sanitize_email' provides 2 times the same param
--------------------------+-----------------------------
 Reporter:  ChriCo        |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Formatting    |    Version:  5.0
 Severity:  normal        |   Keywords:  has-patch
  Focuses:                |
--------------------------+-----------------------------
 The function {{{sanitize_email()}}} in wp-includes/formatting.php L3447
 provides a filter which allows to hook into the sanitize-function with a
 given context. The docBlock for this filter is saying following:


 {{{#!php
 * @param string $email   The sanitized email address.
 * @param string $email   The email address, as provided to
 sanitize_email().
 * @param string $message A message to pass to the user.
 }}}

 Following errors are present here:

 ----

 **duplicated var**

 The first and second param are the same var, while the description says
 something completly different.

 ----


 **(maybe) wrong assigment**

 On top of that, if the sanitization is successful, the {{{$email}}} is
 build together again before returning it by assigning it via: {{{$email =
 $local . '@' . $domain;}}}.

 This means, that the either the documentation is wrong, or the
 {{{$email}}} before last return is wrongly assigned.

 **wrong type hint**

 {{{string $message}}} is not correct, since the last applied filter uses
 {{{null}}}. This should be either {{{''}}}, a message or the docBlock has
 to be updated. Since we propably have to deal with "BC" and some users are
 already checking this filter with {{{if($message === null)}}}, i'll just
 update the docBlock.


 ----


 My patch contains following:

 1. Rename docblock first {{{$email}}} to {{{$sanitized_email}}}.
 2. Update docBlock for {{{string|null $message}}}.
 3. Change assigment before return to {{{$sanitized_email = $local . '@' .
 $domain;}}}.
 4. Inject {{{sanitized_email}}} first param after hook name.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/45595>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform