Question about USE blocks in PSR-2

[Greg Sherwood]

Hi all,

I'm finishing off the PSR-2 coding standard for PHP_CodeSniffer but have come across something a little ambiguous. I'm not sure exactly what errors to report for one of the namespace rules, so I'm hoping others can help with a decision.

The PSR-2 standard says "There MUST be one blank line after the use block". This, along with the sample code, seems to indiciate that all USE statements must be together in a single block of code with no spacing between each. But PSR-2 does not specifically say this or define what a "USE block" is. It also doesn't say to refer to the sample code for spacing, as it does with some other code samples.

So, taking a code sample from the PHP manual, is this valid code or should it generate errors on lines 3 and 6 for having additional lines between USE statements?

1. <?php
2. namespace foo;
3. use My\Full\Classname as Another;
4. 
5. // this is the same as use My\Full\NSname as NSname
6. use My\Full\NSname;
7. 
8. // importing a global class
9. use ArrayObject;

You could also have something like this, where USE statements are grouped and commented on together. Is this valid or should it generate an error on line 6 for having additional lines between USE statements?

1. <?php
2. namespace foo;

3.

4. // Comment here.

5. use My\Full\Classname as Another;

6. use My\Full\NSname;

7.

8. // importing a global class
9. use ArrayObject;

Both these would be valid if the standard was interpreted as "USE statements must be followed by another USE statement or a single blank line" but I'm not sure if this is what the standard intends.

Any help greatly appreciated.

[Nicolas Dermine]

Hi Greg,

I would interpret the standard as requiring one blank line after the last use statement.

I would find it too restrictive to forbid blank lines between use statements.

Nico

>
> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/wV6iafUrH2YJ.
> For more options, visit https://groups.google.com/groups/opt_out.
>  
>  

[Greg Sherwood]

On Wednesday, 1 August 2012 17:46:19 UTC+10, nico wrote:

I would interpret the standard as requiring one blank line after the last use statement.

Thanks for replying. If that's the case, I wonder if there are any restrictions on the spacing between use statements. Is this valid?

1. <?php
2. namespace foo;
3. use My\Full\Classname as Another;
4. 

5. use My\Full\NSname;
6. 

7. use ArrayObject;

And is this valid?

1. <?php
2. namespace foo;
3. use My\Full\Classname as Another;
4. 

5.

6. use My\Full\NSname;
7.

8. 

9. use ArrayObject;

Sorry if this all looks a bit silly. It's just that there are no grey areas in an automated tool, so I need to think about all the different bits of code that PHP_CodeSniffer might come across and make sure I have a clear goal of what the code should look like.

[Hari K T]

Hi Greg , 

I thought I should wait for someone to reply for this for I am not really a voting member .

So this is what I can say .

I'm finishing off the PSR-2 coding standard for PHP_CodeSniffer but have come across something a little ambiguous. I'm not sure exactly what errors to report for one of the namespace rules, so I'm hoping others can help with a decision.

Good lets finish it soon :) .

 

The PSR-2 standard says "There MUST be one blank line after the use block". This, along with the sample code, seems to indiciate that all USE statements must be together in a single block of code with no spacing between each.

Yes you are right .

 

But PSR-2 does not specifically say this or define what a "USE block" is. It also doesn't say to refer to the sample code for spacing, as it does with some other code samples.

I am not sure what you mean by defining use block . It does mentions for eg : so I feel it makes sense . No ?

The code and wordings I am taking from PSR-2

When present, there MUST be one blank line after the namespace declaration.

When present, all use declarations MUST go after the namespace declaration.

There MUST be one use keyword per declaration.

There MUST be one blank line after the use block.

For example:

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

 

So, taking a code sample from the PHP manual, is this valid code or should it generate errors on lines 3 and 6 for having additional lines between USE statements?

1. <?php
2. namespace foo;
3. use My\Full\Classname as Another;
4. 
5. // this is the same as use My\Full\NSname as NSname
6. use My\Full\NSname;
7. 
8. // importing a global class
9. use ArrayObject;

Line 3 must be a blank line .

It should throw errors on lines 4 , 7  for there are new lines between use statements .

You could also have something like this, where USE statements are grouped and commented on together. Is this valid or should it generate an error on line 6 for having additional lines between USE statements?

I think this para applied to the example above. so my answer is yes it should throw errors in between lines of use statement .

 

1. <?php
2. namespace foo;

3.

4. // Comment here.

5. use My\Full\Classname as Another;

6. use My\Full\NSname;

7.

8. // importing a global class
9. use ArrayObject;

Both these would be valid if the standard was interpreted as "USE statements must be followed by another USE statement or a single blank line" but I'm not sure if this is what the standard intends.

This example also will throw error in 7 for new line between use .

Thank you

 

Any help greatly appreciated.

[Hari K T]

I would interpret the standard as requiring one blank line after the last use statement.

No you should never intepret like that for it mentions

There MUST be one blank line after the use block.

 

See block , not statement :) .

[Hari K T]

Thanks for replying. If that's the case, I wonder if there are any restrictions on the spacing between use statements. Is this valid?

1. <?php
2. namespace foo;
3. use My\Full\Classname as Another;
4. 

5. use My\Full\NSname;
6. 

7. use ArrayObject;

And is this valid?

No and never :)

 

1. <?php
2. namespace foo;
3. use My\Full\Classname as Another;
4. 

5.

6. use My\Full\NSname;
7.

8. 

9. use ArrayObject;

Sorry if this all looks a bit silly. It's just that there are no grey areas in an automated tool, so I need to think about all the different bits of code that PHP_CodeSniffer might come across and make sure I have a clear goal of what the code should look like.

--

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

To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/DytviBB2Z10J.

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

Hari K T
M: +91-9388758821 | W: http://harikt.com/blog

[Greg Sherwood]

First, thanks for taking the time to reply. I actually agree with you if your interpretation, but I'd really like to hear what the voting members think so I know what the intention of the standard is.

Also, I am fully aware is says block and not statement (see original post). My problem is that is doesn't say there must be one block of USE statements per file or what "block" means. We are talking semantics here, but a block of code doesn't necessarily mean multiple lines of code without empty lines. Even if it did, is this valid?

1. <?php

2. namespace foo;

3.

4. use My\Full\Classname as Another; 

5. // this is the same as use My\Full\NSname as NSname

6. use My\Full\NSname;

7. // importing a global class

8. use ArrayObject;

PSR-2 omits all commenting standards, so I don't think I'd be able to throw an error here unless I defined a block as multiple lines of code without empty lines or comment lines. So then can developers do this?

1. <?php

2. namespace foo;

3.

4. use My\Full\Classname as Another;  

5. use My\Full\NSname; // this is the same as use My\Full\NSname as NSname

6. use ArrayObject; // importing a global class

PHPCS is not able to be as ambiguous as a written standard because it has to report an error, or not. If I get it wrong, suddenly I get complaints from people saying that they like commenting their USE blocks and the PSR-2 standard doesn't say they are not allowed to. They're not going to come to this group first to see if PHPCS is right or not. They start by reporting a PHPCS bug, so I'd like to know what these lines mean from the people who wrote them. If this isn't the right place to ask, can someone point me in the right direction.

[Paul Dragoonis]

Hi Greg,

You can define have as many use statements as you want in the same
block, you can put as many fancy comments in it, they don't count as
actual code.

"
<?php

namespace foo;

use Something;
use SomethingElse;

// Comments here
use AnotherThing;
[ important space after the _last_ use statement, defining the end of
the _use block_ ]
class Foo {
}

"

I hope this clarifies everything for you, please let us know if you
have more questions

Paul

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-fig/-/VwJTXISMykEJ.

[Hari K T]

You can define have as many use statements as you want in the same
block, you can put as many fancy comments in it, they don't count as
actual code.

"
<?php

namespace foo;

use Something;
use SomethingElse;

// Comments here
use AnotherThing;
[ important space after the _last_ use statement, defining the end of
the _use block_ ]
class Foo {
}

I am confused here .

"There MUST be one blank line after the use block."

That means the blank line after use SomethingElse should throw error  . But if I am correct understanding you , you didn't mentioned this is wrong and was telling space after the last use statement.

I feel its not space, its blank line.
 

[Paul Dragoonis]

On Mon, Aug 6, 2012 at 11:11 AM, Hari K T <ktha...@gmail.com> wrote:
>
>> You can define have as many use statements as you want in the same
>> block, you can put as many fancy comments in it, they don't count as
>> actual code.
>>
>> "
>> <?php
>>
>> namespace foo;
>>
>> use Something;
>> use SomethingElse;
>>
>> // Comments here
>> use AnotherThing;
>> [ important space after the _last_ use statement, defining the end of
>> the _use block_ ]
>> class Foo {
>> }
>
>
> I am confused here .
>
>
> "There MUST be one blank line after the use block."
>
> That means the blank line after use SomethingElse should throw error . But
> if I am correct understanding you , you didn't mentioned this is wrong and
> was telling space after the last use statement.
>
> I feel its not space, its blank line.
>

The key part here Hari is "There MUST be one blank line after the use block."

This is talking only about the use block, and not the newlines inside
it. After the last use statement there must be a blank line.

use Something[\n] <-- end of use block
[\n]
class A { ...

Does this help you?

[Hari K T]

Hey @Paul ,

Yes that makes sense ..

So after use blocks there should be a new line .

Eg :

use MyClass1;
use MyClass2;

use MyClass3;

use MyClass4;
// with comments
use MyClass5;
use MyClass6;

Hari K T
M: +91-9388758821 | W: http://harikt.com/blog

[Paul Dragoonis]

Yep, that's right.

[Lucas Arruda]

The sentence is clear to me, however the main purpose of this thread may be whether the current rule is not covering all possibilities or if the main reason that resulted in this rule is not being clearly covered at all, am I right?

Lucas Arruda

[Lucas Arruda]

This example you gave us opened a question for me about whether is it fine to have multiple USE blocks altogether but separated by a new line feed, and also if we can consider a single USE statement as a USE block.

Lucas Arruda

[Paul Dragoonis]

On Mon, Aug 6, 2012 at 11:30 AM, Lucas Arruda <luna...@gmail.com> wrote:
> This example you gave us opened a question for me about whether is it fine to have multiple USE blocks altogether but separated by a new line feed, and also if we can consider a single USE statement as a USE block.

Imagine there's invisible braces around your use block.

"

namespace Foo;

{
use A;
use B;

use C;
}
class A

[Paul Dragoonis]

Hi Greg,

After some back an forth discussions we may have drifted slightly from
your original query, can you review the above comments and let us know
if you seek any further clarification on things.

Thanks.

[justin]

On Tue, Jul 31, 2012 at 8:47 PM, Greg Sherwood <gshe...@gmail.com> wrote:
> The PSR-2 standard says "There MUST be one blank line after the use block".

A more clear sentence might be: "There MUST be one blank line after
the last use statement."

--j

[Greg Sherwood]

Thanks Paul, very helpful.

So it looks like the rule I'm going to implement is: the last USE statement in a file must be followed by a single blank line.

This effectively ignores all other USE statements in the file, allowing code such as double blank lines between USE statements. Is this valid code?

1. use Something;

2. 

3. 

4. use SomethingElse;

5. use LastThing;

6. 

7. class Foo {

8. }

I think that's the last question I have. Thanks for all the help so far.

> php-fig+unsubscribe@googlegroups.com.

[Paul Dragoonis]

Yep, I agree with your logic, it'll work nicely.

Cheers.

>> > php-fig+u...@googlegroups.com.

>> > To view this discussion on the web visit
>> > https://groups.google.com/d/msg/php-fig/-/VwJTXISMykEJ.
>> >
>> > For more options, visit https://groups.google.com/groups/opt_out.
>> >
>> >
>

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to

> php-fig+u...@googlegroups.com.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-fig/-/TMwxAnHbGCkJ.

[Greg Sherwood]

Thanks again Paul.

>> > php-fig+unsubscribe@googlegroups.com.

>> > To view this discussion on the web visit
>> > https://groups.google.com/d/msg/php-fig/-/VwJTXISMykEJ.
>> >
>> > For more options, visit https://groups.google.com/groups/opt_out.
>> >
>> >
>
> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to

> php-fig+unsubscribe@googlegroups.com.

[Jason Judge]

Where would comments after the last use statement fit in this? Are they a part of the use-block, part of the main class block, an additional (optional) comment block, or completely illegal? It goes back to the original question of "what defines a use-block?", i.e. where does a user-block start and end.

-- Jason

[Paul Dragoonis]

You can put in comments where you like.

When all comments are stripped out then the blank line between the use block and the class keyword must still be there.

Emailing from HTC phone.

>> php-fig+u...@googlegroups.com.

>> To view this discussion on the web visit
>> https://groups.google.com/d/msg/php-fig/-/VwJTXISMykEJ.
>>
>> For more options, visit
>

> To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/6GV9N5f3N98J.

[Jason Judge]

Cool. So the code formatting rules apply after the comment-only lines are [conceptually] removed.

>> php-fig+unsubscribe@googlegroups.com.