1 <?php
2 /**
3 * @package FrameworkOnFramework
4 * @subpackage hal
5 * @copyright Copyright (C) 2010-2016 Nicholas K. Dionysopoulos / Akeeba Ltd. All rights reserved.
6 * @license GNU General Public License version 2 or later; see LICENSE.txt
7 */
8 defined('FOF_INCLUDED') or die;
9
10 /**
11 * Implementation of the Hypertext Application Language links in PHP. This is
12 * actually a collection of links.
13 *
14 * @package FrameworkOnFramework
15 * @since 2.1
16 */
17 class FOFHalLinks
18 {
19 /**
20 * The collection of links, sorted by relation
21 *
22 * @var array
23 */
24 private $_links = array();
25
26 /**
27 * Add a single link to the links collection
28 *
29 * @param string $rel The relation of the link to the document. See RFC 5988
30 * http://tools.ietf.org/html/rfc5988#section-6.2.2 A document
31 * MUST always have a "self" link.
32 * @param FOFHalLink $link The actual link object
33 * @param boolean $overwrite When false and a link of $rel relation exists, an array of
34 * links is created. Otherwise the existing link is overwriten
35 * with the new one
36 *
37 * @return boolean True if the link was added to the collection
38 */
39 public function addLink($rel, FOFHalLink $link, $overwrite = true)
40 {
41 if (!$link->check())
42 {
43 return false;
44 }
45
46 if (!array_key_exists($rel, $this->_links) || $overwrite)
47 {
48 $this->_links[$rel] = $link;
49 }
50 elseif (array_key_exists($rel, $this->_links) && !$overwrite)
51 {
52 if (!is_array($this->_links[$rel]))
53 {
54 $this->_links[$rel] = array($this->_links[$rel]);
55 }
56
57 $this->_links[$rel][] = $link;
58 }
59 else
60 {
61 return false;
62 }
63 }
64
65 /**
66 * Add multiple links to the links collection
67 *
68 * @param string $rel The relation of the links to the document. See RFC 5988.
69 * @param array $links An array of FOFHalLink objects
70 * @param boolean $overwrite When false and a link of $rel relation exists, an array
71 * of links is created. Otherwise the existing link is
72 * overwriten with the new one
73 *
74 * @return boolean True if the link was added to the collection
75 */
76 public function addLinks($rel, array $links, $overwrite = true)
77 {
78 if (empty($links))
79 {
80 return false;
81 }
82
83 $localOverwrite = $overwrite;
84
85 foreach ($links as $link)
86 {
87 if ($link instanceof FOFHalLink)
88 {
89 $this->addLink($rel, $link, $localOverwrite);
90 }
91
92 // After the first time we call this with overwrite on we have to
93 // turn it off so that the other links are added to the set instead
94 // of overwriting the first item that's already added.
95 if ($localOverwrite)
96 {
97 $localOverwrite = false;
98 }
99 }
100 }
101
102 /**
103 * Returns the collection of links
104 *
105 * @param string $rel Optional; the relation to return the links for
106 *
107 * @return array|FOFHalLink
108 */
109 public function getLinks($rel = null)
110 {
111 if (empty($rel))
112 {
113 return $this->_links;
114 }
115 elseif (isset($this->_links[$rel]))
116 {
117 return $this->_links[$rel];
118 }
119 else
120 {
121 return array();
122 }
123 }
124 }
125