PSR-13-links
하이퍼 미디어 링크는 HTML 컨텍스트와 다양한 API 형식 컨텍스트에서 점점 더 중요한 웹의 일부가 되고 있습니다. 그러나 일반적인 하이퍼 미디어 형식은 하나도 없으며 형식 간 링크를 나타내는 일반적인 방법도 없습니다. 역자주: 완전히 표준화되지 못했다는 의미
이 스펙은 PHP 개발자에게 사용되는 직렬화 형식과는 별도로 하이퍼 미디어 링크를 표현하는 간단하고 일반적인 방법을 제공하는 것을 목표로 합니다. 그래서 시스템은 하이퍼 미디어 링크를 사용하여 하나 이상의 연결된 포맷으로 응답을 직렬화 할 수 있습니다.
이 문서에서 핵심이 되는 단어는 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL" 입니다. 이것은 [RFC 2119]에 설명 된대로 해석해야 합니다. 역자주: 위의 키워드는 아래의 번역문에 괄호안에 표시하였습니다

References

1. 명세서

하이퍼 미디어 링크는 최소한 다음으로 구성됩니다.
  • 참조되는 대상 자원을 나타내는 URI입니다.
  • 대상 자원과 관련된 소스의 관계를 정의합니다.
사용 된 형식에 따라 링크의 다양한 다른 속성이 존재할 수 있습니다. 추가 속성(additional attributes)은 표준화되거나 보편화되지 않았기 때문에 이 표준은 표준화하려고하지 않습니다.
이 명세서는 목정상 다음의 정의가 적용됩니다.
  • Implementing Object - 이 명세에 정의 된 인터페이스 중 하나를 구현하는 객체.
  • Serializer - 하나 이상의 Link 객체를 사용하고 정의 된 형식으로 직렬화 된 표현을 생성하는 라이브러리 또는 기타 시스템입니다.

1.2 Attributes

모든 링크는 URI와 관계를 넘어 0개 이상의 추가 속성을 포함 할 수있습니다(MAY). 여기에 허용되는 값의 정식 등록된 것이 없으며 값의 유효성은 컨텍스트 및 종종 특정 직렬화 형식에 따라 다릅니다. 일반적으로 지원되는 값에는 'hreflang', 'title'및 'type'이 포함됩니다.
직렬화 포맷에 의해 필요한 경우 링크 객체의 속성을 생략 할 수 있습니다(MAY). 그러나 serializers는 serialization 형식의 정의에 의해 방지되지 않는 한 사용자 확장을 허용하기 위해 가능한 모든 제공된 속성을 인코딩해야합니다 (SHOULD).
일부 속성 (일반적으로 hreflang)은 그들의 문맥에 두 번 이상 나타날 수 있습니다. 따라서 속성 값은 단순한 값이 아닌 값의 배열 일 수 있습니다(MAY). Serializers는 직렬화 된 형식 (공백으로 구분 된 목록, 쉼표로 구분 된 목록 등)에 적합한 형식으로 배열을 인코딩 할 수 있습니다 (MAY). 특정 속성이 특정 컨텍스트에서 다중 값을 가질 수 없는 경우, 직렬자는 제공된 첫 번째 값을 사용하고 모든 후속 값을 무시해야합니다 (MUST).
속성 값이 부울 true이면, serializers는 적절한 경우 축약형을 사용할 수 있고 직렬화 형식으로 지원할 수 있습니다 (MAY). 예를 들어, HTML은 속성의 존재가 부울 의미를 가질 때 속성이 값을 갖지 못하게합니다. 이 규칙은 속성이 부울 true인 경우에만 적용되며 정수 1과 같은 PHP의 "truthy"값은 적용되지 않습니다.
속성 값이 부울 false 인 경우, serializer는 속성의 의미를 변경하지 않는 한 속성을 완전히 생략해서는 안됩니다 (SHOULD). 이 규칙은 속성이 부울 false 인 경우에만 적용되며, 정수 0과 같은 PHP의 다른 "falsey"값에는 적용되지 않습니다.

1.3 Relationships

링크 관계는 문자열로 정의되며 공개적으로 정의 된 관계의 경우 간단한 키워드이고 비공개인 관계의 경우 절대 URI를 사용합니다.
간단한 키워드가 사용되는 경우 IANA 레지스트리의 키워드와 일치해야합니다(SHOULD).
선택적으로 microformats.org 레지스트리를 사용할 수도 있지만(MAY) 모든 컨텍스트에서 유효하지 않을 수 있습니다.
위의 레지스트리 중 하나 또는 이와 유사한 공개 레지스트리에 정의되지 않은 관계는 "비공개"으로 간주됩니다. 즉 특정 응용 프로그램 또는 유스 케이스에 한정됩니다. 그러한 관계는 반드시 절대 URI를 사용해야 합니다(MUST).

1.4 Link Templates

RFC 6570은 URI 템플릿의 형식, 즉 클라이언트에서 제공 한 값으로 채워질 것으로 예상되는 URI의 패턴을 정의합니다. 일부 하이퍼 미디어 형식은 템플릿 링크를 지원하지만 다른 링크는 템플릿이 아니라는 것을 나타내는 특별한 방법이 있을 수 있습니다. URI 템플릿을 지원하지 않는 형식의 Serializer는 템플릿 기반 링크가 발견되면 이를 무시해야 합니다 (MUST).

1.5 Evolvable providers

어떤 경우에는 링크 공급자가 추가 링크를 추가해야 할 수도 있습니다. 어떤 경우에는 링크 공급자가 반드시 읽기 전용이며 링크는 런타임시 다른 데이터 소스에서 파생됩니다. 이러한 이유로 수정 가능한 공급자는 선택적으로 구현 될 수 있는 보조 인터페이스입니다.
또한 PSR-7 응답 객체 같은 일부 링크 공급자 객체는 의도적으로 변경할 수 없습니다. 이것은 메소드를 해당 링크에 추가하는 방법은 맞지 않는 다는 것을 의미합니다 따라서 EvolvableLinkProviderInterface 의 단일 메소드는 원본과 동일하지만 추가 링크 객체가 포함 된 새로운 객체가 반환되어야 합니다.

1.6 Evolvable link objects

링크 오브젝트는 대부분의 경우 값 오브젝트입니다. 따라서 PSR-7 값 객체와 동일한 방식으로 처리하도록 하는 것이 좋은 방식입니다. 역자주: 원문은 evolve이지만 의역하였습니다 이러한 이유 때문에, 단일 변경으로 새 객체 인스턴스를 생성하는 메소드인 EvolvableLinkInterface가 추가적으로 제공됩니다. 같은 방식이 PSR-7에서 사용되었고, PHP의 copy-on-write 동작 덕분에 여전히 CPU와 메모리가 효율적입니다.
그러나 링크의 templated 된 값은 href 값에 기반하므로 templated 된 값에 대한 확장 가능한 방법은 없습니다. 역자주: evolvable지만 좀 더 좋은 단어를 찾지 못하였습니다 이것은 독립적으로 설정하면 안되지만(MUST NOT), href 값이 RFC 6570 링크 템플릿인지에 따라서 결정됩니다.

2. Package

설명 한 인터페이스와 클래스는 psr/link 패키지의 일부로 제공됩니다.

3. Interfaces

1
<?php
2
3
namespace Psr\Link;
4
5
/**
6
* A readable link object.
7
*/
8
interface LinkInterface
9
{
10
/**
11
* Returns the target of the link.
12
*
13
* The target link must be one of:
14
* - An absolute URI, as defined by RFC 5988.
15
* - A relative URI, as defined by RFC 5988. The base of the relative link
16
* is assumed to be known based on context by the client.
17
* - A URI template as defined by RFC 6570.
18
*
19
* If a URI template is returned, isTemplated() MUST return True.
20
*
21
* @return string
22
*/
23
public function getHref();
24
25
/**
26
* Returns whether or not this is a templated link.
27
*
28
* @return bool
29
* True if this link object is templated, False otherwise.
30
*/
31
public function isTemplated();
32
33
/**
34
* Returns the relationship type(s) of the link.
35
*
36
* This method returns 0 or more relationship types for a link, expressed
37
* as an array of strings.
38
*
39
* @return string[]
40
*/
41
public function getRels();
42
43
/**
44
* Returns a list of attributes that describe the target URI.
45
*
46
* @return array
47
* A key-value list of attributes, where the key is a string and the value
48
* is either a PHP primitive or an array of PHP strings. If no values are
49
* found an empty array MUST be returned.
50
*/
51
public function getAttributes();
52
}
Copied!
1
<?php
2
3
namespace Psr\Link;
4
5
/**
6
* An evolvable link value object.
7
*/
8
interface EvolvableLinkInterface extends LinkInterface
9
{
10
/**
11
* Returns an instance with the specified href.
12
*
13
* @param string $href
14
* The href value to include. It must be one of:
15
* - An absolute URI, as defined by RFC 5988.
16
* - A relative URI, as defined by RFC 5988. The base of the relative link
17
* is assumed to be known based on context by the client.
18
* - A URI template as defined by RFC 6570.
19
* - An object implementing __toString() that produces one of the above
20
* values.
21
*
22
* An implementing library SHOULD evaluate a passed object to a string
23
* immediately rather than waiting for it to be returned later.
24
*
25
* @return static
26
*/
27
public function withHref($href);
28
29
/**
30
* Returns an instance with the specified relationship included.
31
*
32
* If the specified rel is already present, this method MUST return
33
* normally without errors, but without adding the rel a second time.
34
*
35
* @param string $rel
36
* The relationship value to add.
37
* @return static
38
*/
39
public function withRel($rel);
40
41
/**
42
* Returns an instance with the specified relationship excluded.
43
*
44
* If the specified rel is already not present, this method MUST return
45
* normally without errors.
46
*
47
* @param string $rel
48
* The relationship value to exclude.
49
* @return static
50
*/
51
public function withoutRel($rel);
52
53
/**
54
* Returns an instance with the specified attribute added.
55
*
56
* If the specified attribute is already present, it will be overwritten
57
* with the new value.
58
*
59
* @param string $attribute
60
* The attribute to include.
61
* @param string $value
62
* The value of the attribute to set.
63
* @return static
64
*/
65
public function withAttribute($attribute, $value);
66
67
/**
68
* Returns an instance with the specified attribute excluded.
69
*
70
* If the specified attribute is not present, this method MUST return
71
* normally without errors.
72
*
73
* @param string $attribute
74
* The attribute to remove.
75
* @return static
76
*/
77
public function withoutAttribute($attribute);
78
}
Copied!
1
<?php
2
3
namespace Psr\Link;
4
5
/**
6
* A link provider object.
7
*/
8
interface LinkProviderInterface
9
{
10
/**
11
* Returns an iterable of LinkInterface objects.
12
*
13
* The iterable may be an array or any PHP \Traversable object. If no links
14
* are available, an empty array or \Traversable MUST be returned.
15
*
16
* @return LinkInterface[]|\Traversable
17
*/
18
public function getLinks();
19
20
/**
21
* Returns an iterable of LinkInterface objects that have a specific relationship.
22
*
23
* The iterable may be an array or any PHP \Traversable object. If no links
24
* with that relationship are available, an empty array or \Traversable MUST be returned.
25
*
26
* @return LinkInterface[]|\Traversable
27
*/
28
public function getLinksByRel($rel);
29
}
Copied!
1
<?php
2
3
namespace Psr\Link;
4
5
/**
6
* An evolvable link provider value object.
7
*/
8
interface EvolvableLinkProviderInterface extends LinkProviderInterface
9
{
10
/**
11
* Returns an instance with the specified link included.
12
*
13
* If the specified link is already present, this method MUST return normally
14
* without errors. The link is present if $link is === identical to a link
15
* object already in the collection.
16
*
17
* @param LinkInterface $link
18
* A link object that should be included in this collection.
19
* @return static
20
*/
21
public function withLink(LinkInterface $link);
22
23
/**
24
* Returns an instance with the specified link removed.
25
*
26
* If the specified link is not present, this method MUST return normally
27
* without errors. The link is present if $link is === identical to a link
28
* object already in the collection.
29
*
30
* @param LinkInterface $link
31
* The link to remove.
32
* @return static
33
*/
34
public function withoutLink(LinkInterface $link);
35
}
Copied!
Last modified 2yr ago