3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
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-2015
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);
50 $this->assign('operators', CRM_Core_DAO
::acceptedSQLOperators());
52 // List example directories
55 foreach (scandir(CRM_Utils_file
::addTrailingSlash($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() {
80 $basePath = CRM_Utils_file
::addTrailingSlash($civicrm_root, '/');
81 if (!empty($_GET['entity']) && strpos($_GET['entity'], '.') === FALSE) {
83 foreach (scandir($basePath . 'api/v3/examples/' . $_GET['entity']) as $item) {
84 $item = str_replace('.php', '', $item);
85 if ($item && strpos($item, '.') === FALSE) {
86 $examples[] = array('key' => $item, 'value' => $item);
89 CRM_Utils_JSON
::output($examples);
91 if (!empty($_GET['file']) && strpos($_GET['file'], '.') === FALSE) {
92 $fileName = $basePath . 'api/v3/examples/' . $_GET['file'] . '.php';
93 if (file_exists($fileName)) {
94 echo file_get_contents($fileName);
99 CRM_Utils_System
::civiExit();
101 CRM_Utils_System
::permissionDenied();
105 * Ajax callback to display code docs.
107 public static function getDoc() {
108 // Verify the API handler we're talking to is valid.
109 $entities = civicrm_api3('Entity', 'get');
110 $entity = CRM_Utils_Array
::value('entity', $_GET);
111 if (!empty($entity) && in_array($entity, $entities['values']) && strpos($entity, '.') === FALSE) {
112 $action = CRM_Utils_Array
::value('action', $_GET);
113 $doc = self
::getDocblock($entity, $action);
115 'doc' => $doc ? self
::formatDocBlock($doc[0]) : 'Not found.',
116 'code' => $doc ?
$doc[1] : NULL,
117 'file' => $doc ?
$doc[2] : NULL,
120 $actions = civicrm_api3($entity, 'getactions');
121 $result['actions'] = CRM_Utils_Array
::makeNonAssociative(array_combine($actions['values'], $actions['values']));
123 CRM_Utils_JSON
::output($result);
125 CRM_Utils_System
::permissionDenied();
129 * Get documentation block.
131 * @param string $entity
132 * @param string|null $action
136 private static function getDocBlock($entity, $action) {
140 $file = "api/v3/$entity.php";
141 $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH
);
143 // Api does not exist
146 $docblock = $code = array();
147 // Fetch docblock for the api file
149 if (preg_match('#/\*\*\n.*?\n \*/\n#s', $contents, $docblock)) {
150 return array($docblock[0], NULL, $file);
153 // Fetch block for a specific action
155 $action = strtolower($action);
156 $fnName = 'civicrm_api3_' . _civicrm_api_get_entity_name_from_camel($entity) . '_' . $action;
157 // Support the alternate "1 file per action" structure
158 $actionFile = "api/v3/$entity/" . ucfirst($action) . '.php';
159 $actionFileContents = file_get_contents("api/v3/$entity/" . ucfirst($action) . '.php', FILE_USE_INCLUDE_PATH
);
160 if ($actionFileContents) {
162 $contents = $actionFileContents;
164 // If action isn't in this file, try generic
165 if (strpos($contents, "function $fnName") === FALSE) {
166 $fnName = "civicrm_api3_generic_$action";
167 $file = "api/v3/Generic/" . ucfirst($action) . '.php';
168 $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH
);
170 $file = "api/v3/Generic.php";
171 $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH
);
174 if (preg_match('#(/\*\*(\n \*.*)*\n \*/\n)function[ ]+' . $fnName . '#i', $contents, $docblock)) {
175 // Fetch the code in a separate regex to preserve sanity
176 preg_match("#^function[ ]+$fnName.*?^}#ism", $contents, $code);
177 return array($docblock[1], $code[0], $file);
183 * Format a docblock to be a bit more readable
184 * Not a proper doc parser... patches welcome :)
186 * @param string $text
189 private static function formatDocBlock($text) {
190 // Get rid of comment stars
191 $text = str_replace(array("\n * ", "\n *\n", "\n */\n", "/**\n"), array("\n", "\n\n", '', ''), $text);
194 $text = htmlspecialchars($text);
196 // Extract code blocks - save for later to skip html conversion
198 preg_match_all('#@code(.*?)@endcode#is', $text, $code);
199 $text = preg_replace('#@code.*?@endcode#is', '<pre></pre>', $text);
201 // Convert @annotations to titles
202 $text = preg_replace_callback(
203 '#^[ ]*@(\w+)([ ]*)#m',
205 return "<strong>" . ucfirst($matches[1]) . "</strong>" . (empty($matches[2]) ?
'' : ': ');
209 // Preserve indentation
210 $text = str_replace("\n ", "\n ", $text);
213 $text = nl2br($text);
215 // Add unformatted code blocks back in
216 if ($code && !empty($code[1])) {
217 foreach ($code[1] as $block) {
218 $text = preg_replace('#<pre></pre>#', "<pre>$block</pre>", $text, 1);