3. Interfaces
3.1 Psr\Link\LinkInterface
<?php
namespace Psr\Link;
/**
* A readable link object.
*/
interface LinkInterface
{
/**
* Returns the target of the link.
*
* The target link must be one of:
* - An absolute URI, as defined by RFC 5988.
* - A relative URI, as defined by RFC 5988. The base of the relative link
* is assumed to be known based on context by the client.
* - A URI template as defined by RFC 6570.
*
* If a URI template is returned, isTemplated() MUST return True.
*
* @return string
*/
public function getHref();
/**
* Returns whether or not this is a templated link.
*
* @return bool
* True if this link object is templated, False otherwise.
*/
public function isTemplated();
/**
* Returns the relationship type(s) of the link.
*
* This method returns 0 or more relationship types for a link, expressed
* as an array of strings.
*
* @return string[]
*/
public function getRels();
/**
* Returns a list of attributes that describe the target URI.
*
* @return array
* A key-value list of attributes, where the key is a string and the value
* is either a PHP primitive or an array of PHP strings. If no values are
* found an empty array MUST be returned.
*/
public function getAttributes();
}
3.2 Psr\Link\EvolvableLinkInterface
<?php
namespace Psr\Link;
/**
* An evolvable link value object.
*/
interface EvolvableLinkInterface extends LinkInterface
{
/**
* Returns an instance with the specified href.
*
* @param string $href
* The href value to include. It must be one of:
* - An absolute URI, as defined by RFC 5988.
* - A relative URI, as defined by RFC 5988. The base of the relative link
* is assumed to be known based on context by the client.
* - A URI template as defined by RFC 6570.
* - An object implementing __toString() that produces one of the above
* values.
*
* An implementing library SHOULD evaluate a passed object to a string
* immediately rather than waiting for it to be returned later.
*
* @return static
*/
public function withHref($href);
/**
* Returns an instance with the specified relationship included.
*
* If the specified rel is already present, this method MUST return
* normally without errors, but without adding the rel a second time.
*
* @param string $rel
* The relationship value to add.
* @return static
*/
public function withRel($rel);
/**
* Returns an instance with the specified relationship excluded.
*
* If the specified rel is already not present, this method MUST return
* normally without errors.
*
* @param string $rel
* The relationship value to exclude.
* @return static
*/
public function withoutRel($rel);
/**
* Returns an instance with the specified attribute added.
*
* If the specified attribute is already present, it will be overwritten
* with the new value.
*
* @param string $attribute
* The attribute to include.
* @param string $value
* The value of the attribute to set.
* @return static
*/
public function withAttribute($attribute, $value);
/**
* Returns an instance with the specified attribute excluded.
*
* If the specified attribute is not present, this method MUST return
* normally without errors.
*
* @param string $attribute
* The attribute to remove.
* @return static
*/
public function withoutAttribute($attribute);
}
3.3 Psr\Link\LinkProviderInterface
<?php
namespace Psr\Link;
/**
* A link provider object.
*/
interface LinkProviderInterface
{
/**
* Returns an iterable of LinkInterface objects.
*
* The iterable may be an array or any PHP \Traversable object. If no links
* are available, an empty array or \Traversable MUST be returned.
*
* @return LinkInterface[]|\Traversable
*/
public function getLinks();
/**
* Returns an iterable of LinkInterface objects that have a specific relationship.
*
* The iterable may be an array or any PHP \Traversable object. If no links
* with that relationship are available, an empty array or \Traversable MUST be returned.
*
* @return LinkInterface[]|\Traversable
*/
public function getLinksByRel($rel);
}
3.4 Psr\Link\EvolvableLinkProviderInterface
<?php
namespace Psr\Link;
/**
* An evolvable link provider value object.
*/
interface EvolvableLinkProviderInterface extends LinkProviderInterface
{
/**
* Returns an instance with the specified link included.
*
* If the specified link is already present, this method MUST return normally
* without errors. The link is present if $link is === identical to a link
* object already in the collection.
*
* @param LinkInterface $link
* A link object that should be included in this collection.
* @return static
*/
public function withLink(LinkInterface $link);
/**
* Returns an instance with the specifed link removed.
*
* If the specified link is not present, this method MUST return normally
* without errors. The link is present if $link is === identical to a link
* object already in the collection.
*
* @param LinkInterface $link
* The link to remove.
* @return static
*/
public function withoutLink(LinkInterface $link);
}