Twenty Seventeen: twentyseventeen_edit_link() function passed

[westonruter]

As part of #64680 to increase the PHPStan rule level to 1 (​PR), PHPStan identified that Twenty Seventeen is passing get_the_ID() into twentyseventeen_edit_link(). Nevertheless, this function does not take any parameters. I had ​removed the argument from being passed, but I wondered if the fact that it is a pluggable function could cause issues for child themes that may have overridden that function and is doing something with the parameter.

As ​discovered by @sabernhardt:

I wondered why the function did not have a parameter and then found out it had an $id parameter in the ​initial commit. But then the ​page/post context was removed, and the ​parameter was removed before the function was ever pluggable (and before version 1.0). Also, the ​comment about context does not seem appropriate.

Trac ticket:

## Use of AI Tools

[mukesh27]

Looks good.

The function documentation update just needs to be reverted, and then it should be ready for commit.

[sabernhardt]

child theme that replaces the twentyseventeen_edit_link() with a version from early development (which expects a parameter)

[westonruter]

To me, then, it seems we should actually go ahead and document the parameter and actually use it:

src/wp-content/themes/twentyseventeen/inc/template-tags.php

@@ -116 +116 @@
          * (post or page?) so that users understand a bit more where they are in terms
          * of the template hierarchy and their content. Helpful when/if the single-page
          * layout with multiple posts/pages shown gets confusing.
+         *
+         * @param int $post_id Post ID. Default 0.
          */
-        function twentyseventeen_edit_link() {
+        function twentyseventeen_edit_link( $post = 0 ) {
                 edit_post_link(
                         sprintf(
                                 /* translators: %s: Post title. Only visible to screen readers. */
                                 __( 'Edit<span class="screen-reader-text"> "%s"</span>', 'twentyseventeen' ),
-                                get_the_title()
+                                get_the_title( $post )
                         ),
                         '<span class="edit-link">',
-                        '</span>'
+                        '</span>',
+                        $post
                 );
         }
 endif;

The get_the_title() and edit_post_link() functions take a $post param that defaults to 0 anyway, the end result would be identical.

Note: There do not appear to be any child themes on the directory that override this pluggable function: <​https://veloria.dev/search/ec609afc-8b60-4ea2-8333-6c58d559c618>. Although there could be outside the directory.

[sabernhardt]

Removing the parameter from page content templates should have very low risk, but that is higher than zero.

With the attached child theme:

• Single post and any archive (including blog and front page of posts) templates would already require adjustments to template files if a custom twentyseventeen_edit_link() requires a parameter. If the site has pages without any posts, that could avoid the errors, but then why would someone create a replacement function with a parameter?
• The single page template and static front page (with or without page panels) would start to throw PHP fatal errors with PR 11209, unless those templates are also included in the child theme with a parameter.

[westonruter]

@sabernhardt So what about what I propose in my comment?

The templates can be left as-is.

[sabernhardt]

Searches:

• A ​GitHub code search found ​one theme that assigns a Boolean parameter in its replacement function, with a default value, and adjusts templates accordingly.
• A ​plugin directory search found 3 plugins that use get_the_ID() as a parameter (Customize Twenty Seventeen, Page Sidebar for Twenty Seventeen, and Ultimate Booking Manager) and the CloudSearch plugin uses the function without a parameter.
• A ​theme directory search found Dynamic Seventeen with the parameter, Chandigarh without it, and Minimal 20/17 and Delect use the function both with and without a parameter.

Adds a $post_id parameter to twentyseventeen_edit_link() and updates documentation.

Trac 64825

Use of AI Tools: none

[sabernhardt]

I have no expectation that sites would require the parameter, so I did not like the idea of adding a parameter to the theme's function just for code quality.

However, PR 11242 did not affect the output for any of these edit links:

• front page (Home)
• the four pages added to the front page section content panels
• single page (About)
• page of posts (Blog)
• single post (Today's post)
• category archive (Uncategorized)

PR 11242 did not alter the function output when I added these filters either (in a custom must-use plugin):

/**
 * Appends the post type and ID after the post edit link anchor tag.
 *
 * @param string $link    Anchor tag for the edit link.
 * @param int    $post_id Post ID.
 */
function edit_post_link_add_post_type_and_id( $link, $post_id = 0 ) {
	$post_type = get_post_type( $post_id );
	if ( $post_type ) {
		$link .= ' ' . $post_type . '-' . $post_id;
	}

	return $link;
}
add_filter( 'edit_post_link', 'edit_post_link_add_post_type_and_id', 10, 2 );

/**
 * Appends the post type and ID after the post title.
 *
 * @param string $post_title The post title.
 * @param int    $post_id    The post ID.
 */
function the_title_add_post_type_and_id( $post_title, $post_id = 0 ) {
	$post_type = get_post_type( $post_id );
	if ( $post_type ) {
		$post_title .= ' ' . $post_type . '-' . $post_id;
	}

	return $post_title;
}
add_filter( 'the_title', 'the_title_add_post_type_and_id', 10, 2 );

[westonruter]

In 62000:

Twenty Seventeen: Restore $post_id parameter to twentyseventeen_edit_link() which is being passed in some templates.

This addresses arguments.count errors identified by PHPStan at rule level 1.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11242

Follow-up to WordPress/twentyseventeen commits: ​1afb73c, ​7dd3025, ​6948288.

Props sabernhardt, westonruter.
See #64680.
Fixes #64825.

[westonruter]

I've amended @pratiknawkar94 and @mukesh27 to props on r62000 via Core Props.

Committed in r62000 (b00c4ac)