1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage Twitter
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 * Twitter API Direct Messages class for the Joomla Platform.
14 *
15 * @since 12.3
16 * @deprecated 4.0 Use the `joomla/twitter` package via Composer instead
17 */
18 class JTwitterDirectmessages extends JTwitterObject
19 {
20 /**
21 * Method to get the most recent direct messages sent to the authenticating user.
22 *
23 * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
24 * @param integer $max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
25 * @param integer $count Specifies the number of direct messages to try and retrieve, up to a maximum of 200.
26 * @param boolean $entities When set to true, each tweet will include a node called "entities,". This node offers a variety of metadata
27 * about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
28 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
29 *
30 * @return array The decoded JSON response
31 *
32 * @since 12.3
33 */
34 public function getDirectMessages($since_id = 0, $max_id = 0, $count = 20, $entities = null, $skip_status = null)
35 {
36 // Check the rate limit for remaining hits
37 $this->checkRateLimit('direct_messages');
38
39 // Set the API path
40 $path = '/direct_messages.json';
41
42 // Check if since_id is specified.
43 if ($since_id)
44 {
45 $data['since_id'] = $since_id;
46 }
47
48 // Check if max_id is specified.
49 if ($max_id)
50 {
51 $data['max_id'] = $max_id;
52 }
53
54 // Check if count is specified.
55 if ($count)
56 {
57 $data['count'] = $count;
58 }
59
60 // Check if entities is specified.
61 if (!is_null($entities))
62 {
63 $data['include_entities'] = $entities;
64 }
65
66 // Check if skip_status is specified.
67 if (!is_null($skip_status))
68 {
69 $data['skip_status'] = $skip_status;
70 }
71
72 // Send the request.
73 return $this->sendRequest($path, 'GET', $data);
74 }
75
76 /**
77 * Method to get the most recent direct messages sent by the authenticating user.
78 *
79 * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
80 * @param integer $max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
81 * @param integer $count Specifies the number of direct messages to try and retrieve, up to a maximum of 200.
82 * @param integer $page Specifies the page of results to retrieve.
83 * @param boolean $entities When set to true, each tweet will include a node called "entities,". This node offers a variety of metadata
84 * about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
85 *
86 * @return array The decoded JSON response
87 *
88 * @since 12.3
89 */
90 public function getSentDirectMessages($since_id = 0, $max_id = 0, $count = 20, $page = 0, $entities = null)
91 {
92 // Check the rate limit for remaining hits
93 $this->checkRateLimit('direct_messages', 'sent');
94
95 // Set the API path
96 $path = '/direct_messages/sent.json';
97
98 // Check if since_id is specified.
99 if ($since_id)
100 {
101 $data['since_id'] = $since_id;
102 }
103
104 // Check if max_id is specified.
105 if ($max_id)
106 {
107 $data['max_id'] = $max_id;
108 }
109
110 // Check if count is specified.
111 if ($count)
112 {
113 $data['count'] = $count;
114 }
115
116 // Check if page is specified.
117 if ($page)
118 {
119 $data['page'] = $page;
120 }
121
122 // Check if entities is specified.
123 if (!is_null($entities))
124 {
125 $data['include_entities'] = $entities;
126 }
127
128 // Send the request.
129 return $this->sendRequest($path, 'GET', $data);
130 }
131
132 /**
133 * Method to send a new direct message to the specified user from the authenticating user.
134 *
135 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
136 * @param string $text The text of your direct message. Be sure to keep the message under 140 characters.
137 *
138 * @return array The decoded JSON response
139 *
140 * @since 12.3
141 * @throws RuntimeException
142 */
143 public function sendDirectMessages($user, $text)
144 {
145 // Set the API path
146 $path = '/direct_messages/new.json';
147
148 // Determine which type of data was passed for $user
149 if (is_numeric($user))
150 {
151 $data['user_id'] = $user;
152 }
153 elseif (is_string($user))
154 {
155 $data['screen_name'] = $user;
156 }
157 else
158 {
159 // We don't have a valid entry
160 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
161 }
162
163 $data['text'] = $text;
164
165 // Send the request.
166 return $this->sendRequest($path, 'POST', $data);
167 }
168
169 /**
170 * Method to get a single direct message, specified by an id parameter.
171 *
172 * @param integer $id The ID of the direct message.
173 *
174 * @return array The decoded JSON response
175 *
176 * @since 12.3
177 */
178 public function getDirectMessagesById($id)
179 {
180 // Check the rate limit for remaining hits
181 $this->checkRateLimit('direct_messages', 'show');
182
183 // Set the API path
184 $path = '/direct_messages/show.json';
185
186 $data['id'] = $id;
187
188 // Send the request.
189 return $this->sendRequest($path, 'GET', $data);
190 }
191
192 /**
193 * Method to delete the direct message specified in the required ID parameter.
194 *
195 * @param integer $id The ID of the direct message.
196 * @param boolean $entities When set to true, each tweet will include a node called "entities,". This node offers a variety of metadata
197 * about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
198 *
199 * @return array The decoded JSON response
200 *
201 * @since 12.3
202 */
203 public function deleteDirectMessages($id, $entities = null)
204 {
205 // Set the API path
206 $path = '/direct_messages/destroy.json';
207
208 $data['id'] = $id;
209
210 // Check if entities is specified.
211 if (!is_null($entities))
212 {
213 $data['include_entities'] = $entities;
214 }
215
216 // Send the request.
217 return $this->sendRequest($path, 'POST', $data);
218 }
219 }
220