3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2017 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2017
37 class CRM_Admin_Page_APIExplorer
extends CRM_Core_Page
{
44 public function run() {
45 CRM_Core_Resources
::singleton()
46 ->addScriptFile('civicrm', 'templates/CRM/Admin/Page/APIExplorer.js')
47 ->addScriptFile('civicrm', 'bower_components/google-code-prettify/bin/prettify.min.js', 99)
48 ->addStyleFile('civicrm', 'bower_components/google-code-prettify/bin/prettify.min.css', 99)
49 ->addVars('explorer', array('max_joins' => \Civi\API\Api3SelectQuery
::MAX_JOINS
));
51 $this->assign('operators', CRM_Core_DAO
::acceptedSQLOperators());
53 // List example directories
55 foreach (scandir(\Civi
::paths()->getPath('[civicrm.root]/api/v3/examples')) as $item) {
56 if ($item && strpos($item, '.') === FALSE) {
60 $this->assign('examples', $examples);
71 public function userContext() {
76 * AJAX callback to fetch examples.
78 public static function getExampleFile() {
79 if (!empty($_GET['entity']) && strpos($_GET['entity'], '.') === FALSE) {
81 foreach (scandir(\Civi
::paths()->getPath("[civicrm.root]/api/v3/examples/{$_GET['entity']}")) as $item) {
82 $item = str_replace('.php', '', $item);
83 if ($item && strpos($item, '.') === FALSE) {
84 $examples[] = array('key' => $item, 'value' => $item);
87 CRM_Utils_JSON
::output($examples);
89 if (!empty($_GET['file']) && strpos($_GET['file'], '.') === FALSE) {
90 $fileName = \Civi
::paths()->getPath("[civicrm.root]/api/v3/examples/{$_GET['file']}.php");
91 if (file_exists($fileName)) {
92 echo file_get_contents($fileName);
97 CRM_Utils_System
::civiExit();
99 CRM_Utils_System
::permissionDenied();
103 * Ajax callback to display code docs.
105 public static function getDoc() {
106 // Verify the API handler we're talking to is valid.
107 $entities = civicrm_api3('Entity', 'get');
108 $entity = CRM_Utils_Array
::value('entity', $_GET);
109 if (!empty($entity) && in_array($entity, $entities['values']) && strpos($entity, '.') === FALSE) {
110 $action = CRM_Utils_Array
::value('action', $_GET);
111 $doc = self
::getDocblock($entity, $action);
113 'doc' => $doc ? self
::formatDocBlock($doc[0]) : 'Not found.',
114 'code' => $doc ?
$doc[1] : NULL,
115 'file' => $doc ?
$doc[2] : NULL,
118 $actions = civicrm_api3($entity, 'getactions');
119 $result['actions'] = CRM_Utils_Array
::makeNonAssociative(array_combine($actions['values'], $actions['values']));
121 CRM_Utils_JSON
::output($result);
123 CRM_Utils_System
::permissionDenied();
127 * Get documentation block.
129 * @param string $entity
130 * @param string|null $action
134 private static function getDocBlock($entity, $action) {
138 $file = "api/v3/$entity.php";
139 $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH
);
141 // Api does not exist
144 $docblock = $code = array();
145 // Fetch docblock for the api file
147 if (preg_match('#/\*\*\n.*?\n \*/\n#s', $contents, $docblock)) {
148 return array($docblock[0], NULL, $file);
151 // Fetch block for a specific action
153 $action = strtolower($action);
154 $fnName = 'civicrm_api3_' . _civicrm_api_get_entity_name_from_camel($entity) . '_' . $action;
155 // Support the alternate "1 file per action" structure
156 $actionFile = "api/v3/$entity/" . ucfirst($action) . '.php';
157 $actionFileContents = file_get_contents("api/v3/$entity/" . ucfirst($action) . '.php', FILE_USE_INCLUDE_PATH
);
158 if ($actionFileContents) {
160 $contents = $actionFileContents;
162 // If action isn't in this file, try generic
163 if (strpos($contents, "function $fnName") === FALSE) {
164 $fnName = "civicrm_api3_generic_$action";
165 $file = "api/v3/Generic/" . ucfirst($action) . '.php';
166 $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH
);
168 $file = "api/v3/Generic.php";
169 $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH
);
172 if (preg_match('#(/\*\*(\n \*.*)*\n \*/\n)function[ ]+' . $fnName . '#i', $contents, $docblock)) {
173 // Fetch the code in a separate regex to preserve sanity
174 preg_match("#^function[ ]+$fnName.*?^}#ism", $contents, $code);
175 return array($docblock[1], $code[0], $file);
181 * Format a docblock to be a bit more readable
182 * Not a proper doc parser... patches welcome :)
184 * @param string $text
187 public static function formatDocBlock($text) {
188 // Normalize #leading spaces.
189 $lines = explode("\n", $text);
190 $lines = preg_replace('/^ +\*/', ' *', $lines);
191 $text = implode("\n", $lines);
193 // Get rid of comment stars
194 $text = str_replace(array("\n * ", "\n *\n", "\n */\n", "/**\n"), array("\n", "\n\n", '', ''), $text);
197 $text = htmlspecialchars($text);
199 // Extract code blocks - save for later to skip html conversion
201 preg_match_all('#@code(.*?)@endcode#is', $text, $code);
202 $text = preg_replace('#@code.*?@endcode#is', '<pre></pre>', $text);
204 // Convert @annotations to titles
205 $text = preg_replace_callback(
206 '#^[ ]*@(\w+)([ ]*)#m',
208 return "<strong>" . ucfirst($matches[1]) . "</strong>" . (empty($matches[2]) ?
'' : ': ');
212 // Preserve indentation
213 $text = str_replace("\n ", "\n ", $text);
216 $text = nl2br($text);
218 // Add unformatted code blocks back in
219 if ($code && !empty($code[1])) {
220 foreach ($code[1] as $block) {
221 $text = preg_replace('#<pre></pre>#', "<pre>$block</pre>", $text, 1);