在HTML上下文和各种API格式上下文中,超媒体链接正变得越来越重要。但是,没有单一的常见超媒体格式,也没有一种通用的方式来表示格式之间的链接。
该规范旨在为PHP开发人员提供一种简单,通用的方式来表示超媒体链接,而不依赖于所使用的序列化格式。这反过来允许系统将具有超媒体链接的响应序列化为一种或多种有线格式,而与决定这些链接应该是什么的过程无关。
本文档中的关键词“必须”,“必须”,“必需”,“应该”,“不应该”,“应该”,“不应该”,“推荐”,“可以”和“可选”按照RFC 2119中的描述进行解释。
1 规格
1.1 基本链接
超媒体链接至少包括:
- 表示正在引用的目标资源的URI。
- 定义目标资源与源相关的关系。
根据使用的格式,可能存在链接的各种其他属性。由于附加属性没有很好地标准化或通用,因此本规范并未寻求将它们标准化。
出于本说明书的目的,以下定义适用。
- 实现Object -An实现此规范定义的接口之一的对象。
- Serializer - 一个库或其他系统,它接受一个或多个Link对象并以某种定义的格式生成它的序列化表示。
1.2 属性
除URI和关系外,所有链接可以包含零个或多个附加属性。此处不允许使用正式的值注册表,值的有效性取决于上下文,通常取决于特定的序列化格式。常用的值包括'hreflang','title'和'type'。
如果需要通过序列化格式,序列化程序可以省略链接对象上的属性。但是,序列化程序应该尽可能编码所有提供的属性,以便允许用户扩展,除非序列化格式的定义阻止。
某些属性(通常是hreflang)可能在其上下文中出现不止一次。因此,属性值可以是值数组而不是简单值。 Serializers可以以适合序列化格式的任何格式(例如以空格分隔的列表,以逗号分隔的列表等)编码该数组。如果不允许给定属性在特定上下文中具有多个值,则序列化器必须使用提供的第一个值并忽略所有后续值。
如果属性值为布尔值true,则序列化程序可以使用缩写形式(如果适用)并由序列化格式支持。例如,当属性的存在具有布尔含义时,HTML允许属性没有值。当且仅当属性为布尔值true时才适用此规则,而不适用于PHP中的任何其他“truthy”值,例如整数1。
如果属性值是布尔值false,序列化程序应该完全省略该属性,除非这样做会改变结果的语义。当且仅当属性为布尔值false时才适用此规则,而不适用于PHP中的任何其他“falsey”值,例如整数0。
1.3 关系
链接关系定义为字符串,在公开定义的关系中是简单关键字,在私有关系的情况下是绝对URI。
如果使用简单的关键字,它应该与IANA注册表中的一个匹配:
http://www.iana.org/assignments/link-relations/link-relations.xhtml
可选地,可以使用microformats.org注册表,但这可能在每个上下文中都无效:
http://microformats.org/wiki/existing-rel-values
未在上述注册表之一或类似公共注册中心中定义的关系被视为“私有”,即特定于特定应用程序或用例。这种关系必须使用绝对URI。
1.4 链接模板
RFC 6570定义了URI模板的格式,即URI的模式,预期用客户端工具提供的值填充。一些超媒体格式支持模板化链接,而其他格式不支持,并且可能有一种特殊方式来表示链接是模板。用于不支持URI模板的格式的Serializer必须忽略它遇到的任何模板化链接。
![](/qrcode.jpg)
1.5 Evolvable提供者
在某些情况下,链接提供商可能需要能够添加其他链接。在其他情况下,链接提供程序必须是只读的,其中链接在运行时从某些其他数据源派生。因此,可修改的提供程序是可以选择实现的辅助接口。
此外,某些链接提供程序对象(如PSR-7响应对象)在设计上是不可变的。这意味着在原地添加链接的方法将是不兼容的。因此,EvolvableLinkProviderInterface的单个方法要求返回一个新对象,与原始对象相同但包含其他链接对象。
1.6 Evolvable链接对象
链接对象在大多数情况下是值对象。因此,允许它们以与PSR-7值对象相同的方式发展是一个有用的选择。因此,包含了一个额外的EvolvableLinkInterface,它提供了通过单个更改生成新对象实例的方法。 PSR-7使用相同的模型,并且由于PHP的写时复制行为,仍然是CPU和内存效率。
然而,对于模板化没有可进化的方法,因为链接的模板化值仅基于href值。它不能单独设置,而是根据href值是否为RFC 6570链接模板得出。
2.包装
所描述的接口和类是作为psr / link包的一部分提供的。