Commit | Line | Data |
---|---|---|
6a488035 TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
bc77d7c0 | 4 | | Copyright CiviCRM LLC. All rights reserved. | |
6a488035 | 5 | | | |
bc77d7c0 TO |
6 | | This work is published under the GNU AGPLv3 license with some | |
7 | | permitted exceptions and without any warranty. For full license | | |
8 | | and copyright information, see https://civicrm.org/licensing | | |
6a488035 | 9 | +--------------------------------------------------------------------+ |
d25dd0ee | 10 | */ |
6a488035 TO |
11 | |
12 | /** | |
13 | * | |
14 | * @package CRM | |
ca5cec67 | 15 | * @copyright CiviCRM LLC https://civicrm.org/licensing |
6a488035 TO |
16 | */ |
17 | ||
18 | /** | |
0c3a6e64 | 19 | * Api Explorer |
6a488035 TO |
20 | */ |
21 | class CRM_Admin_Page_APIExplorer extends CRM_Core_Page { | |
22 | ||
7d16f66d SL |
23 | /** |
24 | * Return unique paths for checking for examples. | |
25 | * @return array | |
26 | */ | |
27 | private static function uniquePaths() { | |
28 | // Ensure that paths with trailing slashes are properly dealt with | |
29 | $paths = explode(PATH_SEPARATOR, get_include_path()); | |
30 | foreach ($paths as $id => $rawPath) { | |
31 | $pathParts = explode(DIRECTORY_SEPARATOR, $rawPath); | |
32 | foreach ($pathParts as $partId => $part) { | |
33 | if (empty($part)) { | |
34 | unset($pathParts[$partId]); | |
35 | } | |
36 | } | |
37 | $newRawPath = implode(DIRECTORY_SEPARATOR, $pathParts); | |
38 | if ($newRawPath != $rawPath) { | |
39 | $paths[$id] = DIRECTORY_SEPARATOR . $newRawPath; | |
40 | } | |
41 | } | |
42 | $paths = array_unique($paths); | |
43 | return $paths; | |
44 | } | |
45 | ||
e0ef6999 | 46 | /** |
ce064e4f | 47 | * Run page. |
48 | * | |
e0ef6999 EM |
49 | * @return string |
50 | */ | |
00be9182 | 51 | public function run() { |
2b6e1174 CW |
52 | CRM_Core_Resources::singleton() |
53 | ->addScriptFile('civicrm', 'templates/CRM/Admin/Page/APIExplorer.js') | |
37d79aed | 54 | ->addScriptFile('civicrm', 'bower_components/google-code-prettify/bin/prettify.min.js', 99) |
5b46e216 | 55 | ->addStyleFile('civicrm', 'bower_components/google-code-prettify/bin/prettify.min.css', 99) |
be2fb01f | 56 | ->addVars('explorer', ['max_joins' => \Civi\API\Api3SelectQuery::MAX_JOINS]); |
89ee60d5 | 57 | |
e4176358 | 58 | $this->assign('operators', CRM_Core_DAO::acceptedSQLOperators()); |
89ee60d5 CW |
59 | |
60 | // List example directories | |
7d16f66d | 61 | // use get_include_path to ensure that extensions are captured. |
be2fb01f | 62 | $examples = []; |
7d16f66d SL |
63 | $paths = self::uniquePaths(); |
64 | foreach ($paths as $path) { | |
65 | $dir = \CRM_Utils_File::addTrailingSlash($path) . 'api' . DIRECTORY_SEPARATOR . 'v3' . DIRECTORY_SEPARATOR . 'examples'; | |
66 | if (is_dir($dir)) { | |
67 | foreach (scandir($dir) as $item) { | |
68 | if ($item && strpos($item, '.') === FALSE && array_search($item, $examples) === FALSE) { | |
69 | $examples[] = $item; | |
70 | } | |
71 | } | |
89ee60d5 CW |
72 | } |
73 | } | |
7d16f66d | 74 | sort($examples); |
89ee60d5 CW |
75 | $this->assign('examples', $examples); |
76 | ||
6a488035 TO |
77 | return parent::run(); |
78 | } | |
79 | ||
6a488035 TO |
80 | /** |
81 | * Get user context. | |
82 | * | |
a6c01b45 CW |
83 | * @return string |
84 | * user context. | |
6a488035 | 85 | */ |
00be9182 | 86 | public function userContext() { |
d5a9020d | 87 | return 'civicrm/api'; |
6a488035 | 88 | } |
96025800 | 89 | |
89ee60d5 | 90 | /** |
ce064e4f | 91 | * AJAX callback to fetch examples. |
89ee60d5 CW |
92 | */ |
93 | public static function getExampleFile() { | |
89ee60d5 | 94 | if (!empty($_GET['entity']) && strpos($_GET['entity'], '.') === FALSE) { |
be2fb01f | 95 | $examples = []; |
7d16f66d SL |
96 | $paths = self::uniquePaths(); |
97 | foreach ($paths as $path) { | |
98 | $dir = \CRM_Utils_File::addTrailingSlash($path) . 'api' . DIRECTORY_SEPARATOR . 'v3' . DIRECTORY_SEPARATOR . 'examples' . DIRECTORY_SEPARATOR . $_GET['entity']; | |
99 | if (is_dir($dir)) { | |
100 | foreach (scandir($dir) as $item) { | |
749595cc | 101 | $item = str_replace('.ex.php', '', $item); |
7d16f66d | 102 | if ($item && strpos($item, '.') === FALSE) { |
be2fb01f | 103 | $examples[] = ['key' => $item, 'value' => $item]; |
7d16f66d SL |
104 | } |
105 | } | |
89ee60d5 CW |
106 | } |
107 | } | |
108 | CRM_Utils_JSON::output($examples); | |
109 | } | |
110 | if (!empty($_GET['file']) && strpos($_GET['file'], '.') === FALSE) { | |
7d16f66d SL |
111 | $paths = self::uniquePaths(); |
112 | $fileFound = FALSE; | |
113 | foreach ($paths as $path) { | |
749595cc | 114 | $fileName = \CRM_Utils_File::addTrailingSlash($path) . 'api' . DIRECTORY_SEPARATOR . 'v3' . DIRECTORY_SEPARATOR . 'examples' . DIRECTORY_SEPARATOR . $_GET['file'] . '.ex.php'; |
7d16f66d SL |
115 | if (!$fileFound && file_exists($fileName)) { |
116 | $fileFound = TRUE; | |
117 | echo file_get_contents($fileName); | |
118 | } | |
89ee60d5 | 119 | } |
7d16f66d | 120 | if (!$fileFound) { |
89ee60d5 CW |
121 | echo "Not found."; |
122 | } | |
123 | CRM_Utils_System::civiExit(); | |
124 | } | |
bc4aa590 CW |
125 | CRM_Utils_System::permissionDenied(); |
126 | } | |
127 | ||
128 | /** | |
ce064e4f | 129 | * Ajax callback to display code docs. |
bc4aa590 CW |
130 | */ |
131 | public static function getDoc() { | |
e80f05b2 CB |
132 | // Verify the API handler we're talking to is valid. |
133 | $entities = civicrm_api3('Entity', 'get'); | |
9c1bc317 | 134 | $entity = $_GET['entity'] ?? NULL; |
6469e038 | 135 | if (!empty($entity) && in_array($entity, $entities['values']) && strpos($entity, '.') === FALSE) { |
9c1bc317 | 136 | $action = $_GET['action'] ?? NULL; |
bc4aa590 | 137 | $doc = self::getDocblock($entity, $action); |
be2fb01f | 138 | $result = [ |
bc4aa590 CW |
139 | 'doc' => $doc ? self::formatDocBlock($doc[0]) : 'Not found.', |
140 | 'code' => $doc ? $doc[1] : NULL, | |
cf3a4f07 | 141 | 'file' => $doc ? $doc[2] : NULL, |
be2fb01f | 142 | ]; |
bc4aa590 CW |
143 | if (!$action) { |
144 | $actions = civicrm_api3($entity, 'getactions'); | |
145 | $result['actions'] = CRM_Utils_Array::makeNonAssociative(array_combine($actions['values'], $actions['values'])); | |
146 | } | |
147 | CRM_Utils_JSON::output($result); | |
148 | } | |
149 | CRM_Utils_System::permissionDenied(); | |
150 | } | |
151 | ||
152 | /** | |
ce064e4f | 153 | * Get documentation block. |
154 | * | |
bc4aa590 CW |
155 | * @param string $entity |
156 | * @param string|null $action | |
157 | * @return array|bool | |
158 | * [docblock, code] | |
159 | */ | |
160 | private static function getDocBlock($entity, $action) { | |
161 | if (!$entity) { | |
162 | return FALSE; | |
163 | } | |
cf3a4f07 CW |
164 | $file = "api/v3/$entity.php"; |
165 | $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH); | |
bc4aa590 CW |
166 | if (!$contents) { |
167 | // Api does not exist | |
168 | return FALSE; | |
169 | } | |
be2fb01f | 170 | $docblock = $code = []; |
bc4aa590 CW |
171 | // Fetch docblock for the api file |
172 | if (!$action) { | |
173 | if (preg_match('#/\*\*\n.*?\n \*/\n#s', $contents, $docblock)) { | |
be2fb01f | 174 | return [$docblock[0], NULL, $file]; |
bc4aa590 CW |
175 | } |
176 | } | |
177 | // Fetch block for a specific action | |
178 | else { | |
179 | $action = strtolower($action); | |
74c303ca | 180 | $fnName = 'civicrm_api3_' . CRM_Core_DAO_AllCoreTables::convertEntityNameToLower($entity) . '_' . $action; |
bc4aa590 | 181 | // Support the alternate "1 file per action" structure |
cf3a4f07 CW |
182 | $actionFile = "api/v3/$entity/" . ucfirst($action) . '.php'; |
183 | $actionFileContents = file_get_contents("api/v3/$entity/" . ucfirst($action) . '.php', FILE_USE_INCLUDE_PATH); | |
184 | if ($actionFileContents) { | |
185 | $file = $actionFile; | |
186 | $contents = $actionFileContents; | |
bc4aa590 CW |
187 | } |
188 | // If action isn't in this file, try generic | |
41bd5fcb | 189 | if (strpos($contents, "function $fnName") === FALSE) { |
bc4aa590 | 190 | $fnName = "civicrm_api3_generic_$action"; |
cf3a4f07 CW |
191 | $file = "api/v3/Generic/" . ucfirst($action) . '.php'; |
192 | $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH); | |
bc4aa590 | 193 | if (!$contents) { |
cf3a4f07 CW |
194 | $file = "api/v3/Generic.php"; |
195 | $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH); | |
bc4aa590 CW |
196 | } |
197 | } | |
198 | if (preg_match('#(/\*\*(\n \*.*)*\n \*/\n)function[ ]+' . $fnName . '#i', $contents, $docblock)) { | |
199 | // Fetch the code in a separate regex to preserve sanity | |
200 | preg_match("#^function[ ]+$fnName.*?^}#ism", $contents, $code); | |
be2fb01f | 201 | return [$docblock[1], $code[0], $file]; |
bc4aa590 CW |
202 | } |
203 | } | |
204 | } | |
205 | ||
206 | /** | |
207 | * Format a docblock to be a bit more readable | |
0b882a86 CW |
208 | * |
209 | * FIXME: APIv4 uses markdown in code docs. Switch to that. | |
bc4aa590 CW |
210 | * |
211 | * @param string $text | |
212 | * @return string | |
213 | */ | |
eecd39e1 TO |
214 | public static function formatDocBlock($text) { |
215 | // Normalize #leading spaces. | |
216 | $lines = explode("\n", $text); | |
217 | $lines = preg_replace('/^ +\*/', ' *', $lines); | |
218 | $text = implode("\n", $lines); | |
219 | ||
bc4aa590 | 220 | // Get rid of comment stars |
be2fb01f | 221 | $text = str_replace(["\n * ", "\n *\n", "\n */\n", "/**\n"], ["\n", "\n\n", '', ''], $text); |
bc4aa590 CW |
222 | |
223 | // Format for html | |
224 | $text = htmlspecialchars($text); | |
225 | ||
226 | // Extract code blocks - save for later to skip html conversion | |
be2fb01f | 227 | $code = []; |
0b882a86 CW |
228 | preg_match_all('#(@code|```)(.*?)(@endcode|```)#is', $text, $code); |
229 | $text = preg_replace('#(@code|```)(.*?)(@endcode|```)#is', '<pre></pre>', $text); | |
bc4aa590 CW |
230 | |
231 | // Convert @annotations to titles | |
232 | $text = preg_replace_callback( | |
233 | '#^[ ]*@(\w+)([ ]*)#m', | |
234 | function($matches) { | |
235 | return "<strong>" . ucfirst($matches[1]) . "</strong>" . (empty($matches[2]) ? '' : ': '); | |
236 | }, | |
237 | $text); | |
238 | ||
239 | // Preserve indentation | |
240 | $text = str_replace("\n ", "\n ", $text); | |
241 | ||
242 | // Convert newlines | |
243 | $text = nl2br($text); | |
244 | ||
245 | // Add unformatted code blocks back in | |
0b882a86 CW |
246 | if ($code && !empty($code[2])) { |
247 | foreach ($code[2] as $block) { | |
fea52a54 | 248 | $text = preg_replace('#<pre></pre>#', "<pre>$block</pre>", $text, 1); |
bc4aa590 CW |
249 | } |
250 | } | |
251 | return $text; | |
89ee60d5 CW |
252 | } |
253 | ||
6a488035 | 254 | } |