1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage Feed
5 *
6 * @copyright Copyright (C) 2005 - 2017 Open Source Matters, Inc. All rights reserved.
7 * @license GNU General Public License version 2 or later; see LICENSE
8 */
9
10 defined('JPATH_PLATFORM') or die;
11
12 /**
13 * Class to encapsulate a feed entry for the Joomla Platform.
14 *
15 * @property JFeedPerson $author Person responsible for feed entry content.
16 * @property array $categories Categories to which the feed entry belongs.
17 * @property string $content The content of the feed entry.
18 * @property array $contributors People who contributed to the feed entry content.
19 * @property string $copyright Information about rights, e.g. copyrights, held in and over the feed entry.
20 * @property array $links Links associated with the feed entry.
21 * @property JDate $publishedDate The publication date for the feed entry.
22 * @property JFeed $source The feed from which the entry is sourced.
23 * @property string $title A human readable title for the feed entry.
24 * @property JDate $updatedDate The last time the content of the feed entry changed.
25 * @property string $uri Universal, permanent identifier for the feed entry.
26 *
27 * @since 12.3
28 */
29 class JFeedEntry
30 {
31 /**
32 * @var array The entry properties.
33 * @since 12.3
34 */
35 protected $properties = array(
36 'uri' => '',
37 'title' => '',
38 'updatedDate' => '',
39 'content' => '',
40 'categories' => array(),
41 'contributors' => array(),
42 'links' => array(),
43 );
44
45 /**
46 * Magic method to return values for feed entry properties.
47 *
48 * @param string $name The name of the property.
49 *
50 * @return mixed
51 *
52 * @since 12.3
53 */
54 public function __get($name)
55 {
56 return (isset($this->properties[$name])) ? $this->properties[$name] : null;
57 }
58
59 /**
60 * Magic method to set values for feed properties.
61 *
62 * @param string $name The name of the property.
63 * @param mixed $value The value to set for the property.
64 *
65 * @return void
66 *
67 * @since 12.3
68 */
69 public function __set($name, $value)
70 {
71 // Ensure that setting a date always sets a JDate instance.
72 if ((($name == 'updatedDate') || ($name == 'publishedDate')) && !($value instanceof JDate))
73 {
74 $value = new JDate($value);
75 }
76
77 // Validate that any authors that are set are instances of JFeedPerson or null.
78 if (($name == 'author') && (!($value instanceof JFeedPerson) || ($value === null)))
79 {
80 throw new InvalidArgumentException('JFeedEntry "author" must be of type JFeedPerson. ' . gettype($value) . 'given.');
81 }
82
83 // Validate that any sources that are set are instances of JFeed or null.
84 if (($name == 'source') && (!($value instanceof JFeed) || ($value === null)))
85 {
86 throw new InvalidArgumentException('JFeedEntry "source" must be of type JFeed. ' . gettype($value) . 'given.');
87 }
88
89 // Disallow setting categories, contributors, or links directly.
90 if (($name == 'categories') || ($name == 'contributors') || ($name == 'links'))
91 {
92 throw new InvalidArgumentException('Cannot directly set JFeedEntry property "' . $name . '".');
93 }
94
95 $this->properties[$name] = $value;
96 }
97
98 /**
99 * Method to add a category to the feed entry object.
100 *
101 * @param string $name The name of the category to add.
102 * @param string $uri The optional URI for the category to add.
103 *
104 * @return JFeedEntry
105 *
106 * @since 12.3
107 */
108 public function addCategory($name, $uri = '')
109 {
110 $this->properties['categories'][$name] = $uri;
111
112 return $this;
113 }
114
115 /**
116 * Method to add a contributor to the feed entry object.
117 *
118 * @param string $name The full name of the person to add.
119 * @param string $email The email address of the person to add.
120 * @param string $uri The optional URI for the person to add.
121 * @param string $type The optional type of person to add.
122 *
123 * @return JFeedEntry
124 *
125 * @since 12.3
126 */
127 public function addContributor($name, $email, $uri = null, $type = null)
128 {
129 $contributor = new JFeedPerson($name, $email, $uri, $type);
130
131 // If the new contributor already exists then there is nothing to do, so just return.
132 foreach ($this->properties['contributors'] as $c)
133 {
134 if ($c == $contributor)
135 {
136 return $this;
137 }
138 }
139
140 // Add the new contributor.
141 $this->properties['contributors'][] = $contributor;
142
143 return $this;
144 }
145
146 /**
147 * Method to add a link to the feed entry object.
148 *
149 * @param JFeedLink $link The link object to add.
150 *
151 * @return JFeedEntry
152 *
153 * @since 12.3
154 */
155 public function addLink(JFeedLink $link)
156 {
157 // If the new link already exists then there is nothing to do, so just return.
158 foreach ($this->properties['links'] as $l)
159 {
160 if ($l == $link)
161 {
162 return $this;
163 }
164 }
165
166 // Add the new link.
167 $this->properties['links'][] = $link;
168
169 return $this;
170 }
171
172 /**
173 * Method to remove a category from the feed entry object.
174 *
175 * @param string $name The name of the category to remove.
176 *
177 * @return JFeedEntry
178 *
179 * @since 12.3
180 */
181 public function removeCategory($name)
182 {
183 unset($this->properties['categories'][$name]);
184
185 return $this;
186 }
187
188 /**
189 * Method to remove a contributor from the feed entry object.
190 *
191 * @param JFeedPerson $contributor The person object to remove.
192 *
193 * @return JFeedEntry
194 *
195 * @since 12.3
196 */
197 public function removeContributor(JFeedPerson $contributor)
198 {
199 // If the contributor exists remove it.
200 foreach ($this->properties['contributors'] as $k => $c)
201 {
202 if ($c == $contributor)
203 {
204 unset($this->properties['contributors'][$k]);
205 $this->properties['contributors'] = array_values($this->properties['contributors']);
206
207 return $this;
208 }
209 }
210
211 return $this;
212 }
213
214 /**
215 * Method to remove a link from the feed entry object.
216 *
217 * @param JFeedLink $link The link object to remove.
218 *
219 * @return JFeedEntry
220 *
221 * @since 12.3
222 */
223 public function removeLink(JFeedLink $link)
224 {
225 // If the link exists remove it.
226 foreach ($this->properties['links'] as $k => $l)
227 {
228 if ($l == $link)
229 {
230 unset($this->properties['links'][$k]);
231 $this->properties['links'] = array_values($this->properties['links']);
232
233 return $this;
234 }
235 }
236
237 return $this;
238 }
239
240 /**
241 * Shortcut method to set the author for the feed entry object.
242 *
243 * @param string $name The full name of the person to set.
244 * @param string $email The email address of the person to set.
245 * @param string $uri The optional URI for the person to set.
246 * @param string $type The optional type of person to set.
247 *
248 * @return JFeedEntry
249 *
250 * @since 12.3
251 */
252 public function setAuthor($name, $email, $uri = null, $type = null)
253 {
254 $author = new JFeedPerson($name, $email, $uri, $type);
255
256 $this->properties['author'] = $author;
257
258 return $this;
259 }
260 }
261