Newline required after opening brace triggered for allowed loop syntax

[desrosj]

The WordPress coding standards state:

You are free to use the alternative syntax for control structures (e.g. if/endif, while/endwhile)—especially in your templates where PHP code is embedded within HTML, for instance:

<?php if ( have_posts() ) : ?>
    <div class="hfeed">
        <?php while ( have_posts() ) : the_post(); ?>
            <article id="post-<?php the_ID() ?>" class="<?php post_class() ?>">
                <!-- ... -->
            </article>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

The current version of the standard does not allow this though. Newline required after opening brace is thrown for the following code snippets:

• <?php while ( have_posts() ) : the_post(); ?>
• <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>

Running phpcbf on these two examples will produce the following, respectively:

<?php
	while ( have_posts() ) :
		the_post();
?>

<?php
	if ( have_posts() ) :
		while ( have_posts() ) :
			the_post();
?>

[GaryJones]

Where you put the <?php delimiter, is unrelated to the use of alternative control structure syntax.

<?php
if ( have_posts() ) :
	?>
	<div class="hfeed">
		<?php
		while ( have_posts() ) :
			the_post();
			?>
			<article id="post-<?php the_ID() ?>" class="<?php post_class() ?>">
				<!-- ... -->
			</article>
			<?php
		endwhile;
		?>
	</div>
	<?php
endif;
?>

Would likely pass.

[desrosj]

Maybe I mislabeled the ticket.

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<?php if ( have_posts() ) : the_post(); ?>
and
<?php while ( have_posts() ) : the_post(); ?> are very common, have been for a long time, and are documented as allowed in the handbook.

My opinion is that new lines should not be required for these cases.

[desrosj]

Updated the ticket title (the first title I wrote before diving deeper into the issue to debug)

[jrfnl]

This was previously discussed in #1000 and the requirement for PHP open/close tags to be on their own lines for multi-statement embedded PHP has been added explicitly to the WP Core Handbook:
https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#opening-and-closing-php-tags

So, no, this is not "allowed in the handbook".

[GaryJones]

The reference @jrfnl gave leads to:

When embedding multi-line PHP snippets within a HTML block, the PHP open and close tags must be on a line by themselves.

Though, to be fair, that's a little confusing when it relates to, for instance <?php endwhile; ?>.

[JDGrimes]

Though, to be fair, that's a little confusing when it relates to, for instance <?php endwhile; ?>.

Yeah, they are allowed to both be on the same line, but if only one of them is on the line, then it has to be by itself without other code.

Which is why "multi-line" is the important word there.

---

But this isn't about the tags, it is about brace style. And the handbook does indeed include this example:

<?php if ( have_posts() ) : ?>
    <div class="hfeed">
        <?php while ( have_posts() ) : the_post(); ?>
            <article id="post-<?php the_ID() ?>" class="<?php post_class() ?>">
                <!-- ... -->
            </article>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#brace-style

The third line (<?php while ( have_posts() ) : the_post(); ?>) puts code on the line after the "brace."

It could be changed to this:

 <?php while ( have_posts() ) : ?>
     <?php the_post(); ?>

And that would also pass.

But I think this pattern is common enough that we might want to consider making a special allowance for it.

[jrfnl]

Which is why "multi-line" is the important word there.

Actually, it's not about "multi-line", but about "multi-statement". This is not clear enough in the handbook and I think it would be good to clarify this there.

Regarding the brace style example - IMHO it would be better to change that code snippet in the handbook to the below:

<?php
while ( have_posts() ) :
     the_post();
     ?>

But I think this pattern is common enough that we might want to consider making a special allowance for it.

The reason the handbook was adjusted and this sniff was added to the Core ruleset is that without it we get into trouble with fixer conflicts.

As it's been decided to add it, I would very much be in favour of applying it consistently and not having semi-random "exceptions".

[GaryJones]

I'm in agreement here - just the wording / example in the Handbook needs tweaking to make it clearer.

[desrosj]

For some more context, Codex actually displays this loop format as well (acknowledging that parts of the Codex are outdated).

My point was only that this is very common out in the wild, and many learning resources I have seen people use have taught this style. Not against change, but just wanted to raise that this is very common, and may be worth looking at further.

[JDGrimes]

I'm fine with updating the handbook and codex, I just wanted to make sure that we're all on the same page with regard to the fact that this has basically been the de facto standard up to now. Personally, I think that one statement per line is far more readable; it's easy to miss the second statement. So I'm happy to just say this isn't really feasible technically to add an exception for, and move on.

[jrfnl]

Pinging @pento @ntwb - if you agree with the above, could either of you adjust the handbook accordingly ?

[jrfnl]

Ping @pento @ntwb ⬆️