[wp-trac] [WordPress Trac] #53946: Improve return types for sanitizing/escaping functions

[WordPress Trac]

#53946: Improve return types for sanitizing/escaping functions
-------------------------+------------------------------
 Reporter:  malthert     |       Owner:  (none)
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Security     |     Version:
 Severity:  normal       |  Resolution:
 Keywords:               |     Focuses:  docs
-------------------------+------------------------------

Comment (by SergeyBiryukov):

 Replying to [comment:5 johnbillion]:
 > I think this is a wontfix, unfortunately, but I would welcome a patch
 which improves the descriptions of these functions in order to better
 explain the possible return types.

 I've found some similar instances mentioning "same type":
 * `sanitize_bookmark()`:
 {{{
  * @param stdClass|array $bookmark Bookmark row.
  * @param string         $context  Optional. How to filter the fields.
 Default 'display'.
  * @return stdClass|array Same type as $bookmark but with fields
 sanitized.
  */
 function sanitize_bookmark( $bookmark, $context = 'display' ) {
 }}}
 * `sanitize_category()`:
 {{{
  * @param object|array $category Category data.
  * @param string       $context  Optional. Default 'display'.
  * @return object|array Same type as $category with sanitized data for
 safe use.
  */
 function sanitize_category( $category, $context = 'display' ) {
 }}}
 * `sanitize_category_field()`
 {{{
  * @param string $field   Category key to sanitize.
  * @param mixed  $value   Category value to sanitize.
  * @param int    $cat_id  Category ID.
  * @param string $context What filter to use, 'raw', 'display', etc.
  * @return mixed Same type as $value after $value has been sanitized.
  */
 function sanitize_category_field( $field, $value, $cat_id, $context ) {
 }}}
 * `sanitize_user_object()`:
 {{{
  * @param object|array $user    The user object or array.
  * @param string       $context Optional. How to sanitize user fields.
 Default 'display'.
  * @return object|array The now sanitized user object or array (will be
 the same type as $user).
  */
 function sanitize_user_object($user, $context = 'display') {
 }}}
 * `sanitize_post()`:
 {{{
  * @param object|WP_Post|array $post    The post object or array
  * @param string               $context Optional. How to sanitize post
 fields.
  *                                      Accepts 'raw', 'edit', 'db',
 'display',
  *                                      'attribute', or 'js'. Default
 'display'.
  * @return object|WP_Post|array The now sanitized post object or array
 (will be the
  *                              same type as `$post`).
  */
 function sanitize_post( $post, $context = 'display' ) {
 }}}
 * `wpdb::_escape()`
 {{{
  * @param string|array $data Data to escape.
  * @return string|array Escaped data, in the same type as supplied.
  */
 public function _escape( $data ) {
 }}}

 So I think something like this would work here as well:
 {{{
  * @param string|array $data Unescaped data.
  * @return string|array Escaped data, in the same type as supplied.
  */
 function esc_sql( $data ) {

 ...
  * @param string|array $value String or array of data to slash.
  * @return string|array Slashed $value, in the same type as supplied.
  */
 function wp_slash( $value ) {

 ...
 * @param string|array $value String or array of data to unslash.
 * @return string|array Unslashed $value, in the same type as supplied.
 */
 function wp_unslash( $value )
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/53946#comment:6>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform