Make addLink accessor public

[jkrzefski]

When customizing the links of a document it is rather challenging to have the addLink method not publicly available. This PR fixes that.

[kocsismate]

Hi @jkrzefski ,

Could you please precise me what kind of customizations you would like to achieve?

The AbstractLinks::addLink() method is intentionally hidden from the outside, because this way, only spec-compliant links can be added to documents/resources/relationships/errors (documents are an exception though because the DocumentLinks::setLinks() can be abused to pass non standard-compliant links).

If you really want to add unsupported link relations to let's say resources, then you can do the following:

• extend ResourceLinks
• define your custom methods in the new class which make it possible to pass custom links
• instantiate and return the new class in your resource's getLinks() method

I don't know if this workflow suits your needs, but generally, this should be the way to go.

[jkrzefski]

Yes, that was exactly my case. I wanted to extend the ResourceLinks and I found no public method to do it. So I did exactly what you suggested (extend the class) and then filed this PR to make extending links easier. To be honest, I was unaware of the fact that the links you can use are also part of the specification.

But still, having this accessor public does not mean, your library is incompatible with the specification. It only makes it a more versatile utility for people who (for whatever reason) have to use custom links. So I can still see this being useful somehow.

Or maybe you know a better (more compliant) way to add custom links to a resource. In my case the resource was a file and I added a link download for an instant download.

[kocsismate]

OK, I understand your point, it makes sense to make adding custom links easier.

However, the addLink() method is not good for this purpose. It doesn't return anything (not suitable for chaining method calls) and it's name is also not the best.

So instead of making addLink() public, what about moving these methods from DocumentLinks to the AbstractLinks class?

/**
     * @param Link[] $links
     */
    public function setLinks(array $links): DocumentLinks
    {
        foreach ($links as $rel => $link) {
            $this->addLink($rel, $link);
        }

        return $this;
    }

    public function setLink(string $name, ?Link $link): DocumentLinks
    {
        $this->addLink($name, $link);

        return $this;
    }

Of course, the return type declarations should be removed, and replaced with a @return static type hint. Could you please do it?

[jkrzefski]

I undid my accessor change and added your suggested change instead. I did one thing slightly different though: I used the return type self in the methods instead of a type hint for static. Do you think, it works this way? If not, I will change it to type hints for static, of course.

[kocsismate]

@jkrzefski Thanks for the change! I think the static PHPDoc type hint would be better (even if it's not a proper type declaration), because that way, PHPStorm (or maybe other IDEs too) will be able to type hint against the appropriate subclass of AbstractLinks.

[jkrzefski]

Done.

[kocsismate]

Perfect, thanks for your work! I'll create a release with this change in the coming days (possibly today or tomorrow).