[Proposal] Hypermedia Link PSR

[Larry Garfield]

Around the time of PSR-7 and a bit earlier, there was discussion of
handling Hypermedia Links. A small working group split off, led by
Evert Pot, to investigate the matter further. It was active for a while
but then died down, but by then had developed a good starting point for
a Link PSR.

To that end, I have put together a proposal for a Link PSR, based mostly
on Evert Pot's research from earlier this year. (Links in the meta
doc.) I would like to put it forward for consideration as a PSR, and
already have a Coordinator (MWOP) and Sponsor (Evert) lined up.
Unfortunately this would end up with me being editor of PSR-13 after
all, but, eh, whatcha gonna do.

PR:
https://github.com/php-fig/fig-standards/pull/683

More readable versions:

https://github.com/Crell/fig-standards/blob/psr-link/proposed/links.md
https://github.com/Crell/fig-standards/blob/psr-link/proposed/links-meta.md

Proof of concept implementation, as part of a larger library I built
recently:

https://github.com/Crell/HtmlModel

(Note the use of with*() pseudo-mutator interfaces as well. We really
ought to develop a better name for those things.)

My hope is that as it is a fairly small scope and most of the work has
already been done we can get it completed in relatively short order (by
FIG standards, anyway). There is an outstanding list of todo items in
the metadoc, which we'd work through during Draft phase.

Baring any major pushback, I would ask MWOP to start an entrance vote in
a week or two.

I now open the floor for comments, and jump out of the way of the trap
door. (The one that just opened in the floor, I mean.)

--Larry Garfield

[Alexander Makarov]

Looks good to me. I support it.

[Dracony]

The idea is nice, but maybe while you're at it you could port ome more HTML-like interfaces there? So it's not just the links alone ( it feels like it should be part of some HTML-context PSR idk)

[Gary Hockin]

It looks very very useful. I have a feeling that I'm missing something obvious, but is there any reason why the getHref method is returning a string, rather than a PSR-7 Url object?

G

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

[William Durand]

Hi!

I like it. That is the direction we took in Hateoas too: https://github.com/willdurand/Hateoas/blob/master/src/Hateoas/Model/Link.php.

--

William

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

[Larry Garfield]

Because the initial research was done before the PSR-7 URL object fully developed. :-)  As noted in the metadoc, one of the open questions we'd want to sort through in Draft is whether to use a PSR-7 URL object instead or not, and what the implications would be.  (At the moment I'm undecided.)

--Larry Garfield

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

[Larry Garfield]

Hypermedia Links apply to far more than just HTML.  The goal here is narrow; to standardize the handling of hypermedia links between HTML, HAL, JSON-LD, Atom, HTTP headers, and assorted others.  Evert's post linked from the metadoc goes into much more detail.

Modelling all of HTML is out of scope for the PSR.  However, if you check the HtmlModel library I link below that's exactly what I was doing. The goal there is to model HTML as a REST structure, with Links as well as the rest of the HEAD elements modelled.  I don't believe that needs to be a PSR, but I do believe it's a useful library (or else I wouldn't have written it).

--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/8ffb4de9-b01a-4a24-a711-229ea66461d4%40googlegroups.com.

[Gary Hockin]

Point noted, I'll read the meta before commenting in future :)

G

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

[Evert Pot]

On 2015-11-26 6:41 AM, Gary Hockin wrote:
> It looks very very useful. I have a feeling that I'm missing something
> obvious, but is there any reason why the getHref method is returning a
> string, rather than a PSR-7 Url object?

IMHO, The best type to pass a Url is around is a string. Not an unwieldy
URL object.

Evert

[Gary Hockin]

I don't agree, the Url interface has a __toString method so you can easily cast to string if you need to.

--
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/56574019.5080702%40gmail.com.

[will.g...@couchbase.com]

Hi,

This proposal looks really solid for what it sets out to do. However it does come across as a little abstract. Would I be correct in thinking that the proposals principle target would be for controller output, e.g. for serialising to JSON for a REST API and also serialising to HTML as an a/link tag?

Will

[Evert Pot]

The problem is that in a lot of cases urls start their life as as
string, and also end there.

Unless you're manipulating URLs, why force it in an object that parses
it out, generates a new string later from its components and takes up
significantly more memory.

It's a lot of extra work that in my opinion is better kept as an
'opt-in' thing. If you want to manipulate urls, use the URL object.

Evert

On 2015-11-26 12:25 PM, Gary Hockin wrote:
> I don't agree, the Url interface has a __toString method so you can
> easily cast to string if you need to.
>
> On Thu, 26 Nov 2015 at 17:23 Evert Pot <ever...@gmail.com
> <mailto:ever...@gmail.com>> wrote:
>
> On 2015-11-26 6:41 AM, Gary Hockin wrote:
> > It looks very very useful. I have a feeling that I'm missing something
> > obvious, but is there any reason why the getHref method is returning a
> > string, rather than a PSR-7 Url object?
>
> IMHO, The best type to pass a Url is around is a string. Not an unwieldy
> URL object.
>
> Evert
>
> --
> You received this message because you are subscribed to the Google
> Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to php-fig+u...@googlegroups.com

> <mailto:php-fig%2Bunsu...@googlegroups.com>.

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

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

> To view this discussion on the web visit
> https://groups.google.com/d/msgid/php-fig/56574019.5080702%40gmail.com.
> For more options, visit https://groups.google.com/d/optout.
>

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

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

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

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

> To view this discussion on the web visit

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

[Larry Garfield]

Yes, that's likely a main use case.  The use case I've been thinking of is "I've got this domain object with links on it, and I want to pull those off and stick them into my hypermedia representation object".  So for instance, you could populate a hypermedia representation like so:

$hal = new Hal(json_encode($order);
foreach ($order->getLinks() as $link) {
  $hal->addLink($link);
}

// Sometime later...

foreach ($hal->getLinks() as $link) {
  $response = $response->withLink($link);
}

And now you have all of the relevant links from your domain model exposed in both HAL and as HTTP Link headers; you could also pull just selected links out to add Link preload headers, which an HTTP2 connection can use to push dependent resources.  And if you're using Atom rather than HAL, nothing changes in the above code other than that first line.

--Larry Garfield

[Korvin Szanto]

I think this is great Larry.  +1 for string URL's for the reasons already stated.

--
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/5657525B.9040808%40garfieldtech.com.

[Matthew Weier O'Phinney]

On Thu, Nov 26, 2015 at 5:15 AM, Dracony <draco...@gmail.com> wrote:
> The idea is nice, but maybe while you're at it you could port ome more
> HTML-like interfaces there? So it's not just the links alone ( it feels like
> it should be part of some HTML-context PSR idk)

It's separate from HTML, because it's targeting *hypermedia*, of which
HTML is just one potential target. Hypermedia == linking, and the
necessity for this arose due to a need to represent links and link
relations for purposes of generating specifically links for API
payloads. A specification around HTML context could certainly leverage
this, but keeping it separate from HTML allows usage in far more
arenas.

> --
> 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/8ffb4de9-b01a-4a24-a711-229ea66461d4%40googlegroups.com.

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

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

[Evert Pot]

I am very excited about this. I'd even say I'm a bit optimistic that this might be a relatively pain-free proposal due to the fact it's a pretty simple one.
If anyone is interested in more detail, this why original research in figuring out how the interface should look like:

http://evertpot.com/whats-in-a-link/

Good luck Larry, and let me know if there's areas I can help with.

Cheers,
Evert

[Larry Garfield]

It seems no one is against the idea, so yay. :-) Matthew, I'm
comfortable with you opening an entrance vote for the current PR
whenever you're ready.

--Larry Garfield