Pre-review stage review of PSR-12

[Michael Cullum]

Hi all,

PSR-12 [Extended Coding Style guide] was never intended to be that much more than PSR-2 ever was. It was intended to fix a few issues in PSR-2 with clarifications, or things that were meant but not said, and PHP 7 functionality primarily in addition to a couple of things that it was felt really should be included due to PHP 7 functionality (such as declare statements and operators).

PSR-12 is now basically ready for review but I wanted to post to the list and ask people to have a quick look over it before that as once we enter review, we have a much more bureaucratic process with regards to making any necessary changes. Assuming nothing major comes up, we'll be looking to move it into review towards the end of the week. We have provided a non-comprehensive changelog of some of the most notable changes in the meta document should you wish you just review those parts and not the whole specification (which includes all of PSR-2).

You can view it here: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md

Thanks all!

--

Michael

[Alexander Makarov]

And there's meta: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide-meta.md

[Matteo Beccati]

On 02/12/2015 11:08, Michael Cullum wrote:
> Hi all,
>

> You can view it here:
> https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md
>
> Thanks all!

In most if not all the examples a blank line is missing between <?php
and namespace, whereas "When no declare declarations are present there
MUST be a blank line after the opening <?php tag."

However, I'm also wondering why declare() should be an exception. Most,
if not all, the code I've been seeing in the past few (many?) years has
a blank line after <?php, hence my suggestion about declare() following
suit.

I'm sorry if this has been discussed already. If so, I must have missed it.


Cheers
--
Matteo Beccati

Development & Consulting - http://www.beccati.com/

[Paul M. Jones]

> On Dec 2, 2015, at 04:08, Michael Cullum <m...@michaelcullum.com> wrote:
>
> Hi all,
>
> PSR-12 [Extended Coding Style guide] was never intended to be that much more than PSR-2 ever was. It was intended to fix a few issues in PSR-2 with clarifications, or things that were meant but not said, and PHP 7 functionality primarily in addition to a couple of things that it was felt really should be included due to PHP 7 functionality (such as declare statements and operators).
>
> PSR-12 is now basically ready for review but I wanted to post to the list and ask people to have a quick look over it before that as once we enter review, we have a much more bureaucratic process with regards to making any necessary changes. Assuming nothing major comes up, we'll be looking to move it into review towards the end of the week. We have provided a non-comprehensive changelog of some of the most notable changes in the meta document should you wish you just review those parts and not the whole specification (which includes all of PSR-2).

I have not yet reviewed the document. A comment, and a question.

Comment: It is stil my opinion that the document should be *de*scriptive of what member projects already do, not *pre*scriptive in telling them what to do in future. As such, waiting until member projects adopt PHP 7 and start working with it would be the better course of action regarding a style document.

Question: How much research did the authors do, regarding what existing projects already do, and making sure the document matches the pre-existing majority behaviors, especially in the case with non-PHP-7-specific guidelines?


--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

Modernizing Legacy Applications in PHP
https://leanpub.com/mlaphp

Solving the N+1 Problem in PHP
https://leanpub.com/sn1php

[Christopher Pitt]

From: https://groups.google.com/forum/#!searchin/php-fig/meeting$20notes/php-fig/pxezV88Uk1I/eW3GvtPRCgAJ

At this time, the recommendation from the meeting is for the PSR-12 team to watch and see what projects that adopt PHP 7 end up doing over the next 6-12 months, and take their lead from that.  That doesn't necessarily mean "just do what they do", but be informed by it.

[Christopher Pitt]

Further to this (and Paul's point); PSR-2 was relatively easy to do because projects/group were surveyed as to what they were doing at the time/wanted the style to be. There is bound to be disagreement with at least some of the MUST's in this draft, and a single yes/no vote to everything becomes meaningless at that point.

[Adrien Crivelli]

Hey,

I join Matteo Beccati here and it seems the situation about blank line after "<?php" tag is not clear yet. It would be best to clarify before final release. As a matter of fact this concern was already raised in https://github.com/php-fig/fig-standards/issues/655, but IMHO not resolved as clearly as it should have been.

If I had to give an opinion on that, I'd say no exception for declare() statement and always have exactly 1 blank line after opening tag. That seems much simpler to explain and implements.

Cheers,

Adrien

[Woody Gilk]

+1 for always requiring a blank line after the opening tag.

--
Woody Gilk
http://about.me/shadowhand

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/ba3d6af4-f731-47b9-801d-5d0282941871%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Shefik]

I also agree about requiring a blank line, after the opening tag.

- Shefik

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6KMrxY-m8JxL1tVKFd7kcP%3D_ncpQZ4%2BYGH4uZZTy%2B%2B9bg%40mail.gmail.com.

[Marcus Bointon]

Section 3 says:

When no declare declarations are present there MUST be a blank line after the opening <?php tag.

I think this blank line is really pointless, just a waste of space. As testament to this being entirely unnatural, notice that this rule is contravened by almost every example in the PSR-12 doc! What good reason is there for requiring it? I don't recall seeing any code that does this.

Personally I would expect the first thing after an initial opening php tag to be a file-level docblock, but comments are not mentioned in PSR-12.

Marcus

[Christopher Pitt]

I don't recall seeing any code that does this.

...Perhaps this is because there are no community standards for languages features new in PHP 7.

[Michael Cullum]

Hi all,

Regarding the opening line that was an error, what it should have said, and now does, is "When the opening `<?php` tag is on the first line of the file, it MUST be on it's own line with no other statements."

To address the questions from PMJ and Christopher raised the vast majority of things we applied existing logic from PSR-2 in a lot of things such as the finally blocks or lowercase type hints. The only things we couldn't really apply much logic from are the spacing and lines for return type declarations and declare statement (same line as opening tag or new line). For return type declarations we looked at a lot of the PHP 7 talks going on, documentation, wiki and all of them that we found were using it in the same way and we therefore were of the opinion this is likely to be the most defined way of formatting it in addition to the fact that subjectively we surveyed a number of people who preferred that formatting and thought it looked better.

There was always going to be a small bit of prescriptive vs descriptive. Ultimately the point of having lots of projects in the FIG is that we can see if there are any objections from projects doing it this particular way and if any projects, when implementing this, would do it a different way so I'd be open to hear from other projects if they have things to suggest. Asking what projects would do if they were to do it now is almost exactly the same as looking at what they are doing in 3 years, they are just making the decision earlier. 

--

Michael C

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/70611ae2-3290-4ba7-b3d8-2a63cc271ba1%40googlegroups.com.

[Marcus Bointon]

On Thursday, 3 December 2015 11:26:34 UTC+1, Christopher Pitt wrote:

...Perhaps this is because there are no community standards for languages features new in PHP 7.

None of declare, use or namespace are new in PHP7. Blank lines after '<?php' have been possible since the beginning of PHP, but I don't see anyone doing it in any volume.

[Matteo Beccati]

On 03/12/2015 11:26, Michael Cullum wrote:
> Asking what projects would do if they were to do it now is almost
> exactly the same as looking at what they are doing in 3 years, they
> are just making the decision earlier.

I agree. I see no point in waiting here.

In fact, I guess someone might already be looking into our direction for
guidance, and the worst thing we could do is to suggest them to do
whatever they please now, then tell them they were wrong all along after
a few years.

[Alessandro Pellizzari]

On 02/12/2015 10:08, Michael Cullum wrote:

> PSR-12 is now basically ready for review but I wanted to post to the
> list and ask people to have a quick look over it before that as once we
> enter review, we have a much more bureaucratic process with regards to
> making any necessary changes.

I don't think using MUST for use namespace grouping is a good choice.
I checked some projects (just to name a couple, Symfony and Propel) and
none uses grouping in the use lines.

Probably it's because IDEs don't group them, and many people just rely
on IDEs autocomplete to insert the use statements.

I would use SHOULD there, or remove the grouping completely.


I also still hate spaces for indentation (I find them perfect for
alignment) but I don't think you will change your mind on this, so I
will continue to use an exception in my code.

Bye.

[Michael Cullum]

Using SHOULDs is not preferable. As that line makes the spec incompatible with any projects running PHP <7 as well I've removed it (Or at least, I will have once my PR is merged).

--

Michael C

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/56602806.9030800%40amiran.it.

[Matteo Beccati]

Hi,

On 03/12/2015 11:26, Michael Cullum wrote:

> Regarding the opening line that was an error, what it should have said,
> and now does, is "When the opening `<?php` tag is on the first line of
> the file, it MUST be on it's own line with no other statements."

Thanks for the clarification. However PSR-12 (and PSR-2) do not enforce
the no-blank line policy after <?php for anything but declare now, which
feels a bit weird.

I personally am a fan of the blank-line. PHP-CS-Fixer has a fixer in the
"symfony" group that takes care of that if the file is "monolithic php".
Some will surely disagree with me, but I think it is important is to
either define a rule covers everything (not just declare), or none at all.

[Woody Gilk]

There is a requirement for a newline after the first "namespace" and after the last "use". I personally have always found it weird there is no requirement about a newline after the opening tag. It just looks more balanced with whitespace before and after "namespace".

--
Woody Gilk
http://about.me/shadowhand

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/56605146.7000501%40beccati.com.

[Brian Retterer]

Initial review from me brings up two points.

1: I agree with the desire to have a blank line after the opening <?php as it looks better and is easier to read in my opinion.

2: I do not agree with the requiring () after instantiating a new class. https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#4-classes-properties-and-methods states "When instantiating a new class, parenthesis MUST always be present even when there are no arguments passed to the constructor." but this feels a little broken to me when we get down to Anonymous Classes.  Yes, I understand that it is an anonymous class, but to instantiate that, you do `new class` with no closing ().  I have always been a fan that I can just say `new Foo;` if there are no arguments making it cleaner code to my eyes.

Just some initial thoughts here.

[Michael Cullum]

1. I'd rather not require it as there isn't good consensus but there does seem to be good consensus that namespaces must not be on the same line as the opening php tag.

2. It wouldn't apply to anonymous classes? It's more about $var = \Foo(); vs $var = \Foo;

--
Thanks,
Michael Cullum

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/eed0e8ad-7cea-4e06-a638-8136f0a3e269%40googlegroups.com.

[Gary Hockin]

<pedantry>

$var = new \Foo(); vs $var = new \Foo;

</pedantry>

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAAqcDMiODf-YQ1rc-EoZAx6yFxBT_ptZUXV_RoFKcuFAz9LLkQ%40mail.gmail.com.

[Woody Gilk]

+1 for not requiring () on "new Foo". There should be no recommendation either way for that, it is entirely personal preference imo.

--
Woody Gilk
http://about.me/shadowhand

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAAueXOWV%2BDoMaUsXNUpWJ1zZoRqa0smGBzZ2mfPJJT09OVpnwg%40mail.gmail.com.

[Gary Hockin]

I would like to see it quantified one way or another, I was under the assumption that code style standards are there to remove personal preference?

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6LNuBMG0CeuboVghzN6RH82ZDsCRXGkioD4r__syvKxRw%40mail.gmail.com.

[Larry Garfield]

I much prefer to see code with the () always after a class name. Then I
don't need to think about it, and if a parameter gets added later the
parens are already there. It's in the same vein as {} on a for loop.

Drupal's coding standards have long included a () on classes.

> <mailto:php-fig+u...@googlegroups.com>.

> To post to this group, send email to
> php...@googlegroups.com

> <mailto:php...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/php-fig/eed0e8ad-7cea-4e06-a638-8136f0a3e269%40googlegroups.com
> <https://groups.google.com/d/msgid/php-fig/eed0e8ad-7cea-4e06-a638-8136f0a3e269%40googlegroups.com?utm_medium=email&utm_source=footer>.

> For more options, visit
> https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to
> the Google Groups "PHP Framework Interoperability Group"
> group.
> To unsubscribe from this group and stop receiving emails
> from it, send an email to
> php-fig+u...@googlegroups.com

> <mailto:php-fig+u...@googlegroups.com>.

> To post to this group, send email to

> php...@googlegroups.com <mailto:php...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/php-fig/CAAqcDMiODf-YQ1rc-EoZAx6yFxBT_ptZUXV_RoFKcuFAz9LLkQ%40mail.gmail.com
> <https://groups.google.com/d/msgid/php-fig/CAAqcDMiODf-YQ1rc-EoZAx6yFxBT_ptZUXV_RoFKcuFAz9LLkQ%40mail.gmail.com?utm_medium=email&utm_source=footer>.

> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the
> Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from
> it, send an email to php-fig+u...@googlegroups.com

> <mailto:php-fig+u...@googlegroups.com>.

> To post to this group, send email to php...@googlegroups.com

> <mailto:php...@googlegroups.com>.

>
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/php-fig/CAAueXOWV%2BDoMaUsXNUpWJ1zZoRqa0smGBzZ2mfPJJT09OVpnwg%40mail.gmail.com
> <https://groups.google.com/d/msgid/php-fig/CAAueXOWV%2BDoMaUsXNUpWJ1zZoRqa0smGBzZ2mfPJJT09OVpnwg%40mail.gmail.com?utm_medium=email&utm_source=footer>.

>
>
> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google
> Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to php-fig+u...@googlegroups.com

> <mailto:php-fig+u...@googlegroups.com>.

> To post to this group, send email to php...@googlegroups.com

> <mailto:php...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/php-fig/CAGOJM6LNuBMG0CeuboVghzN6RH82ZDsCRXGkioD4r__syvKxRw%40mail.gmail.com
> <https://groups.google.com/d/msgid/php-fig/CAGOJM6LNuBMG0CeuboVghzN6RH82ZDsCRXGkioD4r__syvKxRw%40mail.gmail.com?utm_medium=email&utm_source=footer>.

> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google
> Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to php-fig+u...@googlegroups.com

> <mailto:php-fig+u...@googlegroups.com>.

> To post to this group, send email to php...@googlegroups.com

> <mailto:php...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/php-fig/CAAueXOXwWkEDCg-ynk_ifwwuPLa4zFHhGMQKKrS3gGM_GDCA1A%40mail.gmail.com
> <https://groups.google.com/d/msgid/php-fig/CAAueXOXwWkEDCg-ynk_ifwwuPLa4zFHhGMQKKrS3gGM_GDCA1A%40mail.gmail.com?utm_medium=email&utm_source=footer>.

> For more options, visit https://groups.google.com/d/optout.

--

--Larry Garfield

[Woody Gilk]

Neither PSR-1 or PSR-2 make mention of it. I'd prefer it stay that way.

On Thu, Dec 3, 2015 at 10:16 AM, Larry Garfield <la...@garfieldtech.com> wrote:

I much prefer to see code with the () always after a class name. Then I don't need to think about it, and if a parameter gets added later the parens are already there.  It's in the same vein as {} on a for loop.

It is definitely not the same as {}, because even if you change:

    new Foo;

And add some arguments:

    new Foo('bar');

You're already going to be editing one line, you're just typing 2 extra characters (or 1 with most editors). If you add multiple with newlines:

    new Foo(

        'bar',

        'baz',

    );

You're already going to be making a multi-line change.

All of which makes it not at all equivalent to {} braces, nor is it a block level statement.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/56606AE8.2090104%40garfieldtech.com.

[Paul M. Jones]

> On Dec 3, 2015, at 10:16, Larry Garfield <la...@garfieldtech.com> wrote:
>
> I much prefer to see code with the () always after a class name. Then I don't need to think about it, and if a parameter gets added later the parens are already there. It's in the same vein as {} on a for loop.
>
> Drupal's coding standards have long included a () on classes.

As done in the PSR-2 discussions, the way to settle this is to do a survey and see what existing projects are doing. It takes actual work, but is harder to refute on basis of "personal preference." The authors should do their research first, and publish it as an addendum, as we did for PSR-2.

[Michael Cullum]

I shouldn't type code when replying to emails on my phone and tired.

Woody, so are most things in a coding style guide....

--

Michael C

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAAueXOWV%2BDoMaUsXNUpWJ1zZoRqa0smGBzZ2mfPJJT09OVpnwg%40mail.gmail.com.

[Larry Garfield]

On 12/3/15 1:45 PM, Paul M. Jones wrote:
>> On Dec 3, 2015, at 10:16, Larry Garfield <la...@garfieldtech.com> wrote:
>>
>> I much prefer to see code with the () always after a class name. Then I don't need to think about it, and if a parameter gets added later the parens are already there. It's in the same vein as {} on a for loop.
>>
>> Drupal's coding standards have long included a () on classes.
> As done in the PSR-2 discussions, the way to settle this is to do a survey and see what existing projects are doing. It takes actual work, but is harder to refute on basis of "personal preference." The authors should do their research first, and publish it as an addendum, as we did for PSR-2.

As with PSR-2, I reject the idea that a survey of current practices is
the ultimate arbiter of what a coding standard should be. There are at
least some objective inputs that can be provided. See, for instance:

http://mnapoli.fr/approaching-coding-style-rationally/

A lowest-common-opinion-denominator is a rather poor form of decision
making, regardless of the topic at hand.

--
--Larry Garfield

[Paul M. Jones]

> On Dec 3, 2015, at 18:40, Larry Garfield <la...@garfieldtech.com> wrote:
>
> On 12/3/15 1:45 PM, Paul M. Jones wrote:
>>> On Dec 3, 2015, at 10:16, Larry Garfield <la...@garfieldtech.com> wrote:
>>>
>>> I much prefer to see code with the () always after a class name. Then I don't need to think about it, and if a parameter gets added later the parens are already there. It's in the same vein as {} on a for loop.
>>>
>>> Drupal's coding standards have long included a () on classes.
>> As done in the PSR-2 discussions, the way to settle this is to do a survey and see what existing projects are doing. It takes actual work, but is harder to refute on basis of "personal preference." The authors should do their research first, and publish it as an addendum, as we did for PSR-2.
>
> As with PSR-2, I reject the idea that a survey of current practices is the ultimate arbiter of what a coding standard should be. There are at least some objective inputs that can be provided. See, for instance:
>
> http://mnapoli.fr/approaching-coding-style-rationally/

And I reject your rejection. Also, "s/rational/rationalizing/".

[Jason Judge]

On Wednesday, 2 December 2015 10:08:20 UTC, Michael Cullum wrote:

Hi all,

PSR-12 [Extended Coding Style guide] was never intended to be that much more than PSR-2 ever was. It was intended to fix a few issues in PSR-2 with clarifications, or things that were meant but not said, and PHP 7 functionality primarily in addition to a couple of things that it was felt really should be included due to PHP 7 functionality (such as declare statements and operators).

PSR-12 is now basically ready for review but I wanted to post to the list and ask people to have a quick look over it before that as once we enter review, we have a much more bureaucratic process with regards to making any necessary changes. Assuming nothing major comes up, we'll be looking to move it into review towards the end of the week. We have provided a non-comprehensive changelog of some of the most notable changes in the meta document should you wish you just review those parts and not the whole specification (which includes all of PSR-2).

You can view it here: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md

Thanks all!

--

Michael

Thanks Michael,

Just to focus on one thing that I thought was ambiguous in the first specs (PSR-1/PSR-2), I think the definitions are still a little unclear. I do understand the intent, but I'm not sure the text puts that across. It's the definition of lines, blank lines, last lines, line endings that I think needs some changes. The description probably comes from observations of how a specific IDE or editor presents a file, not not what is actually in the file.

First to define the structure of a file:

* A file consists of ONE or more lines.
* A line consists of zero or more non-LF characters followed by a single LF character.

That then covers what this statement is trying to say:

> All PHP files MUST end with a single line, containing only a single newline (LF) character.

Taken at face value, this means every file must end with TWO LF characters - the last line of code THEN a blank line. It is not the intent to force an extra blank line onto the end of every file (previous discussions have brought this up). It is enough to just say the file ends with a line. But even that is already said by stating that a file consists of one or more lines - it can ONLY end with a line if that is all it contains. So I think that statement above can go completely.

Next, non-blank lines must not have trailing white space. Does that mean blank lines *can* have trailing white space? So what *is* a blank line? Can a line containing *only* white space be considered a blank line? I guess it is - if am *empty* line (just a LF) is unambiguously blank, then I would be allowed to give it trailing white space, so I now have a line containing only spaces. It may be considered blank, or or may not, but it's allowed. Is that the intention? Are lines containing just spaces and nothing else something that is useful or accepted or perhaps cannot be avoided and so just t

Lastly - soft and hard line length limits. Is there an accepted definition of what these terms mean in the digital age? I'm guessing on an old typewriter the hard limit was when you ran out of paper and the soft limit was when the bell range, but those concepts don't exist in a file (in an editor, maybe, but not the file). Personally I don't have a clue. Maybe these terms should be defined.

Thanks,

-- Jason

[Woody Gilk]

I think the intent is this:

> There MUST NOT be trailing whitespace at the end lines.

https://github.com/php-fig/fig-standards/pull/692

--
Woody Gilk
http://about.me/shadowhand

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/46563e9a-57d9-4a50-a06b-be10047334f9%40googlegroups.com.

[Jason Judge]

On Thursday, 3 December 2015 04:38:36 UTC, Woody Gilk wrote:

+1 for always requiring a blank line after the opening tag.

--
Woody Gilk
http://about.me/shadowhand

Just to be clear, you mean this:

~~~
<?php

namespace Foo;
~~~

rather than this:

~~~
<?php
namespace Foo;
~~~

-- Jason

[Woody Gilk]

Exactly, Jason.

--
Woody Gilk
http://about.me/shadowhand

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/f11f4467-4efb-43e0-af4c-183031611904%40googlegroups.com.

[Korvin Szanto]

On Fri, Dec 4, 2015 at 6:56 AM Woody Gilk <woody...@gmail.com> wrote:

Exactly, Jason.

--
Woody Gilk
http://about.me/shadowhand

On Fri, Dec 4, 2015 at 8:54 AM, Jason Judge <jason...@consil.co.uk> wrote:

On Thursday, 3 December 2015 04:38:36 UTC, Woody Gilk wrote:

+1 for always requiring a blank line after the opening tag.

--
Woody Gilk
http://about.me/shadowhand

Just to be clear, you mean this:

~~~
<?php

namespace Foo;
~~~

rather than this:

~~~
<?php
namespace Foo;
~~~

IMHO we should simply say that there MUST NOT be more than one blank lines after the opening tag (which I think is already technically covered) and leave it at that. I don't think having a blank line there or not will effect readability for me at all.

 

-- Jason

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/f11f4467-4efb-43e0-af4c-183031611904%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6LOOV0rsAjtswwqXJwRumFhXBiKbd3h%3DU-oZPNt-ZFVLg%40mail.gmail.com.

[Shefik]

+1 for this:

<?php

namespace Foo;

- Shefik

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANeXGWX8zvdsLw73mFEr7y7cEvk02XoX%3DtCLQtMthf%2B5UOmqMw%40mail.gmail.com.

[Paul M. Jones]

> On Dec 4, 2015, at 16:49, Shefik <shefik....@gmail.com> wrote:
>
> +1 for this:
>
> <?php
>
> namespace Foo;

Biggest possible -1, and also, *do your research*. Find out what existing projects do, and tally it up. It's nothing short of laziness on the part of the authors to avoid doing the work of research-and-discovery.

Honestly, I'll have to vote -1 on a Review stage until the authors put forth some real effort into surveying the existing landscape.

[Larry Garfield]

On 12/04/2015 07:28 PM, Paul M. Jones wrote:
>> On Dec 4, 2015, at 16:49, Shefik <shefik....@gmail.com> wrote:
>>
>> +1 for this:
>>
>> <?php
>>
>> namespace Foo;
>
> Biggest possible -1, and also, *do your research*. Find out what existing projects do, and tally it up. It's nothing short of laziness on the part of the authors to avoid doing the work of research-and-discovery.
>
> Honestly, I'll have to vote -1 on a Review stage until the authors put forth some real effort into surveying the existing landscape.

Or decide that consistency is more valuable than plurality rules on
individual points?

--Larry Garfield

[Paul M. Jones]

Start with a consistency that originates from actual practice, and then rationalize deviations from it.

[Andrew Carter]

It's going to be a few years before the projects with the largest code bases in this group start targetting PHP 7 features.

When they do, they will need to create a style guide anyway. It's not as if the larger projects here are going to let all of their contributors just wing it with PHP 7 features without any guidance on style.

Would it not make for more sense for these projects to sit down now and discuss what their style guides would look like if they decided to target PHP 7 tomorrow? As far as I can see, this is all Michael is asking and it sounds pretty reasonable.

I can see no utility in waiting for all the projects to create their own (different) style guides and then tell them two months later that they need to rebase all their open pull requests and change all their code - developer time is too important for that and we can avoid it this time.

[Gary Hockin]

It depends if we are looking for prevalence or readability for me. One person can create a style guide for a huge project that everyone else is then following. For me popularity of a style on GitHub doesn't make it "right".

G

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/bce2a133-a1a1-4ecc-9f1c-9560368fdfb7%40googlegroups.com.

[Marcus Bointon]

I don't see that PHP7 requires any major changes in coding standards. The only new language feature that isn't similar to things we have already is return typing. There's not much value in changing anything else - psr-2 has it covered. If standards get too opinionated, they become more hindrance than help. For example this blank line business is nothing to do with PHP7, so it should not be in here at all.

Marcus

Sent from my iPhone

--
You received this message because you are subscribed to a topic in the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/php-fig/VVZe7eI0Clg/unsubscribe.
To unsubscribe from this group and all its topics, send an email to php-fig+u...@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/bce2a133-a1a1-4ecc-9f1c-9560368fdfb7%40googlegroups.com.

[Michael Cullum]

Marcus, PMJ and others:

As has already been stated, that was removed as that was not was intended, I see no need for this discussion to continue as it's no longer a change from PSR-2. It seems controversial and will hurt the migration path for a lot of popular projects so I'd rather not add it either.

```

<?php namespace Foo/Bar;

```

On the more general points being made:

Obviously projects can use whatever criteria they wish to vote +1/-1, however I'd suggest that voting -1 because you aren't sure other projects would like it is counter productive. Projects vote on behalf of themselves and if all projects are happy with it for themselves, but worried that other projects might not like it, then we'd have thirty -1 votes when no project is actually unhappy about it and the entire representation system breaks down.

If people/projects have specific comments on statements they disagree with or they believe they would do things a different way then please post that here and you're all also of course welcome to send me a tweet, IRC message (#phpfig on Freenode) or private email if you prefer but I'd suggest that general comments along the lines of 'I think not enough projects would agree with the things in this specification, please do more research' is unproductive. My main method of research is asking if anyone disagrees with things and an appeal to you all (individuals and projects) for reviewing of the specification, of which so far I've had almost no disagreement (if any at all) on existing statements. That's why I posted up this pre-review review. We have a few hundred members on this list I'm sure and it's all of you I'm appealing to if you disagree with things. If there appear to be particularly contentious points then we can discuss the best way to go about it or whether or not it's worth having in the spec at all (especially if it will hurt PSR-2 to PSR-12 migration paths).

--

Michael Cullum

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/5043217F-5FA4-486F-B142-81374AD9FC13%40gmail.com.

[Rasmus Schultz]

I for one will no abide by this.

throw new \Exception();

Not in my source-code - I will consistently import everything with use-statements, and you will never see a leading backslash anywhere.

Consistency, please. No exceptions. Not even for Exceptions ;-)

[Alexander Makarov]

I'm actually doing the same. Importing everything.

[Paul M. Jones]

> On Dec 6, 2015, at 10:20, Michael Cullum <m...@michaelcullum.com> wrote:
>
> On the more general points being made:
> Obviously projects can use whatever criteria they wish to vote +1/-1, however I'd suggest that voting -1 because you aren't sure other projects would like it is counter productive.

There's an easy way to remedy that objection, and pretty much all others: do a survey of the member projects regarding each point-of-change you want to make. Then, if you don't like the majority preference, you can rationalize a rejection and replacement of that point-of-change.

Is it just me, or are the PSR-12 editor and sponsors resistant to that very reasonable and sensible approach, which worked to great success in PSR-2? If so, why are they resistant?

[Michael Cullum]

Inline

On 6 December 2015 at 1,8:15, Paul M. Jones <pmjo...@gmail.com> wrote:

> On Dec 6, 2015, at 10:20, Michael Cullum <m...@michaelcullum.com> wrote:
>
> On the more general points being made:
> Obviously projects can use whatever criteria they wish to vote +1/-1, however I'd suggest that voting -1 because you aren't sure other projects would like it is counter productive.

There's an easy way to remedy that objection, and pretty much all others: do a survey of the member projects regarding each point-of-change you want to make.  Then, if you don't like the majority preference, you can rationalize a rejection and replacement of that point-of-change.

That is what is being done, if anyone wishes to -1 anything they are more than welcome to do so in this email thread.

Is it just me, or are the PSR-12 editor and sponsors resistant to that very reasonable and sensible approach, which worked to great success in PSR-2? If so, why are they resistant?

1) Firstly, you say it worked to great success but one of the biggest reasons people (Including plenty of voting members) moan about PSR-1/PSR-2 is that it seems every decision was simply down to a majority of projects doing it one way and not down to discussion and reason like every single other PSR. I'm not saying it was not a success, please don't misunderstand, but simply that I think it's a rather large assumption to describe it as such.

2) It's a rather different scenario. In PSR-2 you could analyse what existing projects were doing in their coding guidelines by running a script. That's obviously not possible for PSR-12.

3) I'm not resistant, I'm just failing to see what is wrong with doing it this way over your way.

In case I haven't been entirely clear (which is all very possible), the point of this topic is to ask projects if they have any objections to certain parts of the specification. In that sense, this is a survey where +1s are the default and if there are any -1s then we can start a discussion about that and if it is to be found that some things are contentious then after discussions we can reach a decision via whatever means is appropriate whether that is a survey on which option is preferred by projects or, people might change their opinions.

Paul, I don't think we are disagreeing here, just doing the same thing a slightly different, and in my personal opinion (and I think that of many others), an appropriate way when considering the purview of the specification.

Thanks,

Michael C

[Paul M. Jones]

> On Dec 6, 2015, at 11:55, Michael Cullum <m...@michaelcullum.com> wrote:
>
>> There's an easy way to remedy that objection, and pretty much all others: do a survey of the member projects regarding each point-of-change you want to make. Then, if you don't like the majority preference, you can rationalize a rejection and replacement of that point-of-change.
>
> That is what is being done, if anyone wishes to -1 anything they are more than welcome to do so in this email thread.

Excellent; I have not seen the survey questions or its results from the various projects. Where can I find it?

> 1) Firstly, you say it worked to great success but one of the biggest reasons people (Including plenty of voting members) moan about PSR-1/PSR-2 is that it seems every decision was simply down to a majority of projects doing it one way and not down to discussion and reason like every single other PSR. I'm not saying it was not a success, please don't misunderstand, but simply that I think it's a rather large assumption to describe it as such.

By "success" I mean that it provided data to back up (or refute) assertions made by proponents of any particular style choice. It turned out to be very informative.

> 2) It's a rather different scenario. In PSR-2 you could analyse what existing projects were doing in their coding guidelines by running a script. That's obviously not possible for PSR-12.

"Running a script?" No, we had an actual by-hand survey, where we looked at the codebase of each project (sometimes with the help of the project representative) and determined exactly how many projects were using a particular element of style. The results are attached as an appendix to PSR-2: <http://www.php-fig.org/psr/psr-2/#appendix-a-survey>

Doing the same for PSR-12 is therefore well within the range of possibility.

> 3) I'm not resistant, I'm just failing to see what is wrong with doing it this way over your way.

It was not "my way." After lots of back-and-forth, *someone else* suggested doing a survey, so that at least there would be some measurable, quantifiable data to back up assertions. It was a simple and reasonable solution, and turned out to be hugely useful.

> In case I haven't been entirely clear (which is all very possible), the point of this topic is to ask projects if they have any objections to certain parts of the specification.

"Asking for objections" is very different from "finding out what projects are actually doing." That's not a survey to discover actual practice, that's an opinion poll about possible future preferences, and thus not the same thing at all.

Again, I urge you in the strongest possible terms to discover what projects are actually doing on each point of style you wish to include in PSR-12. It's not as much fun as coming up with ideas on your own and then rationalizing them, but it will have the benefit of being reflective of impersonal reality.

[Alexander Makarov]

Since PSR-12 target is future, it's clear that no member project does much of what this code style is going to regulate. So PSR-12 is about making an agreement in advance. I think it's OK to do it for a coding style.

Each point of PSR-12 is either liked¹ (or at least acceptable) by every member of mailing list or not². In a first case noone's posting issues. In a second case issues are popping up.

The only issue I see with this approach is that it's not clear how many members actually read it and provided feedback. Paul M. Jones, is it lack of such stats what bothers you?

[Christopher Pitt]

17 people have participated in this thread, 8 of them representing member projects. Out of 43 member projects. How do you propose we determine who has even read the document? 

"nobody complained" is a poor basis for recommendations we recommend the entire community follow.

[Andrew Carter]

Moving it into review requires a vote, which requires the attention of member projects.

Surely that is what the review process is all about? Reviewing it?

[Christopher Pitt]

Sure, now is as good a time as any for member projects to figure out if they like these recommendations or not. That doesn't mean they have, or will. I'm sure you can appreciate the difference between PSR's focussed on one focussed interoperability aspect (like cache or logging) and PSR's which affect every line of code (like PSR-2 or PSR-12). Especially when the former (and PSR-2) were based on real-world usage while this doc is based on conjecture.

[Michael Cullum]

No it doesn't.

--
Thanks,
Michael Cullum

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/22d2c5d5-2f69-4a0b-be28-7238b411d4d9%40googlegroups.com.

[Paul M. Jones]

> On Dec 6, 2015, at 17:16, Christopher Pitt <cgp...@gmail.com> wrote:
>
> 17 people have participated in this thread, 8 of them representing member projects. Out of 43 member projects. How do you propose we determine who has even read the document?
>
> "nobody complained" is a poor basis for recommendations we recommend the entire community follow.

Hear, hear.

[Larry Garfield]

On 12/06/2015 01:42 PM, Paul M. Jones wrote:
> Again, I urge you in the strongest possible terms to discover what
> projects are actually doing on each point of style you wish to include
> in PSR-12. It's not as much fun as coming up with ideas on your own
> and then rationalizing them, but it will have the benefit of being
> reflective of impersonal reality.

To clarify my position and earlier statements: I am all for gathering
data where data is available to be gathered, although as has been
pointed out there is not much data to gather at this point. I would not
be opposed to an active survey to see what projects are doing now along
lines similar to those being discussed here, and if there's any data to
glean, let's do it before we go to Review.

What I am firmly opposed to is the idea that "well, the plurality or
non-overwhelming majority are doing X in this case, so we clearly should
do X in that case as well, no more discussion, stop inventing things,
kthxbye." That's how PSR-2 felt like it went (I'm sure some will
disagree, but that's how it seemed to go on my end), and such an
approach for PSR-12 would net a -1 from me as well.

--Larry Garfield

[Ryan Parman]

Just doing my first review of PSR-12.

----

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#42-using-traits

“Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.”

The coding example then goes-on to show the `use` statement for Traits being used in a way that was identified and discarded for Namespace Aliases in PSR-2 discussions. The instruction is also somewhat ambiguous, allowing for multiple styles of using the `use` statement for Traits.

IMO, we should keep the pattern for Namespace Aliases and Traits the same.

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#7-closures

Was the text for Closures always part of PSR-2? I’ve read this document dozens of times, and I did not recall that section being there before.

I am curious as to the thinking behind requiring a space after the function keyword. Why didn’t the syntax for Closures match the syntax for Methods and Functions (i.e., no space between the function’s name and the opening paren)?

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#3-declare-statements-namespace-and-use-declarations

1. “You MUST NOT use `use` statements for classes in the root namespace. Therefore you should use `throw new \Exception();` instead of `use Exception; throw new Exception();`”

What is the rationale for this (in a nutshell)? I greatly prefer the latter format because it reads more cleanly to my eyes. If anything, I would prefer to NOT standardize this and leave it up to the project owner.

2. “Classes, functions or constants grouped together into a single line must be listed alphabetically.”

In this case, the statement matches my preference. That said, I still think that this should NOT be standardized. For example, “Two” comes later in the alphabet than “Three”. And “Four” is before all of those. (Yes, this example is silly, but it illustrates my point.)

3. “Declare statements MUST contain no spaces and MUST look like declare(strict_types=1);.”

This is counter to how we define variables. It seems to me that this format should match variables because that’s essentially what this is.

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#8-anonymous-classes

“The opening bracket MAY be on the same line as the class keyword so long as the list of implements interfaces does not wrap. If the list of interfaces wraps, the bracket MUST be placed on the line immediately following the last interface.”

IMO, all classes — anonymous or otherwise — should match in how they are defined. I recognize that this is written to match how Closures (a.k.a. Anonymous Functions) are formatted, but that doesn’t make sense to me either. Why do the “anonymous” things have a different style of definition from the concrete things?

——

There are some things that I believe were missed in PSR-1/2, and IMO are worthy to be addressed in a coding style document of some kind.

Braces are required (#)

AFAICT, this is never actually mentioned anywhere. (Haven’t looked for this, specifically, in a while.)

View/Template Intermingling (#)

Are short-open tags allowed for wrapping control structures in PHP templates? (This is not a discussion about why we should be using an abstraction.)

<? if (condition): ?>

  <tag>View-layer code.</tag>

<? endif ?>

Arrays (#)

We should all be using “short array” syntax. Also, we should pay attention to our trailing commas.

String Interpolation (#)

$variable, {$variable}, ${variable}, or sprintf?

Language Constructs (#)

echo, require, include, print should not use parentheses for invokation.

Type Casting/Juggling (#)

Long or short form casts?

Increment/Decrement Operators (#)

Unless you’re inside a for-loop, give them a line of their own.

Variables (#)

I personally use snake_case for readability for variable names. Some code fixer tools freak-out about this, even though it’s valid. That said, $StudlyCase variable names are the devil.

Constants (#)

Constants should be named as uppercase with underscore separators. This isn’t actually anywhere in the spec — only in the (non-canonical) appendix.

Non-docblock Comments (#)

Please don’t use `#`, but `//` and `/**/` are cool. Give comments some breathing room so that they are easier to read.

--

Ryan Parman

http://ryanparman.com

http://twitter.com/skyzyx

"At times of change, the learners are the ones who will inherit the world, while the knowers will be beautifully prepared for a world which no longer exists." — Alistair Smith

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/56651018.70508%40garfieldtech.com.

[Michael Cullum]

Hi Ryan,

Thanks for your feedback!

I've put comments inline on the changes. In regards to the new statements you'd like to see added I've not commented as I'd rather avoid adding new statements now. I'd also add that most of your changes break BC quite a bit or would enforce behaviour instead of just coding style, we discussed what was out of scope in reference to whether we should require strict types and we decided that those kinds of things do not really belong here.

This email thread is rather large so if I miss anyone elses comments please let me know.

--

Michael C

On 7 December 2015 at 08:17, Ryan Parman <ry...@ryanparman.com> wrote:

Just doing my first review of PSR-12.

----

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#42-using-traits

“Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.”

The coding example then goes-on to show the `use` statement for Traits being used in a way that was identified and discarded for Namespace Aliases in PSR-2 discussions. The instruction is also somewhat ambiguous, allowing for multiple styles of using the `use` statement for Traits.

IMO, we should keep the pattern for Namespace Aliases and Traits the same.

I'm not entirely sure what you mean. Would you mind submitting a pull request with what you think makes more sense as that would make it easier to see what you mean?

 

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#7-closures

Was the text for Closures always part of PSR-2? I’ve read this document dozens of times, and I did not recall that section being there before.

I am curious as to the thinking behind requiring a space after the function keyword. Why didn’t the syntax for Closures match the syntax for Methods and Functions (i.e., no space between the function’s name and the opening paren)?

Closures was in PSR-2 and I'd rather not change it.

 

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#3-declare-statements-namespace-and-use-declarations

1. “You MUST NOT use `use` statements for classes in the root namespace. Therefore you should use `throw new \Exception();` instead of `use Exception; throw new Exception();`”

What is the rationale for this (in a nutshell)? I greatly prefer the latter format because it reads more cleanly to my eyes. If anything, I would prefer to NOT standardize this and leave it up to the project owner. 

2. “Classes, functions or constants grouped together into a single line must be listed alphabetically.”

In this case, the statement matches my preference. That said, I still think that this should NOT be standardized. For example, “Two” comes later in the alphabet than “Three”. And “Four” is before all of those. (Yes, this example is silly, but it illustrates my point.)

Sure but how often do you name classes with numbers? I don't really think it matters as that's quite an isolated example (Where another ordering system for words makes more sense because those words represent numbers) but if other people have objections we can revisit this.

 

3. “Declare statements MUST contain no spaces and MUST look like declare(strict_types=1);.”

This is counter to how we define variables. It seems to me that this format should match variables because that’s essentially what this is.

I'd actually counter that with declare acts more like a function that evaluates a string. Declare is odd because it's not a normal assignment (otherwise we'd just have `strict_types = 1`) but the argument it accepts is not actually a string either. Either way, it's not a normal statement in and I'd say that therefore it's not an exception but a separately defined rule. As I said, this seems to be the de facto standard so far of doing it from every PHP 7 talk I've seen including Cal Evans who is doing the Zend trainings on PHP 7, it's also the same in the PHP documentation and RFC which is where a lot of people are pulling it from and as such it seems to be the most commonly way of coding it including large projects such as PHP files contained within Facebook's HHVM. https://github.com/search?utf8=%E2%9C%93&q=declare%28strict_types%3D1%29%3B&type=Code&ref=searchresults

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#8-anonymous-classes

“The opening bracket MAY be on the same line as the class keyword so long as the list of implements interfaces does not wrap. If the list of interfaces wraps, the bracket MUST be placed on the line immediately following the last interface.”

IMO, all classes — anonymous or otherwise — should match in how they are defined. I recognize that this is written to match how Closures (a.k.a. Anonymous Functions) are formatted, but that doesn’t make sense to me either. Why do the “anonymous” things have a different style of definition from the concrete things?

I'd rather follow the consistency here from anonymous functions and in being consistent with anonymous functions, like anonymous functions, you should be inconsistent with the non-anonymous variant. So we are being consistent two-fold by being inconsistent with non-anonymous classes as PSR-2 was intentionally inconsistent and this was the decided on method through surveys and lengthy discussions.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/etPan.5665409f.1fa8a635.c682%40skyzyx.local.

[Korvin Szanto]

On Sun, Dec 6, 2015 at 4:19 PM Christopher Pitt <cgp...@gmail.com> wrote:

Sure, now is as good a time as any for member projects to figure out if they like these recommendations or not. That doesn't mean they have, or will. I'm sure you can appreciate the difference between PSR's focussed on one focussed interoperability aspect (like cache or logging) and PSR's which affect every line of code (like PSR-2 or PSR-12). Especially when the former (and PSR-2) were based on real-world usage while this doc is based on conjecture.

I think it is a shame that we feel that the PHP-FIG mailing list is not an adequate place to communicate with PHP-FIG member projects. I'm sad to hear that we have 45 member projects - some of the most influential projects powering the internet as we know it - in our ranks yet we feel that we cannot discuss this as a group in public on the mailing list and instead feel the need to discuss and survey privately through other channels. I hope some day we can actually all collaborating and work together the way we should be working together.

That said, I've gone to twitter and pinged every representative who hasn't already weighed in asking for some more eyes before we enter review [1]. 

[1] https://twitter.com/KorvinSzanto/status/674011648282071040  

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/b7a0e39c-fdc4-4855-b62a-6f210ecb0ff0%40googlegroups.com.

[Christopher Pitt]

I don't think anybody is suggesting any private discussion, or that this is an inadequate place to discuss this issue. My reservations are for deciding the standards without an exhaustive discussion or empirical data. Thank you for pinging the people - hopefully we can get more clarity here.

[Paul M. Jones]

> On Dec 7, 2015, at 18:22, Korvin Szanto <korvin...@gmail.com> wrote:
>
> I think it is a shame that we feel that the PHP-FIG mailing list is not an adequate place to communicate with PHP-FIG member projects. I'm sad to hear that we have 45 member projects - some of the most influential projects powering the internet as we know it - in our ranks yet we feel that we cannot discuss this as a group in public on the mailing list and instead feel the need to discuss and survey privately through other channels. I hope some day we can actually all collaborating and work together the way we should be working together.

It's easy to do a survey: you, personally, review the 45 codebases; and you, personally, report the results. It's not hard, although it is a little more like *work* than you might prefer.

[Woody Gilk]

On Mon, Dec 7, 2015 at 6:00 PM, Michael Cullum <m...@michaelcullum.com> wrote:

1. “You MUST NOT use `use` statements for classes in the root namespace. Therefore you should use `throw new \Exception();` instead of `use Exception; throw new Exception();`”

Why is this being proposed? What benefit could this possibly have, other than making lines of code longer? PSR-2 has nothing like this..

[Jeremy Lindblom]

Some of my thoughts:

---

> You MUST NOT use use statements for classes in the root namespace. Therefore you should use throw new \Exception(); instead of use Exception; throw new Exception();

WAT?!?! Why? Seems arbitrary. It also seems needlessly annoying to implement that as a rule in code analysis tools.

---

In the declare/namespaces/use section (and in the entire document), the term "compound namespaces" is used once. It's not really defined well, and it is also not explained in any way, other than in the code sample following the use of the term, that mutli-line "compound namespaces" are actually allowed.

Perhaps borrowing some words from the extends/implements section could help:

> Lists of implements and extends MAY be split across multiple lines, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the next line, and there MUST be only one interface per line.

And though I understand that the rule stating "There MUST be one use keyword per declaration" does not actually contradict with the idea of compound namespaces, it might seem that way to a reader. Seems like some clarifications are needed around this concept of compound namespaces.

---

> When instantiating a new class, parenthesis MUST always be present even when there are no arguments passed to the constructor.

The only time I really hate this rule is when you are calling a method like this:

$result = (new Thing)->doStuff($args);

I'm not sure I care that much though.

---

> Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.

Why would we allow multi-line trait using when we don't allow multi-line namespace using? Seems inconsistent without a reason.

Also, the grammar in this description is off. That first sentence isn't a complete sentence. You may want to clean that up.

---

In the function arguments and return types section it says:

> When the argument list is split across multiple lines, the closing parenthesis and opening brace MUST be placed together on their own line with one space between them.

This does not adequately address the situation where you have arguments on multiple lines AND a return type declared.

    public function aVeryLongMethodName(
        int $arg1,
        string $arg2,
        array $arg3 = []
    ): string {
        // method body
    }

---

There are no examples of closures with a return type declared.

---

That's all for now!

--
Jeremy Lindblom (@jeremeamia)
Software/Platform Engineer at Engrade (part of McGraw-Hill Education)

Co-founder of the Pacific Northwest PHP Conference (@PNWPHP)

Co-author of the AWS SDK for PHP (@awsforphp)

PHP-FIG Representative for the Guzzle project

Looking for a senior-level software engineering position doing PHP? I have some available with McGraw-Hill Education in Seattle and Los Angeles (Santa Monica or Irvine). Contact me for me more information.

On Mon, Dec 7, 2015 at 4:26 PM, Christopher Pitt <cgp...@gmail.com> wrote:

I don't think anybody is suggesting any private discussion, or that this is an inadequate place to discuss this issue. My reservations are for deciding the standards without an exhaustive discussion or empirical data. Thank you for pinging the people - hopefully we can get more clarity here.

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/34ab34ff-bb17-4a43-8a01-c1603984b1c0%40googlegroups.com.

[Korvin Szanto]

On Mon, Dec 7, 2015 at 4:38 PM Paul M. Jones <pmjo...@gmail.com> wrote:

> On Dec 7, 2015, at 18:22, Korvin Szanto <korvin...@gmail.com> wrote:
>
> I think it is a shame that we feel that the PHP-FIG mailing list is not an adequate place to communicate with PHP-FIG member projects. I'm sad to hear that we have 45 member projects - some of the most influential projects powering the internet as we know it - in our ranks yet we feel that we cannot discuss this as a group in public on the mailing list and instead feel the need to discuss and survey privately through other channels. I hope some day we can actually all collaborating and work together the way we should be working together.

It's easy to do a survey: you, personally, review the 45 codebases; and you, personally, report the results.  It's not hard, although it is a little more like *work* than you might prefer.

While my involvement in PSR-12 has certainly been lacking, I really don't appreciate you attacking my work ethic here in a position that I volunteered to fill. Can you please try to find a professional way to get your ideas across without attacking me personally?

 

I actually wrote a tool that would survey all of the projects automatically and pull out specific statement types [1], I ran it to see how projects were using operators in conditionals and quickly realized that projects don't follow rules for things that aren't specifically described in their code style guide so the results were mixed and unhelpful as one would expect. 

That's still an option but I think it's been said many many times now that we cannot do that for PHP7 features which is the whole point of this PSR. It seems much more reasonable to me to audit the changes we've put forth as a group regardless of my work ethic.

[1] https://github.com/KorvinSzanto/PSR12_surveyer

 

--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

Modernizing Legacy Applications in PHP
https://leanpub.com/mlaphp

Solving the N+1 Problem in PHP
https://leanpub.com/sn1php

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/8166B98D-5FAD-4779-82B4-AFBCD6DCC5F3%40gmail.com.

[Michael Cullum]

Paul,

I have to say I'm rather surprised that we've now sunk to depths of rudeness, especially towards Korvin who I'd asked if he could tweet all the member projects asking them for their feedback after your and Christopher's comments that not many voting members had responded to this topic. I'd hope we, as an organisation of lead developers and respected developers within large projects, could find a way to work together in a civil fashion that sets an example to those who contribute to our projects and the wider PHP community.

Have you read the specification yet? If not then I'd appreciate your more specific feedback on its contents but otherwise I think you've made your point. If you want to continue to discuss this then you're welcome to make another mailing list thread but I'd like to try and keep this one related to the actual specification's contents itself as it's becoming hard to follow and get feedback from other projects (which is exactly what you're saying you wanted).

--

Michael C

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/8166B98D-5FAD-4779-82B4-AFBCD6DCC5F3%40gmail.com.

[Korvin Szanto]

On Mon, Dec 7, 2015 at 5:09 PM Jeremy Lindblom <jerem...@gmail.com> wrote:

Some of my thoughts:

---

> You MUST NOT use use statements for classes in the root namespace. Therefore you should use throw new \Exception(); instead of use Exception; throw new Exception();

WAT?!?! Why? Seems arbitrary. It also seems needlessly annoying to implement that as a rule in code analysis tools.

 

I agree, we talked on this a bit earlier today in a pull request https://github.com/php-fig/fig-standards/pull/697

 

---

In the declare/namespaces/use section (and in the entire document), the term "compound namespaces" is used once. It's not really defined well, and it is also not explained in any way, other than in the code sample following the use of the term, that mutli-line "compound namespaces" are actually allowed.

Perhaps borrowing some words from the extends/implements section could help:

> Lists of implements and extends MAY be split across multiple lines, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the next line, and there MUST be only one interface per line.

And though I understand that the rule stating "There MUST be one use keyword per declaration" does not actually contradict with the idea of compound namespaces, it might seem that way to a reader. Seems like some clarifications are needed around this concept of compound namespaces.

Extra clarification here would be good. I know we've discussed this a few times in the IRC and in pull requests so you're right to point it out.

 

--- 

> When instantiating a new class, parenthesis MUST always be present even when there are no arguments passed to the constructor.

The only time I really hate this rule is when you are calling a method like this:

$result = (new Thing)->doStuff($args);

I'm not sure I care that much though.

That is a good case to bring up, I'm of the opinion that always including the parenthesis increases readability but I don't think I can justify those feelings. I'm interested to see more discussion around this. 

 

---

> Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.

Why would we allow multi-line trait using when we don't allow multi-line namespace using? Seems inconsistent without a reason.

I don't think we intend to disallow mutliline namespace using, so this seems consistent to me.

 

Also, the grammar in this description is off. That first sentence isn't a complete sentence. You may want to clean that up.

--- 

In the function arguments and return types section it says:

> When the argument list is split across multiple lines, the closing parenthesis and opening brace MUST be placed together on their own line with one space between them.

This does not adequately address the situation where you have arguments on multiple lines AND a return type declared.

    public function aVeryLongMethodName(
        int $arg1,
        string $arg2,
        array $arg3 = []
    ): string {
        // method body
    }

---

There are no examples of closures with a return type declared.

Good catches, thanks Jeremy!

 

---

That's all for now!

--
Jeremy Lindblom (@jeremeamia)
Software/Platform Engineer at Engrade (part of McGraw-Hill Education)

Co-founder of the Pacific Northwest PHP Conference (@PNWPHP)

Co-author of the AWS SDK for PHP (@awsforphp)

PHP-FIG Representative for the Guzzle project

Looking for a senior-level software engineering position doing PHP? I have some available with McGraw-Hill Education in Seattle and Los Angeles (Santa Monica or Irvine). Contact me for me more information.

On Mon, Dec 7, 2015 at 4:26 PM, Christopher Pitt <cgp...@gmail.com> wrote:

I don't think anybody is suggesting any private discussion, or that this is an inadequate place to discuss this issue. My reservations are for deciding the standards without an exhaustive discussion or empirical data. Thank you for pinging the people - hopefully we can get more clarity here.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/34ab34ff-bb17-4a43-8a01-c1603984b1c0%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CALDVupLeOVYsuVEor19oj-pvCf%2B_gHqg-n-EaHm%3DYi%3DaqGRFeA%40mail.gmail.com.

[Paul M. Jones]

> On Dec 7, 2015, at 19:20, Korvin Szanto <korvin...@gmail.com> wrote:
>
> On Mon, Dec 7, 2015 at 4:38 PM Paul M. Jones <pmjo...@gmail.com> wrote:
>
> > On Dec 7, 2015, at 18:22, Korvin Szanto <korvin...@gmail.com> wrote:
> >
> > I think it is a shame that we feel that the PHP-FIG mailing list is not an adequate place to communicate with PHP-FIG member projects. I'm sad to hear that we have 45 member projects - some of the most influential projects powering the internet as we know it - in our ranks yet we feel that we cannot discuss this as a group in public on the mailing list and instead feel the need to discuss and survey privately through other channels. I hope some day we can actually all collaborating and work together the way we should be working together.
>
> It's easy to do a survey: you, personally, review the 45 codebases; and you, personally, report the results. It's not hard, although it is a little more like *work* than you might prefer.
>
>
> While my involvement in PSR-12 has certainly been lacking, I really don't appreciate you attacking my work ethic here in a position that I volunteered to fill. Can you please try to find a professional way to get your ideas across without attacking me personally?

I'm not attacking "you personally". I'm stating the level-of-involvement I expect from the Editor, Coordinator, and Sponsor of a "Proposed Standards Recommendation." If the holders of those roles cannot be bothered to expend some effort beyond "nobody has complained" then I admit I lack confidence in the contents of the PSR itself.

[Paul M. Jones]

> On Dec 7, 2015, at 19:33, Michael Cullum <m...@michaelcullum.com> wrote:
>
> Have you read the specification yet?

I have, and I find it lacks a even a preliminary survey of the existing practices of the member projects. As I have stated previously, and will do so again here, I consider such a survey a *minimum* prerequisite to voting +1 on this PSR entering the review stage.

[Korvin Szanto]

On Mon, Dec 7, 2015 at 6:18 PM Paul M. Jones <pmjo...@gmail.com> wrote:

> On Dec 7, 2015, at 19:20, Korvin Szanto <korvin...@gmail.com> wrote:
>
> On Mon, Dec 7, 2015 at 4:38 PM Paul M. Jones <pmjo...@gmail.com> wrote:
>
> > On Dec 7, 2015, at 18:22, Korvin Szanto <korvin...@gmail.com> wrote:
> >
> > I think it is a shame that we feel that the PHP-FIG mailing list is not an adequate place to communicate with PHP-FIG member projects. I'm sad to hear that we have 45 member projects - some of the most influential projects powering the internet as we know it - in our ranks yet we feel that we cannot discuss this as a group in public on the mailing list and instead feel the need to discuss and survey privately through other channels. I hope some day we can actually all collaborating and work together the way we should be working together.
>
> It's easy to do a survey: you, personally, review the 45 codebases; and you, personally, report the results.  It's not hard, although it is a little more like *work* than you might prefer.
>
>
> While my involvement in PSR-12 has certainly been lacking, I really don't appreciate you attacking my work ethic here in a position that I volunteered to fill. Can you please try to find a professional way to get your ideas across without attacking me personally?

I'm not attacking "you personally". I'm stating the level-of-involvement I expect from the Editor, Coordinator, and Sponsor of a "Proposed Standards Recommendation." If the holders of those roles cannot be bothered to expend some effort beyond "nobody has complained" then I admit I lack confidence in the contents of the PSR itself.

It doesn't look like you're actually reading any of these replies so I'm alright with taking your -1 at this point.

Thanks,

Korvin

 

--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

Modernizing Legacy Applications in PHP
https://leanpub.com/mlaphp

Solving the N+1 Problem in PHP
https://leanpub.com/sn1php

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/9EAADBFA-F36B-4526-9D91-8747C4C8E4C4%40gmail.com.

[Paul M. Jones]

> On Dec 7, 2015, at 20:29, Korvin Szanto <korvin...@gmail.com> wrote:
>
>
>
> On Mon, Dec 7, 2015 at 6:18 PM Paul M. Jones <pmjo...@gmail.com> wrote:
>
> > On Dec 7, 2015, at 19:20, Korvin Szanto <korvin...@gmail.com> wrote:
> >
> > On Mon, Dec 7, 2015 at 4:38 PM Paul M. Jones <pmjo...@gmail.com> wrote:
> >
> > > On Dec 7, 2015, at 18:22, Korvin Szanto <korvin...@gmail.com> wrote:
> > >
> > > I think it is a shame that we feel that the PHP-FIG mailing list is not an adequate place to communicate with PHP-FIG member projects. I'm sad to hear that we have 45 member projects - some of the most influential projects powering the internet as we know it - in our ranks yet we feel that we cannot discuss this as a group in public on the mailing list and instead feel the need to discuss and survey privately through other channels. I hope some day we can actually all collaborating and work together the way we should be working together.
> >
> > It's easy to do a survey: you, personally, review the 45 codebases; and you, personally, report the results. It's not hard, although it is a little more like *work* than you might prefer.
> >
> >
> > While my involvement in PSR-12 has certainly been lacking, I really don't appreciate you attacking my work ethic here in a position that I volunteered to fill. Can you please try to find a professional way to get your ideas across without attacking me personally?
>
> I'm not attacking "you personally". I'm stating the level-of-involvement I expect from the Editor, Coordinator, and Sponsor of a "Proposed Standards Recommendation." If the holders of those roles cannot be bothered to expend some effort beyond "nobody has complained" then I admit I lack confidence in the contents of the PSR itself.
>
>
> It doesn't look like you're actually reading any of these replies so I'm alright with taking your -1 at this point.

And it doesn't look like you're actually going to do any work, aside from intellection self-stimulation. -1 it is, until you and the other role-holders do a survey.

[Dracony]

One thing I really want this PSR to address is empty line indentation. E.g. if you are inside a function and you are adding anempty line that lines SHOULD still have the indentation whitespace. Editors like Atom remove any trailing whitespace including indentation bydefault, which makes browsing code rather annoying since the cursor is jumping to the very left of the screen each time you encounter an empty line. 

Can we please address that?

[Aaron Scherer]

Seriously? What is the point of the attack here Paul? Try and aspire to be an outstanding member of the community, not someone who pushes other members of the community down.

[Jason Judge]

On Tuesday, 8 December 2015 09:08:01 UTC, Dracony wrote:

One thing I really want this PSR to address is empty line indentation. E.g. if you are inside a function and you are adding anempty line that lines SHOULD still have the indentation whitespace. Editors like Atom remove any trailing whitespace including indentation bydefault, which makes browsing code rather annoying since the cursor is jumping to the very left of the screen each time you encounter an empty line. 

Can we please address that?

The current intention of the proposal is that no trailing whitespace is allowed on any line:

https://github.com/php-fig/fig-standards/pull/692

Originally it said that trailing whitespace is not allowed on non-blank lines, which sounds like it was trying to say that lines containing only indentation characters are allowed (possibly for the reason you are finding with some editors and code formatters), so it has changed from that.

Why don't you give a minimal example of what you would like to be able to put in your code, and we can take it from there. A real example may be a little less ambiguous. As it is, the ambiguity of what is "a non-blank line" is an issue to me. Nowhere does is say a line *of code*. Trailing whitespace in a non-code block of a PHP file - why not?
 

[Jason Judge]

On Tuesday, 8 December 2015 00:00:28 UTC, Michael Cullum wrote:

Hi Ryan,

Thanks for your feedback!

I've put comments inline on the changes. In regards to the new statements you'd like to see added I've not commented as I'd rather avoid adding new statements now. I'd also add that most of your changes break BC quite a bit or would enforce behaviour instead of just coding style, we discussed what was out of scope in reference to whether we should require strict types and we decided that those kinds of things do not really belong here.

This email thread is rather large so if I miss anyone elses comments please let me know.

--

Michael C

On 7 December 2015 at 08:17, Ryan Parman <ry...@ryanparman.com> wrote:

Just doing my first review of PSR-12.

----

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#42-using-traits

“Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.”

The coding example then goes-on to show the `use` statement for Traits being used in a way that was identified and discarded for Namespace Aliases in PSR-2 discussions. The instruction is also somewhat ambiguous, allowing for multiple styles of using the `use` statement for Traits.

IMO, we should keep the pattern for Namespace Aliases and Traits the same.

I'm not entirely sure what you mean. Would you mind submitting a pull request with what you think makes more sense as that would make it easier to see what you mean?

 

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#7-closures

Was the text for Closures always part of PSR-2? I’ve read this document dozens of times, and I did not recall that section being there before.

I am curious as to the thinking behind requiring a space after the function keyword. Why didn’t the syntax for Closures match the syntax for Methods and Functions (i.e., no space between the function’s name and the opening paren)?

Closures was in PSR-2 and I'd rather not change it.

Probably better not to mention it at all in this PSR, if it is not changing. It is difficult to pick out what has been duplicated from PSR-2, what is an extension to PSR-2, and what are new rules that have been thrown in. If PSR-12 is an extension to PSR-2 then IMO it would be better to describe how it extends PSR-2 and not to have an arbitrary mix of extension and repetition. If it's a *replacement* of PSR-2, then that's something else altogether.
 

 

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#3-declare-statements-namespace-and-use-declarations

1. “You MUST NOT use `use` statements for classes in the root namespace. Therefore you should use `throw new \Exception();` instead of `use Exception; throw new Exception();`”

What is the rationale for this (in a nutshell)? I greatly prefer the latter format because it reads more cleanly to my eyes. If anything, I would prefer to NOT standardize this and leave it up to the project owner. 

 
What is the rationale for this (in a nutshell)? I don't do this, and many other projects don't do this. Some projects do.

2. “Classes, functions or constants grouped together into a single line must be listed alphabetically.”

In this case, the statement matches my preference. That said, I still think that this should NOT be standardized. For example, “Two” comes later in the alphabet than “Three”. And “Four” is before all of those. (Yes, this example is silly, but it illustrates my point.)

Sure but how often do you name classes with numbers? I don't really think it matters as that's quite an isolated example (Where another ordering system for words makes more sense because those words represent numbers) but if other people have objections we can revisit this.

I'll voice an objection then, so this does not get brushed under the carpet of "your use-case isn't very common".

What is the reasoning behind ordering these things alphabetically? It is a burden on the developer, and I have seen no reason given for why it should be enforced.
 

[Woody Gilk]

On Tue, Dec 8, 2015 at 3:08 AM, Dracony <draco...@gmail.com> wrote:

One thing I really want this PSR to address is empty line indentation. E.g. if you are inside a function and you are adding anempty line that lines SHOULD still have the indentation whitespace. Editors like Atom remove any trailing whitespace including indentation bydefault, which makes browsing code rather annoying since the cursor is jumping to the very left of the screen each time you encounter an empty line. 

I cannot disagree any more strongly. Trailing whitespace should always be removed at all times. Nothing is more annoying than browsing a file full of whitespace on blank lines.

[Paul M. Jones]

> On Dec 8, 2015, at 04:09, Aaron Scherer <aeq...@gmail.com> wrote:
>
> Seriously? What is the point of the attack here Paul? Try and aspire to be an outstanding member of the community, not someone who pushes other members of the community down.

Who's pushing anyone down? I am exhorting the PSR-12 team to excellence. In no way is "do your research before attempting to impose your own ideas" an attack.

[Paul M. Jones]

Yet another element that is amenable to survey, if only to discover what is actually common practice, and then make decisions based on that knowledge.

[Alexander Makarov]

Please stop arguing. We've got the message and will probably do a survey at some point.

[Paul M. Jones]

> On Dec 8, 2015, at 08:58, Alexander Makarov <alexande...@googlemail.com> wrote:
>
> We've got the message and will probably do a survey at some point.

"Probably" is better than "certainly never", but it's still a bit of waffling. I'll say it yet again: a survey of existing practices is a sine qua non for something like this. Until it is done, and done well, I'll be -1 on every single stage.

[Alexander Makarov]

Got it.

[Korvin Szanto]

On Tue, Dec 8, 2015 at 2:44 AM Jason Judge <jason...@consil.co.uk> wrote:

On Tuesday, 8 December 2015 09:08:01 UTC, Dracony wrote:

One thing I really want this PSR to address is empty line indentation. E.g. if you are inside a function and you are adding anempty line that lines SHOULD still have the indentation whitespace. Editors like Atom remove any trailing whitespace including indentation bydefault, which makes browsing code rather annoying since the cursor is jumping to the very left of the screen each time you encounter an empty line. 

Can we please address that?

The current intention of the proposal is that no trailing whitespace is allowed on any line:

https://github.com/php-fig/fig-standards/pull/692

Originally it said that trailing whitespace is not allowed on non-blank lines, which sounds like it was trying to say that lines containing only indentation characters are allowed (possibly for the reason you are finding with some editors and code formatters), so it has changed from that.

The before and after are equivalent in that pull request, if you have whitespace on a line it is therefore "non-blank" and subject to the rule. It was never the intention of PSR-2 (AFAIK) to allow trailing whitespace and until now I hadn't heard anyone challenge that.

 

Why don't you give a minimal example of what you would like to be able to put in your code, and we can take it from there. A real example may be a little less ambiguous. As it is, the ambiguity of what is "a non-blank line" is an issue to me. Nowhere does is say a line *of code*. Trailing whitespace in a non-code block of a PHP file - why not?

An example of what you mean would be good, IMO non-code is not PHP and is therefore not necessarily subject to PHP's coding guidelines.

 

 

On Wednesday, December 2, 2015 at 11:08:20 AM UTC+1, Michael Cullum wrote:

Hi all,

PSR-12 [Extended Coding Style guide] was never intended to be that much more than PSR-2 ever was. It was intended to fix a few issues in PSR-2 with clarifications, or things that were meant but not said, and PHP 7 functionality primarily in addition to a couple of things that it was felt really should be included due to PHP 7 functionality (such as declare statements and operators).

PSR-12 is now basically ready for review but I wanted to post to the list and ask people to have a quick look over it before that as once we enter review, we have a much more bureaucratic process with regards to making any necessary changes. Assuming nothing major comes up, we'll be looking to move it into review towards the end of the week. We have provided a non-comprehensive changelog of some of the most notable changes in the meta document should you wish you just review those parts and not the whole specification (which includes all of PSR-2).

You can view it here: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md

Thanks all!

--

Michael

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/8d7aff8a-9fdc-48ed-926a-4cf209219167%40googlegroups.com.

[Korvin Szanto]

On Tue, Dec 8, 2015 at 5:17 AM Jason Judge <jason...@consil.co.uk> wrote:

On Tuesday, 8 December 2015 00:00:28 UTC, Michael Cullum wrote:

Hi Ryan,

Thanks for your feedback!

I've put comments inline on the changes. In regards to the new statements you'd like to see added I've not commented as I'd rather avoid adding new statements now. I'd also add that most of your changes break BC quite a bit or would enforce behaviour instead of just coding style, we discussed what was out of scope in reference to whether we should require strict types and we decided that those kinds of things do not really belong here.

This email thread is rather large so if I miss anyone elses comments please let me know.

--

Michael C

On 7 December 2015 at 08:17, Ryan Parman <ry...@ryanparman.com> wrote:

Just doing my first review of PSR-12.

----

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#42-using-traits

“Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.”

The coding example then goes-on to show the `use` statement for Traits being used in a way that was identified and discarded for Namespace Aliases in PSR-2 discussions. The instruction is also somewhat ambiguous, allowing for multiple styles of using the `use` statement for Traits.

IMO, we should keep the pattern for Namespace Aliases and Traits the same.

I'm not entirely sure what you mean. Would you mind submitting a pull request with what you think makes more sense as that would make it easier to see what you mean?

 

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#7-closures

Was the text for Closures always part of PSR-2? I’ve read this document dozens of times, and I did not recall that section being there before.

I am curious as to the thinking behind requiring a space after the function keyword. Why didn’t the syntax for Closures match the syntax for Methods and Functions (i.e., no space between the function’s name and the opening paren)?

Closures was in PSR-2 and I'd rather not change it.

Probably better not to mention it at all in this PSR, if it is not changing. It is difficult to pick out what has been duplicated from PSR-2, what is an extension to PSR-2, and what are new rules that have been thrown in. If PSR-12 is an extension to PSR-2 then IMO it would be better to describe how it extends PSR-2 and not to have an arbitrary mix of extension and repetition. If it's a *replacement* of PSR-2, then that's something else altogether.
 

PSR-12 is a replacement for PSR-2.

 

 

——

https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#3-declare-statements-namespace-and-use-declarations

1. “You MUST NOT use `use` statements for classes in the root namespace. Therefore you should use `throw new \Exception();` instead of `use Exception; throw new Exception();`”

What is the rationale for this (in a nutshell)? I greatly prefer the latter format because it reads more cleanly to my eyes. If anything, I would prefer to NOT standardize this and leave it up to the project owner. 

 
What is the rationale for this (in a nutshell)? I don't do this, and many other projects don't do this. Some projects do.

I'm not for this rule, I believe we should leave it to the implementors. I think Michael's original thought was that using a class or function in the root namespace duplicates code.

 

2. “Classes, functions or constants grouped together into a single line must be listed alphabetically.”

In this case, the statement matches my preference. That said, I still think that this should NOT be standardized. For example, “Two” comes later in the alphabet than “Three”. And “Four” is before all of those. (Yes, this example is silly, but it illustrates my point.)

Sure but how often do you name classes with numbers? I don't really think it matters as that's quite an isolated example (Where another ordering system for words makes more sense because those words represent numbers) but if other people have objections we can revisit this.

I'll voice an objection then, so this does not get brushed under the carpet of "your use-case isn't very common".

What is the reasoning behind ordering these things alphabetically? It is a burden on the developer, and I have seen no reason given for why it should be enforced.
 

This seems like a fair point to me.

 

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/2f6ab734-5149-4ff4-baed-2ba32b279371%40googlegroups.com.

[Ryan Parman]

On December 8, 2015 at 9:35:20 AM, Korvin Szanto (korvin...@gmail.com(mailto:korvin...@gmail.com)) wrote:

> On Tue, Dec 8, 2015 at 5:17 AM Jason Judge wrote:

>

> > On Tuesday, 8 December 2015 00:00:28 UTC, Michael Cullum wrote:

> >

> > > I've put comments inline on the changes. In regards to the new statements you'd like to see added I've not commented as I'd rather avoid adding new statements now. I'd also add that most of your changes break BC quite a bit or would enforce behaviour instead of just coding style, we discussed what was out of scope in reference to whether we should require strict types and we decided that those kinds of things do not really belong here.

Fair enough.

> > > On 7 December 2015 at 08:17, Ryan Parman wrote:

> > >

> > > > https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#42-using-traits

> > > >

> > > > “Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.”

> > > >

> > > > The coding example then goes-on to show the `use` statement for Traits being used in a way that was identified and discarded for Namespace Aliases in PSR-2 discussions. The instruction is also somewhat ambiguous, allowing for multiple styles of using the `use` statement for Traits.

> > > >

> > > > IMO, we should keep the pattern for Namespace Aliases and Traits the same.

> > >

> > > I'm not entirely sure what you mean. Would you mind submitting a pull request with what you think makes more sense as that would make it easier to see what you mean?

https://github.com/php-fig/fig-standards/pull/701

> > > > https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#7-closures

> > > >

> > > > Was the text for Closures always part of PSR-2? I’ve read this document dozens of times, and I did not recall that section being there before.

> > > >

> > > > I am curious as to the thinking behind requiring a space after the function keyword. Why didn’t the syntax for Closures match the syntax for Methods and Functions (i.e., no space between the function’s name and the opening paren)?

> > >

> > > Closures was in PSR-2 and I'd rather not change it.

> >

> > Probably better not to mention it at all in this PSR, if it is not changing. It is difficult to pick out what has been duplicated from PSR-2, what is an extension to PSR-2, and what are new rules that have been thrown in. If PSR-12 is an extension to PSR-2 then IMO it would be better to describe how it extends PSR-2 and not to have an arbitrary mix of extension and repetition. If it's a *replacement* of PSR-2, then that's something else altogether.

>

> PSR-12 is a replacement for PSR-2.

I remember the PSR-2 discussions, and that it was simply an attempt to formalize what the majority of projects were doing.

No worries. I just didn't recall seeing the section on Closures before, nor notice that the recommendation for anonymous function syntax differed from function/method syntax.

> > > > 2. “Classes, functions or constants grouped together into a single line must be listed alphabetically.”

> > > >

> > > > In this case, the statement matches my preference. That said, I still think that this should NOT be standardized. For example, “Two” comes later in the alphabet than “Three”. And “Four” is before all of those. (Yes, this example is silly, but it illustrates my point.)

> > >

> > > Sure but how often do you name classes with numbers? I don't really think it matters as that's quite an isolated example (Where another ordering system for words makes more sense because those words represent numbers) but if other people have objections we can revisit this.

> >

> > I'll voice an objection then, so this does not get brushed under the carpet of "your use-case isn't very common".

> >

> > What is the reasoning behind ordering these things alphabetically? It is a burden on the developer, and I have seen no reason given for why it should be enforced.

>

> This seems like a fair point to me.

Essentially, I would be okay with making this a _recommendation_ (at most), but breaking from the alphabetical pattern should neither be a WARNING nor an ERROR.

> > > > 3. “Declare statements MUST contain no spaces and MUST look like declare(strict_types=1);.”

> > > >

> > > > This is counter to how we define variables. It seems to me that this format should match variables because that’s essentially what this is.

> > >

> > > I'd actually counter that with declare acts more like a function that evaluates a string. Declare is odd because it's not a normal assignment (otherwise we'd just have `strict_types = 1`) but the argument it accepts is not actually a string either. Either way, it's not a normal statement in and I'd say that therefore it's not an exception but a separately defined rule. As I said, this seems to be the de facto standard so far of doing it from every PHP 7 talk I've seen including Cal Evans who is doing the Zend trainings on PHP 7, it's also the same in the PHP documentation and RFC which is where a lot of people are pulling it from and as such it seems to be the most commonly way of coding it including large projects such as PHP files contained within Facebook's HHVM. https://github.com/search?utf8=%E2%9C%93&q=declare%28strict_types%3D1%29%3B&type=Code&ref=searchresults

I can buy that. Fair enough.

> > > > https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#8-anonymous-classes

> > > >

> > > > “The opening bracket MAY be on the same line as the class keyword so long as the list of implements interfaces does not wrap. If the list of interfaces wraps, the bracket MUST be placed on the line immediately following the last interface.”

> > > >

> > > > IMO, all classes — anonymous or otherwise — should match in how they are defined. I recognize that this is written to match how Closures (a.k.a. Anonymous Functions) are formatted, but that doesn’t make sense to me either. Why do the “anonymous” things have a different style of definition from the concrete things?

> > >

> > > I'd rather follow the consistency here from anonymous functions and in being consistent with anonymous functions, like anonymous functions, you should be inconsistent with the non-anonymous variant. So we are being consistent two-fold by being inconsistent with non-anonymous classes as PSR-2 was intentionally inconsistent and this was the decided on method through surveys and lengthy discussions.

Consistent in our inconsistency, because of PSR-2, which was simply a matter of documenting what the majority of projects were doing instead of trying to fix inconsistencies.

Not worth the energy to fight it, but let's call a spade a spade.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANeXGWUejuRLEGM0JeFBiFsrNej04CbuZiFiOHAYXb0mAhOgbQ%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Ryan Parman
http://ryanparman.com

"If you don't have passion for what you do, you won't be very good at it."

[Mike van Riel]

I have reviewed PSR-12 and have the following questions and comments. I have tried to keep up with the thread but due to the number of comments I may address issues that have been addressed before.

 

This guide extends and expands on PSR-2, the coding style guide and PSR-1, the basic coding standard.

A) is it a guide or specification?

B) In this thread the intention has been given that PSR-12 supersedes PSR-2; but this intro suggests (at least to me) that this PSR is used in addition to PSR-2 and not supersede it.

PSR-2 was accepted in 2012 and since then a number of changes have been made to PHP which have implications for coding style guidelines. Whilst PSR-2 is very comprehensive of PHP functionality that existed at the time of writing, new functionality is very open to interpretation. This PSR therefore seeks to clarify the content of PSR-2 in a more modern context with new functionality available, and make the errata to PSR-2 binding.

This section looks more like it belongs to the meta document and not in the specification.

There MUST NOT be a hard limit on line length.

The soft limit on line length MUST be 120 characters; automated style checkers MUST warn but MUST NOT error at the soft limit.

Lines SHOULD NOT be longer than 80 characters; lines longer than that SHOULD be split into multiple subsequent lines of no more than 80 characters each.

This section is ambiguous to me; are there three types of line lengths? None, 120 and 80? When should which be enforced, or is this actually just moot?

Code MUST use an indent of 4 spaces, and MUST NOT use tabs for indenting.

This technically states that all code must be indented with 4 spaces while the intention is that each level of indentation is indicated by 4 spaces. (though I am not sure indicated is an accurate word here)

The PHP types and keywords int, true, object, float, false, mixed, bool, null, numeric, string andresource MUST be in lower case

Shouldn’t ‘void’ also be added?

Use statements MUST be in blocks, grouped by varying entity (classes [inc. interfaces and traits], functions or constants). To elaborate, this means that any and all classes are in a block together; any and all functions are in a block together; and any and all constants must be grouped together. Within each block there MUST be no blank lines. If a block has multiple lines there MUST be a blank line before the first line and a blank line after the last line.

To me this sounds a bit strict, I frequently split longer use blocks in groups that are separated by whitelines.

Classes, functions or constants grouped together into a single line must be listed alphabetically.

Again: too strict for my taste. If people hate aligning assignment operators they will also hate this. Also: I sometimes group on theme.

When wishing to declare strict types in files containing markup outside PHP opening and closing tags MUST, on the first line, include an opening php tag, the strict types declaration and closing tag.

This section and example contradicts the rule that the opening <?php should always be on its own line.

Using multiple lines for traits, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the same line of the use keyword, and there MUST be only one trait per line.

Why is it required to have a use keyword per namespace alias but not for traits? This seems inconsistent

When you have a return type declaration present there MUST be one space after the colon with followed by the type declaration. The colon and declaration MUST be on the same line as the argument list closing parentheses with no spaces between the two characters. The declaration keyword (e.g. string) MUST be lowercase.

The last part (’The declaration keyword (e.g. string) MUST be lowercase’) could be a little more elaborate and include that this only applies if a recognised php keyword is used; types such as classes, interfaces and traits should have their respective case.

somefunction($foo, $bar, [
  // ...
], $baz);

This example breaks the rule that a multi-line function call should have each argument on their own line

• The structure body MUST be indented once

I consider this an ambiguous statement; in a nested control structure this could mean that everything beyond the first control structure has the same indentation level

 

A for statement looks like the following

I would prefer if the for statement receives a little more text since the argument(s) of a for follow special rules themselves (noteworthy: a space after each semi-colon) that deviate from the default rules mentioned in the opening of the control structures chapter

A foreach statement looks like the following.

Same as the for statement

All binary and ternary operators MUST be preceded

To make it more obvious that the logical not operator is excluded from this rule I would prepend here a text alike ‘Apart from the logical not operator (!),’

Also: I am missing information on what you SHOULD do with the logical not operator; how you should deal with that appears to be omitted.

I hope this suffices for now, thanks for your effort on this PSR.

Mike

[Jordi Boggiano]

Heya,

Here are my comments, given the length of existing discussion I
apologize if I repeat things, feel free to ignore those.

- 2.5. Maybe should be titled "Keywords and types"?

- 3. "Compound namespaces with a depth of two or more MUST not be used.
Therefore the following is the maximum compounding depth allowed:" This
sentence isn't clear enough IMO. A negative example of something that is
not allowed would be good to have.

- 3. The `use` rules are overall quite lengthy and nitpicky. The
ordering of things and especially alphabetical ordering within a line as
a bit hardcore if you don't use an IDE that does it for you. I feel like
this oversteps a bit from code styling into micro-management.

That is all, the rest appears to be a pretty straightforward port of the
existing guidelines onto the new constructs, so good work and thank you!

Cheers

--
Jordi Boggiano
@seldaek - http://seld.be

[Chris Riley]

Hi,

Is this PSR intended to supersede PSR 2? 

Possibly a little controversial but I'd like to suggest adding a rule against "use" ing none namespaced classes, functions and constants; instead preferring to prefix them with a \ I find that doing this more succinctly displays that you are using a (usually) built in class eg \Exception instead of one you brought in from a library or that exists in the same namespace.

~C

[Woody Gilk]

Chris,

That's been discussed already. I for one, am completely against this idea. I prefer to declare ALL my dependencies, including built-in classes, at the top of the file with "use" statements.

--
Woody Gilk
http://about.me/shadowhand

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/75d6f6a8-ea02-485d-8c4e-9c7d9fa7e0d3%40googlegroups.com.

[Michael Cullum]

Have I missed anything?

-------------------------------

So I think the vast majority of the issues raised in this topic have been addressed or changed in the specification now. If there are any points I've missed please do feel free to re-highlight them, this is a large thread and stuff does get missed and I certainly don't want any issues or objections to get swept under the carpet.

Survey

---------

Paul, I've discussed this with Korvin and Alexander and we are now preparing a survey for voting members to respond to as a result of your feedback but the spec will not just be decided on the results of a poll but will take other factors into consideration. The reason for the poll will be to alert the WG to any points that are controversial so they can be brought forward for larger discussion until consensus is found.

Editor/Role Changes

----------------------------

I'm also stepping down as Editor of PSR-12 as I'd always intended to only be Editor of PSR-12 for the remainder of 2015. Korvin, Alexander and others were aware of this since the initial formation discussions occurred on IRC. Korvin will be taking over as Editor and Alexander will be moving to Coordinator and Korvin is currently looking for new second sponsor, if anyone's interested I'd suggest dropping him an email or messaging him on IRC (#phpfig on Freenode), to be announced in due course. I will still be continuing as a contributor to PSR-12 though and around just as much (if not more so) than I was before.

So, back to my point at the top of the post, have I missed any points out from this thread? Also if you have any more points then they would be appreciated. If not, I believe the survey will be going ahead in the next week or two, open for a couple of weeks, then if nothing is shown to be controversial, that will be added to the meta and it will go into review phase, if there are issues highlighted from the survey they will of course be addressed first.

Link to the spec again in case you don't have it to hand: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md 

Happy new year all!

--

Michael C

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6%2BXQXvrrFgEwR9xzRJ5RTGicv5gCjwSOh%3DWbK11u7yv%2BQ%40mail.gmail.com.

[Richard Fussenegger]

I am not through the whole thread yet but the current version still misses that blank line after the opening PHP tag. This makes it impossible to add a file-level PhpDoc to any file and introduces a huge BC for PhpDoc. It is also inconsistent since all other structural elements require blank lines before and after them. PSR-2 already contains enough inconsistency, stop the madness and correct this. Imho there is no need for a survey on this one, simply because it introduces a BC for PhpDoc and is inconsistent.

[Michael Cullum]

Richard,

I agree... that's why no such instruction/rule is in the specification requiring a blank line after `<?php`?

--

Michael C

On 2 January 2016 at 23:21, Richard Fussenegger <richard.f...@gmail.com> wrote:

I am not through the whole thread yet but the current version still misses that blank line after the opening PHP tag. This makes it impossible to add a file-level PhpDoc to any file and introduces a huge BC for PhpDoc. It is also inconsistent since all other structural elements require blank lines before and after them. PSR-2 already contains enough inconsistency, stop the madness and correct this. Imho there is no need for a survey on this one, simply because it introduces a BC for PhpDoc and is inconsistent.

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/02686502-23c1-4cde-b0c9-dde0c0dad1de%40googlegroups.com.

[Richard Fussenegger]

On Sunday, January 3, 2016 at 12:36:18 AM UTC+1, Michael Cullum wrote:

Richard,

I agree... that's why no such instruction/rule is in the specification requiring a blank line after `<?php`?

--

Michael C

 The problem is that no blank line is required: “There MUST NOT be a blank line before declare statements such as those for strict types or ticks. They MUST be contained on the lines immediately following the opening tag (which must be on the first line when declare statement(s) are present).”

<?php
/**
 * @author Richard Fussenegger <richard@fussenegger>
 * @copyright 2016 Richard Fussenegger
 * @license MIT
 */
declare(strict_types=1);

// More code …

Current PhpDoc implementations require DocBlocks to precede the structural element that is being documented. There is one single exception to this rule, the filelevel DocBlock. Simply becuase it is impossible to place it before the opening PHP tag. Now have a look at the above example code that follows the PSR-12 rule to not place a blank linke before the declare structural element. It is impossible for a PhpDoc implementation to tell if this is a filelevel DocBlock or a documentation for the declare statement.

<?php
/**
 * @author Richard Fussenegger <richard@fussenegger>
 * @copyright 2016 Richard Fussenegger
 * @license MIT
 */

declare(strict_types=1);

// More code …

Now it is clear. Additionally it is consistent with all other groupable and non-groupable elements that require preceding and succeeding blank lines. Imho it would be more future proof to actually define that rule as such: “All statements MUST be preceeded and succeeded by a single blank line unless contained within a block.” Or something similar, what it means:

<?php

declare(strict_types=1);
declare(ticks=1);

namespace PhpFig\Psr12;

const NS_CONST_1 = 1;
const NS_CONST_2 = 2;

function nsFn() {
    // Within block!
}

use Something;
use Something\Else;

class CodingStandard

{
    // Within block!
    public function fn()

    {
        // Within block!
    }
}

[Michael Cullum]

Actually that code is PSR-12 incompatible, note the second part to the following instruction: "There MUST NOT be a blank line before declare statements such as those for strict types or ticks. They MUST be contained on the lines immediately following the opening tag (which must be on the first line when declare statement(s) are present)."

So the declare statement must always follow the `<?php` tag with nothing in between.

--

Michael C

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/b9353abb-0280-4287-a3bb-2cd3bbe47eef%40googlegroups.com.

[Woody Gilk]

I agree with Richard, the requirement for there to be no new line
between opening tag and declare is inconsistent and unnecessary.

--
Woody Gilk
http://about.me/shadowhand

> https://groups.google.com/d/msgid/php-fig/CAAqcDMj41WUzO81pD6sHaGjoh0A7nmUXeyrw%3D55RJ_a9nWf9ng%40mail.gmail.com.

[Larry Garfield]

I concur. In fact, that whole section seems to be clumsily worded.

I would recommend instead something like the following (feel free to
crib as appropriate):

-----

The header of a PHP-only file may consist of a number of different
blocks. If present, each of the blocks below MUST be separated by a
single blank line, and MUST NOT contain a blank line. Each block MUST
be in the order listed below, although blocks that are not relevant may
be omitted.

Opening PHP tag <?php

File-level docblock.

One or more declare statements.

The namespace declaration of the file.

One or more class-based `use` statements.

One or more function-based `use` statements.

One or more `const`-based use statements.

The remainder of the code in the file.

-----

That gives the header section a very consistent order and formatting,
while keeping the language describing it fairly short and sweet. (One
blank line between sections, sections in this order, kthxbye.)

The code sample currently puts function and const use statements
together in a block, which technically violates the wording in the text
already as well as my suggested text above.

Related tangent: In Drupal, we debated at length about the order of
`use` statements and eventually settled on not having a standard. In
practice, though, since PHPStorm is so popular among Drupal devs these
days most of our code is using alphabetical order since PHPStom has a
single command to do that. (I preferred source-clustering initially, so
Symfony-based stuff was together followed by Drupal-namespaced stuff,
but have largely given up and adopted alphabetic as well.) Do we want
to specify an alphabetic order for `use` statements or no?

--Larry Garfield

[Woody Gilk]

On Sun, Jan 3, 2016 at 2:01 PM, Larry Garfield <la...@garfieldtech.com> wrote:
> That gives the header section a very consistent order and formatting, while
> keeping the language describing it fairly short and sweet. (One blank line
> between sections, sections in this order, kthxbye.)

+1

> I preferred source-clustering initially, so Symfony-based stuff was together
> followed by Drupal-namespaced stuff, but have largely given up and adopted
> alphabetic as well.

I spent a few months doing this and largely gave up because it
required extra mental effort to decide how to group things. Going
alphabetical is the best way to keep cognitive load to a minimum.

[Larry Garfield]

On 01/02/2016 04:31 PM, Michael Cullum wrote:

Have I missed anything?

-------------------------------

So I think the vast majority of the issues raised in this topic have been addressed or changed in the specification now. If there are any points I've missed please do feel free to re-highlight them, this is a large thread and stuff does get missed and I certainly don't want any issues or objections to get swept under the carpet.

*snip*

Link to the spec again in case you don't have it to hand: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md 

Happy new year all!

Other random notes as I read through the spec:

4.0: The text here uses "parentheses" to refer to ().  The metadoc, however (section 5), refers to those characters as brackets.  Brackets are these things: []. :-)  Please update the metadoc.

4.1: "Lists of implements and extends MAY be split across multiple lines, where each subsequent line is indented once."

That should be lists of implements, as extends is never a list. 

4.3/4.4: Why is not using a _ prefix as a visibility modifier only a SHOULD NOT, rather than MUST NOT?  It's 2016 and we're talking about PHP 7.  Those were a PHP 4 convention that makes no sense at all today, and I've not seen it in a long time myself.  Why not go all the way on that?

4.5: The metadoc says that the space on only one side of the return type colon is "for consistency".  With what? I don't see anything else where that would be consistent with it.  Rather, I see almost everything else having a space on either side, save for functionName(.  Looking at the anon function example right above it:

$app->get('/hello/{name}', function ($name) use ($app) {
    return 'Hello '.$app->escape($name);
});

function space param-list space use space use-list space brace.  Everything there has a space.  The same is true for control structures.  Why make : odd-man-out?  Putting a space on both sides of the colon seems both more consistent and more readable to me.


5.6: "A try catch finally block" is better read as "A try-catch-finally block".  The highlighting on the 3 keywords is too faint and insufficient, especially when accessibility is taken into account.  Dashes FTW.

6: Why is the string concat operator not a binary operator?  It takes a pre-argument and a post-argument, and evaluates to a new argument, exactly like + does.  (Drupal used to have string-concat only sometimes take a padding space.  We eventually concluded that was stupid and moved to always having the padding space, exactly as binary operators here.)

7: As with the header block (see previous email), the wording here is quite clumsy.  The intent appears to be "every section separated by a space if it exists", but with collapsed spaces for the parens.  So just say that.  The wording here, without the example, would take too long for my brain to parse.

The text would also appear to forbid even super-short inlined anon functions:

array_map(function ($a) { return $a->b(); }, $arr);

Is that intentional?  If the body is single-line and short I'd argue that is more readable than forcing it to multiple lines.  (This may be leftover from PSR-2, I'm not sure.)

--Larry Garfield

[Michael Cullum]

I do quite like that style of formatting the header rules, it is a lot easier to read.

-1 to requiring alphabetical ordering. We had this in some other places in the spec but removed it after feedback it steps into micromanagement, doesn't really help anything and can be a nightmare without an IDE.

Other comments inline

Thanks!

--

Michael C

On 3 January 2016 at 20:30, Larry Garfield <la...@garfieldtech.com> wrote:

On 01/02/2016 04:31 PM, Michael Cullum wrote:

Have I missed anything?

-------------------------------

So I think the vast majority of the issues raised in this topic have been addressed or changed in the specification now. If there are any points I've missed please do feel free to re-highlight them, this is a large thread and stuff does get missed and I certainly don't want any issues or objections to get swept under the carpet.

*snip*

Link to the spec again in case you don't have it to hand: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md 

Happy new year all!

Other random notes as I read through the spec:

4.0: The text here uses "parentheses" to refer to ().  The metadoc, however (section 5), refers to those characters as brackets.  Brackets are these things: []. :-)  Please update the metadoc.

Whoops, that's me being British. We refer to () as brackets and square brackets, so it's not wrong, just ambiguous. I'll fix that (as parentheses aren't ambiguous).

4.1: "Lists of implements and extends MAY be split across multiple lines, where each subsequent line is indented once."

That should be lists of implements, as extends is never a list. 

Ah yes, thanks for pointing that out.

4.3/4.4: Why is not using a _ prefix as a visibility modifier only a SHOULD NOT, rather than MUST NOT?  It's 2016 and we're talking about PHP 7.  Those were a PHP 4 convention that makes no sense at all today, and I've not seen it in a long time myself.  Why not go all the way on that?

I'm not sure how I feel about this but I think I agree.

4.5: The metadoc says that the space on only one side of the return type colon is "for consistency".  With what? I don't see anything else where that would be consistent with it.  Rather, I see almost everything else having a space on either side, save for functionName(.  Looking at the anon function example right above it:

$app->get('/hello/{name}', function ($name) use ($app) {
    return 'Hello '.$app->escape($name);
});

function space param-list space use space use-list space brace.  Everything there has a space.  The same is true for control structures.  Why make : odd-man-out?  Putting a space on both sides of the colon seems both more consistent and more readable to me.

Korvin might have a better recollection of the reasons around this than I (https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-returntypesspacing-php) but I believe the intention was to create the visual effect that the closing parameter bracket and colon look more like one character. As nothing can ever go between those two characters, the colon is more of a modifier to the closing parentheses to tell you to expect a return type declaration as opposed to enclosing a statement or number of statements as parentheses/square brackets/curly braces are used in PHP. A crude example of having two pieces of punctuation next to each other (instead of the second piece of punctuation being more of a modifier to the first pieces) would be `statement;;` vs `statement;`. I've not really talked about consistency here so either the meta document could be incorrect in that aspect or I'm forgetting other reasons for that decision that Korvin might remember. Our decision was also influenced by this being the most common way used in code on github (from some crude searching), php documentation and the RFCs but this wasn't the deciding factor.

5.6: "A try catch finally block" is better read as "A try-catch-finally block".  The highlighting on the 3 keywords is too faint and insufficient, especially when accessibility is taken into account.  Dashes FTW.

+1 

 

6: Why is the string concat operator not a binary operator?  It takes a pre-argument and a post-argument, and evaluates to a new argument, exactly like + does.  (Drupal used to have string-concat only sometimes take a padding space.  We eventually concluded that was stupid and moved to always having the padding space, exactly as binary operators here.)

String concat is a binary operator, hence it says excluding the string concatenation operator. The reason for the exclusion was to reduce migration friction from PSR-2. For PSR-12 one thing we wanted to do was avoid breaking any more BC than was necessary in order to make that migration path easier. I'd be +1 to removing the exclusion if people think that wouldn't be a problem though.

 

7: As with the header block (see previous email), the wording here is quite clumsy.  The intent appears to be "every section separated by a space if it exists", but with collapsed spaces for the parens.  So just say that.  The wording here, without the example, would take too long for my brain to parse.

The text would also appear to forbid even super-short inlined anon functions:

array_map(function ($a) { return $a->b(); }, $arr);

Is that intentional?  If the body is single-line and short I'd argue that is more readable than forcing it to multiple lines.  (This may be leftover from PSR-2, I'm not sure.)

I haven't touched section 7 at all and it remains as-is from PSR-2. I'd probably be +1 to something cleaning up the wording there though I wouldn't say it was strictly necessary as it is just PSR-2 stuff.

--Larry Garfield

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/568984EF.10208%40garfieldtech.com.

[Larry Garfield]

On 01/03/2016 03:38 PM, Michael Cullum wrote:

On 3 January 2016 at 20:30, Larry Garfield <la...@garfieldtech.com> wrote:

4.5: The metadoc says that the space on only one side of the return type colon is "for consistency".  With what? I don't see anything else where that would be consistent with it.  Rather, I see almost everything else having a space on either side, save for functionName(.  Looking at the anon function example right above it:

$app->get('/hello/{name}', function ($name) use ($app) {
    return 'Hello '.$app->escape($name);
});

function space param-list space use space use-list space brace.  Everything there has a space.  The same is true for control structures.  Why make : odd-man-out?  Putting a space on both sides of the colon seems both more consistent and more readable to me.

Korvin might have a better recollection of the reasons around this than I (https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-returntypesspacing-php) but I believe the intention was to create the visual effect that the closing parameter bracket and colon look more like one character. As nothing can ever go between those two characters, the colon is more of a modifier to the closing parentheses to tell you to expect a return type declaration as opposed to enclosing a statement or number of statements as parentheses/square brackets/curly braces are used in PHP. A crude example of having two pieces of punctuation next to each other (instead of the second piece of punctuation being more of a modifier to the first pieces) would be `statement;;` vs `statement;`. I've not really talked about consistency here so either the meta document could be incorrect in that aspect or I'm forgetting other reasons for that decision that Korvin might remember. Our decision was also influenced by this being the most common way used in code on github (from some crude searching), php documentation and the RFCs but this wasn't the deciding factor.

The pseudo-single-character argument is unconvincing for me.  There are many syntax features that inherently go together where PSR-2/12 still mandate a space.  if {, use (, class Foo \n{, catch (, and a few dozen others.  I don't think "statement;;" is a valid example as that's just pointless extra floatsam that has always been bad practice anyway.

The consistency argument in the metadoc applies to finally (as finally following the same pattern as catch, or if-elseif-else, makes a great deal of sense), but seems to be counter to the stated : usage.

6: Why is the string concat operator not a binary operator?  It takes a pre-argument and a post-argument, and evaluates to a new argument, exactly like + does.  (Drupal used to have string-concat only sometimes take a padding space.  We eventually concluded that was stupid and moved to always having the padding space, exactly as binary operators here.)

String concat is a binary operator, hence it says excluding the string concatenation operator. The reason for the exclusion was to reduce migration friction from PSR-2. For PSR-12 one thing we wanted to do was avoid breaking any more BC than was necessary in order to make that migration path easier. I'd be +1 to removing the exclusion if people think that wouldn't be a problem though.

Did PSR-2 specify either way?  If not, then it's not a BC break with PSR-2.  It may or may not be a change from what people happen to have in their code base now, but that's true of anything PSR-12 adds.  Off hand I don't see why we'd expect strong-concat to be any more of an issue than + in this regard.

--Larry Garfield

[Richard Fussenegger]

On Sunday, January 3, 2016 at 9:01:49 PM UTC+1, Larry Garfield wrote:

Opening PHP tag <?php

File-level docblock.

One or more declare statements.

The namespace declaration of the file.

One or more class-based `use` statements.

One or more function-based `use` statements.

One or more `const`-based use statements.

The remainder of the code in the file.

There cannot be an empty line between the filelevel DocBlock and the opneing PHP tag as it might break some PhpDoc implementations. As of now the filelevel DocBlock must come directly after the opening PHP tag:

<?php
/** file level docblock */

declare

namespace

use

class

 

[Christopher Pitt]

it might break some PhpDoc implementations

I don't think that's a good reason not to allow it.

[Alexander Makarov]

Survey is posponed since we're getting enough valuable feedback to think of for now. Thanks for it btw.

Larry Garfield, could you submit structure proposal as pull request. It will be easier to get an idea. I'm a bit lost in comments (probably new year celebration consequences).

Brackets → Parentheses: https://github.com/php-fig/fig-standards/pull/726

There could be no list of extends: https://github.com/php-fig/fig-standards/pull/728

try-catch-finally: https://github.com/php-fig/fig-standards/commit/6e85d0c71795e9d99d2b9f7df7e0e56973dcdd69