CRM/Admin/Page/APIExplorer.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  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.   |
  13  |                                                                    |
  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.        |
  18  |                                                                    |
  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  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2015
  32  * $Id$
  33  *
  34  */
  35
  36 /**
  37  * Api Explorer
  38  */
  39 class CRM_Admin_Page_APIExplorer extends CRM_Core_Page {
  40
  41   /**
  42    * @return string
  43    */
  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
  50     $this->assign('operators', CRM_Core_DAO::acceptedSQLOperators());
  51
  52     // List example directories
  53     global $civicrm_root;
  54     $examples = array();
  55     foreach (scandir(CRM_Utils_file::addTrailingSlash($civicrm_root, '/') . 'api/v3/examples') as $item) {
  56       if ($item && strpos($item, '.') === FALSE) {
  57         $examples[] = $item;
  58       }
  59     }
  60     $this->assign('examples', $examples);
  61
  62     return parent::run();
  63   }
  64
  65   /**
  66    * Get user context.
  67    *
  68    * @return string
  69    *   user context.
  70    */
  71   public function userContext() {
  72     return 'civicrm/api';
  73   }
  74
  75   /**
  76    * AJAX callback to fetch examples
  77    */
  78   public static function getExampleFile() {
  79     global $civicrm_root;
  80     $basePath = CRM_Utils_file::addTrailingSlash($civicrm_root, '/');
  81     if (!empty($_GET['entity']) && strpos($_GET['entity'], '.') === FALSE) {
  82       $examples = array();
  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);
  87         }
  88       }
  89       CRM_Utils_JSON::output($examples);
  90     }
  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);
  95       }
  96       else {
  97         echo "Not found.";
  98       }
  99       CRM_Utils_System::civiExit();
 100     }
 101     CRM_Utils_System::permissionDenied();
 102   }
 103
 104   /**
 105    * Ajax callback to display code docs
 106    */
 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);
 114       $result = array(
 115         'doc' => $doc ? self::formatDocBlock($doc[0]) : 'Not found.',
 116         'code' => $doc ? $doc[1] : NULL,
 117         'file' => $doc ? $doc[2] : NULL,
 118       );
 119       if (!$action) {
 120         $actions = civicrm_api3($entity, 'getactions');
 121         $result['actions'] = CRM_Utils_Array::makeNonAssociative(array_combine($actions['values'], $actions['values']));
 122       }
 123       CRM_Utils_JSON::output($result);
 124     }
 125     CRM_Utils_System::permissionDenied();
 126   }
 127
 128   /**
 129    * @param string $entity
 130    * @param string|null $action
 131    * @return array|bool
 132    *   [docblock, code]
 133    */
 134   private static function getDocBlock($entity, $action) {
 135     if (!$entity) {
 136       return FALSE;
 137     }
 138     $file = "api/v3/$entity.php";
 139     $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH);
 140     if (!$contents) {
 141       // Api does not exist
 142       return FALSE;
 143     }
 144     $docblock = $code = array();
 145     // Fetch docblock for the api file
 146     if (!$action) {
 147       if (preg_match('#/\*\*\n.*?\n \*/\n#s', $contents, $docblock)) {
 148         return array($docblock[0], NULL, $file);
 149       }
 150     }
 151     // Fetch block for a specific action
 152     else {
 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) {
 159         $file = $actionFile;
 160         $contents = $actionFileContents;
 161       }
 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);
 167         if (!$contents) {
 168           $file = "api/v3/Generic.php";
 169           $contents = file_get_contents($file, FILE_USE_INCLUDE_PATH);
 170         }
 171       }
 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);
 176       }
 177     }
 178   }
 179
 180   /**
 181    * Format a docblock to be a bit more readable
 182    * Not a proper doc parser... patches welcome :)
 183    *
 184    * @param string $text
 185    * @return string
 186    */
 187   private static function formatDocBlock($text) {
 188     // Get rid of comment stars
 189     $text = str_replace(array("\n * ", "\n *\n", "\n */\n", "/**\n"), array("\n", "\n\n", '', ''), $text);
 190
 191     // Format for html
 192     $text = htmlspecialchars($text);
 193
 194     // Extract code blocks - save for later to skip html conversion
 195     $code = array();
 196     preg_match_all('#@code(.*?)@endcode#is', $text, $code);
 197     $text = preg_replace('#@code.*?@endcode#is', '<pre></pre>', $text);
 198
 199     // Convert @annotations to titles
 200     $text = preg_replace_callback(
 201       '#^[ ]*@(\w+)([ ]*)#m',
 202       function($matches) {
 203         return "<strong>" . ucfirst($matches[1]) . "</strong>" . (empty($matches[2]) ? '' : ': ');
 204       },
 205       $text);
 206
 207     // Preserve indentation
 208     $text = str_replace("\n ", "\n&nbsp;&nbsp;&nbsp;&nbsp;", $text);
 209
 210     // Convert newlines
 211     $text = nl2br($text);
 212
 213     // Add unformatted code blocks back in
 214     if ($code && !empty($code[1])) {
 215       foreach ($code[1] as $block) {
 216         $text = preg_replace('#<pre></pre>#', "<pre>$block</pre>", $text, 1);
 217       }
 218     }
 219     return $text;
 220   }
 221
 222 }