diff --git a/packages/block-library/src/archives/index.php b/packages/block-library/src/archives/index.php index 695affde760a8a..2846b6ca1a03e1 100644 --- a/packages/block-library/src/archives/index.php +++ b/packages/block-library/src/archives/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/archives` block on server. * + * @since 5.0.0 + * * @see WP_Widget_Archives * * @param array $attributes The block attributes. @@ -106,6 +108,8 @@ function render_block_core_archives( $attributes ) { /** * Register archives block. + * + * @since 5.0.0 */ function register_block_core_archives() { register_block_type_from_metadata( diff --git a/packages/block-library/src/avatar/index.php b/packages/block-library/src/avatar/index.php index 303b35458eb1ae..b2f8ecace75a69 100644 --- a/packages/block-library/src/avatar/index.php +++ b/packages/block-library/src/avatar/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/avatar` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -99,6 +101,8 @@ function render_block_core_avatar( $attributes, $content, $block ) { * Generates class names and styles to apply the border support styles for * the Avatar block. * + * @since 6.3.0 + * * @param array $attributes The block attributes. * @return array The border-related classnames and styles for the block. */ @@ -149,6 +153,8 @@ function get_block_core_avatar_border_attributes( $attributes ) { /** * Registers the `core/avatar` block on the server. + * + * @since 6.0.0 */ function register_block_core_avatar() { register_block_type_from_metadata( diff --git a/packages/block-library/src/block/index.php b/packages/block-library/src/block/index.php index 49b5786eacc79f..9403205c186596 100644 --- a/packages/block-library/src/block/index.php +++ b/packages/block-library/src/block/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/block` block on server. * + * @since 5.0.0 + * * @global WP_Embed $wp_embed * * @param array $attributes The block attributes. @@ -97,6 +99,8 @@ function render_block_core_block( $attributes ) { /** * Registers the `core/block` block. + * + * @since 5.3.0 */ function register_block_core_block() { register_block_type_from_metadata( diff --git a/packages/block-library/src/calendar/index.php b/packages/block-library/src/calendar/index.php index fd2914a7e88691..44b56af25e4662 100644 --- a/packages/block-library/src/calendar/index.php +++ b/packages/block-library/src/calendar/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/calendar` block on server. * + * @since 5.2.0 + * * @global int $monthnum. * @global int $year. * @@ -79,6 +81,8 @@ function render_block_core_calendar( $attributes ) { /** * Registers the `core/calendar` block on server. + * + * @since 5.2.0 */ function register_block_core_calendar() { register_block_type_from_metadata( @@ -97,6 +101,8 @@ function register_block_core_calendar() { * Used to hide the calendar block when there are no published posts. * This compensates for a known Core bug: https://core.trac.wordpress.org/ticket/12016 * + * @since 5.9.0 + * * @return bool Has any published posts or not. */ function block_core_calendar_has_published_posts() { @@ -120,6 +126,8 @@ function block_core_calendar_has_published_posts() { * Queries the database for any published post and saves * a flag whether any published post exists or not. * + * @since 5.9.0 + * * @global wpdb $wpdb WordPress database abstraction object. * * @return bool Has any published posts or not. @@ -137,6 +145,8 @@ function block_core_calendar_update_has_published_posts() { /** * Handler for updating the has published posts flag when a post is deleted. * + * @since 5.9.0 + * * @param int $post_id Deleted post ID. */ function block_core_calendar_update_has_published_post_on_delete( $post_id ) { @@ -152,6 +162,8 @@ function block_core_calendar_update_has_published_post_on_delete( $post_id ) { /** * Handler for updating the has published posts flag when a post status changes. * + * @since 5.9.0 + * * @param string $new_status The status the post is changing to. * @param string $old_status The status the post is changing from. * @param WP_Post $post Post object. diff --git a/packages/block-library/src/categories/index.php b/packages/block-library/src/categories/index.php index c35376505b134f..1a6e6f43b1d939 100644 --- a/packages/block-library/src/categories/index.php +++ b/packages/block-library/src/categories/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/categories` block on server. * + * @since 5.0.0 + * * @param array $attributes The block attributes. * * @return string Returns the categories list/dropdown markup. @@ -63,6 +65,8 @@ function render_block_core_categories( $attributes ) { /** * Generates the inline script for a categories dropdown field. * + * @since 5.0.0 + * * @param string $dropdown_id ID of the dropdown field. * * @return string Returns the dropdown onChange redirection script. @@ -87,6 +91,8 @@ function onCatChange() { /** * Registers the `core/categories` block on server. + * + * @since 5.0.0 */ function register_block_core_categories() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comment-author-name/index.php b/packages/block-library/src/comment-author-name/index.php index d3cd68c0dfbfc6..2f9227964ad448 100644 --- a/packages/block-library/src/comment-author-name/index.php +++ b/packages/block-library/src/comment-author-name/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comment-author-name` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -53,6 +55,8 @@ function render_block_core_comment_author_name( $attributes, $content, $block ) /** * Registers the `core/comment-author-name` block on the server. + * + * @since 6.0.0 */ function register_block_core_comment_author_name() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comment-content/index.php b/packages/block-library/src/comment-content/index.php index 50bca402acf034..3f7f5e1f4083ba 100644 --- a/packages/block-library/src/comment-content/index.php +++ b/packages/block-library/src/comment-content/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comment-content` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -69,6 +71,8 @@ function render_block_core_comment_content( $attributes, $content, $block ) { /** * Registers the `core/comment-content` block on the server. + * + * @since 6.0.0 */ function register_block_core_comment_content() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comment-date/index.php b/packages/block-library/src/comment-date/index.php index 0f9c18bf2c0068..f5876bb237b67d 100644 --- a/packages/block-library/src/comment-date/index.php +++ b/packages/block-library/src/comment-date/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comment-date` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -46,6 +48,8 @@ function render_block_core_comment_date( $attributes, $content, $block ) { /** * Registers the `core/comment-date` block on the server. + * + * @since 6.0.0 */ function register_block_core_comment_date() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comment-edit-link/index.php b/packages/block-library/src/comment-edit-link/index.php index ce7ad9bf207d43..53eaf9a2cda6c6 100644 --- a/packages/block-library/src/comment-edit-link/index.php +++ b/packages/block-library/src/comment-edit-link/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comment-edit-link` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -48,6 +50,8 @@ function render_block_core_comment_edit_link( $attributes, $content, $block ) { /** * Registers the `core/comment-edit-link` block on the server. + * + * @since 6.0.0 */ function register_block_core_comment_edit_link() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comment-reply-link/index.php b/packages/block-library/src/comment-reply-link/index.php index 3f7b6e48b617c8..7121b6f25a195e 100644 --- a/packages/block-library/src/comment-reply-link/index.php +++ b/packages/block-library/src/comment-reply-link/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comment-reply-link` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -70,6 +72,8 @@ function render_block_core_comment_reply_link( $attributes, $content, $block ) { /** * Registers the `core/comment-reply-link` block on the server. + * + * @since 6.0.0 */ function register_block_core_comment_reply_link() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comment-template/index.php b/packages/block-library/src/comment-template/index.php index 915c5880a8f962..ec462e6a050de2 100644 --- a/packages/block-library/src/comment-template/index.php +++ b/packages/block-library/src/comment-template/index.php @@ -92,6 +92,8 @@ function block_core_comment_template_render_comments( $comments, $block ) { /** * Renders the `core/comment-template` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -136,6 +138,8 @@ function render_block_core_comment_template( $attributes, $content, $block ) { /** * Registers the `core/comment-template` block on the server. + * + * @since 6.0.0 */ function register_block_core_comment_template() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comments-pagination-next/index.php b/packages/block-library/src/comments-pagination-next/index.php index 51d1f75c58d477..cb8350e561b6e4 100644 --- a/packages/block-library/src/comments-pagination-next/index.php +++ b/packages/block-library/src/comments-pagination-next/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comments-pagination-next` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -48,6 +50,8 @@ function render_block_core_comments_pagination_next( $attributes, $content, $blo /** * Registers the `core/comments-pagination-next` block on the server. + * + * @since 6.0.0 */ function register_block_core_comments_pagination_next() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comments-pagination-numbers/index.php b/packages/block-library/src/comments-pagination-numbers/index.php index b172e0c8d43f86..093a6450930f12 100644 --- a/packages/block-library/src/comments-pagination-numbers/index.php +++ b/packages/block-library/src/comments-pagination-numbers/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comments-pagination-numbers` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -50,6 +52,8 @@ function render_block_core_comments_pagination_numbers( $attributes, $content, $ /** * Registers the `core/comments-pagination-numbers` block on the server. + * + * @since 6.0.0 */ function register_block_core_comments_pagination_numbers() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comments-pagination-previous/index.php b/packages/block-library/src/comments-pagination-previous/index.php index f194e8ab517f57..092a28da677922 100644 --- a/packages/block-library/src/comments-pagination-previous/index.php +++ b/packages/block-library/src/comments-pagination-previous/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comments-pagination-previous` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @param WP_Block $block Block instance. @@ -40,6 +42,8 @@ function render_block_core_comments_pagination_previous( $attributes, $content, /** * Registers the `core/comments-pagination-previous` block on the server. + * + * @since 6.0.0 */ function register_block_core_comments_pagination_previous() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comments-pagination/index.php b/packages/block-library/src/comments-pagination/index.php index 2f9cef27f78cf6..1543fc04027eef 100644 --- a/packages/block-library/src/comments-pagination/index.php +++ b/packages/block-library/src/comments-pagination/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comments-pagination` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * @param string $content Block default content. * @@ -34,6 +36,8 @@ function render_block_core_comments_pagination( $attributes, $content ) { /** * Registers the `core/comments-pagination` block on the server. + * + * @since 6.0.0 */ function register_block_core_comments_pagination() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comments-title/index.php b/packages/block-library/src/comments-title/index.php index 62119fc0c2ca88..130132ec3fa527 100644 --- a/packages/block-library/src/comments-title/index.php +++ b/packages/block-library/src/comments-title/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/comments-title` block on the server. * + * @since 6.0.0 + * * @param array $attributes Block attributes. * * @return string Return the post comments title. @@ -84,6 +86,8 @@ function render_block_core_comments_title( $attributes ) { /** * Registers the `core/comments-title` block on the server. + * + * @since 6.0.0 */ function register_block_core_comments_title() { register_block_type_from_metadata( diff --git a/packages/block-library/src/comments/index.php b/packages/block-library/src/comments/index.php index 69e0fec8108578..e776db9b18d9d5 100644 --- a/packages/block-library/src/comments/index.php +++ b/packages/block-library/src/comments/index.php @@ -16,6 +16,8 @@ * the block is in legacy mode. If not, the HTML generated in the editor is * returned instead. * + * @since 6.1.0 + * * @global WP_Post $post Global post object. * * @param array $attributes Block attributes. @@ -85,6 +87,8 @@ function render_block_core_comments( $attributes, $content, $block ) { /** * Registers the `core/comments` block on the server. + * + * @since 6.1.0 */ function register_block_core_comments() { register_block_type_from_metadata( @@ -100,6 +104,8 @@ function register_block_core_comments() { /** * Use the button block classes for the form-submit button. * + * @since 6.1.0 + * * @param array $fields The default comment form arguments. * * @return array Returns the modified fields. @@ -118,6 +124,8 @@ function comments_block_form_defaults( $fields ) { * Enqueues styles from the legacy `core/post-comments` block. These styles are * required only by the block's fallback. * + * @since 6.1.0 + * * @param string $block_name Name of the new block type. */ function enqueue_legacy_post_comments_block_styles( $block_name ) { @@ -143,6 +151,8 @@ function enqueue_legacy_post_comments_block_styles( $block_name ) { * The same approach was followed when core/query-loop was renamed to * core/post-template. * + * @since 6.1.0 + * * @see https://github.com/WordPress/gutenberg/pull/41807 * @see https://github.com/WordPress/gutenberg/pull/32514 */ diff --git a/packages/block-library/src/cover/index.php b/packages/block-library/src/cover/index.php index 5f6b2cadaaa570..2fca0b0374dd29 100644 --- a/packages/block-library/src/cover/index.php +++ b/packages/block-library/src/cover/index.php @@ -8,6 +8,8 @@ /** * Renders the `core/cover` block on server. * + * @since 6.0.0 + * * @param array $attributes The block attributes. * @param string $content The block rendered content. * @@ -66,6 +68,8 @@ function render_block_core_cover( $attributes, $content ) { /** * Registers the `core/cover` block renderer on server. + * + * @since 6.0.0 */ function register_block_core_cover() { register_block_type_from_metadata( diff --git a/packages/block-library/src/file/index.php b/packages/block-library/src/file/index.php index ba0343ae6b25c6..df19052b4dad6c 100644 --- a/packages/block-library/src/file/index.php +++ b/packages/block-library/src/file/index.php @@ -8,6 +8,8 @@ /** * When the `core/file` block is rendering, check if we need to enqueue the `wp-block-file-view` script. * + * @since 5.8.0 + * * @param array $attributes The block attributes. * @param string $content The block content. * @param WP_Block $block The parsed block. @@ -65,6 +67,8 @@ static function ( $matches ) { /** * Registers the `core/file` block on server. + * + * @since 5.8.0 */ function register_block_core_file() { register_block_type_from_metadata( diff --git a/packages/block-library/src/gallery/index.php b/packages/block-library/src/gallery/index.php index 292ddeaf32ee2b..10237b6bfe39c6 100644 --- a/packages/block-library/src/gallery/index.php +++ b/packages/block-library/src/gallery/index.php @@ -13,6 +13,8 @@ * we add a custom `data-id` attribute before rendering the gallery * so that the Image Block can pick it up in its render_callback. * + * @since 5.9.0 + * * @param array $parsed_block The block being rendered. * @return array The migrated block object. */ @@ -35,6 +37,8 @@ function block_core_gallery_data_id_backcompatibility( $parsed_block ) { /** * Renders the `core/gallery` block on the server. * + * @since 6.0.0 + * * @param array $attributes Attributes of the block being rendered. * @param string $content Content of the block being rendered. * @return string The content of the block being rendered. @@ -164,6 +168,8 @@ static function () use ( $image_blocks, &$i ) { } /** * Registers the `core/gallery` block on server. + * + * @since 5.9.0 */ function register_block_core_gallery() { register_block_type_from_metadata( diff --git a/packages/block-library/src/heading/index.php b/packages/block-library/src/heading/index.php index 5a7e8dbaab43cf..471e31f19f2ee9 100644 --- a/packages/block-library/src/heading/index.php +++ b/packages/block-library/src/heading/index.php @@ -14,6 +14,8 @@ * Would be transformed to: *

Hello World

* + * @since 6.2.0 + * * @param array $attributes Attributes of the block being rendered. * @param string $content Content of the block being rendered. * @@ -39,6 +41,8 @@ function block_core_heading_render( $attributes, $content ) { /** * Registers the `core/heading` block on server. + * + * @since 6.2.0 */ function register_block_core_heading() { register_block_type_from_metadata( diff --git a/packages/block-library/src/home-link/index.php b/packages/block-library/src/home-link/index.php index 9ec0c185872c0f..fb7235834459d0 100644 --- a/packages/block-library/src/home-link/index.php +++ b/packages/block-library/src/home-link/index.php @@ -9,6 +9,8 @@ * Build an array with CSS classes and inline styles defining the colors * which will be applied to the home link markup in the front-end. * + * @since 6.0.0 + * * @param array $context home link block context. * @return array Colors CSS classes and inline styles. */ @@ -61,6 +63,8 @@ function block_core_home_link_build_css_colors( $context ) { * Build an array with CSS classes and inline styles defining the font sizes * which will be applied to the home link markup in the front-end. * + * @since 6.0.0 + * * @param array $context Home link block context. * @return array Font size CSS classes and inline styles. */ @@ -88,6 +92,8 @@ function block_core_home_link_build_css_font_sizes( $context ) { /** * Builds an array with classes and style for the li wrapper * + * @since 6.0.0 + * * @param array $context Home link block context. * @return string The li wrapper attributes. */ @@ -121,6 +127,8 @@ function block_core_home_link_build_li_wrapper_attributes( $context ) { /** * Renders the `core/home-link` block. * + * @since 6.0.0 + * * @param array $attributes The block attributes. * @param string $content The saved content. * @param WP_Block $block The parsed block. @@ -155,6 +163,8 @@ function render_block_core_home_link( $attributes, $content, $block ) { /** * Register the home block * + * @since 6.0.0 + * * @uses render_block_core_home_link() * @throws WP_Error An WP_Error exception parsing the block definition. */ diff --git a/packages/block-library/src/image/index.php b/packages/block-library/src/image/index.php index 0b75bf95a7d4ce..2351f6aad6c46c 100644 --- a/packages/block-library/src/image/index.php +++ b/packages/block-library/src/image/index.php @@ -9,6 +9,8 @@ * Renders the `core/image` block on the server, * adding a data-id attribute to the element if core/gallery has added on pre-render. * + * @since 5.9.0 + * * @param array $attributes The block attributes. * @param string $content The block content. * @param WP_Block $block The block object. @@ -85,6 +87,8 @@ function render_block_core_image( $attributes, $content, $block ) { * * This is used to determine whether the lightbox should be rendered or not. * + * @since 6.4.0 + * * @param array $block Block data. * * @return array Filtered block data. @@ -115,6 +119,8 @@ function block_core_image_get_lightbox_settings( $block ) { /** * Adds the directives and layout needed for the lightbox behavior. * + * @since 6.4.0 + * * @param string $block_content Rendered block content. * @param array $block Block object. * @@ -219,6 +225,9 @@ class="lightbox-trigger" return $body_content; } +/** + * @since 6.5.0 + */ function block_core_image_print_lightbox_overlay() { $close_button_label = esc_attr__( 'Close' ); @@ -238,7 +247,7 @@ function block_core_image_print_lightbox_overlay() { } echo << + + + /packages/block-library/src/.+/*\.php$ + diff --git a/test/php/gutenberg-coding-standards/Gutenberg/Sniffs/Commenting/FunctionCommentSinceTagSniff.php b/test/php/gutenberg-coding-standards/Gutenberg/Sniffs/Commenting/FunctionCommentSinceTagSniff.php new file mode 100644 index 00000000000000..54b8b367560fc5 --- /dev/null +++ b/test/php/gutenberg-coding-standards/Gutenberg/Sniffs/Commenting/FunctionCommentSinceTagSniff.php @@ -0,0 +1,162 @@ + + */ + public function register() { + return array( T_FUNCTION ); + } + + /** + * Processes the tokens that this sniff is interested in. + * + * @param File $phpcsFile The file being scanned. + * @param int $stackPtr The position of the current token in the stack passed in $tokens. + */ + public function process( File $phpcsFile, $stackPtr ) { + if ( static::is_experimental_block( $phpcsFile ) ) { + // The "@since" tag is not required for experimental blocks since they are not yet included in WordPress Core. + return; + } + + $tokens = $phpcsFile->getTokens(); + $function_name = $phpcsFile->getDeclarationName( $stackPtr ); + + $wrapping_tokens_to_check = array( + T_CLASS, + T_INTERFACE, + T_TRAIT, + ); + + foreach ( $wrapping_tokens_to_check as $wrapping_token_to_check ) { + if ( false !== $phpcsFile->getCondition( $stackPtr, $wrapping_token_to_check, false ) ) { + // This sniff only processes functions, not class methods. + return; + } + } + + $missing_since_tag_error_message = sprintf( '@since tag is missing for the "%s()" function.', $function_name ); + + // All these tokens could be present before the docblock. + $tokens_before_the_docblock = array( + T_PUBLIC, + T_PROTECTED, + T_PRIVATE, + T_STATIC, + T_FINAL, + T_ABSTRACT, + T_WHITESPACE, + ); + + $doc_block_end_token = $phpcsFile->findPrevious( $tokens_before_the_docblock, ( $stackPtr - 1 ), null, true, null, true ); + if ( ( false === $doc_block_end_token ) || ( T_DOC_COMMENT_CLOSE_TAG !== $tokens[ $doc_block_end_token ]['code'] ) ) { + $phpcsFile->addError( $missing_since_tag_error_message, $stackPtr, 'MissingSinceTag' ); + return; + } + + // The sniff intentionally doesn't check if the docblock has a valid open tag. + // Its only job is to make sure that the @since tag is present and has a valid version value. + $doc_block_start_token = $phpcsFile->findPrevious( Tokens::$commentTokens, ( $doc_block_end_token - 1 ), null, true, null, true ); + if ( false === $doc_block_start_token ) { + $phpcsFile->addError( $missing_since_tag_error_message, $stackPtr, 'MissingSinceTag' ); + return; + } + + // This is the first non-docblock token, so the next token should be used. + ++$doc_block_start_token; + + $since_tag_token = $phpcsFile->findNext( T_DOC_COMMENT_TAG, $doc_block_start_token, $doc_block_end_token, false, '@since', true ); + if ( false === $since_tag_token ) { + $phpcsFile->addError( $missing_since_tag_error_message, $stackPtr, 'MissingSinceTag' ); + return; + } + + $version_token = $phpcsFile->findNext( T_DOC_COMMENT_WHITESPACE, $since_tag_token + 1, null, true, null, true ); + if ( ( false === $version_token ) || ( T_DOC_COMMENT_STRING !== $tokens[ $version_token ]['code'] ) ) { + $phpcsFile->addError( $missing_since_tag_error_message, $since_tag_token, 'MissingSinceTag' ); + return; + } + + $version_value = $tokens[ $version_token ]['content']; + + if ( version_compare( $version_value, '0.0.1', '>=' ) ) { + // Validate the version value. + return; + } + + $phpcsFile->addError( + 'Invalid @since version value for the "%s()" function: "%s". Version value must be greater than or equal to 0.0.1.', + $version_token, + 'InvalidSinceTagVersionValue', + array( + $function_name, + $version_value, + ) + ); + } + + /** + * Checks if the current block is experimental. + * + * @param File $phpcsFile The file being scanned. + * @return bool Returns true if the current block is experimental. + */ + private static function is_experimental_block( File $phpcsFile ) { + $block_json_filepath = dirname( $phpcsFile->getFilename() ) . DIRECTORY_SEPARATOR . 'block.json'; + + if ( isset( static::$cache[ $block_json_filepath ] ) ) { + return static::$cache[ $block_json_filepath ]; + } + + if ( ! is_file( $block_json_filepath ) || ! is_readable( $block_json_filepath ) ) { + static::$cache[ $block_json_filepath ] = false; + return static::$cache[ $block_json_filepath ]; + } + + // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- this Composer package doesn't depend on WordPress. + $block_metadata = file_get_contents( $block_json_filepath ); + if ( false === $block_metadata ) { + static::$cache[ $block_json_filepath ] = false; + return static::$cache[ $block_json_filepath ]; + } + + $block_metadata = json_decode( $block_metadata, true ); + if ( ! is_array( $block_metadata ) ) { + static::$cache[ $block_json_filepath ] = false; + return static::$cache[ $block_json_filepath ]; + } + + $experimental_flag = '__experimental'; + static::$cache[ $block_json_filepath ] = array_key_exists( $experimental_flag, $block_metadata ) && ( false !== $block_metadata[ $experimental_flag ] ); + return static::$cache[ $block_json_filepath ]; + } +} diff --git a/test/php/gutenberg-coding-standards/Gutenberg/Tests/Commenting/FunctionCommentSinceTagUnitTest.inc b/test/php/gutenberg-coding-standards/Gutenberg/Tests/Commenting/FunctionCommentSinceTagUnitTest.inc new file mode 100644 index 00000000000000..43d11694bb25eb --- /dev/null +++ b/test/php/gutenberg-coding-standards/Gutenberg/Tests/Commenting/FunctionCommentSinceTagUnitTest.inc @@ -0,0 +1,39 @@ + => + */ + public function getErrorList() { + // The sniff only supports PHP functions for now; it ignores class, trait, and interface methods. + return array( + 9 => 1, + 19 => 1, + 24 => 1, + ); + } + + /** + * Returns the lines where warnings should occur. + * + * @return array => + */ + public function getWarningList() { + return array(); + } +}