PSR-4 Change request for clarification

[Steve Ward]

Should "within a "base directory"" be changed to "of the "base directory""

Hi All,

First up, apologies if this issue has already been raised.

Upon reading PSR-4: Autoloader, I found a statement that I think may benefit with a small change to clarify it's intent.

In Section 2.Specification, Subsection 3. When loading a file that corresponds to a fully qualified class name ...

Clause 2 states

"The contiguous sub-namespace names after the "namespace prefix" correspond to a subdirectory within a "base directory""

The problem I have experienced is with the use of "within a". Using the second example in section 3. Examples

FULLY QUALIFIED CLASS NAME: \Aura\Web\Response\Status
NAMESPACE PREFIX: Aura\Web
BASE DIRECTORY: /path/to/aura-web/src/
RESULTING FILE PATH: /path/to/aura-web/src/Response/Status.php

I would interpret "a subdirectory within a "base directory"" here to refer to either "/path/", "/to/", "/aura-web/" or "/src/" and not the subdirectory "/Response/", which appears to be the intention.

Personally I think clause 2 would become more clear if within a where changed to of the as follows

"The contiguous sub-namespace names after the "namespace prefix" correspond to a subdirectory of the "base directory""

Whilst I think I have eventually been able to work out the meaning from the examples, the current phrasing of clause 2 confused me originally requiring a few re-reads.

What does everyone think?

Has anyone else found the current phrasing confusing or is it adequate?

Would my suggestion make things better or worse?

Is there another phrasing that could be considered? 

Best Regards,
Steve Ward

[Vincent de Lau]

On Saturday, June 22, 2024 at 4:36:27 AM UTC+2 Steve Ward wrote:

Should "within a "base directory"" be changed to "of the "base directory""

Short answer: No.

Slightly less short answer: No, I don't see why this would be confusing.

 

Hi All,

First up, apologies if this issue has already been raised.

Upon reading PSR-4: Autoloader, I found a statement that I think may benefit with a small change to clarify it's intent.

In Section 2.Specification, Subsection 3. When loading a file that corresponds to a fully qualified class name ...

Clause 2 states

"The contiguous sub-namespace names after the "namespace prefix" correspond to a subdirectory within a "base directory""

The problem I have experienced is with the use of "within a". Using the second example in section 3. Examples

FULLY QUALIFIED CLASS NAME: \Aura\Web\Response\Status
NAMESPACE PREFIX: Aura\Web
BASE DIRECTORY: /path/to/aura-web/src/
RESULTING FILE PATH: /path/to/aura-web/src/Response/Status.php

I would interpret "a subdirectory within a "base directory"" here to refer to either "/path/", "/to/", "/aura-web/" or "/src/" and not the subdirectory "/Response/", which appears to be the intention.

For me, a these 'path elements' are not subdirectories. The parts you are mentioning are parent directories of the base. A subdirectory is further down the tree, away from root, relative to the current (base) directory.

 

Personally I think clause 2 would become more clear if within a where changed to of the as follows

"The contiguous sub-namespace names after the "namespace prefix" correspond to a subdirectory of the "base directory""

Whilst I think I have eventually been able to work out the meaning from the examples, the current phrasing of clause 2 confused me originally requiring a few re-reads.

 

I think the wording might be a bit convoluted to avoid specifying a direct subdirectory of the base directory, instead of potentially further subdirectories if there are multiple levels of namespaces left after removing the namespace prefix. There may also have been some relying of understanding of PSR-0, which is the starting point for this PSR. In PSR-0 all namespace separators are replaced with the directory separator.

What does everyone think?

Has anyone else found the current phrasing confusing or is it adequate?

Would my suggestion make things better or worse?

Is there another phrasing that could be considered?

It might have been nice to have some examples of this deeper namespace/directory structure behaviour in the PSR text itself. As far as I'm aware though, this has never led to issues, so I don't think it warrants an errata.

--

Vincent