WordPress 4.7.1

[autoinstalls/wordpress.git] / wp-includes / shortcodes.php

diff --git a/wp-includes/shortcodes.php b/wp-includes/shortcodes.php
index 22f33c32efe3f201304802b5186bdcc19def7b4e..32720cd2768b981c228fd2c3c059561a174b7ab6 100644 (file)
--- a/wp-includes/shortcodes.php
+++ b/wp-includes/shortcodes.php
@@ -1,7 +1,7 @@
 <?php
 /**
- * WordPress API for creating bbcode like tags or what WordPress calls
- * "shortcodes." The tag and attribute parsing or regular expression code is
+ * WordPress API for creating bbcode-like tags or what WordPress calls
+ * "shortcodes". The tag and attribute parsing or regular expression code is
  * based on the Textpattern tag parser.
  *
  * A few examples are below:
@@ -95,9 +95,9 @@ function add_shortcode($tag, $func) {
                return;
        }
 
-       if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20]@', $tag ) ) {
-               /* translators: %s: shortcode name */
-               $message = sprintf( __( 'Invalid shortcode name: %s. Do not use spaces or reserved characters: & / < > [ ]' ), $tag );
+       if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
+               /* translators: 1: shortcode name, 2: space separated list of reserved characters */
+               $message = sprintf( __( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ), $tag, '& / < > [ ] =' );
                _doing_it_wrong( __FUNCTION__, $message, '4.4.0' );
                return;
        }
@@ -210,7 +210,7 @@ function do_shortcode( $content, $ignore_html = false ) {
                return $content;
 
        // Find all registered tag names in $content.
-       preg_match_all( '@\[([^<>&/\[\]\x00-\x20]++)@', $content, $matches );
+       preg_match_all( '@\[([^<>&/\[\]\x00-\x20=]++)@', $content, $matches );
        $tagnames = array_intersect( array_keys( $shortcode_tags ), $matches[1] );
 
        if ( empty( $tagnames ) ) {
@@ -244,10 +244,11 @@ function do_shortcode( $content, $ignore_html = false ) {
  * 6 - An extra ] to allow for escaping shortcodes with double [[]]
  *
  * @since 2.5.0
+ * @since 4.4.0 Added the `$tagnames` parameter.
  *
  * @global array $shortcode_tags
  *
- * @param array $tagnames List of shortcodes to find. Optional. Defaults to all registered shortcodes.
+ * @param array $tagnames Optional. List of shortcodes to find. Defaults to all registered shortcodes.
  * @return string The shortcode search regular expression
  */
 function get_shortcode_regex( $tagnames = null ) {
@@ -321,13 +322,39 @@ function do_shortcode_tag( $m ) {
                return $m[0];
        }
 
-       if ( isset( $m[5] ) ) {
-               // enclosing tag - extra parameter
-               return $m[1] . call_user_func( $shortcode_tags[$tag], $attr, $m[5], $tag ) . $m[6];
-       } else {
-               // self-closing tag
-               return $m[1] . call_user_func( $shortcode_tags[$tag], $attr, null,  $tag ) . $m[6];
+       /**
+        * Filters whether to call a shortcode callback.
+        *
+        * Passing a truthy value to the filter will effectively short-circuit the
+        * shortcode generation process, returning that value instead.
+        *
+        * @since 4.7.0
+        *
+        * @param bool|string $return      Short-circuit return value. Either false or the value to replace the shortcode with.
+        * @param string      $tag         Shortcode name.
+        * @param array       $attr        Shortcode attributes array,
+        * @param array       $m           Regular expression match array.
+        */
+       $return = apply_filters( 'pre_do_shortcode_tag', false, $tag, $attr, $m );
+       if ( false !== $return ) {
+               return $return;
        }
+
+       $content = isset( $m[5] ) ? $m[5] : null;
+
+       $output = $m[1] . call_user_func( $shortcode_tags[ $tag ], $attr, $content, $tag ) . $m[6];
+
+       /**
+        * Filters the output created by a shortcode callback.
+        *
+        * @since 4.7.0
+        *
+        * @param string $output Shortcode output.
+        * @param string $tag    Shortcode name.
+        * @param array  $attr   Shortcode attributes array,
+        * @param array  $m      Regular expression match array.
+        */
+       return apply_filters( 'do_shortcode_tag', $output, $tag, $attr, $m );
 }
 
 /**
@@ -537,7 +564,7 @@ function shortcode_atts( $pairs, $atts, $shortcode = '' ) {
                        $out[$name] = $default;
        }
        /**
-        * Filter a shortcode's default attributes.
+        * Filters a shortcode's default attributes.
         *
         * If the third parameter of the shortcode_atts() function is present then this filter is available.
         * The third parameter, $shortcode, is the name of the shortcode.
@@ -578,8 +605,21 @@ function strip_shortcodes( $content ) {
                return $content;
 
        // Find all registered tag names in $content.
-       preg_match_all( '@\[([^<>&/\[\]\x00-\x20]++)@', $content, $matches );
-       $tagnames = array_intersect( array_keys( $shortcode_tags ), $matches[1] );
+       preg_match_all( '@\[([^<>&/\[\]\x00-\x20=]++)@', $content, $matches );
+
+       $tags_to_remove = array_keys( $shortcode_tags );
+
+       /**
+        * Filters the list of shortcode tags to remove from the content.
+        *
+        * @since 4.7.0
+        *
+        * @param array  $tag_array Array of shortcode tags to remove.
+        * @param string $content   Content shortcodes are being removed from.
+        */
+       $tags_to_remove = apply_filters( 'strip_shortcodes_tagnames', $tags_to_remove, $content );
+
+       $tagnames = array_intersect( $tags_to_remove, $matches[1] );
 
        if ( empty( $tagnames ) ) {
                return $content;
@@ -597,9 +637,12 @@ function strip_shortcodes( $content ) {
 }
 
 /**
+ * Strips a shortcode tag based on RegEx matches against post content.
+ *
+ * @since 3.3.0
  *
- * @param array $m
- * @return string|false
+ * @param array $m RegEx matches against post content.
+ * @return string|false The content stripped of the tag, otherwise false.
  */
 function strip_shortcode_tag( $m ) {
        // allow [[foo]] syntax for escaping a tag