coding-standard-php-short-echo-tag.md

Coding Standard Proposal: Allow the use of the PHP short echo tag

Currently, the WordPress Coding Standard explicitly forbids the use of the PHP short echo tag (<?=) along with the PHP short tag (<?). This post proposes modifying this rule to allow the use of the short echo tag for single statements.

Motivation

Prior to PHP 5.4, it was possible to disable the PHP short echo tag (<?=) using the PHP short_open_tag ini directive. This meant that scripts using this tag could not be used in code that must work on different PHP installations, as the content within those tags may be printed instead of executed, which could lead to code exposure. For this reason, the WordPress Coding Standards forbid its use.

Since PHP 5.4, the short echo tag is always available, and changing the short_open_tag directive no longer affects it. WordPress dropped support for versions prior to PHP 5.6 in 2019, and since then raised the minimum supported PHP version to 7.2. Currently, according to WordPress.org stats, the percentage of active WP installs using PHP < 5.4 is 0.4% and the percentage of sites still using WP < 5.2 is 4.0%. Therefore, it is now safe to allow the use of short echo tags.

This tag is useful as it provides a more concise syntax for outputting values in template files. WordPress developers should be allowed to use it. An issue requesting this change is the most liked issue in the WPCS repository, indicating community support.

This proposal is about allowing the use of the short echo tag for single statements, not encouraging its use, so no immediate changes are required. In practice, this means that:

• Existing open patches for Core are not affected as either style is allowed.
• Existing WP Core code and code in official WP themes should not be updated as both styles are permitted. A patch to enforce the use of short echo tags in all possible places will NOT be accepted.
• However, a new official theme could choose to use short echo tags if desired.

Suggested change to the handbook

The suggestion is to modify the rule titled "No Shorthand PHP Tags" as follows:

New title: No PHP short open tag

Content:

Important: Never use the PHP short open tag (`<?`). Always use the full PHP open tag (`<?php`). Using the PHP short echo tag (`<?=`) is allowed, though short echo tag snippets should only contain a single statement.

Correct:

<?php ... ?>
<?= esc_html( $var ); ?>

Incorrect:

<? ... ?>

How to keep short echo tags forbidden in a given project

If this proposal is accepted, but a project wants to keep the short echo tag forbidden in its own codebase, it can do so by adding the following snippet to its PHPCS configuration after the WordPress standard is included:

<rule ref="Generic.PHP.DisallowShortOpenTag.EchoFound">
    <severity>5</severity>
</rule>

References

• Related issue in the WPCS repository: WordPress/WordPress-Coding-Standards#1642

#codingstandards, #php, #wpcs

Hi @rodrigoprimo, I've had a read through this. Here are my notes:

• Please don't mention "RFC". WP/WPCS does not have a formal RFC process, so this could cause a discussion about that instead of about the actual proposal.
• I would move the "Motivation" section up to above the "handbook change". The motivation justifies making the handbook change, the handbook change is the end result.
• "Up until PHP 5.3" is ambiguous. Maybe change this to "Prior to PHP 5.4" ?
• "... using the short_open_tag directive." => "... using the PHP short_open_tag ini directive."
• "This meant that this tag could not be used in code that must work on different PHP installs" - why not ? Let's explain this a little. I.e. as the code within those tags may not be executed and this could lead to code exposure.
• "which is probably why the WordPress Coding Standards forbid its use." - no "probably" about it. That is the reason. (For the short open tag, an additional reason is problems around file interpretation with XML).
• "So, there is no reason why WordPress code should not use the PHP short open tag anymore." - Let's be a little more specific here. Yes, WP dropped support for PHP < 5.6 in 2019 and since then raised the minimum supported PHP version to 7.2. But moreover, lots of plugins have followed suite and dropped support for PHP < 7.2, the number of active WP installs using PHP < 5.4 has dropped to ..%, and the number of sites still using WP < 5.2 has dropped to ..%, so it should now be considered safe to allow the use of short open echo tags.
• "Note that the PHP short echo tag is allowed." => "Using the PHP short echo tag is allowed, though short echo tag snippets should only contain a single statement."
• Code sample: please end the statement with a ; before the close tag.

/cc @GaryJones @dingo-d

In principle, I'm not against allowing short echo tags, but if we allow them, why not allow short open PHP tags as well?

In practice though, I always found them confusing, and have seen legacy code littered with regular PHP tags, short tags, and short echo tags, which made the code a bit harder to read (personal experience, and others can have different opinions ofc).

That is my experience and why I'm not in favor of using them. I like things to be consistent throughout the codebase 🤷‍♂️

In principle, I'm not against allowing short echo tags, but if we allow them, why not allow short open PHP tags as well?

The reasons to not allow short open tags <? are still the same:

• These are still under the control of the short_open_tag directive, which if "Off" by default.
• This is a setting which cannot be changed at runtime.
• And even if it could, changing it at runtime might break other plugins/themes.
• So the short open tag could still lead to code exposure.
• And also may break on XML files or XML code within PHP files within inline HTML <?xml....

That is my experience and why I'm not in favor of using them. I like things to be consistent throughout the codebase 🤷‍♂️

Short open echo tags can still be forbidden, even if we remove the rule, but in that case, you'd need to do it in your own ruleset ;-)

Yeah, those arguments are all why I'm not for allowing it, as it just causes inconsistencies, and nobody forbids them to be used in plugins or themes to my knowledge. This proposal would be for core standards or extra?

@dingo-d What are the inconsistencies you see ?

I mean, with the addition I suggest about "one statement only", it means the following difference:

-<div class="<?php echo esc_attr($classes); ?>"><p><?php echo esc_html($username); ?></p></div>
+<div class="<?= esc_attr($classes); ?>"><p><?= esc_html($username); ?></p></div>

// This would not be changable.
<?php
foreach ([$foo, $bar] as $name) {
    echo $name . '</br>'
}
?>

<!-- And this would also still not be allowed. -->
<?= $name;
do_something_else();

Having said that, maybe it is a good idea to explicitly state in the Make post that it no longer being forbidden has no immediate impact, as the rule is not replaced with an encouragement to use short open echo tags. It is only allowed.
In practice, this means that

• Existing open patches for Core are not affected as either style is allowed.
• Existing WP Core code and code in official WP themes should not be updated as there is no reason to. Both styles are allowed.
  This also means that a patch to enforce the use of short open echo tags in all possible places will NOT be accepted.
• However, a new official theme, could choose to use short open echo tags if they'd want to.

Also keep in mind, this is the most "liked" issue in the WPCS repo.
It is an often requested change, especially by plugin/theme devs who want to follow the coding standards, and run into WPCS forbidding it as Core forbids it.

And just like the "remove the yoda conditions requirement" change proposal, the Make post is only a proposal and can still be rejected. If it is, at least we then have a solid argument to close issue #1642. If it's not, we make a lot of people happy (and still nobody is forced to use it).

Short open echo tags can still be forbidden, even if we remove the rule, but in that case, you'd need to do it in your own ruleset ;-)

Maybe we should add a code snippet in the Make post showing how to do that ?

Something like, "If this proposal would be accepted, but you still want to forbid short open echo tags in your own codebase, this is how you do it..."

Thanks for checking this proposal, @jrfnl! I just finished updating it and it is ready for another check.

Regarding your first comment, I added all the suggestions that you made. I have just one note about the item below:

"Note that the PHP short echo tag is allowed." => "Using the PHP short echo tag is allowed, though short echo tag snippets should only contain a single statement."

Besides what you suggested, I modified the first paragraph of the proposal to also mention that this change applies only to single statements: "This post proposes that this rule is modified to allow the use of the short echo tag." => "This post proposes modifying this rule to allow the use of the short echo tag for single statements."

Regarding the other comments:

Having said that, maybe it is a good idea to explicitly state in the Make post that it no longer being forbidden has no immediate impact, as the rule is not replaced with an encouragement to use short open echo tags.

Good point, I added the text that you suggested with some small modifications.

Also keep in mind, this is the most "liked" issue in the WPCS repo.

I also included a sentence about this issue being the most liked one in the WPCS repo.

Maybe we should add a code snippet in the Make post showing how to do that ?

There is now a new section at the end of the proposal with the snippet that can be added to a custom ruleset to keep short echo tags forbidden. My assumption is that if this proposal is accepted, it will be implemented with the code below and I based my snippet on that. Please let me know if that is not the case.

<rule ref="Generic.PHP.DisallowShortOpenTag.EchoFound">
    <severity>0</severity>
</rule>

Since PHP 5.4, ...

This paragraph contains too much text as a link. Make the links wrap fewer key words where possible please.

Using the PHP short echo tag is allowed

Change this to:

Using the PHP short echo tag (<?=) is allowed

...so it's immediately clear (and comparable to the previous two examples in that paragraph) what we mean in case folks aren't familiar with the named terminology.

This tag is useful, especially when writing PHP templates, and WordPress developers should be allowed to use it.

There's no explanation of how it's useful.

as the content within those tags may not be executed, which could lead to code exposure.

This sentence doesn't work as there is no logic between the two parts. How about this:

as the content within those tags may be printed instead of executed, which could lead to code exposure.

Probably also a good idea to update the text in which you reference to stats about PHP version usage amongst WP users.

Thanks for your input, @GaryJones and @jrfnl! I have made the changes that you mentioned and also made small adjustments to two sentences to improve the text.

@GaryJones, regarding two of your remarks:

This paragraph contains too much text as a link. Make the links wrap fewer key words where possible please.

Do you think it is better now or do you suggest wrapping even fewer words?

There's no explanation of how it's useful.

The new sentence is "This tag is useful as it provides a more concise syntax for outputting values in template files". Do you think I should highlight any other benefit of using this tag?

changing the short_open_tag directive no longer affects it.

I'd have made it:

changing the short_open_tag directive no longer affects it.

but otherwise, yes, that paragraph is better.

I think the new reason sentence is enough for now.

I'd have made it:

changing the short_open_tag directive no longer affects it.

Yeah, that is better. I just updated the text. Thanks.