/libraries/joomla/github/commits.php

  1<?php
  2/**
  3 * @package     Joomla.Platform
  4 * @subpackage  GitHub
  5 *
  6 * @copyright   Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
  7 * @license     GNU General Public License version 2 or later; see LICENSE
  8 */
  9
 10defined('JPATH_PLATFORM') or die;
 11
 12/**
 13 * GitHub API Commits class for the Joomla Platform.
 14 *
 15 * @since  12.1
 16 */
 17class JGithubCommits extends JGithubObject
 18{
 19	/**
 20	 * Method to create a commit.
 21	 *
 22	 * @param   string  $user     The name of the owner of the GitHub repository.
 23	 * @param   string  $repo     The name of the GitHub repository.
 24	 * @param   string  $message  The commit message.
 25	 * @param   string  $tree     SHA of the tree object this commit points to.
 26	 * @param   array   $parents  Array of the SHAs of the commits that were the parents of this commit.
 27	 *                            If omitted or empty, the commit will be written as a root commit.
 28	 *                            For a single parent, an array of one SHA should be provided.
 29	 *                            For a merge commit, an array of more than one should be provided.
 30	 *
 31	 * @deprecated  use data->commits->create()
 32	 *
 33	 * @return  object
 34	 *
 35	 * @since   12.1
 36	 */
 37	public function create($user, $repo, $message, $tree, array $parents = array())
 38	{
 39		// Build the request path.
 40		$path = '/repos/' . $user . '/' . $repo . '/git/commits';
 41
 42		$data = json_encode(
 43			array('message' => $message, 'tree' => $tree, 'parents' => $parents)
 44		);
 45
 46		// Send the request.
 47		$response = $this->client->post($this->fetchUrl($path), $data);
 48
 49		// Validate the response code.
 50		if ($response->code != 201)
 51		{
 52			// Decode the error response and throw an exception.
 53			$error = json_decode($response->body);
 54			throw new DomainException($error->message, $response->code);
 55		}
 56
 57		return json_decode($response->body);
 58	}
 59
 60	/**
 61	 * Method to create a comment on a commit.
 62	 *
 63	 * @param   string   $user      The name of the owner of the GitHub repository.
 64	 * @param   string   $repo      The name of the GitHub repository.
 65	 * @param   string   $sha       The SHA of the commit to comment on.
 66	 * @param   string   $comment   The text of the comment.
 67	 * @param   integer  $line      The line number of the commit to comment on.
 68	 * @param   string   $filepath  A relative path to the file to comment on within the commit.
 69	 * @param   integer  $position  Line index in the diff to comment on.
 70	 *
 71	 * @deprecated  use repositories->comments->create()
 72	 *
 73	 * @return  object
 74	 *
 75	 * @since   12.1
 76	 */
 77	public function createCommitComment($user, $repo, $sha, $comment, $line, $filepath, $position)
 78	{
 79		// Build the request path.
 80		$path = '/repos/' . $user . '/' . $repo . '/commits/' . $sha . '/comments';
 81
 82		$data = json_encode(
 83			array(
 84				'body' => $comment,
 85				'commit_id' => $sha,
 86				'line' => (int) $line,
 87				'path' => $filepath,
 88				'position' => (int) $position
 89			)
 90		);
 91
 92		// Send the request.
 93		$response = $this->client->post($this->fetchUrl($path), $data);
 94
 95		// Validate the response code.
 96		if ($response->code != 201)
 97		{
 98			// Decode the error response and throw an exception.
 99			$error = json_decode($response->body);
100			throw new DomainException($error->message, $response->code);
101		}
102
103		return json_decode($response->body);
104	}
105
106	/**
107	 * Method to delete a comment on a commit.
108	 *
109	 * @param   string  $user  The name of the owner of the GitHub repository.
110	 * @param   string  $repo  The name of the GitHub repository.
111	 * @param   string  $id    The ID of the comment to edit.
112	 *
113	 * @deprecated  use repositories->comments->delete()
114	 *
115	 * @return  object
116	 *
117	 * @since   12.1
118	 */
119	public function deleteCommitComment($user, $repo, $id)
120	{
121		// Build the request path.
122		$path = '/repos/' . $user . '/' . $repo . '/comments/' . $id;
123
124		// Send the request.
125		$response = $this->client->delete($this->fetchUrl($path));
126
127		// Validate the response code.
128		if ($response->code != 204)
129		{
130			// Decode the error response and throw an exception.
131			$error = json_decode($response->body);
132			throw new DomainException($error->message, $response->code);
133		}
134
135		return json_decode($response->body);
136	}
137
138	/**
139	 * Method to edit a comment on a commit.
140	 *
141	 * @param   string  $user     The name of the owner of the GitHub repository.
142	 * @param   string  $repo     The name of the GitHub repository.
143	 * @param   string  $id       The ID of the comment to edit.
144	 * @param   string  $comment  The text of the comment.
145	 *
146	 * @deprecated  use repositories->comments->edit()
147	 *
148	 * @return  object
149	 *
150	 * @since   12.1
151	 */
152	public function editCommitComment($user, $repo, $id, $comment)
153	{
154		// Build the request path.
155		$path = '/repos/' . $user . '/' . $repo . '/comments/' . $id;
156
157		$data = json_encode(
158			array(
159				'body' => $comment
160			)
161		);
162
163		// Send the request.
164		$response = $this->client->patch($this->fetchUrl($path), $data);
165
166		// Validate the response code.
167		if ($response->code != 200)
168		{
169			// Decode the error response and throw an exception.
170			$error = json_decode($response->body);
171			throw new DomainException($error->message, $response->code);
172		}
173
174		return json_decode($response->body);
175	}
176
177	/**
178	 * Method to get a single commit for a repository.
179	 *
180	 * @param   string   $user   The name of the owner of the GitHub repository.
181	 * @param   string   $repo   The name of the GitHub repository.
182	 * @param   string   $sha    The SHA of the commit to retrieve.
183	 * @param   integer  $page   Page to request
184	 * @param   integer  $limit  Number of results to return per page
185	 *
186	 * @deprecated  use repositories->commits->get()
187	 *
188	 * @return  array
189	 *
190	 * @since   12.1
191	 */
192	public function getCommit($user, $repo, $sha, $page = 0, $limit = 0)
193	{
194		// Build the request path.
195		$path = '/repos/' . $user . '/' . $repo . '/commits/' . $sha;
196
197		// Send the request.
198		$response = $this->client->get($this->fetchUrl($path, $page, $limit));
199
200		// Validate the response code.
201		if ($response->code != 200)
202		{
203			// Decode the error response and throw an exception.
204			$error = json_decode($response->body);
205			throw new DomainException($error->message, $response->code);
206		}
207
208		return json_decode($response->body);
209	}
210
211	/**
212	 * Method to get a single comment on a commit.
213	 *
214	 * @param   string   $user  The name of the owner of the GitHub repository.
215	 * @param   string   $repo  The name of the GitHub repository.
216	 * @param   integer  $id    ID of the comment to retrieve
217	 *
218	 * @deprecated  use repositories->comments->get()
219	 *
220	 * @return  array
221	 *
222	 * @since   12.1
223	 */
224	public function getCommitComment($user, $repo, $id)
225	{
226		// Build the request path.
227		$path = '/repos/' . $user . '/' . $repo . '/comments/' . $id;
228
229		// Send the request.
230		$response = $this->client->get($this->fetchUrl($path));
231
232		// Validate the response code.
233		if ($response->code != 200)
234		{
235			// Decode the error response and throw an exception.
236			$error = json_decode($response->body);
237			throw new DomainException($error->message, $response->code);
238		}
239
240		return json_decode($response->body);
241	}
242
243	/**
244	 * Method to get a list of comments for a single commit for a repository.
245	 *
246	 * @param   string   $user   The name of the owner of the GitHub repository.
247	 * @param   string   $repo   The name of the GitHub repository.
248	 * @param   string   $sha    The SHA of the commit to retrieve.
249	 * @param   integer  $page   Page to request
250	 * @param   integer  $limit  Number of results to return per page
251	 *
252	 * @deprecated  use repositories->comments->getList()
253	 *
254	 * @return  array
255	 *
256	 * @since   12.1
257	 */
258	public function getCommitComments($user, $repo, $sha, $page = 0, $limit = 0)
259	{
260		// Build the request path.
261		$path = '/repos/' . $user . '/' . $repo . '/commits/' . $sha . '/comments';
262
263		// Send the request.
264		$response = $this->client->get($this->fetchUrl($path, $page, $limit));
265
266		// Validate the response code.
267		if ($response->code != 200)
268		{
269			// Decode the error response and throw an exception.
270			$error = json_decode($response->body);
271			throw new DomainException($error->message, $response->code);
272		}
273
274		return json_decode($response->body);
275	}
276
277	/**
278	 * Method to get a diff for two commits.
279	 *
280	 * @param   string  $user  The name of the owner of the GitHub repository.
281	 * @param   string  $repo  The name of the GitHub repository.
282	 * @param   string  $base  The base of the diff, either a commit SHA or branch.
283	 * @param   string  $head  The head of the diff, either a commit SHA or branch.
284	 *
285	 * @deprecated  use repositories->commits->compare()
286	 *
287	 * @return  array
288	 *
289	 * @since   12.1
290	 */
291	public function getDiff($user, $repo, $base, $head)
292	{
293		// Build the request path.
294		$path = '/repos/' . $user . '/' . $repo . '/compare/' . $base . '...' . $head;
295
296		// Send the request.
297		$response = $this->client->get($this->fetchUrl($path));
298
299		// Validate the response code.
300		if ($response->code != 200)
301		{
302			// Decode the error response and throw an exception.
303			$error = json_decode($response->body);
304			throw new DomainException($error->message, $response->code);
305		}
306
307		return json_decode($response->body);
308	}
309
310	/**
311	 * Method to list commits for a repository.
312	 *
313	 * @param   string   $user   The name of the owner of the GitHub repository.
314	 * @param   string   $repo   The name of the GitHub repository.
315	 * @param   integer  $page   Page to request
316	 * @param   integer  $limit  Number of results to return per page
317	 *
318	 * @deprecated  use repositories->commits->getList()
319	 *
320	 * @return  array
321	 *
322	 * @since   12.1
323	 */
324	public function getList($user, $repo, $page = 0, $limit = 0)
325	{
326		// Build the request path.
327		$path = '/repos/' . $user . '/' . $repo . '/commits';
328
329		// Send the request.
330		$response = $this->client->get($this->fetchUrl($path, $page, $limit));
331
332		// Validate the response code.
333		if ($response->code != 200)
334		{
335			// Decode the error response and throw an exception.
336			$error = json_decode($response->body);
337			throw new DomainException($error->message, $response->code);
338		}
339
340		return json_decode($response->body);
341	}
342
343	/**
344	 * Method to get a list of commit comments for a repository.
345	 *
346	 * @param   string   $user   The name of the owner of the GitHub repository.
347	 * @param   string   $repo   The name of the GitHub repository.
348	 * @param   integer  $page   Page to request
349	 * @param   integer  $limit  Number of results to return per page
350	 *
351	 * @deprecated  use repositories->comments->getListRepository()
352	 *
353	 * @return  array
354	 *
355	 * @since   12.1
356	 */
357	public function getListComments($user, $repo, $page = 0, $limit = 0)
358	{
359		// Build the request path.
360		$path = '/repos/' . $user . '/' . $repo . '/comments';
361
362		// Send the request.
363		$response = $this->client->get($this->fetchUrl($path, $page, $limit));
364
365		// Validate the response code.
366		if ($response->code != 200)
367		{
368			// Decode the error response and throw an exception.
369			$error = json_decode($response->body);
370			throw new DomainException($error->message, $response->code);
371		}
372
373		return json_decode($response->body);
374	}
375}