Support for HAL 'templated' and 'title' link parameters

[bgaillard]

Hi, is it possible to generate the 'templated' and 'title' HAL link parameters with PhlyRestfully ?

Because we used an old version of PhlyRestfully we created our own implementation of the Link class.

I don't known if this functionality has been added in new PhlyRestfully versions... If not, here is the implementation of our Link class.

namespace Gomoob\PhlyRestfully;

/**
 * Custom HAL Link implementation which overwrites the <tt>PhlyRestfully\Link</tt> class. The purpose of this class is 
 * to be compliant with the HAL Specifications.
 * 
 * <p>To be compliant with the HAL Specifications a HAL Link should be able to contain the following attributes:</p>
 * <ul>
 *     <li>href      : For indicating the target URI. href corresponds with the ’Target IRI’ as defined in Web Linking 
 *                     (RFC 5988). This attribute MAY contain a URI Template (RFC6570) and in which case, SHOULD be 
 *                     complemented by an additional templated attribtue on the link with a boolean value true.</li>
 *     <li>rel       : For identifying how the target URI relates to the 'Subject Resource'. The Subject Resource is the 
 *                     closest parent Resource element. This attribute is not a requirement for the root element of a 
 *                     HAL representation, as it has an implicit default value of 'self'. rel corresponds with the 
 *                     'relation parameter' as defined in Web Linking (RFC 5988). rel attribute SHOULD be used for 
 *                     identifying Resource and Link elements in a HAL representation.</li>
 *     <li>name      : For distinguishing between Resource and Link elements that share the same rel value. The name 
 *                     attribute SHOULD NOT be used exclusively for identifying elements within a HAL representation, it 
 *                     is intended only as a ‘secondary key’ to a given rel value.</li>
 *     <li>hreflang  : For indicating what the language of the result of dereferencing the link should be.</li>
 *     <li>title     : For labeling the destination of a link with a human-readable identifier.</li>
 *     <li>templated : This attribute SHOULD be present with a boolean value of true when the href of the link contains 
 *                     a URI Template (RFC6570).</li>
 *      
 * </ul>
 * 
 * @author Baptiste GAILLARD (baptiste.gaillard@gomoob.com)
 * @see http://stateless.co/hal_specification.html
 * @see http://tools.ietf.org/html/rfc5988
 * @see http://tools.ietf.org/html/rfc6570
 */
class Link extends \PhlyRestfully\Link {

    /**
     * The 'templated' HAL Link attribute. 
     * 
     * <p>This attribute SHOULD be present with a boolean value of true when the href of the link contains a URI 
     *    Template (RFC6570).</p>
     * 
     * @var string
     */
    private $templated = null;

    /**
     * The 'title' HAL Link attribute.
     * 
     * <p>The title is used for labeling the destination of a link with a human-readable identifier.</p>
     * 
     * @var string
     */
    private $title = null;

    /**
     * Indicates is the HAL Link is templated. 
     * 
     * <p>This attribute SHOULD be present with a boolean value of true when the href of the link contains a URI 
     *    Template (RFC6570).</p>
     * 
     * @return string <code>true</tt> if the link is templated, <code>false</tt> otherwise.
     */
    public function isTemplated() {

        return $this -> templated;;

    }

    /**
     * Gets the 'title' HAL Link attribute.
     * 
     * <p>The title is used for labeling the destination of a link with a human-readable identifier.</p>
     * 
     * @return string the 'title' HAL Link attribute.
     */
    public function getTitle() {

        return $this -> title;

    }

    /**
     * Sets the 'templated' HAL Link attribute.
     * 
     * <p>This attribute SHOULD be present with a boolean value of true when the href of the link contains a URI 
     *    Template (RFC6570).</p>
     * 
     * @param unknown $templated the 'templated' HAL Link attribute to set.
     */
    public function setTemplated($templated) {

        $this -> templated = $templated;

    }

    /**
     * Sets the 'title' HAL Link attribute.
     * 
     * <p>The title is used for labeling the destination of a link with a human-readable identifier.</p>
     * 
     * @param unknown $title the 'title' HAL Link attribute to set.
     */
    public function setTitle($title) {

        $this -> title = $title;

    }

}

Besides the Link class we had to overwrite the HalLinks.fromLink method :

/**
     * Create a URL from a Link
     *
     * @param  Link $linkDefinition
     * @return string
     * @throws Exception\DomainException if Link is incomplete
     */
    protected function fromLink(\PhlyRestfully\Link $linkDefinition) {

        $linkArray = parent::fromLink($linkDefinition);

        // -- Decode %XX URL codes
        $linkArray['href'] = urldecode($linkArray['href']);

        // -- If the link definition corresponds to the GoMoob implementation we generate additionnal HAL link
        // -- attributes.
        if ($linkDefinition instanceof \Gomoob\PhlyRestfully\Link) {

            // -- If a 'title' attribute is provided we set it
            if ($linkDefinition -> getTitle() !== null) {

                $linkArray['title'] = $linkDefinition -> getTitle();

            }

            // -- If a 'templated' attribute is provided we set it
            if ($linkDefinition->isTemplated() !== null) {

                $linkArray['templated'] = $linkDefinition -> isTemplated();

            }

        }

        return $linkArray;

    }

I think the 'rel', 'name' and 'hreflang' parameters should be available also.

Hope this helps.

Baptiste