DocumentationService.php 10.1 KB
Newer Older
1
2
3
<?php
namespace TYPO3\CMS\Documentation\Service;

4
/*
5
 * This file is part of the TYPO3 CMS project.
6
 *
7
8
9
 * It is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, either version 2
 * of the License, or any later version.
10
 *
11
12
 * For the full copyright and license information, please read the
 * LICENSE.txt file that was distributed with this source code.
13
 *
14
15
 * The TYPO3 project - inspiring people to share!
 */
16

17
use TYPO3\CMS\Core\Utility\GeneralUtility;
18
19
20
21
22
23
24
25
26
27
28
29
30
31

/**
 * Service class to connect to docs.typo3.org.
 */
class DocumentationService {

	/**
	 * Returns the list of official documents on docs.typo3.org.
	 *
	 * @return array
	 */
	public function getOfficialDocuments() {
		$documents = array();

32
		$json = GeneralUtility::getUrl('https://docs.typo3.org/typo3cms/documents.json');
33
34
35
		if ($json) {
			$documents = json_decode($json, TRUE);
			foreach ($documents as &$document) {
36
				$document['icon'] = \TYPO3\CMS\Documentation\Utility\MiscUtility::getIcon($document['key']);
37
38
39
			}

			// Cache file locally to be able to create a composer.json file when fetching a document
40
			$absoluteCacheFilename = GeneralUtility::getFileAbsFileName('typo3temp/documents.json');
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
			GeneralUtility::writeFile($absoluteCacheFilename, $json);
		}
		return $documents;
	}

	/**
	 * Returns the list of local extensions.
	 *
	 * @return array
	 */
	public function getLocalExtensions() {
		$documents = array();

		foreach ($GLOBALS['TYPO3_LOADED_EXT'] as $extensionKey => $extensionData) {
			$absoluteExtensionPath = GeneralUtility::getFileAbsFileName($extensionData['siteRelPath']);
			if (is_file($absoluteExtensionPath . 'README.rst') || is_file($absoluteExtensionPath . 'Documentation' . DIRECTORY_SEPARATOR . 'Index.rst')) {
57
				$metadata = \TYPO3\CMS\Documentation\Utility\MiscUtility::getExtensionMetaData($extensionKey);
58
59
60
61
62
63
64
65
66
				if ($extensionData['type'] === 'S') {
					$version = TYPO3_branch;
				} else {
					$version = substr($metadata['release'], -4) === '-dev' ? 'latest' : $metadata['release'];
				}

				$documentKey = 'typo3cms.extensions.' . $extensionKey;
				$documents[] = array(
					'title'   => $metadata['title'],
67
					'icon'    => \TYPO3\CMS\Documentation\Utility\MiscUtility::getIcon($documentKey),
68
69
					'type'    => 'Extension',
					'key'     => $documentKey,
70
					'shortcut' => $extensionKey,
71
					'url'     => 'https://docs.typo3.org/typo3cms/extensions/' . $extensionKey . '/',
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
					'version' => $version,
				);
			}
		}

		return $documents;
	}

	/**
	 * Fetches the nearest version of a document from docs.typo3.org.
	 *
	 * Algorithm is as follows:
	 *
	 * 1) If exact version/language pair exists, fetch it
	 * 2) If document with version trimmed down to 2 digits and given language exists, fetch it
	 * 3) If document with version 'latest' and given language exists, fetch it
	 * 4) Restart at step 1) with language 'default'
	 *
	 * @param string $url
	 * @param string $key
	 * @param string $version
	 * @param string $language
94
	 * @return bool TRUE if fetch succeeded, otherwise FALSE
95
96
	 */
	public function fetchNearestDocument($url, $key, $version = 'latest', $language = 'default') {
97
98
99
		// In case we could not find a working combination
		$success = FALSE;

100
		$packages = $this->getAvailablePackages($url);
101
		if (empty($packages)) {
102
			return $success;
103
104
105
106
107
108
109
110
111
		}

		$languages = array($language);
		if ($language !== 'default') {
			$languages[] = 'default';
		}
		foreach ($languages as $language) {
			// Step 1)
			if (isset($packages[$version][$language])) {
112
113
114
115
				$success |= $this->fetchDocument($url, $key, $version, $language);
				// Fetch next language
				continue;
			} else {
116
117
118
119
120
121
122
				if (isset($packages[$version])) {
					foreach ($packages[$version] as $locale => $_) {
						if (GeneralUtility::isFirstPartOfStr($locale, $language)) {
							$success |= $this->fetchDocument($url, $key, $version, $locale);
							// Fetch next language (jump current foreach up to the loop of $languages)
							continue 2;
						}
123
124
					}
				}
125
126
127
128
129
130
			}
			// Step 2)
			if (preg_match('/^(\d+\.\d+)\.\d+$/', $version, $matches)) {
				// Instead of a 3-digit version, try to get it on 2 digits
				$shortVersion = $matches[1];
				if (isset($packages[$shortVersion][$language])) {
131
132
133
					$success |= $this->fetchDocument($url, $key, $shortVersion, $language);
					// Fetch next language
					continue;
134
135
136
137
				}
			}
			// Step 3)
			if ($version !== 'latest' && isset($packages['latest'][$language])) {
138
139
140
				$success |= $this->fetchDocument($url, $key, 'latest', $language);
				// Fetch next language
				continue;
141
142
143
			}
		}

144
		return $success;
145
146
147
148
149
150
151
152
153
	}

	/**
	 * Fetches a document from docs.typo3.org.
	 *
	 * @param string $url
	 * @param string $key
	 * @param string $version
	 * @param string $language
154
	 * @return bool TRUE if fetch succeeded, otherwise FALSE
155
156
157
158
159
160
	 */
	public function fetchDocument($url, $key, $version = 'latest', $language = 'default') {
		$result = FALSE;
		$url = rtrim($url, '/') . '/';

		$packagePrefix = substr($key, strrpos($key, '.') + 1);
161
162
		$languageSegment = str_replace('_', '-', strtolower($language));
		$packageName = sprintf('%s-%s-%s.zip', $packagePrefix, $version, $languageSegment);
163
		$packageUrl = $url . 'packages/' . $packageName;
164
		$absolutePathToZipFile = GeneralUtility::getFileAbsFileName('typo3temp/' . $packageName);
165
166

		$packages = $this->getAvailablePackages($url);
167
		if (empty($packages) || !isset($packages[$version][$language])) {
168
169
170
171
172
173
174
175
176
177
178
179
180
			return FALSE;
		}

		// Check if a local version of the package is already present
		$hasArchive = FALSE;
		if (is_file($absolutePathToZipFile)) {
			$localMd5 = md5_file($absolutePathToZipFile);
			$remoteMd5 = $packages[$version][$language];
			$hasArchive = $localMd5 === $remoteMd5;
		}

		if (!$hasArchive) {
			/** @var $http \TYPO3\CMS\Core\Http\HttpRequest */
181
			$http = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Http\HttpRequest::class, $packageUrl);
182
183
184
185
186
187
188
			$response = $http->send();
			if ($response->getStatus() == 200) {
				GeneralUtility::writeFile($absolutePathToZipFile, $response->getBody());
			}
		}

		if (is_file($absolutePathToZipFile)) {
189
			$absoluteDocumentPath = GeneralUtility::getFileAbsFileName('typo3conf/Documentation/');
190
191
192
193

			$result = $this->unzipDocumentPackage($absolutePathToZipFile, $absoluteDocumentPath);

			// Create a composer.json file
194
			$absoluteCacheFilename = GeneralUtility::getFileAbsFileName('typo3temp/documents.json');
195
196
197
198
199
200
201
202
			$documents = json_decode(file_get_contents($absoluteCacheFilename), TRUE);
			foreach ($documents as $document) {
				if ($document['key'] === $key) {
					$composerData = array(
						'name' => $document['title'],
						'type' => 'documentation',
						'description' => 'TYPO3 ' . $document['type'],
					);
203
204
					$relativeComposerFilename = $key . '/' . $language . '/composer.json';
					$absoluteComposerFilename = GeneralUtility::getFileAbsFileName('typo3conf/Documentation/' . $relativeComposerFilename);
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
					GeneralUtility::writeFile($absoluteComposerFilename, json_encode($composerData));
					break;
				}
			}
		}

		return $result;
	}

	/**
	 * Returns the available packages (version + language) for a given
	 * document on docs.typo3.org.
	 *
	 * @param string $url
	 * @return array
	 */
	protected function getAvailablePackages($url) {
		$packages = array();
		$url = rtrim($url, '/') . '/';
		$indexUrl = $url . 'packages/packages.xml';

		$remote = GeneralUtility::getUrl($indexUrl);
		if ($remote) {
			$packages = $this->parsePackagesXML($remote);
		}

		return $packages;
	}

	/**
	 * Parses content of packages.xml into a suitable array.
	 *
	 * @param string $string: XML data to parse
	 * @throws \TYPO3\CMS\Documentation\Exception\XmlParser
	 * @return array Array representation of XML data
	 */
	protected function parsePackagesXML($string) {
		$data = json_decode(json_encode((array)simplexml_load_string($string)), TRUE);
243
		if (count($data) !== 2) {
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
			throw new \TYPO3\CMS\Documentation\Exception\XmlParser('Error in XML parser while decoding packages XML file.', 1374222437);
		}

		// SimpleXML does not properly handle arrays with only 1 item
		if ($data['languagePackIndex']['languagepack'][0] === NULL) {
			$data['languagePackIndex']['languagepack'] = array($data['languagePackIndex']['languagepack']);
		}

		$packages = array();
		foreach ($data['languagePackIndex']['languagepack'] as $languagePack) {
			$language = $languagePack['@attributes']['language'];
			$version = $languagePack['@attributes']['version'];
			$packages[$version][$language] = $languagePack['md5'];
		}

		return $packages;
	}

	/**
	 * Unzips a document package.
	 *
	 * @param string $file path to zip file
	 * @param string $path path to extract to
	 * @throws \TYPO3\CMS\Documentation\Exception\Document
268
	 * @return bool
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
	 */
	protected function unzipDocumentPackage($file, $path) {
		$zip = zip_open($file);
		if (is_resource($zip)) {
			$result = TRUE;

			if (!is_dir($path)) {
				GeneralUtility::mkdir_deep($path);
			}

			while (($zipEntry = zip_read($zip)) !== FALSE) {
				$zipEntryName = zip_entry_name($zipEntry);
				if (strpos($zipEntryName, '/') !== FALSE) {
					$zipEntryPathSegments =  explode('/', $zipEntryName);
					$fileName = array_pop($zipEntryPathSegments);
					// It is a folder, because the last segment is empty, let's create it
					if (empty($fileName)) {
						GeneralUtility::mkdir_deep($path, implode('/', $zipEntryPathSegments));
					} else {
						$absoluteTargetPath = GeneralUtility::getFileAbsFileName($path . implode('/', $zipEntryPathSegments) . '/' . $fileName);
289
						if (trim($absoluteTargetPath) !== '') {
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
							$return = GeneralUtility::writeFile(
								$absoluteTargetPath, zip_entry_read($zipEntry, zip_entry_filesize($zipEntry))
							);
							if ($return === FALSE) {
								throw new \TYPO3\CMS\Documentation\Exception\Document('Could not write file ' . $zipEntryName, 1374161546);
							}
						} else {
							throw new \TYPO3\CMS\Documentation\Exception\Document('Could not write file ' . $zipEntryName, 1374161532);
						}
					}
				} else {
					throw new \TYPO3\CMS\Documentation\Exception\Document('Extension directory missing in zip file!', 1374161519);
				}
			}
		} else {
			throw new \TYPO3\CMS\Documentation\Exception\Document('Unable to open zip file ' . $file, 1374161508);
		}

		return $result;
	}

}