1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage GitHub
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 * GitHub API Repositories Contents class for the Joomla Platform.
14 *
15 * These API methods let you retrieve the contents of files within a repository as Base64 encoded content.
16 * See media types for requesting raw or other formats.
17 *
18 * @documentation https://developer.github.com/v3/repos/contents
19 *
20 * @since 11.3
21 * @deprecated 4.0 Use the `joomla/github` package via Composer instead
22 */
23 class JGithubPackageRepositoriesContents extends JGithubPackage
24 {
25 /**
26 * Get the README
27 *
28 * This method returns the preferred README for a repository.
29 *
30 * GET /repos/:owner/:repo/readme
31 *
32 * Parameters
33 *
34 * ref
35 * Optional string - The String name of the Commit/Branch/Tag. Defaults to master.
36 *
37 * Response
38 *
39 * Status: 200 OK
40 * X-RateLimit-Limit: 5000
41 * X-RateLimit-Remaining: 4999
42 *
43 * {
44 * "type": "file",
45 * "encoding": "base64",
46 * "_links": {
47 * "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
48 * "self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
49 * "html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
50 * },
51 * "size": 5362,
52 * "name": "README.md",
53 * "path": "README.md",
54 * "content": "encoded content ...",
55 * "sha": "3d21ec53a331a6f037a91c368710b99387d012c1"
56 * }
57 *
58 * @param string $owner The name of the owner of the GitHub repository.
59 * @param string $repo The name of the GitHub repository.
60 * @param string $ref The String name of the Commit/Branch/Tag. Defaults to master.
61 *
62 * @since 3.3 (CMS)
63 *
64 * @return object
65 */
66 public function getReadme($owner, $repo, $ref = '')
67 {
68 // Build the request path.
69 $path = '/repos/' . $owner . '/' . $repo . '/readme';
70
71 if ($ref)
72 {
73 $path .= '?ref=' . $ref;
74 }
75
76 // Send the request.
77 return $this->processResponse(
78 $this->client->get($this->fetchUrl($path))
79 );
80 }
81
82 /**
83 * Get contents
84 *
85 * This method returns the contents of any file or directory in a repository.
86 *
87 * GET /repos/:owner/:repo/contents/:path
88 *
89 * Parameters
90 *
91 * path
92 * Optional string - The content path.
93 * ref
94 * Optional string - The String name of the Commit/Branch/Tag. Defaults to master.
95 *
96 * Response
97 *
98 * Status: 200 OK
99 * X-RateLimit-Limit: 5000
100 * X-RateLimit-Remaining: 4999
101 *
102 * {
103 * "type": "file",
104 * "encoding": "base64",
105 * "_links": {
106 * "git": "https://api.github.com/repos/octokit/octokit.rb/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
107 * "self": "https://api.github.com/repos/octokit/octokit.rb/contents/README.md",
108 * "html": "https://github.com/octokit/octokit.rb/blob/master/README.md"
109 * },
110 * "size": 5362,
111 * "name": "README.md",
112 * "path": "README.md",
113 * "content": "encoded content ...",
114 * "sha": "3d21ec53a331a6f037a91c368710b99387d012c1"
115 * }
116 *
117 * @param string $owner The name of the owner of the GitHub repository.
118 * @param string $repo The name of the GitHub repository.
119 * @param string $path The content path.
120 * @param string $ref The String name of the Commit/Branch/Tag. Defaults to master.
121 *
122 * @since 3.3 (CMS)
123 *
124 * @return object
125 */
126 public function get($owner, $repo, $path, $ref = '')
127 {
128 // Build the request path.
129 $rPath = '/repos/' . $owner . '/' . $repo . '/contents/' . $path;
130
131 if ($ref)
132 {
133 $rPath .= '?ref=' . $ref;
134 }
135
136 // Send the request.
137 return $this->processResponse(
138 $this->client->get($this->fetchUrl($rPath))
139 );
140 }
141
142 /**
143 * Get archive link
144 *
145 * This method will return a 302 to a URL to download a tarball or zipball archive for a repository.
146 * Please make sure your HTTP framework is configured to follow redirects or you will need to use the Location header to make a second GET request.
147 *
148 * Note: For private repositories, these links are temporary and expire quickly.
149 *
150 * GET /repos/:owner/:repo/:archive_format/:ref
151 *
152 * Parameters
153 *
154 * archive_format
155 * Either tarball or zipball
156 * ref
157 * Optional string - valid Git reference, defaults to master
158 *
159 * Response
160 *
161 * Status: 302 Found
162 * Location: http://github.com/me/myprivate/tarball/master?SSO=thistokenexpires
163 * X-RateLimit-Limit: 5000
164 * X-RateLimit-Remaining: 4999
165 *
166 * To follow redirects with curl, use the -L switch:
167 *
168 * curl -L https://api.github.com/repos/octokit/octokit.rb/tarball > octokit.tar.gz
169 *
170 * @param string $owner The name of the owner of the GitHub repository.
171 * @param string $repo The name of the GitHub repository.
172 * @param string $archive_format Either tarball or zipball.
173 * @param string $ref The String name of the Commit/Branch/Tag. Defaults to master.
174 *
175 * @throws UnexpectedValueException
176 * @since 3.3 (CMS)
177 *
178 * @return object
179 */
180 public function getArchiveLink($owner, $repo, $archive_format = 'zipball', $ref = '')
181 {
182 if (false == in_array($archive_format, array('tarball', 'zipball')))
183 {
184 throw new UnexpectedValueException('Archive format must be either "tarball" or "zipball".');
185 }
186
187 // Build the request path.
188 $path = '/repos/' . $owner . '/' . $repo . '/' . $archive_format;
189
190 if ($ref)
191 {
192 $path .= '?ref=' . $ref;
193 }
194
195 // Send the request.
196 return $this->processResponse(
197 $this->client->get($this->fetchUrl($path)),
198 302
199 );
200 }
201 }
202