[REVIEW] PSR-13: Link definition interfaces

[Matthew Weier O'Phinney]

As coordinator of "PSR-13: Link definition interfaces", I hereby
officially place the proposal in Review status. Review will end no
earlier than 17:22 on 29 August 2016.

The specification may be found here:

- https://github.com/php-fig/fig-standards/blob/master/proposed/links.md

with a metadocument covering background and decisions here:

- https://github.com/php-fig/fig-standards/blob/master/proposed/links-meta.md

Please take some time to review the proposed standard.

As a reminder, during the review period, we may incorporate minor
changes, but no substantive changes. If you have a suggestion for a
substantive change, please open a thread to discuss it, so we can
determine whether we need to return to Draft status to address the
change, or whether we will choose to move forward.

Thanks in advance!

--
Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/

[Paul Jones]

> On Aug 15, 2016, at 12:22, Matthew Weier O'Phinney <mweiero...@gmail.com> wrote:
>
> Please take some time to review the proposed standard.

Are any member projects currently doing anything that resembles the proposal? If so, is there some copy of the research on those implementations?


--

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

[Matthew Weier O'Phinney]

On Mon, Aug 15, 2016 at 12:27 PM, Paul Jones <pmjo...@gmail.com> wrote:
>
>> On Aug 15, 2016, at 12:22, Matthew Weier O'Phinney <mweiero...@gmail.com> wrote:
>>
>> Please take some time to review the proposed standard.
>
> Are any member projects currently doing anything that resembles the proposal? If so, is there some copy of the research on those implementations?

Yes.

The original idea came from several of us who have worked on API
payloads, which often require or suggest relational links (think
HATEOAS), as well as utilities like DAV clients and servers (which are
essentially REST services). sabredav, from Evert Pot, was one of
these, as is zf-hal from the Apigility project; I suspect that Larry
was proposing it due to a need in Drupal, but I'll deer to him to
answer.

For the part of zf-hal, we already define Link and LinkCollection
instances that are not dissimilar to what is proposed here. With
shared interfaces, users could provide alternate implementations
within the entities they wish to expose via the API; Apigility would
simply need to introspect those to generate the payload.

--

Matthew Weier O'Phinney
mweiero...@gmail.com

https://mwop.net/

[Paul Jones]

> On Aug 15, 2016, at 13:34, Matthew Weier O'Phinney <mweiero...@gmail.com> wrote:
>
> On Mon, Aug 15, 2016 at 12:27 PM, Paul Jones <pmjo...@gmail.com> wrote:
>>
>>> On Aug 15, 2016, at 12:22, Matthew Weier O'Phinney <mweiero...@gmail.com> wrote:
>>>
>>> Please take some time to review the proposed standard.
>>
>> Are any member projects currently doing anything that resembles the proposal? If so, is there some copy of the research on those implementations?
>
> Yes.

...

> sabredav, from Evert Pot, was one of
> these, as is zf-hal from the Apigility project; I suspect that Larry
> was proposing it due to a need in Drupal, but I'll deer to him to
> answer.

Nice. I think it'd be useful to have links to (or descriptions of) those in the meta, so there's some easy-to-access historical information available.

[Paul Jones]

All,

On consideration, this strikes me as a perfect example of something that should be created as a *-interop project prior to being accepted. That will help "shake out" any problems revealed by real-world use, especially use by people not participating in the creation of the PSR.

[Larry Garfield]

On 09/01/2016 01:50 PM, Paul Jones wrote:
> All,
>
> On consideration, this strikes me as a perfect example of something that should be created as a *-interop project prior to being accepted. That will help "shake out" any problems revealed by real-world use, especially use by people not participating in the creation of the PSR.

On consideration, forcing it to be an "outside group" from FIG first
would add absolutely no value whatsoever to the process or the spec. It
being under the FIG name in no way prevents or discourages anyone from
"trying it out" if they wish, and the Review period (current status) is
exactly for further "try it out". FIG 3's Review period includes an
explicit requirement for it.

Paul, given your clear and stated desire to keep FIG limited to its 2009
definition (despite your own work on innovative specs) I really do not
know how to interpret your desire to "split the baby" by disbanding FIG
in practice if not in name. "You must work elsewhere first" (aka,
independent interop groups) as a policy is effectively the same thing as
just disbanding FIG outright.

Do you have any technical feedback on the spec itself?

--Larry Garfield

[Woody Gilk]

On Thu, Sep 1, 2016 at 2:14 PM, Larry Garfield <la...@garfieldtech.com> wrote:

It being under the FIG name in no way prevents or discourages anyone from "trying it out" if they wish, and the Review period (current status) is exactly for further "try it out".  FIG 3's Review period includes an explicit requirement for it.

Larry, I think Paul is referring the fact that a PSR document is not (and cannot) be published on Packagist to get a feel for real-world usage without every project copy/pasting the interfaces in and potentially getting out of sync.

I am in favor of PSRs being published on Packagist with 0.x versions before the PSR is ratified. We already see real benefits from this in http-interop.

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

[Larry Garfield]

As you note, there's nothing about an independent interop group that's necessary for pre-release packages on Packagist.  PSR-13 already has pre-release packages on Packagist:

https://packagist.org/packages/psr/link
https://packagist.org/packages/fig/link-util

We should be doing that more often, I agree.  There's nothing at all preventing FIG from doing so.

--Larry Garfield

[Michael Cullum]

As a general secretarial note, the minimum 2 week review period is now complete as of the 30th August and this can be put to a vote at any time from this point onwards.

--

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+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/62449748-94bb-1d0b-5aa5-d531540fe75b%40garfieldtech.com.

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

[Paul Jones]

Hi all,

> On Sep 4, 2016, at 10:57, Michael Cullum <m...@michaelcullum.com> wrote:
>
> As a general secretarial note, the minimum 2 week review period is now complete as of the 30th August and this can be put to a vote at any time from this point onwards.

As a general oversight-of-secretaries note, is it now the habit of secretaries to generate these kinds of reminders for all pre-vote discussions? There are a couple that have not received this treatment. Michael, if you're going to do this for one, you're going to need to do it for all (or for none) -- for the sake of consistency if nothing else.

[Lukas Kahwe Smith]

I do not see it as a secretary accountability to send such reminders. So if Michael chooses to send one is his prerogative on a case by case basis.

my 2 cents.

regards,
Lukas

[Paul Jones]

Hi Larry,

This is a *fascinating* response. Since you saw fit to bring up these other topics in this thread, I feel it's reasonable responding to them inline here, even though they may not all fit the nominal thread topic.

> On Sep 1, 2016, at 14:14, Larry Garfield <la...@garfieldtech.com> wrote:
>
> On 09/01/2016 01:50 PM, Paul Jones wrote:
>> All,
>>
>> On consideration, this strikes me as a perfect example of something that should be created as a *-interop project prior to being accepted. That will help "shake out" any problems revealed by real-world use, especially use by people not participating in the creation of the PSR.
>
> On consideration, forcing it to be an "outside group" from FIG first would add absolutely no value whatsoever to the process or the spec.

I disagree. It adds a great deal of value to the process *and* to the spec. It helps make sure the spec has some real-world use before it is finalized. It provides a "shake-out" period during which people not involved in the building of the spec can test the spec and find previously unexpected weaknesses. I opine, in hindsight, that PSR-6 and PSR-7 would have benefitted from such a trial.

> It being under the FIG name in no way prevents or discourages anyone from "trying it out" if they wish, and the Review period (current status) is exactly for further "try it out". FIG 3's Review period includes an explicit requirement for it.

The neat thing is that you can do it *right now* without waiting for FIG 3 (which may or may not pass). If it's valuable enough to do it in FIG 3, perhaps it's valuable enough to try it as a *-interop group. If it's not valuable enough to do it as a *-interop group, perhaps it does not fit in FIG 3.

> Paul, given your clear and stated desire to keep FIG limited to its 2009 definition

And you and Michael (and perhaps others) have a clear and stated desire to depart from its founding vision. (/me shrugs)

Anyway, "limited" is a funny word here. By way of analogy, one could say that "2+2" is "limited" to its original definition as "4".

No, instead of keeping the FIG "limited to" its founding vision, I would say keeping the FIG "loyal to" its founding vision (or perhaps "constant to"). Any changes to the FIG should be incremental perfections of that founding vision, not substantial departures as you wish to effect.

> (despite your own work on innovative specs)

I am flattered that you think (I presume) PSR-1, 2, and 4 are "innovative." 1 and 2 were essentially the results of research and collation across all the member projects, and 4 was more a refinement on 0 than an innovation.

This proposal, though, appears to have no pre-existing basis across a wide range of member projects, and would definitely benefit from seeing some real use before being categorized as a "standards recommendation."

> I really do not know how to interpret your desire to "split the baby" by disbanding FIG in practice if not in name.

I'm not sure what you find hard to interpret. You want to depart from the original mission to follow one of your own making; I, on the other hand, think perhaps that means the FIG's time is done. If it is *not* done, it should continue on its existing mission, rather be co-opted for other purposes.

> "You must work elsewhere first" (aka, independent interop groups) as a policy is effectively the same thing as just disbanding FIG outright.

That's an interesting insight; I wonder if it's true.

[Lukas Smith]

Top posting because I will not touch on every point but do want to make the context available if desired.

I found Paul's statement about doing it as an interop project valid, though instead of "should" I would have used "could" or "might benefit".

At the end of the day we indeed can do whatever we wish in terms of how to mature our proposals and I also find it entirely legitimate to propose approaches

For example for the security PSR I decided to create a new mailinglist.

Overall this discussion seems more like a power struggle over FIGs direction than a productive way to move PSR-13 forward. But not my call to make :)

regards,
Lukas

> --
> 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/28D3F822-47D5-4CAE-BA4B-2965041414EB%40gmail.com.

[Andreas Heigl]

I have two things I'd like to mention regarding PSR-13:

First, for me personally it makes less sense to have a LinkCollectionInterface that doesn't act like I'D expect a Collection to work. For me a collection is a set of similar items I can then iterate over. Whether that's a collection of links, headers, or teapots doesn't matter. So I'd expect an object implementing a CollectionInterface to be iterable and to already contain the items in question. The current implementation of the LinkCollectionInterface though looks more like a CollectorInterface. Something that collects linkInterfaces and can return a LinkCollectionInterface. I know it's only a slight difference in wording, but for me it would make a difference in understanding what happens.

Second, I'm not so happy with the way the relation and the link are bound together in the LinkInterface. For me it makes more sense to have a single relation to a given resource. As is explicitly outlined in the meta-document to the PSR it's perfectly valid to use the linkInterface in such a way I was asking myself whether it wouldn't enhance ease of usage and implementation to remove allowing multiple relations in a LinkInterface. It would remove two methods from the EvolvableLinkInterface and therefore ease implementations. 

That's just my 0.02 €

Cheers

Andreas

[Matthew Weier O'Phinney]

On Mon, Sep 12, 2016 at 1:04 AM, Andreas Heigl <and...@heigl.org> wrote:
> I have two things I'd like to mention regarding PSR-13:
>
> First, for me personally it makes less sense to have a
> LinkCollectionInterface that doesn't act like I'D expect a Collection to
> work. For me a collection is a set of similar items I can then iterate over.
> Whether that's a collection of links, headers, or teapots doesn't matter. So
> I'd expect an object implementing a CollectionInterface to be iterable and
> to already contain the items in question. The current implementation of the
> LinkCollectionInterface though looks more like a CollectorInterface.
> Something that collects linkInterfaces and can return a
> LinkCollectionInterface. I know it's only a slight difference in wording,
> but for me it would make a difference in understanding what happens.

Thanks for this feedback! Until recently, I didn't typically think of
collections as requiring iteration, but considering that the
terminology has definitely been moving in that direction the last few
years (google for "first-class collection", and you'll see fairly
consistent definitions!), it may make sense to change the name. I'll
discuss with Larry today.

> Second, I'm not so happy with the way the relation and the link are bound
> together in the LinkInterface. For me it makes more sense to have a single
> relation to a given resource. As is explicitly outlined in the meta-document
> to the PSR it's perfectly valid to use the linkInterface in such a way I was
> asking myself whether it wouldn't enhance ease of usage and implementation
> to remove allowing multiple relations in a LinkInterface. It would remove
> two methods from the EvolvableLinkInterface and therefore ease
> implementations.

The idea behind the proposal is to provide interfaces that work with
known, existing systems. While many (most?) have a 1:1 relationship
between a link and its relation, there *are* several, of which the
HTML spec itself is the most important! (The spec indicates that any
`rel` attribute can be a "space-separated list" of relationships!).
So, while 1:1 would be easiest to model, it would effectively make it
impossible to do multi-relationships, which are defined by one of our
key specification targets.

Thanks for the feedback, and we'll post soon regarding the decision
about the collection interface; if we decide to change it, we'll start
a new review period.

> Am Montag, 15. August 2016 19:22:20 UTC+2 schrieb Matthew Weier O'Phinney:
>>
>> As coordinator of "PSR-13: Link definition interfaces", I hereby
>> officially place the proposal in Review status. Review will end no
>> earlier than 17:22 on 29 August 2016.
>>
>> The specification may be found here:
>>
>> - https://github.com/php-fig/fig-standards/blob/master/proposed/links.md
>>
>> with a metadocument covering background and decisions here:
>>
>> -
>> https://github.com/php-fig/fig-standards/blob/master/proposed/links-meta.md
>>
>> Please take some time to review the proposed standard.
>>
>> As a reminder, during the review period, we may incorporate minor
>> changes, but no substantive changes. If you have a suggestion for a
>> substantive change, please open a thread to discuss it, so we can
>> determine whether we need to return to Draft status to address the
>> change, or whether we will choose to move forward.
>>
>> Thanks in advance!
>>
>> --
>> Matthew Weier O'Phinney
>> mweiero...@gmail.com
>> https://mwop.net/
>

> --
> 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/c0ba8212-74f9-409f-9735-2d8130a0ce16%40googlegroups.com.

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

[Larry Garfield]

On 09/12/2016 09:40 AM, Matthew Weier O'Phinney wrote:
> On Mon, Sep 12, 2016 at 1:04 AM, Andreas Heigl <and...@heigl.org> wrote:
>> I have two things I'd like to mention regarding PSR-13:
>>
>> First, for me personally it makes less sense to have a
>> LinkCollectionInterface that doesn't act like I'D expect a Collection to
>> work. For me a collection is a set of similar items I can then iterate over.
>> Whether that's a collection of links, headers, or teapots doesn't matter. So
>> I'd expect an object implementing a CollectionInterface to be iterable and
>> to already contain the items in question. The current implementation of the
>> LinkCollectionInterface though looks more like a CollectorInterface.
>> Something that collects linkInterfaces and can return a
>> LinkCollectionInterface. I know it's only a slight difference in wording,
>> but for me it would make a difference in understanding what happens.
> Thanks for this feedback! Until recently, I didn't typically think of
> collections as requiring iteration, but considering that the
> terminology has definitely been moving in that direction the last few
> years (google for "first-class collection", and you'll see fairly
> consistent definitions!), it may make sense to change the name. I'll
> discuss with Larry today.

Matthew and I brainstormed a bit more. The only other word we could
come up with that we didn't hate even more than "Collection" was
"Catalog". Which would then result in:

class Whatever implements LinkCatalogInterface {

}

How do people feel about that? Is it more/less descriptive than
Collection? More/less pompous sounding? :-) A few seconds of Googling
didn't find any existing CS definition of "catalog" that would conflict
with it, FWIW.

We went over the name before and Collection was the best we came up
with. So I think it's Collection or Catalog at the end of the day.

--Larry Garfield

[Daniel Hunsaker]

>> I'd expect an object implementing a CollectionInterface to be iterable and
>> to already contain the items in question. The current implementation of the
>> LinkCollectionInterface though looks more like a CollectorInterface.
>> Something that collects linkInterfaces and can return a
>> LinkCollectionInterface.

Matthew and I brainstormed a bit more.  The only other word we could
come up with that we didn't hate even more than "Collection" was
"Catalog".  Which would then result in:

Not against Catalog, personally.  However, Andreas did mention Collector as an alternate; is that one of the more-hated designators that were considered?  That wasn't clear from the above paragraph... 

[Matthew Weier O'Phinney]

I was hesitant about it, as it implies that the instance is collecting instances for purposes of returning a collection, which brings us back to the original naming issue.

[Josh Di Fabio]

Quoting the meta doc.

> Why is a LinkCollectionInterface needed?
> In many contexts, a set of links will be attached to some other object. Those objects may be used in situations where all that is relevant is their links, or some subset of their links. For example, various different value objects may be defined that represent different REST formats such as HAL, JSON-LD, or Atom.

In my opinion, "some other object" should not be defined by this spec. What use is an interface for an object which simply "has a collection of links"? What if that object has multiple accessors for different kinds of links? I don't see any value in this spec attempting to define what such objects should look like, so I'd be interested to see a concrete example of why it is useful (apologies if I missed this in the meta doc).

I would propose either removing the collection interface or making it a true and useful collection object instead of what we have now. Here's a suggestion:

interface LinkCollectionInterface extends \IteratorAggregate

{
    public function getIterator(): Iterator;

    public function filterByRel($rel): LinkCollectionInterface;
}

It would seem better to then replace these interfaces with concrete implementations, since they are clearly fairly simple value objects, but from what I can remember it's in your bylaws only to define interfaces.

--
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_myUZ4XH6mG4pNnXfGKavnAhdxN6fMocVngpxmNT6TLi8yA%40mail.gmail.com.

[Larry Garfield]

The standard example we've been using is a domain object of some sort that then is getting rendered to an HTTP Response.  To wit:

$article = load_article(...);
// Article is a class in a domain model, but can generate links to other articles such as next/prev, up to the index of articles, etc.
// ...
// LinkableResponse is an implementation of PSR-7 ResponseInterface and LinkCollectionInterface
$r = new LinkableResponse(200);

// Whatever app-sensitive rendering logic applies, not our problem.
$r = $r->withBody(new StringStream(render($article));

// The links on article are generated on the fly here,
// based off of the underlying data of article, whatever that is.
foreach ($article->getLinks() as $link) {
  $r = $r->withLink($link);
}

Forcing both Article and Response to be traversable on links is a no-go, as they may have other data sets in them that would make just as much sense to iterate.  But it makes total sense for Article to be able to provide links (read only) and Response to both accept them and be able to return them (or turn them into HTTP headers directly, or whatever else someone feels like doing).  Neither Response nor Article are PSR-13-specific concretions.

--Larry Garfield

On 09/13/2016 08:18 AM, Josh Di Fabio wrote:

[Matthew Weier O'Phinney]

On Tue, Sep 13, 2016 at 8:18 AM, Josh Di Fabio <joshd...@gmail.com> wrote:
> Quoting the meta doc.
>
>> Why is a LinkCollectionInterface needed?
>> In many contexts, a set of links will be attached to some other object.
>> Those objects may be used in situations where all that is relevant is their
>> links, or some subset of their links. For example, various different value
>> objects may be defined that represent different REST formats such as HAL,
>> JSON-LD, or Atom.
>
> In my opinion, "some other object" should not be defined by this spec. What
> use is an interface for an object which simply "has a collection of links"?
> What if that object has multiple accessors for different kinds of links? I
> don't see any value in this spec attempting to define what such objects
> should look like, so I'd be interested to see a concrete example of why it
> is useful (apologies if I missed this in the meta doc).

When creating API payloads that conform to HAL, JSON-LD, Atom, and
other formats, you will typically have one of two situations:

- A value object representing the resource, with a set of relational
links to represent.
- A set of relational links to represent *only*.

This latter is often useful for dashboards or meta-endpoints, as they
allow the consumer then to decide what relations are useful, and then
to follow those links to fetch more data.

We're not defining what these value objects look like; we are only
defining what a collection of links, and what those individual links
look like.

With regards to the "collection" interface, it is essentially only
present to aggregate the link relations *relevant to the resource they
relate to*.

> I would propose either removing the collection interface or making it a true
> and useful collection object instead of what we have now. Here's a
> suggestion:
>
> interface LinkCollectionInterface extends \IteratorAggregate
> {
> public function getIterator(): Iterator;
>
> public function filterByRel($rel): LinkCollectionInterface;
> }
>
> It would seem better to then replace these interfaces with concrete
> implementations, since they are clearly fairly simple value objects, but
> from what I can remember it's in your bylaws only to define interfaces.

Indeed.

Thanks for the feedback; your suggestion for changes to the
LinkCollectionInterface may also address the concerns from Andreas;
I'll discuss with Larry later today.

> https://groups.google.com/d/msgid/php-fig/CAKiSzdCW4WjxP9RrOKD4yXsj%2B0FAbH_xQOTjdGE%2BiBDU0N0iEQ%40mail.gmail.com.

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

--

Matthew Weier O'Phinney
mweiero...@gmail.com

https://mwop.net/

[Josh Di Fabio]

On Tue, Sep 13, 2016 at 2:50 PM Larry Garfield <la...@garfieldtech.com> wrote:

The standard example we've been using is a domain object of some sort that then is getting rendered to an HTTP Response.  To wit: 

 

Thanks for taking the time to reply.

 

$article = load_article(...);
// Article is a class in a domain model, but can generate links to other articles such as next/prev, up to the index of articles, etc.
// ...
// LinkableResponse is an implementation of PSR-7 ResponseInterface and LinkCollectionInterface
$r = new LinkableResponse(200);

// Whatever app-sensitive rendering logic applies, not our problem.
$r = $r->withBody(new StringStream(render($article));

// The links on article are generated on the fly here,
// based off of the underlying data of article, whatever that is.
foreach ($article->getLinks() as $link) {
  $r = $r->withLink($link);
}

Forcing both Article and Response to be traversable on links is a no-go, as they may have other data sets in them that would make just as much sense to iterate.  But it makes total sense for Article to be able to provide links (read only) and Response to both accept them and be able to return them (or turn them into HTTP headers directly, or whatever else someone feels like doing).  Neither Response nor Article are PSR-13-specific concretions.

I don't think I've made myself clear. My contention is that LinkableResponse is not *a collection of links*, rather, it *has* a collection of links. It should not implement LinkCollectionInterface at all. Does this make sense? I fully appreciate that you and Matthew are smart guys who understand that interfaces are analogous to *is a* and not *has a* semantics, but I feel that this spec is currently overcomplicating things a bit.

My suggestion would be that LinkableResponse does not itself implement any interface from this spec, since this spec doesn't attempt to define response objects. Nor does it attempt to define (HTTP) resource objects or objects from any other domain. Consider, for example, a domain object with different types of links; this object might provide methods such as *getPublicLinks*, *getPrivateLinks*, *getJsonHalLinks* , etc. Or consider a case where links are loaded from a repository or some other kind of service object, where there is no domain object which those links are attached to. You can't create an interface which fits all of these different use cases. Instead, LinkableResponse, and other objects which are outside the scope of this spec, can *provide* a collection of links using whatever accessor or property makes sense to them.

For example:

class LinkableResponse
{
    public function getLinks(): LinkCollectionInterface { }
}

interface LinkCollectionInterface implements \IteratorAggregate
{

    public function getIterator(): Iterator

    public function filterByRel($rel): LinkCollectionInterface;

    public function merge(LinkCollectionInterface $collection): LinkCollectionInterface;

    public function withLink(LinkInterface $link): LinkCollectionInterface
}

--Larry Garfield

On 09/13/2016 08:18 AM, Josh Di Fabio wrote:

Quoting the meta doc.

> Why is a LinkCollectionInterface needed?
> In many contexts, a set of links will be attached to some other object. Those objects may be used in situations where all that is relevant is their links, or some subset of their links. For example, various different value objects may be defined that represent different REST formats such as HAL, JSON-LD, or Atom.

In my opinion, "some other object" should not be defined by this spec. What use is an interface for an object which simply "has a collection of links"? What if that object has multiple accessors for different kinds of links? I don't see any value in this spec attempting to define what such objects should look like, so I'd be interested to see a concrete example of why it is useful (apologies if I missed this in the meta doc).

I would propose either removing the collection interface or making it a true and useful collection object instead of what we have now. Here's a suggestion:

interface LinkCollectionInterface extends \IteratorAggregate

{
    public function getIterator(): Iterator;

    public function filterByRel($rel): LinkCollectionInterface;
}

It would seem better to then replace these interfaces with concrete implementations, since they are clearly fairly simple value objects, but from what I can remember it's in your bylaws only to define interfaces.

On Mon, Sep 12, 2016 at 11:52 PM Matthew Weier O'Phinney <mweiero...@gmail.com> wrote:

On Sep 12, 2016 5:31 PM, "Daniel Hunsaker" <danhu...@gmail.com> wrote:
>>
>> >> I'd expect an object implementing a CollectionInterface to be iterable and
>> >> to already contain the items in question. The current implementation of the
>> >> LinkCollectionInterface though looks more like a CollectorInterface.
>> >> Something that collects linkInterfaces and can return a
>> >> LinkCollectionInterface.
>>
>>
>> Matthew and I brainstormed a bit more.  The only other word we could
>> come up with that we didn't hate even more than "Collection" was
>> "Catalog".  Which would then result in:
>
>
> Not against Catalog, personally.  However, Andreas did mention Collector as an alternate; is that one of the more-hated designators that were considered?  That wasn't clear from the above paragraph... 

I was hesitant about it, as it implies that the instance is collecting instances for purposes of returning a collection, which brings us back to the original naming issue.

--
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/1f87a36c-35e2-5129-88a7-a5193dc2c27b%40garfieldtech.com.

[Larry Garfield]

On 09/13/2016 09:28 AM, Josh Di Fabio wrote:

On Tue, Sep 13, 2016 at 2:50 PM Larry Garfield <la...@garfieldtech.com> wrote:

The standard example we've been using is a domain object of some sort that then is getting rendered to an HTTP Response.  To wit: 

 

Thanks for taking the time to reply.

 

$article = load_article(...);
// Article is a class in a domain model, but can generate links to other articles such as next/prev, up to the index of articles, etc.
// ...
// LinkableResponse is an implementation of PSR-7 ResponseInterface and LinkCollectionInterface
$r = new LinkableResponse(200);

// Whatever app-sensitive rendering logic applies, not our problem.
$r = $r->withBody(new StringStream(render($article));

// The links on article are generated on the fly here,
// based off of the underlying data of article, whatever that is.
foreach ($article->getLinks() as $link) {
  $r = $r->withLink($link);
}

Forcing both Article and Response to be traversable on links is a no-go, as they may have other data sets in them that would make just as much sense to iterate.  But it makes total sense for Article to be able to provide links (read only) and Response to both accept them and be able to return them (or turn them into HTTP headers directly, or whatever else someone feels like doing).  Neither Response nor Article are PSR-13-specific concretions.

I don't think I've made myself clear. My contention is that LinkableResponse is not *a collection of links*, rather, it *has* a collection of links. It should not implement LinkCollectionInterface at all. Does this make sense? I fully appreciate that you and Matthew are smart guys who understand that interfaces are analogous to *is a* and not *has a* semantics, but I feel that this spec is currently overcomplicating things a bit.

It sounds like this is another case of naming things (one of the 2 hard problems in CS).  There's a proposal on the table to change it to "Catalog":

https://groups.google.com/d/msg/php-fig/D-qAsZ5_f0s/PrKQL7RzAgAJ

Thoughts there?  (As in, over in that thread.)

The problem with excluding the the ThisObjectHasLinksOnItInterface (whatever it's named) is that it's then impossible to reliably do the transfer I mentioned earlier.  In a multi-stage DDD system (Drupal, or some ADR-esque systems) there could be multiple levels of object transformation in which you want to carry the links along.  Eg, in the example above, you'd wrap the foreach ($article->links ...) in an interface check; that way you can pass any object to a function containing that code and it will transfer links if possible.  That's only doable if you have a ThisObjectHasLinksOnItInterface, which is why we included it.

getLinks() returns an iterable (array|Traversable, technically), so you could filter that however you want; you could even build it with a generator if you were so inclined.

--Larry Garfield

[Josh Di Fabio]

First of all, Larry, thanks for taking the time to reply. Thanks also to Matthew for replying yesterday; I felt my response to Larry was sufficient to cover both emails which is why I haven't quoted you directly.

> It sounds like this is another case of naming things (one of the 2 hard problems in CS).  There's a proposal on the table to change it to "Catalog":

>
> https://groups.google.com/d/msg/php-fig/D-qAsZ5_f0s/PrKQL7RzAgAJ
>
> Thoughts there?  (As in, over in that thread.)

(On a side note, that link takes me to this current thread, which does contain messages about renaming the LinkCollectionInterface to LinkCatalogInterface and is the same one I've been replying to all along. I'm not sure if Gmail is screwing around or if one of us is missing something.)

My contention isn't with the name of the interface, I'm simply arguing that providing an interface for *any object which has links* isn't very helpful (although a proper LinkCollection object might be).

I think it might be helpful to take a step back and project our solution to a problem from a different domain. I think that you, Matthew and I all agree that a Link is a simple value object. A classic example of another type of value object is a quantity of money. Let's imagine we are creating a Money PSR instead of a Link PSR. Consider the following interface, which I believe would be fairly analogous to what you are proposing with the LinkCollectionInterface (semantically ThisObjectHasLinksOnItInterface):

interface HasMoney

{

    public function getMoney(): Money;

}

What use would this interface be? When would we realistically create a polymorphic function to consume such an object? Rather, the way an object would expose any money objects it referenced would depend on what those objects represented in the specific domain of the object itself. For example:

interface SaleableProduct

{

    public function getSalePrice(): Money;

    public function getCostPrice(): Money;

}

Similarly, I think that the way links will be exposed by objects will depend on the domain and context of the object. For example:

interface Author
{

    public function getName(): string;

    public function getPublicLinks(): LinkCollection;

    public function getLinksForUser(string $userId): LinkCollection;

}

I appreciate the example of (HTTP) Resources having links. Defining an interface to allow polymorphic functions which consume HTTP resource objects specifically would make sense, but that isn't what is being proposed here. Regarding your earlier example; there do not appear to be any polymorphic functions and, therefore, nothing which justifies a ThisObjectHasLinksOnItInterface. If you are only dealing with a specific concretion then you have no need to know which abstract interfaces the object implements. I suspect it would be helpful to identify a real-world example of a polymorphic function which would make use of this interface but not require some other domain-specific interface (such as an HttpResourceInterface).

I feel like I've asked all the questions I can. You guys are the stakeholders here and are also more likely than I am to make use of this PSR, so I think I'll leave you to it. I hope my questions have been helpful even if you do decide that the current approach is the right one!

Cheers

--
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/0e9c9b93-880b-a705-69d4-bd7746eddf94%40garfieldtech.com.

[Andreas Heigl]

Hi All

I'm always trying to find analogies in the real word for things I want to name. 

For me a catalog is a set of things I am able to get from someone providing that catalog. It never contains actual concrete objects only references to them. The only thing they need to have in common is that they can be obtained from the same source. And I'm usually not ordering everything the catalog has to offer, just a small subset. Trying to match that to the Links I'm stumbling very soon. 

A Collection on the other hand is a set of concrete objects that someone has gathered. And they all have something in common. They are either stamps or teapots or beermats or whatever that someone has gathered. But they are all of the same kind. And the person gathering these items can without problem gather different items. Like a person can collect postcards as well as guitars. Ask that person to show you the postcard-collection (besides from being a happier person) they won't show you a single guitar.

So taking that analogy to the links, it's possible to have an object containing links as well as headers. It's a Collector of links *and* headers. To know whether you can get links from the object you'll need a way to tell whether that object collects them. That could be a LinkCollectorInterface that defines a method *getLinkCollection*. Know when I have a concrete implementation of an Object I can check whether it's a LinkCollector and if so I know that I can ask for a LinkCollection. And that LinkCollection can be anything from a complex iterable LinkCollectionObject implementing a LinkCollectionInterface to an array of LinkInterface-implementing objects. The main think is that I get something back that contains LinkInterfaces. 

So I would opt for renaming the LinkCollectionInterface to LinkCollectorInterface and would refrain from calling it a Cataloge.

But that's just my 0,02€

Cheers

Andreas

--Larry Garfield

[Marc Alexander]

Hi,

I do not think that calling it "collector" does serve it right. A collector is something that collects and therefore creates a collection. I don't see this applying to the LinkCollectionInterface. A collection however is a group of object which do not necessarily need to be of the same type.

I would recommend to stay with calling it a collection as that describes its purpose pretty well.

-- Marc

[Larry Garfield]

As there doesn't seem to be a clear consensus amongst those who have posted so far, Matthew and I decided to just put it to a poll.

This poll is open to everyone, but we are particularly looking for voting reps to give feedback.  It should take less than 60 seconds to do, so please spare a minute to give feedback:

https://goo.gl/forms/fR0VcqhOfMO2mPQ12

I'll leave it open for a week or so (probably a little more since 1 week will be during DrupalCon) and we'll see where we stand before making a final decision.

--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/9472b271-fbe9-439f-8a38-17023bd53aa2%40googlegroups.com.

[Stefano Torresi]

As far as I can tell, the problem is that currently the so called LinkCollectionInterface describes two methods which, as per docblocks, "return a collection".
So we have something called collection which in turn returns collections; not ideal.

Calling it "Catalog" doesn't cut it, in my opinion, because the ambiguity remains: "catalog" can easily be interpreted as a synonym of "collection".
"Collector" doesn't cut it either, because I would expect it to provide some kind of command (i.e. "collect()"), not queries.

Now I'm not big on naming, but something like LinksProvider or LinkCollectionProvider would probably communicate the intent more accurately.

Then again, the presence of EvolevableLinkCollectionInterface makes it even more unclear whether or not we're talking about something that is-a collection or has-a collection.

I understand the need for this interfaces, but the current naming is confusing.
I don't know better, I'll let you folks brainstorm on this.

Cheers.

[Larry Garfield]

Matthew and I discussed this a bit. LinksProviderInterface is the first
suggestion that for lack of a less emotionally-based term "clicks", and
doesn't become even more confusing. We're tempted to add that to the
poll and restart it. :-) (I saw you posted it there, too.) As you
note, though, EvolvableLinkProviderInterface would be a bit odd.
Thoughts from others?

Really, the core issue is that the object in question contains links,
and MAY allow you to add more to them, but ALSO contains other stuff
that isn't links. So it is a collection of links, but doesn't have the
exclusivity that "collection" has come to have. (Viz, it's not a fancy
OOP array of links.) That's really the problem; the name "collection"
would have likely been fine 3 years ago, but these days we expect more
of that word but have no word to replace its previous, more limited
meaning. :-/

--Larry Garfield

[Chuck Burgess]

I suppose "container" is too loaded a term...  as is "sixpack" :-D

I'm cool with collection, as a "collection of collections" is no more odd to me than an array of arrays.
CRB

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/9472b271-fbe9-439f-8a38-17023bd53aa2%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+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/875a9f23-e4cd-bce4-a404-30f3c570558d%40garfieldtech.com.

[Andreas Heigl]

Hi All.

Am 22.09.16 um 21:00 schrieb Larry Garfield:

> On 09/21/2016 08:57 PM, Stefano Torresi wrote:
>> As far as I can tell, the problem is that currently the so called

[...]

>
> Matthew and I discussed this a bit. LinksProviderInterface is the first
> suggestion that for lack of a less emotionally-based term "clicks", and
> doesn't become even more confusing. We're tempted to add that to the
> poll and restart it. :-) (I saw you posted it there, too.) As you
> note, though, EvolvableLinkProviderInterface would be a bit odd.
> Thoughts from others?
>
> Really, the core issue is that the object in question contains links,
> and MAY allow you to add more to them, but ALSO contains other stuff
> that isn't links. So it is a collection of links, but doesn't have the
> exclusivity that "collection" has come to have. (Viz, it's not a fancy
> OOP array of links.) That's really the problem; the name "collection"
> would have likely been fine 3 years ago, but these days we expect more
> of that word but have no word to replace its previous, more limited
> meaning. :-/

For me the core issue is that - even though the object contains links
(is a LinkContainer so to say) - it also contains other things. And for
me a Collection implies that it contains *only* items of a certain kind.
So for me it's more that the object *contains a collection of links*.
And as such it provides access to links so a LinksProviderInterface
would work for me. I'd prefer a LinksCollectionProviderInterface but
that's getting a bit ridiculous :)

Especially when we come to the EvolvableLinksCollectionProviderInterface…

A LinksContainerInterface would be another option but hey…

My 0,02 €

Cheers

Andreas
--
,,,
(o o)
+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl |
| mailto:and...@heigl.org N 50°22'59.5" E 08°23'58" |
| http://andreas.heigl.org http://hei.gl/wiFKy7 |
+---------------------------------------------------------------------+
| http://hei.gl/root-ca |
+---------------------------------------------------------------------+

[Larry Garfield]

Following up here...

The poll[1] ended with a very clear consensus against Catalog or Collector.  About 7 of the 11 respondants were fine with LinkCollectionInterface.  The other 4 all proposed still more new nouns. :-)  So Catalog and Collector are officially off the table.

As noted above, the only additional suggestion that resonated at all was Provider, vis, [Evolvable]LinkProviderInterface.  I'm still lukewarm on it, but Matthew is increasingly of the mind that Collection is going to cause confusion down the line.

Anyone else want to weigh in before we make a final call?  If left unanswered we'll probably end up with Provider, baring any further feedback here.

--Larry Garfield

[1] https://docs.google.com/forms/d/1EU_ETFgcDgFDJRbB8aoAwjYIYq8a-QwgwtxK0lWrsuE/edit#responses

[Larry Garfield]

Here's the set of PRs that will rename collection to provider:

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

(And linked from there for the code repos.)

If merged, that will reset the 2 week Review period, which is likely to
be the last of it and we'll then call the vote. Matthew, on you to merge.

Note: This is your last chance to bikeshed the name of this interface!
After we make a call here I will snarl in annoyance if anyone brings up
the name again. :-)

--Larry Garfield

[Krzysiek Piasecki]

Hello,

ListCollectionInterface - It's rather filtering data interface so it could be replace with LinkFilterInterface.

Collection and Provider are too abstract names for this small and simple interface. Filter it's a common word and will fit to the collection and provider implementations.

Krzysiek Piasecki

[Larry Garfield]

No, filter implies that it's an object whose purpose is to take an input
set and return a smaller output set. That's not at all what
LinkCollection/LinkProvider is for. It's to indicate an object which
carries and contains links, but potentially other stuff as well. That
there is a method to extract only a subset of those links is just a
convenience routine.

--Larry Garfield

[Krzysiek Piasecki]

On Saturday, 15 October 2016 19:20:11 UTC+2, Larry Garfield wrote:

On 10/15/2016 12:35 AM, Krzysiek Piasecki wrote:

No, filter implies that it's an object whose purpose is to take an input
set and return a smaller output set.

That's not at all what
LinkCollection/LinkProvider is for.  It's to indicate an object which
carries and contains links, but potentially other stuff as well.  

Although the function of this interface is just filtering (there is a direct predicate on link 'rel' attribute and hidden predicate that item is strictly a link) i consider after your response that a proposed name LinkProviderInterface correctly describes the functions of the interface and is the most transparent.


Respectfully
--
Krzysiek Piasecki

[Larry Garfield]

The MRs in question have been merged, and the spec updated.

This change necessitates resetting the review period, so technically
it's pushed back to me as editor, I merged the changes above, and now
hand it back to MWOP. Baring no other issues the vote for PSR-13 may
start as early as 31 October. (Which would be the absolute perfect time
to start the vote for PSR-13!)

--Larry Garfield

[Niklas Keller]

I guess I'm too late. Is there any reason to use the abbreviated `getRels()` and `withRel()`, but the long form for attributes (`getAttributes()`)? Feels inconsistent. I'd prefer `getRelation()` as well.

Regards, Niklas

On Monday, August 15, 2016 at 7:22:20 PM UTC+2, Matthew Weier O'Phinney wrote:

As coordinator of "PSR-13: Link definition interfaces", I hereby
officially place the proposal in Review status. Review will end no
earlier than 17:22 on 29 August 2016.

The specification may be found here:

- https://github.com/php-fig/fig-standards/blob/master/proposed/links.md

with a metadocument covering background and decisions here:

- https://github.com/php-fig/fig-standards/blob/master/proposed/links-meta.md

Please take some time to review the proposed standard.

As a reminder, during the review period, we may incorporate minor
changes, but no substantive changes. If you have a suggestion for a
substantive change, please open a thread to discuss it, so we can
determine whether we need to return to Draft status to address the
change, or whether we will choose to move forward.

Thanks in advance!

--

Matthew Weier O'Phinney
mweiero...@gmail.com

https://mwop.net/

[Matthew Weier O'Phinney]

On Nov 1, 2016 2:51 AM, "Niklas Keller" <nicks.po...@gmail.com> wrote:
>
> I guess I'm too late. Is there any reason to use the abbreviated `getRels()` and `withRel()`, but the long form for attributes (`getAttributes()`)? Feels inconsistent. I'd prefer `getRelation()` as well.

Yes, and it was asked previously: both HTML and several JSON specifications use the shortened form "rel". This spec mirrors those.

> On Monday, August 15, 2016 at 7:22:20 PM UTC+2, Matthew Weier O'Phinney wrote:
>>
>> As coordinator of "PSR-13: Link definition interfaces", I hereby
>> officially place the proposal in Review status. Review will end no
>> earlier than 17:22 on 29 August 2016.
>>
>> The specification may be found here:
>>
>> - https://github.com/php-fig/fig-standards/blob/master/proposed/links.md
>>
>> with a metadocument covering background and decisions here:
>>
>> - https://github.com/php-fig/fig-standards/blob/master/proposed/links-meta.md
>>
>> Please take some time to review the proposed standard.
>>
>> As a reminder, during the review period, we may incorporate minor
>> changes, but no substantive changes. If you have a suggestion for a
>> substantive change, please open a thread to discuss it, so we can
>> determine whether we need to return to Draft status to address the
>> change, or whether we will choose to move forward.
>>
>> Thanks in advance!
>>
>> --
>> Matthew Weier O'Phinney
>> mweiero...@gmail.com
>> https://mwop.net/
>

> --
> 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/bb9283a5-331e-41d7-af82-fcb56353664c%40googlegroups.com.