Psr naming and namespaces
165 views
Skip to first unread message
Oscar Otero
Jul 27, 2017, 8:35:23 AM7/27/17
to php...@googlegroups.com
Hello.
PSR-3
Title: Logger Interface
Namespace: Psr\Log
I’d like to share with everyone a discussion started in the slack channel, in order to get more feedback.
It’s related with the titles and namespaces used in each Psr, and how we could standarize this.
Currently, we have the following standards containing interfaces:
Title: Logger Interface
Namespace: Psr\Log
PSR-6
Title: Caching Interface
Namespace: Psr\Cache
PSR-7
Title: Http Message Interfaces
Namespace: Psr\Http\Message
PSR-11
Title: Container Interface
Namespace: Psr\Container
PSR-13
Title: Hipermedia Links
Namespace: Psr\Link
PSR-16
Title: Simple Cache
Namespace: Psr\SimpleCache
DRAFTS
PSR-8
Title: Huggable Interface
Namespace: Psr\Hug
PSR-14
Title: Event Manager
Namespace: Psr\EventManager
PSR-15
Title: HTTP Middlewares
Namespace: Psr\Http\ServerMiddleware
Http-interop namespace: Interop\Http\ServerMiddleware
PSR-17
Title: HTTP Factories
Namespace: Psr\Http\Message
Http-interop namespace: Interop\Http\Factory
As you can see, most packages have its own title and namespace, reflecting the purpose of the psr. I think this is good because it’s easy to remember.
The exceptions are the http related packages, that are placed inside the Psr\Http\ namespace (instead directly under Psr\). This can be good too, because http is a broad context encompassing many things, some dependent of others.
PSR-17 is special, because it’s using the same namespace of PSR-7, but in the Http-interop package uses the namespace Factory (I had not realized until now, writting this email). Which namespace will be choosen finally?
PSR-15 is another special case, because, the psr has splitted into two interfaces (Middleware and RequestHandler) and seems that there’s no any descriptive name which may cover these two interfaces. So Psr\Http\Server has been choosen. What will be the title of the namespace, now that is not only Middleware either Request Handler? “PSR-15: Request handler and middleware” or “PSR-15: Server side stuff”?
I see some problems with Psr\Http\Server, mainly:
- It indicates that the interfaces are for server-side operations, but does not indicate what operations, unlike in the rest of the psr packages.
- This forces that other server-side things (as for example, a possible psr for routing), must be placed inside Psr\Http\Server (for coherency), so we have Psr\Http\Server\Router, and so on.
- This makes that some psr that can affect to server side, but not exclusively, not use this namespace. For example, in psr-7 we have the ServerRequestInterface, that it’s not in Psr\Http\Server, and in psr-17 the ServerRequestFactoryInterface neither. So, finally we have server-side things outside of the server-side namespace.
IMHO, we should standardize this.
I think a namespace for each psr, as it was done before is good. If we create a standard for emails, Psr\Email. If we create other for databases: Psr\Database, etc. We could create also a namespace for a broad area, in order to group different Psr related with a specific context, like Http does. But not create a deep namespace structure forcing to place each future interface in different namespace, and avoid things like:
- Ok, we created a standard to handle http push notifications
- This interface allows to receive push notifications, so it could be placed in Psr\Http\Client
- Yeap, but we can send notifications too, so some interfaces should be placed in Psr\Http\Server
- Ok, let’s forget about this a create Psr\Http\PushNotifications\
So, for PSR-17, I suggest to use Psr\Http\Factory, (or MessageFactory) because it’s the title of the standard. If anyone want to use this psr, it knows what is the namespace to use.
For PSR-15, it’s more complicated, because after the latest change it contains two different interfaces, with different purposes. The best solution, IMHO, is create two PSR:
PSR-15: Http Middleware => Psr\Http\ServerMiddleware\
PSR-18: Http Request handler => Psr\Http\ServerRequestHandler\
Other solution suggested was use Psr\Http\ServerStrategy, in order to place here different strategies to handle http server requests, but the word “strategy" can be confused.
Having one namespace for each Psr, makes more easy to create new standards and avoid conflicts. This is specially interesting for the FIG, where new standards appear without an initial plan to structure and sort all these things. I guess this is why PSR are numbered incrementally (PSR-0, PSR-1, PSR-2, …)
If a new psr replaces other, it must use the same namespace. For example, a future PSR-34 can deprecate a PSR-7, so it use the same namespace (Psr\Http\Message).
This is my suggestion. There’re other guys who are disagree with this, so I like to share this in order to read other opinions.
Thank you!
Oscar Otero.
Matthew Weier O'Phinney
Jul 27, 2017, 4:12:27 PM7/27/17
to php...@googlegroups.com
Responses inline, below.
On Thu, Jul 27, 2017 at 7:35 AM, Oscar Otero <oscar...@gmail.com> wrote:
<snip>
In regards to this:
> PSR-17 is special, because it’s using the same namespace of PSR-7, but in
> the Http-interop package uses the namespace Factory (I had not realized
> until now, writting this email). Which namespace will be choosen finally?
and this:
> So, for PSR-17, I suggest to use Psr\Http\Factory, (or MessageFactory)
> because it’s the title of the standard. If anyone want to use this psr, it
> knows what is the namespace to use.
I disagree. The factories are specific to the HTTP message interfaces;
having them in the same namespace demonstrates that they are related.
Psr\Http\Factory is too generic (what _kind_ of factory? could we put
middleware factories in here, too?), but Psr\Http\MessageFactory means
that the types the factories are meant to produce are in a different
namespace entirely.
Regarding this:
> PSR-15 is another special case, because, the psr has splitted into two
> interfaces (Middleware and RequestHandler) and seems that there’s no any
> descriptive name which may cover these two interfaces. So Psr\Http\Server
> has been choosen. What will be the title of the namespace, now that is not
> only Middleware either Request Handler? “PSR-15: Request handler and
> middleware” or “PSR-15: Server side stuff”?
The proposed title is "HTTP Server Request Handlers", as the
`RequestHandler` and `Middleware` are both types of server-side
request handlers. Middleware is a specialized type of request handler
that allows delegation to another request handler.
> I see some problems with Psr\Http\Server, mainly:
>
> - It indicates that the interfaces are for server-side operations, but does
> not indicate what operations, unlike in the rest of the psr packages.
We could call the namespace `Psr\Http\ServerRequestHandler`, but I'm
not sure that being more verbose here helps; the name `Server` implies
server-side operations already, and, further, allows us to group other
server-side related interfaces under it later, similar to the
relationship between PSR-7 and PSR-17.
> - This forces that other server-side things (as for example, a possible psr
> for routing), must be placed inside Psr\Http\Server (for coherency), so we
> have Psr\Http\Server\Router, and so on.
Why is this a problem, exactly? Again, if they have related
functionality and/or overlapping domains, why would we not want to do
this?
> - This makes that some psr that can affect to server side, but not
> exclusively, not use this namespace. For example, in psr-7 we have the
> ServerRequestInterface, that it’s not in Psr\Http\Server, and in psr-17 the
> ServerRequestFactoryInterface neither. So, finally we have server-side
> things outside of the server-side namespace.
This last is a red herring to my mind. `ServerRequestInterface` is
still an HTTP message, and derives from and/or consumes other
interfaces in the same namespace. While it addresses server-side
needs, the fact of the matter is that its primary purpose is to
describe an HTTP message.
> IMHO, we should standardize this.
> I think a namespace for each psr, as it was done before is good. If we
> create a standard for emails, Psr\Email. If we create other for databases:
> Psr\Database, etc. We could create also a namespace for a broad area, in
> order to group different Psr related with a specific context, like Http
> does. But not create a deep namespace structure forcing to place each future
> interface in different namespace, and avoid things like:
> - Ok, we created a standard to handle http push notifications
> - This interface allows to receive push notifications, so it could be placed
> in Psr\Http\Client
> - Yeap, but we can send notifications too, so some interfaces should be
> placed in Psr\Http\Server
> - Ok, let’s forget about this a create Psr\Http\PushNotifications\
Why should we not group interfaces that have related domains in the
same namespace and/or in a subnamespace? What problem does this
create, exactly?
> For PSR-15, it’s more complicated, because after the latest change it
> contains two different interfaces, with different purposes. The best
> solution, IMHO, is create two PSR:
> PSR-15: Http Middleware => Psr\Http\ServerMiddleware\
> PSR-18: Http Request handler => Psr\Http\ServerRequestHandler\
This is not entirely true.
The proposal has had two interfaces for quite some time now.
The most recent change was because a number of contributors/commenters
noted that the proposed `DelegateInterface` had utility _by itself_.
This could be addressed by renaming it to indicate its semantic
purpose (`RequestHandlerInterface`), and updating the existing
`MiddlewareInterface` to use that interface.
The proposed `MiddlewareInterface` still requires its collaborator,
and still operates _exactly the same as it did before_.
Further, as I noted earlier, the two have a shared domain: handling
incoming `ServerRequestInterface` instances and returning
`ResponseInterface` instances. Having them under the same namespace
makes sense for that reason.
> Other solution suggested was use Psr\Http\ServerStrategy, in order to place
> here different strategies to handle http server requests, but the word
> “strategy" can be confused.
Exactly; strategy for doing... what?
We fell back to simply `Server` as these are interfaces used when
working with HTTP messages server-side. As noted above, we could
potentially get more specific (`ServerRequestHandler`), if there's
enough consensus that this is necessary.
> Having one namespace for each Psr, makes more easy to create new standards
> and avoid conflicts. This is specially interesting for the FIG, where new
> standards appear without an initial plan to structure and sort all these
> things. I guess this is why PSR are numbered incrementally (PSR-0, PSR-1,
> PSR-2, …)
Exactly; incremental numbers are used in part to allow later proposals
to replace earlier ones; this has been done already with PSR-4
succeeding PSR-0.
> If a new psr replaces other, it must use the same namespace. For example, a
> future PSR-34 can deprecate a PSR-7, so it use the same namespace
> (Psr\Http\Message).
This is already true, and does not pose a problem. Since existing
versions are not supposed to change, we can cut a new major release of
the related repository when a replacement occurs; developers then pin
to the major version representing the proposal they want to code
against.
The question I will raise again is: why do you feel a new PSR must
have a UNIQUE namespace (unless it supercedes a previous PSR), and not
allow subnamespaces?
You've vaguely mentioned potential for conflicts, but not a concrete
way in which a conflict might occur. Otherwise, it seems more like you
have problems with existing or proposed names, to which I will only
note that no name chosen for any specification will completely satisfy
everyone. (Naming being one of the chief problems in computer science
and whatnot.)
--
Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/
On Thu, Jul 27, 2017 at 7:35 AM, Oscar Otero <oscar...@gmail.com> wrote:
<snip>
In regards to this:
> PSR-17 is special, because it’s using the same namespace of PSR-7, but in
> the Http-interop package uses the namespace Factory (I had not realized
> until now, writting this email). Which namespace will be choosen finally?
> So, for PSR-17, I suggest to use Psr\Http\Factory, (or MessageFactory)
> because it’s the title of the standard. If anyone want to use this psr, it
> knows what is the namespace to use.
having them in the same namespace demonstrates that they are related.
Psr\Http\Factory is too generic (what _kind_ of factory? could we put
middleware factories in here, too?), but Psr\Http\MessageFactory means
that the types the factories are meant to produce are in a different
namespace entirely.
Regarding this:
> PSR-15 is another special case, because, the psr has splitted into two
> interfaces (Middleware and RequestHandler) and seems that there’s no any
> descriptive name which may cover these two interfaces. So Psr\Http\Server
> has been choosen. What will be the title of the namespace, now that is not
> only Middleware either Request Handler? “PSR-15: Request handler and
> middleware” or “PSR-15: Server side stuff”?
`RequestHandler` and `Middleware` are both types of server-side
request handlers. Middleware is a specialized type of request handler
that allows delegation to another request handler.
> I see some problems with Psr\Http\Server, mainly:
>
> - It indicates that the interfaces are for server-side operations, but does
> not indicate what operations, unlike in the rest of the psr packages.
not sure that being more verbose here helps; the name `Server` implies
server-side operations already, and, further, allows us to group other
server-side related interfaces under it later, similar to the
relationship between PSR-7 and PSR-17.
> - This forces that other server-side things (as for example, a possible psr
> for routing), must be placed inside Psr\Http\Server (for coherency), so we
> have Psr\Http\Server\Router, and so on.
functionality and/or overlapping domains, why would we not want to do
this?
> - This makes that some psr that can affect to server side, but not
> exclusively, not use this namespace. For example, in psr-7 we have the
> ServerRequestInterface, that it’s not in Psr\Http\Server, and in psr-17 the
> ServerRequestFactoryInterface neither. So, finally we have server-side
> things outside of the server-side namespace.
still an HTTP message, and derives from and/or consumes other
interfaces in the same namespace. While it addresses server-side
needs, the fact of the matter is that its primary purpose is to
describe an HTTP message.
> IMHO, we should standardize this.
> I think a namespace for each psr, as it was done before is good. If we
> create a standard for emails, Psr\Email. If we create other for databases:
> Psr\Database, etc. We could create also a namespace for a broad area, in
> order to group different Psr related with a specific context, like Http
> does. But not create a deep namespace structure forcing to place each future
> interface in different namespace, and avoid things like:
> - Ok, we created a standard to handle http push notifications
> - This interface allows to receive push notifications, so it could be placed
> in Psr\Http\Client
> - Yeap, but we can send notifications too, so some interfaces should be
> placed in Psr\Http\Server
> - Ok, let’s forget about this a create Psr\Http\PushNotifications\
same namespace and/or in a subnamespace? What problem does this
create, exactly?
> For PSR-15, it’s more complicated, because after the latest change it
> contains two different interfaces, with different purposes. The best
> solution, IMHO, is create two PSR:
> PSR-15: Http Middleware => Psr\Http\ServerMiddleware\
> PSR-18: Http Request handler => Psr\Http\ServerRequestHandler\
The proposal has had two interfaces for quite some time now.
The most recent change was because a number of contributors/commenters
noted that the proposed `DelegateInterface` had utility _by itself_.
This could be addressed by renaming it to indicate its semantic
purpose (`RequestHandlerInterface`), and updating the existing
`MiddlewareInterface` to use that interface.
The proposed `MiddlewareInterface` still requires its collaborator,
and still operates _exactly the same as it did before_.
Further, as I noted earlier, the two have a shared domain: handling
incoming `ServerRequestInterface` instances and returning
`ResponseInterface` instances. Having them under the same namespace
makes sense for that reason.
> Other solution suggested was use Psr\Http\ServerStrategy, in order to place
> here different strategies to handle http server requests, but the word
> “strategy" can be confused.
We fell back to simply `Server` as these are interfaces used when
working with HTTP messages server-side. As noted above, we could
potentially get more specific (`ServerRequestHandler`), if there's
enough consensus that this is necessary.
> Having one namespace for each Psr, makes more easy to create new standards
> and avoid conflicts. This is specially interesting for the FIG, where new
> standards appear without an initial plan to structure and sort all these
> things. I guess this is why PSR are numbered incrementally (PSR-0, PSR-1,
> PSR-2, …)
to replace earlier ones; this has been done already with PSR-4
succeeding PSR-0.
> If a new psr replaces other, it must use the same namespace. For example, a
> future PSR-34 can deprecate a PSR-7, so it use the same namespace
> (Psr\Http\Message).
versions are not supposed to change, we can cut a new major release of
the related repository when a replacement occurs; developers then pin
to the major version representing the proposal they want to code
against.
The question I will raise again is: why do you feel a new PSR must
have a UNIQUE namespace (unless it supercedes a previous PSR), and not
allow subnamespaces?
You've vaguely mentioned potential for conflicts, but not a concrete
way in which a conflict might occur. Otherwise, it seems more like you
have problems with existing or proposed names, to which I will only
note that no name chosen for any specification will completely satisfy
everyone. (Naming being one of the chief problems in computer science
and whatnot.)
--
Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/
Stefano Torresi
Jul 28, 2017, 4:04:13 AM7/28/17
to php...@googlegroups.com
As we discussed on slack, I have of the exact same views as Matthew on the issue.
Larry Garfield
Jul 28, 2017, 1:36:26 PM7/28/17
to php...@googlegroups.com
On 07/27/2017 07:35 AM, Oscar Otero wrote:
> Having one namespace for each Psr, makes more easy to create new
> standards and avoid conflicts. This is specially interesting for the
> FIG, where new standards appear without an initial plan to structure
> and sort all these things. I guess this is why PSR are numbered
> incrementally (PSR-0, PSR-1, PSR-2, …)
> If a new psr replaces other, it must use the same namespace. For
> example, a future PSR-34 can deprecate a PSR-7, so it use the same
> namespace (Psr\Http\Message).
>
> This is my suggestion. There’re other guys who are disagree with this,
> so I like to share this in order to read other opinions.
>
> Thank you!
> Oscar Otero.
Background: This was part of the reason behind Anthony Ferrara's
> Having one namespace for each Psr, makes more easy to create new
> standards and avoid conflicts. This is specially interesting for the
> FIG, where new standards appear without an initial plan to structure
> and sort all these things. I guess this is why PSR are numbered
> incrementally (PSR-0, PSR-1, PSR-2, …)
> If a new psr replaces other, it must use the same namespace. For
> example, a future PSR-34 can deprecate a PSR-7, so it use the same
> namespace (Psr\Http\Message).
>
> This is my suggestion. There’re other guys who are disagree with this,
> so I like to share this in order to read other opinions.
>
> Thank you!
> Oscar Otero.
proposal that we switch to numbering PSR namespaces rather than naming
them. So \Psr\Psr15 (or whatever) removes all ambiguity entirely,
except for having to look up which PSR 15 was. :-)
Also, just to make clear, the PHP runtime doesn't give a crap about the
namespaces we choose. This is entirely a human-consumption question.
(Which totally is important, sure, I'm just making it clear in case
anyone was confused.)
--Larry Garfield
Oscar Otero
Jul 28, 2017, 1:53:34 PM7/28/17
to php...@googlegroups.com
There’s no real conflict with Psr\Http\Server\ currently, and maybe never will. I don’t know. I’m just saying that, for example, if the psr for routing was created before, surely the namespace was something like Psr\Http\Router, but after the PSR-15, the namespace will be Psr\Http\Server\Router (or at least, this is what was suggested); of course, this is just an example, maybe we never have a psr for routing. But I see this a bit arbitrary, because we’re building a namespace structure on the fly. And future psr that affect to various aspect can be ambiguous and could be placed in different namespaces and all these namespaces was correct.
Psr\Http\Server\ is a good namespace for PSR-15, but it is good also for create a standard for servers like react-php (just an example). And this is the kind of conflicts which can occur.
Anyway, seems that these arguments are not good enough, so no problem, I’m not insist more. I really can live with this :)
Regards
Oscar Otero.
> --
> 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/CAJp_myUdwBWyu6U3pBgseW%2BgjV%2B0KqHzfnf6ctFxYjebNKdawA%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.
Psr\Http\Server\ is a good namespace for PSR-15, but it is good also for create a standard for servers like react-php (just an example). And this is the kind of conflicts which can occur.
Anyway, seems that these arguments are not good enough, so no problem, I’m not insist more. I really can live with this :)
Regards
Oscar Otero.
> 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/CAJp_myUdwBWyu6U3pBgseW%2BgjV%2B0KqHzfnf6ctFxYjebNKdawA%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.
Woody Gilk
Aug 1, 2017, 10:09:26 AM8/1/17
to PHP Framework Interoperability Group
I think your concerns are valid, Oscar. That said, I think trying to look into a crystal ball and guess what future needs are is a bit of a bike shed problem. I think of it as a "first come, first serve" problem, within reason.
There's nothing that prevents a future PSR from using an existing namespace. In fact, I was counting on PSR-17 sharing with PSR-7 for ease of use.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@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/CAJp_myUdwBWyu6U3pBgseW%2BgjV%2B0KqHzfnf6ctFxYjebNKdawA%40mail.gmail.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+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/ADCD0E27-D0DC-46EC-8C3B-A2C2F1801371%40gmail.com.
Reply all
Reply to author
Forward
0 new messages