includes/hooks.inc

   1 <?php
   2 /**********************************************************************
   3     Copyright (C) FrontAccounting, LLC.
   4         Released under the terms of the GNU General Public License, GPL,
   5         as published by the Free Software Foundation, either version 3
   6         of the License, or (at your option) any later version.
   7     This program is distributed in the hope that it will be useful,
   8     but WITHOUT ANY WARRANTY; without even the implied warranty of
   9     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  10     See the License here <http://www.gnu.org/licenses/gpl-3.0.html>.
  11 ***********************************************************************/
  12 //
  13 // FrontAccounting extension modules integration.
  14 // This file is included in session.inc even before session is started,
  15 // and includes hooks.php connector files from all installed extensions.
  16 // To make hooks active install_hooks() have to be called after interface
  17 // language is set.
  18 //
  19 // To find how various hooks are processed look into respective hook_* functions below.
  20 //
  21 class hooks {
  22         var $module_name; // extension module name.
  23
  24         //
  25         // Helper for updating databases with extension scheme
  26         //
  27         // $comp can be company number, -1 for all,
  28         // $updates - table of filename => array(table, field, property)
  29         // $check_only - don't update database, check table/field/property existence only
  30         //
  31         function update_databases($comp, $updates, $check_only=false)
  32         {
  33                 global $db_connections, $path_to_root;
  34
  35                 if ($comp == -1)
  36                         $conn = $db_connections;
  37                 else
  38                         $conn = array( $comp => $db_connections[$comp]);
  39                 $result = true;
  40
  41                 foreach($conn as $comp => $con) {
  42                         set_global_connection($comp);
  43                         foreach($updates as $file => $update) {
  44                                 $table = @$update[0];
  45                                 $field = @$update[1];
  46                                 $properties = @$update[2];
  47
  48                                 $ok = check_table($con['tbpref'], $table, $field, $properties) == 0;
  49
  50                                 if (!$check_only && !$ok) {
  51                                         $ok = db_import($path_to_root.'/modules/'.$this->module_name.'/sql/'.$file,
  52                                                 $con);
  53                                 }
  54                                 $result &= $ok;
  55                                 if (!$result)
  56                                         break;
  57                         }
  58                         db_close();
  59                         if (!$result)
  60                                 break;
  61                 }
  62                 set_global_connection(0); // return to siteadmin account
  63
  64                 return $result;
  65         }
  66         //
  67         //      Install additional tabs provided by extension
  68         //
  69         function install_tabs($app)
  70         {
  71 //              $app->add_application(new example_class); // add menu tab defined by example_class
  72         }
  73         //
  74         //      Install additonal menu options provided by extension
  75         //
  76         function install_options($app)
  77         {
  78 //              global $path_to_root;
  79 //
  80 //              switch($app->id) {
  81 //                      case 'orders':
  82 //                              $app->add_rapp_function( 0, _("&Example option"),
  83 //                                      $path_to_root.'/modules/example/example.php?', 'SA_OPEN');
  84 //              }
  85         }
  86
  87         function install_access()
  88         {
  89 //              $security_areas['SA_EXAMPLE'] = array(SS_EXAMPLE|100, _("Example security area."));
  90 //
  91 //              $security_sections = array(SS_EXAMPLE => _("Example module implementation"));
  92 //
  93 //              return array($security_areas, $security_sections);
  94         }
  95
  96         //
  97         // Price in words. $doc_type is set to document type and can be used to suppress
  98         // price in words printing for selected document types.
  99         // Used instead of built in simple english price_in_words() function.
 100         //
 101         //      Returns: amount in words as string.
 102
 103         function price_in_words($amount, $doc_type)
 104         {
 105         }
 106
 107         //
 108         // Exchange rate currency $curr as on date $date.
 109         // Keep in mind FA has internally implemented 3 exrate providers
 110         // If any of them supports your currency, you can simply use function below
 111         // with apprioprate provider set, otherwise implement your own.
 112         // Returns: $curr value in home currency units as a real number.
 113
 114         function retrieve_exrate($curr, $date)
 115         {
 116 //              $provider = 'ECB'; // 'ECB', 'YAHOO' or 'GOOGLE'
 117 //              return get_extern_rate($curr, $provider, $date);
 118                 return null;
 119         }
 120
 121         // Generic function called at the end of Tax Report (report 709)
 122         // Can be used e.g. for special database updates on every report printing
 123         // or to print special tax report footer
 124         //
 125         // Returns: nothing
 126         function tax_report_done()
 127         {
 128         }
 129         // Following database transaction hooks akcepts array of parameters:
 130         // 'cart' => transaction data
 131         // 'trans_type' => transaction type
 132
 133         function db_prewrite(&$cart, $trans_type)
 134         {
 135                 return true;
 136         }
 137
 138         function db_postwrite(&$cart, $trans_type)
 139         {
 140                 return true;
 141         }
 142
 143         function db_prevoid($trans_type, $trans_no)
 144         {
 145                 return true;
 146         }
 147         /*
 148                 This method is called after module install.
 149         */
 150         function install_extension($check_only=true)
 151         {
 152                 return true;
 153         }
 154         /*
 155                 This method is called after module uninstall.
 156         */
 157         function uninstall_extension($check_only=true)
 158         {
 159                 return true;
 160         }
 161         /*
 162                 This method is called on extension activation for company.
 163         */
 164         function activate_extension($company, $check_only=true)
 165         {
 166                 return true;
 167         }
 168         /*
 169                 This method is called when extension is deactivated for company.
 170         */
 171         function deactivate_extension($company, $check_only=true)
 172         {
 173                 return true;
 174         }
 175 }
 176
 177 /*
 178         Installs hooks provided by extension modules
 179 */
 180 function install_hooks()
 181 {
 182         global $path_to_root, $Hooks, $installed_extensions;
 183
 184         $Hooks = array();
 185
 186         // include current language related $Hooks object if locale file exists
 187         if (file_exists($path_to_root . "/lang/".$_SESSION['language']->code."/locale.inc"))
 188         {
 189                 include_once($path_to_root . "/lang/".$_SESSION['language']->code."/locale.inc");
 190                 $code = $_SESSION['language']->code;
 191                 $hook_class = 'hooks_'.$code;
 192                 $Hooks[$code] = new $hook_class;
 193                 unset($code, $hook_class);
 194         }
 195         // install hooks provided by active extensions
 196         foreach($installed_extensions as $ext) {
 197                         $hook_class = 'hooks_'.$ext['package'];
 198                         if ($ext['active'] && class_exists($hook_class)) {
 199                                 $Hooks[$ext['package']] = new $hook_class;
 200                         }
 201         }
 202 }
 203 /*
 204         Non active hooks are not included in $Hooks array, so we can use special function to
 205         activate.
 206 */
 207 function activate_hooks($ext, $comp)
 208 {
 209         global $Hooks;
 210
 211         $hooks = @$Hooks[$ext];
 212         if (!$hooks) {
 213                 $hookclass = 'hooks_'.$ext;
 214                 if (class_exists($hookclass))
 215                         $hooks = new $hookclass;
 216                 else
 217                         return true; // extension does not have hooks file
 218         }
 219         if (!$hooks)
 220                 return false;
 221         else
 222                 return $hooks->activate_extension($comp, false);
 223 }
 224 /*
 225         Calls hook $method defined in extension $ext (if any)
 226 */
 227 function hook_invoke($ext, $method, &$data, $opts=null)
 228 {
 229
 230         global $Hooks;
 231
 232         $ret = null;
 233         if (isset($Hooks[$ext]) && method_exists($Hooks[$ext], $method)) {
 234                 set_ext_domain('modules/'.$ext);
 235                 $ret = $Hooks[$ext]->$method($data, $opts);
 236                 set_ext_domain();
 237         }
 238         return $ret;
 239 }
 240
 241 /*
 242         Calls hook $methods defined in all extensions (if any)
 243 */
 244 function hook_invoke_all($method, &$data, $opts=null)
 245 {
 246
 247         global $Hooks;
 248
 249         $result = array();
 250         foreach($Hooks as $ext => $hook)
 251                 if (method_exists($hook, $method)) {
 252                         set_ext_domain('modules/'.$ext);
 253                         $result = $hook->$method($data, $opts);
 254                         if (isset($result) && is_array($result)) {
 255                                 $return = array_merge_recursive($return, $result);
 256                         } else if (isset($result)) {
 257                                 $return[] = $result;
 258                                 }
 259                 }
 260         set_ext_domain();
 261         return $result;
 262 }
 263 /*
 264         Returns first non-null result returned from hook.
 265 */
 266 function hook_invoke_first($method, &$data, $opts=null)
 267 {
 268
 269         global $Hooks;
 270
 271         $result = null;
 272         foreach($Hooks as $ext => $hook) {
 273                 if (method_exists($hook, $method)) {
 274                         set_ext_domain('modules/'.$ext);
 275                         $result = $hook->$method($data, $opts);
 276                         if (isset($result))
 277                                 break;
 278                 }
 279         }
 280         set_ext_domain();
 281         return $result;
 282 }
 283 /*
 284         Returns result of last hook installed. Helps implement hooks overriding by
 285         extensions installed later.
 286
 287 */
 288 function hook_invoke_last($method, &$data, $opts=null)
 289 {
 290
 291         global $Hooks;
 292
 293         $found = false;
 294         foreach($Hooks as $ext => $hook) {
 295                 if (method_exists($hook, $method)) {
 296                         $found = $ext;
 297                 }
 298         }
 299         $ret = null;
 300         if ($found) {
 301                 set_ext_domain('modules/'.$found);
 302                 $ret = $Hooks[$found]->$method($data, $opts);
 303                 set_ext_domain();
 304         }
 305         return $ret;
 306 }
 307 //------------------------------------------------------------------------------------------
 308 //      Database transaction hooks.
 309 //      $type - type of transaction (simplifies cart processing)
 310 //      $cart - transaction cart
 311 //      $args is optional array of parameters
 312 //
 313 // For FA 2.3 prewrite, postwrite and prevoid hooks are implemented for following transaction types:
 314 //
 315 // ST_BANKPAYMENT, ST_BANKDEPOSIT, ST_BANKTRANSFER,
 316 // ST_SALESORDER, ST_SALESQUOTE, ST_SALESINVOICE, ST_CUSTCREDIT, ST_CUSTPAYMENT, ST_CUSTDELIVERY,
 317 // ST_LOCTRANSFER, ST_INVADJUST,
 318 // ST_PURCHORDER, ST_SUPPINVOICE, ST_SUPPCREDIT, ST_SUPPAYMENT, ST_SUPPRECEIVE,
 319 // ST_WORKORDER, ST_MANUISSUE, ST_MANURECEIVE,
 320
 321 /*
 322         Invoked after transaction has been read from database to cart.
 323         Not implemented yet.
 324 */
 325 //function hook_db_postread(&$cart, $type)
 326 //{
 327 //      hook_invoke_all('db_postread', $cart, $type);
 328 //}
 329
 330 /*
 331         Invoked before transaction is written to database.
 332 */
 333 function hook_db_prewrite(&$cart, $type)
 334 {
 335         return hook_invoke_all('db_prewrite', $cart, $type);
 336 }
 337
 338 /*
 339         Invoked after transaction has been written to database.
 340 */
 341 function hook_db_postwrite(&$cart, $type)
 342 {
 343         return hook_invoke_all('db_postwrite', $cart, $type);
 344 }
 345 /*
 346         Invoked before transaction is voided
 347 */
 348 function hook_db_prevoid($type, $type_no)
 349 {
 350         return hook_invoke_all('db_prevoid', $type, $type_no);
 351 }
 352
 353 //-------------------------------------------------------------------------------------------
 354 //
 355 //      Various hooks
 356 //
 357 //      Alternative exchange rates feeds.
 358 //
 359 function hook_retrieve_exrate($currency, $date)
 360 {
 361         return hook_invoke_last('retrieve_exrate', $currency, $date);
 362 }
 363 //
 364 // Generic function called at the end of Tax Report (report 709)
 365 //
 366 function hook_tax_report_done()
 367 {
 368         return hook_invoke_all('tax_report_done', $dummy);
 369 }
 370 //
 371 //      Amount in words displayed on various documents (especially sales invoice)
 372 //
 373 function hook_price_in_words($amount, $document)
 374 {
 375         return hook_invoke_last('price_in_words', $amount, $document);
 376 }
 377 //
 378 //      Session handling hook. This is special case of hook class which have to be run before session is started.
 379 //      If fa_session_manager class is defined in any installed extension, this class provides session handling
 380 //      for application, otherwise standard php session handling is used.
 381 //
 382 function hook_session_start($company)
 383 {
 384         if (class_exists('fa_session_manager')) {
 385                 global $SessionManager;
 386                 $SessionManager = new fa_session_manager($company);
 387                 return $SessionManager->installed;
 388         }
 389         return false;
 390 }