plugins/CasAuthentication/extlib/CAS.php

   1 <?php
   2
   3 // commented in 0.4.22-RC2 for Sylvain Derosiaux
   4 // error_reporting(E_ALL ^ E_NOTICE);
   5
   6 //
   7 // hack by Vangelis Haniotakis to handle the absence of $_SERVER['REQUEST_URI'] in IIS
   8 //
   9 if (!$_SERVER['REQUEST_URI']) {
  10         $_SERVER['REQUEST_URI'] = $_SERVER['SCRIPT_NAME'].'?'.$_SERVER['QUERY_STRING'];
  11 }
  12
  13 //
  14 // another one by Vangelis Haniotakis also to make phpCAS work with PHP5
  15 //
  16 if (version_compare(PHP_VERSION,'5','>=')) {
  17         require_once(dirname(__FILE__).'/CAS/domxml-php4-php5.php');
  18 }
  19
  20 /**
  21  * @file CAS/CAS.php
  22  * Interface class of the phpCAS library
  23  *
  24  * @ingroup public
  25  */
  26
  27 // ########################################################################
  28 //  CONSTANTS
  29 // ########################################################################
  30
  31 // ------------------------------------------------------------------------
  32 //  CAS VERSIONS
  33 // ------------------------------------------------------------------------
  34
  35 /**
  36  * phpCAS version. accessible for the user by phpCAS::getVersion().
  37  */
  38 define('PHPCAS_VERSION','1.0.1');
  39
  40 // ------------------------------------------------------------------------
  41 //  CAS VERSIONS
  42 // ------------------------------------------------------------------------
  43  /**
  44   * @addtogroup public
  45   * @{
  46   */
  47
  48 /**
  49  * CAS version 1.0
  50  */
  51 define("CAS_VERSION_1_0",'1.0');
  52 /*!
  53  * CAS version 2.0
  54  */
  55 define("CAS_VERSION_2_0",'2.0');
  56
  57 /** @} */
  58  /**
  59   * @addtogroup publicPGTStorage
  60   * @{
  61   */
  62 // ------------------------------------------------------------------------
  63 //  FILE PGT STORAGE
  64 // ------------------------------------------------------------------------
  65  /**
  66   * Default path used when storing PGT's to file
  67   */
  68 define("CAS_PGT_STORAGE_FILE_DEFAULT_PATH",'/tmp');
  69 /**
  70  * phpCAS::setPGTStorageFile()'s 2nd parameter to write plain text files
  71  */
  72 define("CAS_PGT_STORAGE_FILE_FORMAT_PLAIN",'plain');
  73 /**
  74  * phpCAS::setPGTStorageFile()'s 2nd parameter to write xml files
  75  */
  76 define("CAS_PGT_STORAGE_FILE_FORMAT_XML",'xml');
  77 /**
  78  * Default format used when storing PGT's to file
  79  */
  80 define("CAS_PGT_STORAGE_FILE_DEFAULT_FORMAT",CAS_PGT_STORAGE_FILE_FORMAT_PLAIN);
  81 // ------------------------------------------------------------------------
  82 //  DATABASE PGT STORAGE
  83 // ------------------------------------------------------------------------
  84  /**
  85   * default database type when storing PGT's to database
  86   */
  87 define("CAS_PGT_STORAGE_DB_DEFAULT_DATABASE_TYPE",'mysql');
  88 /**
  89  * default host when storing PGT's to database
  90  */
  91 define("CAS_PGT_STORAGE_DB_DEFAULT_HOSTNAME",'localhost');
  92 /**
  93  * default port when storing PGT's to database
  94  */
  95 define("CAS_PGT_STORAGE_DB_DEFAULT_PORT",'');
  96 /**
  97  * default database when storing PGT's to database
  98  */
  99 define("CAS_PGT_STORAGE_DB_DEFAULT_DATABASE",'phpCAS');
 100 /**
 101  * default table when storing PGT's to database
 102  */
 103 define("CAS_PGT_STORAGE_DB_DEFAULT_TABLE",'pgt');
 104
 105 /** @} */
 106 // ------------------------------------------------------------------------
 107 // SERVICE ACCESS ERRORS
 108 // ------------------------------------------------------------------------
 109  /**
 110   * @addtogroup publicServices
 111   * @{
 112   */
 113
 114 /**
 115  * phpCAS::service() error code on success
 116  */
 117 define("PHPCAS_SERVICE_OK",0);
 118 /**
 119  * phpCAS::service() error code when the PT could not retrieve because
 120  * the CAS server did not respond.
 121  */
 122 define("PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE",1);
 123 /**
 124  * phpCAS::service() error code when the PT could not retrieve because
 125  * the response of the CAS server was ill-formed.
 126  */
 127 define("PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE",2);
 128 /**
 129  * phpCAS::service() error code when the PT could not retrieve because
 130  * the CAS server did not want to.
 131  */
 132 define("PHPCAS_SERVICE_PT_FAILURE",3);
 133 /**
 134  * phpCAS::service() error code when the service was not available.
 135  */
 136 define("PHPCAS_SERVICE_NOT AVAILABLE",4);
 137
 138 /** @} */
 139 // ------------------------------------------------------------------------
 140 //  LANGUAGES
 141 // ------------------------------------------------------------------------
 142  /**
 143   * @addtogroup publicLang
 144   * @{
 145   */
 146
 147 define("PHPCAS_LANG_ENGLISH",    'english');
 148 define("PHPCAS_LANG_FRENCH",     'french');
 149 define("PHPCAS_LANG_GREEK",      'greek');
 150 define("PHPCAS_LANG_GERMAN",     'german');
 151 define("PHPCAS_LANG_JAPANESE",   'japanese');
 152 define("PHPCAS_LANG_SPANISH",    'spanish');
 153 define("PHPCAS_LANG_CATALAN",    'catalan');
 154
 155 /** @} */
 156
 157 /**
 158  * @addtogroup internalLang
 159  * @{
 160  */
 161
 162 /**
 163  * phpCAS default language (when phpCAS::setLang() is not used)
 164  */
 165 define("PHPCAS_LANG_DEFAULT", PHPCAS_LANG_ENGLISH);
 166
 167 /** @} */
 168 // ------------------------------------------------------------------------
 169 //  DEBUG
 170 // ------------------------------------------------------------------------
 171  /**
 172   * @addtogroup publicDebug
 173   * @{
 174   */
 175
 176 /**
 177  * The default directory for the debug file under Unix.
 178  */
 179 define('DEFAULT_DEBUG_DIR','/tmp/');
 180
 181 /** @} */
 182 // ------------------------------------------------------------------------
 183 //  MISC
 184 // ------------------------------------------------------------------------
 185  /**
 186   * @addtogroup internalMisc
 187   * @{
 188   */
 189
 190 /**
 191  * This global variable is used by the interface class phpCAS.
 192  *
 193  * @hideinitializer
 194  */
 195 $GLOBALS['PHPCAS_CLIENT']  = null;
 196
 197 /**
 198  * This global variable is used to store where the initializer is called from
 199  * (to print a comprehensive error in case of multiple calls).
 200  *
 201  * @hideinitializer
 202  */
 203 $GLOBALS['PHPCAS_INIT_CALL'] = array('done' => FALSE,
 204         'file' => '?',
 205         'line' => -1,
 206         'method' => '?');
 207
 208 /**
 209  * This global variable is used to store where the method checking
 210  * the authentication is called from (to print comprehensive errors)
 211  *
 212  * @hideinitializer
 213  */
 214 $GLOBALS['PHPCAS_AUTH_CHECK_CALL'] = array('done' => FALSE,
 215         'file' => '?',
 216         'line' => -1,
 217         'method' => '?',
 218         'result' => FALSE);
 219
 220 /**
 221  * This global variable is used to store phpCAS debug mode.
 222  *
 223  * @hideinitializer
 224  */
 225 $GLOBALS['PHPCAS_DEBUG']  = array('filename' => FALSE,
 226         'indent' => 0,
 227         'unique_id' => '');
 228
 229 /** @} */
 230
 231 // ########################################################################
 232 //  CLIENT CLASS
 233 // ########################################################################
 234
 235 // include client class
 236 include_once(dirname(__FILE__).'/CAS/client.php');
 237
 238 // ########################################################################
 239 //  INTERFACE CLASS
 240 // ########################################################################
 241
 242 /**
 243  * @class phpCAS
 244  * The phpCAS class is a simple container for the phpCAS library. It provides CAS
 245  * authentication for web applications written in PHP.
 246  *
 247  * @ingroup public
 248  * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>
 249  *
 250  * \internal All its methods access the same object ($PHPCAS_CLIENT, declared
 251  * at the end of CAS/client.php).
 252  */
 253
 254
 255
 256 class phpCAS
 257 {
 258
 259         // ########################################################################
 260         //  INITIALIZATION
 261         // ########################################################################
 262
 263         /**
 264          * @addtogroup publicInit
 265          * @{
 266          */
 267
 268         /**
 269          * phpCAS client initializer.
 270          * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
 271          * called, only once, and before all other methods (except phpCAS::getVersion()
 272          * and phpCAS::setDebug()).
 273          *
 274          * @param $server_version the version of the CAS server
 275          * @param $server_hostname the hostname of the CAS server
 276          * @param $server_port the port the CAS server is running on
 277          * @param $server_uri the URI the CAS server is responding on
 278          * @param $start_session Have phpCAS start PHP sessions (default true)
 279          *
 280          * @return a newly created CASClient object
 281          */
 282         function client($server_version,
 283                                         $server_hostname,
 284                                         $server_port,
 285                                         $server_uri,
 286                                         $start_session = true)
 287                 {
 288                 global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
 289
 290                 phpCAS::traceBegin();
 291                 if ( is_object($PHPCAS_CLIENT) ) {
 292                         phpCAS::error($PHPCAS_INIT_CALL['method'].'() has already been called (at '.$PHPCAS_INIT_CALL['file'].':'.$PHPCAS_INIT_CALL['line'].')');
 293                 }
 294                 if ( gettype($server_version) != 'string' ) {
 295                         phpCAS::error('type mismatched for parameter $server_version (should be `string\')');
 296                 }
 297                 if ( gettype($server_hostname) != 'string' ) {
 298                         phpCAS::error('type mismatched for parameter $server_hostname (should be `string\')');
 299                 }
 300                 if ( gettype($server_port) != 'integer' ) {
 301                         phpCAS::error('type mismatched for parameter $server_port (should be `integer\')');
 302                 }
 303                 if ( gettype($server_uri) != 'string' ) {
 304                         phpCAS::error('type mismatched for parameter $server_uri (should be `string\')');
 305                 }
 306
 307                 // store where the initialzer is called from
 308                 $dbg = phpCAS::backtrace();
 309                 $PHPCAS_INIT_CALL = array('done' => TRUE,
 310                         'file' => $dbg[0]['file'],
 311                         'line' => $dbg[0]['line'],
 312                         'method' => __CLASS__.'::'.__FUNCTION__);
 313
 314                 // initialize the global object $PHPCAS_CLIENT
 315                 $PHPCAS_CLIENT = new CASClient($server_version,FALSE/*proxy*/,$server_hostname,$server_port,$server_uri,$start_session);
 316                 phpCAS::traceEnd();
 317                 }
 318
 319         /**
 320          * phpCAS proxy initializer.
 321          * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
 322          * called, only once, and before all other methods (except phpCAS::getVersion()
 323          * and phpCAS::setDebug()).
 324          *
 325          * @param $server_version the version of the CAS server
 326          * @param $server_hostname the hostname of the CAS server
 327          * @param $server_port the port the CAS server is running on
 328          * @param $server_uri the URI the CAS server is responding on
 329          * @param $start_session Have phpCAS start PHP sessions (default true)
 330          *
 331          * @return a newly created CASClient object
 332          */
 333         function proxy($server_version,
 334                                    $server_hostname,
 335                                    $server_port,
 336                                    $server_uri,
 337                                    $start_session = true)
 338                 {
 339                 global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
 340
 341                 phpCAS::traceBegin();
 342                 if ( is_object($PHPCAS_CLIENT) ) {
 343                         phpCAS::error($PHPCAS_INIT_CALL['method'].'() has already been called (at '.$PHPCAS_INIT_CALL['file'].':'.$PHPCAS_INIT_CALL['line'].')');
 344                 }
 345                 if ( gettype($server_version) != 'string' ) {
 346                         phpCAS::error('type mismatched for parameter $server_version (should be `string\')');
 347                 }
 348                 if ( gettype($server_hostname) != 'string' ) {
 349                         phpCAS::error('type mismatched for parameter $server_hostname (should be `string\')');
 350                 }
 351                 if ( gettype($server_port) != 'integer' ) {
 352                         phpCAS::error('type mismatched for parameter $server_port (should be `integer\')');
 353                 }
 354                 if ( gettype($server_uri) != 'string' ) {
 355                         phpCAS::error('type mismatched for parameter $server_uri (should be `string\')');
 356                 }
 357
 358                 // store where the initialzer is called from
 359                 $dbg = phpCAS::backtrace();
 360                 $PHPCAS_INIT_CALL = array('done' => TRUE,
 361                         'file' => $dbg[0]['file'],
 362                         'line' => $dbg[0]['line'],
 363                         'method' => __CLASS__.'::'.__FUNCTION__);
 364
 365                 // initialize the global object $PHPCAS_CLIENT
 366                 $PHPCAS_CLIENT = new CASClient($server_version,TRUE/*proxy*/,$server_hostname,$server_port,$server_uri,$start_session);
 367                 phpCAS::traceEnd();
 368                 }
 369
 370         /** @} */
 371         // ########################################################################
 372         //  DEBUGGING
 373         // ########################################################################
 374
 375         /**
 376          * @addtogroup publicDebug
 377          * @{
 378          */
 379
 380         /**
 381          * Set/unset debug mode
 382          *
 383          * @param $filename the name of the file used for logging, or FALSE to stop debugging.
 384          */
 385         function setDebug($filename='')
 386                 {
 387                 global $PHPCAS_DEBUG;
 388
 389                 if ( $filename != FALSE && gettype($filename) != 'string' ) {
 390                         phpCAS::error('type mismatched for parameter $dbg (should be FALSE or the name of the log file)');
 391                 }
 392
 393                 if ( empty($filename) ) {
 394                         if ( preg_match('/^Win.*/',getenv('OS')) ) {
 395                                 if ( isset($_ENV['TMP']) ) {
 396                                         $debugDir = $_ENV['TMP'].'/';
 397                                 } else if ( isset($_ENV['TEMP']) ) {
 398                                         $debugDir = $_ENV['TEMP'].'/';
 399                                 } else {
 400                                         $debugDir = '';
 401                                 }
 402                         } else {
 403                                 $debugDir = DEFAULT_DEBUG_DIR;
 404                         }
 405                         $filename = $debugDir . 'phpCAS.log';
 406                 }
 407
 408                 if ( empty($PHPCAS_DEBUG['unique_id']) ) {
 409                         $PHPCAS_DEBUG['unique_id'] = substr(strtoupper(md5(uniqid(''))),0,4);
 410                 }
 411
 412                 $PHPCAS_DEBUG['filename'] = $filename;
 413
 414                 phpCAS::trace('START ******************');
 415                 }
 416
 417         /** @} */
 418         /**
 419          * @addtogroup internalDebug
 420          * @{
 421          */
 422
 423         /**
 424          * This method is a wrapper for debug_backtrace() that is not available
 425          * in all PHP versions (>= 4.3.0 only)
 426          */
 427         function backtrace()
 428                 {
 429                 if ( function_exists('debug_backtrace') ) {
 430                         return debug_backtrace();
 431                 } else {
 432                         // poor man's hack ... but it does work ...
 433                         return array();
 434                 }
 435                 }
 436
 437         /**
 438          * Logs a string in debug mode.
 439          *
 440          * @param $str the string to write
 441          *
 442          * @private
 443          */
 444         function log($str)
 445                 {
 446                 $indent_str = ".";
 447                 global $PHPCAS_DEBUG;
 448
 449                 if ( $PHPCAS_DEBUG['filename'] ) {
 450                         for ($i=0;$i<$PHPCAS_DEBUG['indent'];$i++) {
 451                                 $indent_str .= '|    ';
 452                         }
 453                         error_log($PHPCAS_DEBUG['unique_id'].' '.$indent_str.$str."\n",3,$PHPCAS_DEBUG['filename']);
 454                 }
 455
 456                 }
 457
 458         /**
 459          * This method is used by interface methods to print an error and where the function
 460          * was originally called from.
 461          *
 462          * @param $msg the message to print
 463          *
 464          * @private
 465          */
 466         function error($msg)
 467                 {
 468                 $dbg = phpCAS::backtrace();
 469                 $function = '?';
 470                 $file = '?';
 471                 $line = '?';
 472                 if ( is_array($dbg) ) {
 473                         for ( $i=1; $i<sizeof($dbg); $i++) {
 474                                 if ( is_array($dbg[$i]) ) {
 475                                         if ( $dbg[$i]['class'] == __CLASS__ ) {
 476                                                 $function = $dbg[$i]['function'];
 477                                                 $file = $dbg[$i]['file'];
 478                                                 $line = $dbg[$i]['line'];
 479                                         }
 480                                 }
 481                         }
 482                 }
 483                 echo "<br />\n<b>phpCAS error</b>: <font color=\"FF0000\"><b>".__CLASS__."::".$function.'(): '.htmlentities($msg)."</b></font> in <b>".$file."</b> on line <b>".$line."</b><br />\n";
 484                 phpCAS::trace($msg);
 485                 phpCAS::traceExit();
 486                 exit();
 487                 }
 488
 489         /**
 490          * This method is used to log something in debug mode.
 491          */
 492         function trace($str)
 493                 {
 494                 $dbg = phpCAS::backtrace();
 495                 phpCAS::log($str.' ['.basename($dbg[1]['file']).':'.$dbg[1]['line'].']');
 496                 }
 497
 498         /**
 499          * This method is used to indicate the start of the execution of a function in debug mode.
 500          */
 501         function traceBegin()
 502                 {
 503                 global $PHPCAS_DEBUG;
 504
 505                 $dbg = phpCAS::backtrace();
 506                 $str = '=> ';
 507                 if ( !empty($dbg[2]['class']) ) {
 508                         $str .= $dbg[2]['class'].'::';
 509                 }
 510                 $str .= $dbg[2]['function'].'(';
 511                 if ( is_array($dbg[2]['args']) ) {
 512                         foreach ($dbg[2]['args'] as $index => $arg) {
 513                                 if ( $index != 0 ) {
 514                                         $str .= ', ';
 515                                 }
 516                                 $str .= str_replace("\n","",var_export($arg,TRUE));
 517                         }
 518                 }
 519                 $str .= ') ['.basename($dbg[2]['file']).':'.$dbg[2]['line'].']';
 520                 phpCAS::log($str);
 521                 $PHPCAS_DEBUG['indent'] ++;
 522                 }
 523
 524         /**
 525          * This method is used to indicate the end of the execution of a function in debug mode.
 526          *
 527          * @param $res the result of the function
 528          */
 529         function traceEnd($res='')
 530                 {
 531                 global $PHPCAS_DEBUG;
 532
 533                 $PHPCAS_DEBUG['indent'] --;
 534                 $dbg = phpCAS::backtrace();
 535                 $str = '';
 536                 $str .= '<= '.str_replace("\n","",var_export($res,TRUE));
 537                 phpCAS::log($str);
 538                 }
 539
 540         /**
 541          * This method is used to indicate the end of the execution of the program
 542          */
 543         function traceExit()
 544                 {
 545                 global $PHPCAS_DEBUG;
 546
 547                 phpCAS::log('exit()');
 548                 while ( $PHPCAS_DEBUG['indent'] > 0 ) {
 549                         phpCAS::log('-');
 550                         $PHPCAS_DEBUG['indent'] --;
 551                 }
 552                 }
 553
 554         /** @} */
 555         // ########################################################################
 556         //  INTERNATIONALIZATION
 557         // ########################################################################
 558         /**
 559          * @addtogroup publicLang
 560          * @{
 561          */
 562
 563         /**
 564          * This method is used to set the language used by phpCAS.
 565          * @note Can be called only once.
 566          *
 567          * @param $lang a string representing the language.
 568          *
 569          * @sa PHPCAS_LANG_FRENCH, PHPCAS_LANG_ENGLISH
 570          */
 571         function setLang($lang)
 572                 {
 573                 global $PHPCAS_CLIENT;
 574                 if ( !is_object($PHPCAS_CLIENT) ) {
 575                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 576                 }
 577                 if ( gettype($lang) != 'string' ) {
 578                         phpCAS::error('type mismatched for parameter $lang (should be `string\')');
 579                 }
 580                 $PHPCAS_CLIENT->setLang($lang);
 581                 }
 582
 583         /** @} */
 584         // ########################################################################
 585         //  VERSION
 586         // ########################################################################
 587         /**
 588          * @addtogroup public
 589          * @{
 590          */
 591
 592         /**
 593          * This method returns the phpCAS version.
 594          *
 595          * @return the phpCAS version.
 596          */
 597         function getVersion()
 598                 {
 599                 return PHPCAS_VERSION;
 600                 }
 601
 602         /** @} */
 603         // ########################################################################
 604         //  HTML OUTPUT
 605         // ########################################################################
 606         /**
 607          * @addtogroup publicOutput
 608          * @{
 609          */
 610
 611         /**
 612          * This method sets the HTML header used for all outputs.
 613          *
 614          * @param $header the HTML header.
 615          */
 616         function setHTMLHeader($header)
 617                 {
 618                 global $PHPCAS_CLIENT;
 619                 if ( !is_object($PHPCAS_CLIENT) ) {
 620                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 621                 }
 622                 if ( gettype($header) != 'string' ) {
 623                         phpCAS::error('type mismatched for parameter $header (should be `string\')');
 624                 }
 625                 $PHPCAS_CLIENT->setHTMLHeader($header);
 626                 }
 627
 628         /**
 629          * This method sets the HTML footer used for all outputs.
 630          *
 631          * @param $footer the HTML footer.
 632          */
 633         function setHTMLFooter($footer)
 634                 {
 635                 global $PHPCAS_CLIENT;
 636                 if ( !is_object($PHPCAS_CLIENT) ) {
 637                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 638                 }
 639                 if ( gettype($footer) != 'string' ) {
 640                         phpCAS::error('type mismatched for parameter $footer (should be `string\')');
 641                 }
 642                 $PHPCAS_CLIENT->setHTMLFooter($footer);
 643                 }
 644
 645         /** @} */
 646         // ########################################################################
 647         //  PGT STORAGE
 648         // ########################################################################
 649         /**
 650          * @addtogroup publicPGTStorage
 651          * @{
 652          */
 653
 654         /**
 655          * This method is used to tell phpCAS to store the response of the
 656          * CAS server to PGT requests onto the filesystem.
 657          *
 658          * @param $format the format used to store the PGT's (`plain' and `xml' allowed)
 659          * @param $path the path where the PGT's should be stored
 660          */
 661         function setPGTStorageFile($format='',
 662                 $path='')
 663                 {
 664                 global $PHPCAS_CLIENT,$PHPCAS_AUTH_CHECK_CALL;
 665
 666                 phpCAS::traceBegin();
 667                 if ( !is_object($PHPCAS_CLIENT) ) {
 668                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 669                 }
 670                 if ( !$PHPCAS_CLIENT->isProxy() ) {
 671                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 672                 }
 673                 if ( $PHPCAS_AUTH_CHECK_CALL['done'] ) {
 674                         phpCAS::error('this method should only be called before '.$PHPCAS_AUTH_CHECK_CALL['method'].'() (called at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].')');
 675                 }
 676                 if ( gettype($format) != 'string' ) {
 677                         phpCAS::error('type mismatched for parameter $format (should be `string\')');
 678                 }
 679                 if ( gettype($path) != 'string' ) {
 680                         phpCAS::error('type mismatched for parameter $format (should be `string\')');
 681                 }
 682                 $PHPCAS_CLIENT->setPGTStorageFile($format,$path);
 683                 phpCAS::traceEnd();
 684                 }
 685
 686         /**
 687          * This method is used to tell phpCAS to store the response of the
 688          * CAS server to PGT requests into a database.
 689          * @note The connection to the database is done only when needed.
 690          * As a consequence, bad parameters are detected only when
 691          * initializing PGT storage, except in debug mode.
 692          *
 693          * @param $user the user to access the data with
 694          * @param $password the user's password
 695          * @param $database_type the type of the database hosting the data
 696          * @param $hostname the server hosting the database
 697          * @param $port the port the server is listening on
 698          * @param $database the name of the database
 699          * @param $table the name of the table storing the data
 700          */
 701         function setPGTStorageDB($user,
 702                                                          $password,
 703                                                          $database_type='',
 704                                                                  $hostname='',
 705                                                                          $port=0,
 706                                                                                  $database='',
 707                                                                                          $table='')
 708                 {
 709                 global $PHPCAS_CLIENT,$PHPCAS_AUTH_CHECK_CALL;
 710
 711                 phpCAS::traceBegin();
 712                 if ( !is_object($PHPCAS_CLIENT) ) {
 713                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 714                 }
 715                 if ( !$PHPCAS_CLIENT->isProxy() ) {
 716                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 717                 }
 718                 if ( $PHPCAS_AUTH_CHECK_CALL['done'] ) {
 719                         phpCAS::error('this method should only be called before '.$PHPCAS_AUTH_CHECK_CALL['method'].'() (called at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].')');
 720                 }
 721                 if ( gettype($user) != 'string' ) {
 722                         phpCAS::error('type mismatched for parameter $user (should be `string\')');
 723                 }
 724                 if ( gettype($password) != 'string' ) {
 725                         phpCAS::error('type mismatched for parameter $password (should be `string\')');
 726                 }
 727                 if ( gettype($database_type) != 'string' ) {
 728                         phpCAS::error('type mismatched for parameter $database_type (should be `string\')');
 729                 }
 730                 if ( gettype($hostname) != 'string' ) {
 731                         phpCAS::error('type mismatched for parameter $hostname (should be `string\')');
 732                 }
 733                 if ( gettype($port) != 'integer' ) {
 734                         phpCAS::error('type mismatched for parameter $port (should be `integer\')');
 735                 }
 736                 if ( gettype($database) != 'string' ) {
 737                         phpCAS::error('type mismatched for parameter $database (should be `string\')');
 738                 }
 739                 if ( gettype($table) != 'string' ) {
 740                         phpCAS::error('type mismatched for parameter $table (should be `string\')');
 741                 }
 742                 $PHPCAS_CLIENT->setPGTStorageDB($this,$user,$password,$hostname,$port,$database,$table);
 743                 phpCAS::traceEnd();
 744                 }
 745
 746         /** @} */
 747         // ########################################################################
 748         // ACCESS TO EXTERNAL SERVICES
 749         // ########################################################################
 750         /**
 751          * @addtogroup publicServices
 752          * @{
 753          */
 754
 755         /**
 756          * This method is used to access an HTTP[S] service.
 757          *
 758          * @param $url the service to access.
 759          * @param $err_code an error code Possible values are PHPCAS_SERVICE_OK (on
 760          * success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE, PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE,
 761          * PHPCAS_SERVICE_PT_FAILURE, PHPCAS_SERVICE_NOT AVAILABLE.
 762          * @param $output the output of the service (also used to give an error
 763          * message on failure).
 764          *
 765          * @return TRUE on success, FALSE otherwise (in this later case, $err_code
 766          * gives the reason why it failed and $output contains an error message).
 767          */
 768         function serviceWeb($url,&$err_code,&$output)
 769                 {
 770                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 771
 772                 phpCAS::traceBegin();
 773                 if ( !is_object($PHPCAS_CLIENT) ) {
 774                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 775                 }
 776                 if ( !$PHPCAS_CLIENT->isProxy() ) {
 777                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 778                 }
 779                 if ( !$PHPCAS_AUTH_CHECK_CALL['done'] ) {
 780                         phpCAS::error('this method should only be called after the programmer is sure the user has been authenticated (by calling '.__CLASS__.'::checkAuthentication() or '.__CLASS__.'::forceAuthentication()');
 781                 }
 782                 if ( !$PHPCAS_AUTH_CHECK_CALL['result'] ) {
 783                         phpCAS::error('authentication was checked (by '.$PHPCAS_AUTH_CHECK_CALL['method'].'() at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].') but the method returned FALSE');
 784                 }
 785                 if ( gettype($url) != 'string' ) {
 786                         phpCAS::error('type mismatched for parameter $url (should be `string\')');
 787                 }
 788
 789                 $res = $PHPCAS_CLIENT->serviceWeb($url,$err_code,$output);
 790
 791                 phpCAS::traceEnd($res);
 792                 return $res;
 793                 }
 794
 795         /**
 796          * This method is used to access an IMAP/POP3/NNTP service.
 797          *
 798          * @param $url a string giving the URL of the service, including the mailing box
 799          * for IMAP URLs, as accepted by imap_open().
 800          * @param $flags options given to imap_open().
 801          * @param $err_code an error code Possible values are PHPCAS_SERVICE_OK (on
 802          * success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE, PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE,
 803          * PHPCAS_SERVICE_PT_FAILURE, PHPCAS_SERVICE_NOT AVAILABLE.
 804          * @param $err_msg an error message on failure
 805          * @param $pt the Proxy Ticket (PT) retrieved from the CAS server to access the URL
 806          * on success, FALSE on error).
 807          *
 808          * @return an IMAP stream on success, FALSE otherwise (in this later case, $err_code
 809          * gives the reason why it failed and $err_msg contains an error message).
 810          */
 811         function serviceMail($url,$flags,&$err_code,&$err_msg,&$pt)
 812                 {
 813                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 814
 815                 phpCAS::traceBegin();
 816                 if ( !is_object($PHPCAS_CLIENT) ) {
 817                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 818                 }
 819                 if ( !$PHPCAS_CLIENT->isProxy() ) {
 820                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 821                 }
 822                 if ( !$PHPCAS_AUTH_CHECK_CALL['done'] ) {
 823                         phpCAS::error('this method should only be called after the programmer is sure the user has been authenticated (by calling '.__CLASS__.'::checkAuthentication() or '.__CLASS__.'::forceAuthentication()');
 824                 }
 825                 if ( !$PHPCAS_AUTH_CHECK_CALL['result'] ) {
 826                         phpCAS::error('authentication was checked (by '.$PHPCAS_AUTH_CHECK_CALL['method'].'() at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].') but the method returned FALSE');
 827                 }
 828                 if ( gettype($url) != 'string' ) {
 829                         phpCAS::error('type mismatched for parameter $url (should be `string\')');
 830                 }
 831
 832                 if ( gettype($flags) != 'integer' ) {
 833                         phpCAS::error('type mismatched for parameter $flags (should be `integer\')');
 834                 }
 835
 836                 $res = $PHPCAS_CLIENT->serviceMail($url,$flags,$err_code,$err_msg,$pt);
 837
 838                 phpCAS::traceEnd($res);
 839                 return $res;
 840                 }
 841
 842         /** @} */
 843         // ########################################################################
 844         //  AUTHENTICATION
 845         // ########################################################################
 846         /**
 847          * @addtogroup publicAuth
 848          * @{
 849          */
 850
 851         /**
 852          * Set the times authentication will be cached before really accessing the CAS server in gateway mode:
 853          * - -1: check only once, and then never again (until you pree login)
 854          * - 0: always check
 855          * - n: check every "n" time
 856          *
 857          * @param $n an integer.
 858          */
 859         function setCacheTimesForAuthRecheck($n)
 860                 {
 861                 global $PHPCAS_CLIENT;
 862                 if ( !is_object($PHPCAS_CLIENT) ) {
 863                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 864                 }
 865                 if ( gettype($n) != 'integer' ) {
 866                         phpCAS::error('type mismatched for parameter $header (should be `string\')');
 867                 }
 868                 $PHPCAS_CLIENT->setCacheTimesForAuthRecheck($n);
 869                 }
 870
 871         /**
 872          * This method is called to check if the user is authenticated (use the gateway feature).
 873          * @return TRUE when the user is authenticated; otherwise FALSE.
 874          */
 875         function checkAuthentication()
 876                 {
 877                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 878
 879                 phpCAS::traceBegin();
 880                 if ( !is_object($PHPCAS_CLIENT) ) {
 881                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 882                 }
 883
 884                 $auth = $PHPCAS_CLIENT->checkAuthentication();
 885
 886                 // store where the authentication has been checked and the result
 887                 $dbg = phpCAS::backtrace();
 888                 $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE,
 889                         'file' => $dbg[0]['file'],
 890                         'line' => $dbg[0]['line'],
 891                         'method' => __CLASS__.'::'.__FUNCTION__,
 892                         'result' => $auth );
 893                 phpCAS::traceEnd($auth);
 894                 return $auth;
 895                 }
 896
 897         /**
 898          * This method is called to force authentication if the user was not already
 899          * authenticated. If the user is not authenticated, halt by redirecting to
 900          * the CAS server.
 901          */
 902         function forceAuthentication()
 903                 {
 904                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 905
 906                 phpCAS::traceBegin();
 907                 if ( !is_object($PHPCAS_CLIENT) ) {
 908                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 909                 }
 910
 911                 $auth = $PHPCAS_CLIENT->forceAuthentication();
 912
 913                 // store where the authentication has been checked and the result
 914                 $dbg = phpCAS::backtrace();
 915                 $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE,
 916                         'file' => $dbg[0]['file'],
 917                         'line' => $dbg[0]['line'],
 918                         'method' => __CLASS__.'::'.__FUNCTION__,
 919                         'result' => $auth );
 920
 921                 if ( !$auth ) {
 922                         phpCAS::trace('user is not authenticated, redirecting to the CAS server');
 923                         $PHPCAS_CLIENT->forceAuthentication();
 924                 } else {
 925                         phpCAS::trace('no need to authenticate (user `'.phpCAS::getUser().'\' is already authenticated)');
 926                 }
 927
 928                 phpCAS::traceEnd();
 929                 return $auth;
 930                 }
 931
 932         /**
 933          * This method is called to renew the authentication.
 934          **/
 935         function renewAuthentication() {
 936                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 937
 938                 phpCAS::traceBegin();
 939                 if ( !is_object($PHPCAS_CLIENT) ) {
 940                         phpCAS::error('this method should not be called before'.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 941                 }
 942
 943                 // store where the authentication has been checked and the result
 944                 $dbg = phpCAS::backtrace();
 945                 $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE, 'file' => $dbg[0]['file'], 'line' => $dbg[0]['line'], 'method' => __CLASS__.'::'.__FUNCTION__, 'result' => $auth );
 946
 947                 $PHPCAS_CLIENT->renewAuthentication();
 948                 phpCAS::traceEnd();
 949         }
 950
 951         /**
 952          * This method has been left from version 0.4.1 for compatibility reasons.
 953          */
 954         function authenticate()
 955                 {
 956                 phpCAS::error('this method is deprecated. You should use '.__CLASS__.'::forceAuthentication() instead');
 957                 }
 958
 959         /**
 960          * This method is called to check if the user is authenticated (previously or by
 961          * tickets given in the URL).
 962          *
 963          * @return TRUE when the user is authenticated.
 964          */
 965         function isAuthenticated()
 966                 {
 967                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 968
 969                 phpCAS::traceBegin();
 970                 if ( !is_object($PHPCAS_CLIENT) ) {
 971                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 972                 }
 973
 974                 // call the isAuthenticated method of the global $PHPCAS_CLIENT object
 975                 $auth = $PHPCAS_CLIENT->isAuthenticated();
 976
 977                 // store where the authentication has been checked and the result
 978                 $dbg = phpCAS::backtrace();
 979                 $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE,
 980                         'file' => $dbg[0]['file'],
 981                         'line' => $dbg[0]['line'],
 982                         'method' => __CLASS__.'::'.__FUNCTION__,
 983                         'result' => $auth );
 984                 phpCAS::traceEnd($auth);
 985                 return $auth;
 986                 }
 987
 988         /**
 989          * Checks whether authenticated based on $_SESSION. Useful to avoid
 990          * server calls.
 991          * @return true if authenticated, false otherwise.
 992          * @since 0.4.22 by Brendan Arnold
 993          */
 994         function isSessionAuthenticated ()
 995                 {
 996                 global $PHPCAS_CLIENT;
 997                 if ( !is_object($PHPCAS_CLIENT) ) {
 998                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 999                 }
1000                 return($PHPCAS_CLIENT->isSessionAuthenticated());
1001                 }
1002
1003         /**
1004          * This method returns the CAS user's login name.
1005          * @warning should not be called only after phpCAS::forceAuthentication()
1006          * or phpCAS::checkAuthentication().
1007          *
1008          * @return the login name of the authenticated user
1009          */
1010         function getUser()
1011                 {
1012                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
1013                 if ( !is_object($PHPCAS_CLIENT) ) {
1014                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
1015                 }
1016                 if ( !$PHPCAS_AUTH_CHECK_CALL['done'] ) {
1017                         phpCAS::error('this method should only be called after '.__CLASS__.'::forceAuthentication() or '.__CLASS__.'::isAuthenticated()');
1018                 }
1019                 if ( !$PHPCAS_AUTH_CHECK_CALL['result'] ) {
1020                         phpCAS::error('authentication was checked (by '.$PHPCAS_AUTH_CHECK_CALL['method'].'() at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].') but the method returned FALSE');
1021                 }
1022                 return $PHPCAS_CLIENT->getUser();
1023                 }
1024
1025     /**
1026      * Handle logout requests.
1027      */
1028     function handleLogoutRequests($check_client=true, $allowed_clients=false)
1029         {
1030             global $PHPCAS_CLIENT;
1031             if ( !is_object($PHPCAS_CLIENT) ) {
1032                 phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
1033             }
1034             return($PHPCAS_CLIENT->handleLogoutRequests($check_client, $allowed_clients));
1035         }
1036
1037         /**
1038          * This method returns the URL to be used to login.
1039          * or phpCAS::isAuthenticated().
1040          *
1041          * @return the login name of the authenticated user
1042          */
1043         function getServerLoginURL()
1044                 {
1045                 global $PHPCAS_CLIENT;
1046                 if ( !is_object($PHPCAS_CLIENT) ) {
1047                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
1048                 }
1049                 return $PHPCAS_CLIENT->getServerLoginURL();
1050                 }
1051
1052         /**
1053          * Set the login URL of the CAS server.
1054          * @param $url the login URL
1055          * @since 0.4.21 by Wyman Chan
1056          */
1057         function setServerLoginURL($url='')
1058                 {
1059                 global $PHPCAS_CLIENT;
1060                 phpCAS::traceBegin();
1061                 if ( !is_object($PHPCAS_CLIENT) ) {
1062                         phpCAS::error('this method should only be called after
1063                                 '.__CLASS__.'::client()');
1064                 }
1065                 if ( gettype($url) != 'string' ) {
1066                         phpCAS::error('type mismatched for parameter $url (should be
1067                         `string\')');
1068                 }
1069                 $PHPCAS_CLIENT->setServerLoginURL($url);
1070                 phpCAS::traceEnd();
1071                 }
1072
1073         /**
1074          * This method returns the URL to be used to login.
1075          * or phpCAS::isAuthenticated().
1076          *
1077          * @return the login name of the authenticated user
1078          */
1079         function getServerLogoutURL()
1080                 {
1081                 global $PHPCAS_CLIENT;
1082                 if ( !is_object($PHPCAS_CLIENT) ) {
1083                         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
1084                 }
1085                 return $PHPCAS_CLIENT->getServerLogoutURL();
1086                 }
1087
1088         /**
1089          * Set the logout URL of the CAS server.
1090          * @param $url the logout URL
1091          * @since 0.4.21 by Wyman Chan
1092          */
1093         function setServerLogoutURL($url='')
1094                 {
1095                 global $PHPCAS_CLIENT;
1096                 phpCAS::traceBegin();
1097                 if ( !is_object($PHPCAS_CLIENT) ) {
1098                         phpCAS::error('this method should only be called after
1099                                 '.__CLASS__.'::client()');
1100                 }
1101                 if ( gettype($url) != 'string' ) {
1102                         phpCAS::error('type mismatched for parameter $url (should be
1103                         `string\')');
1104                 }
1105                 $PHPCAS_CLIENT->setServerLogoutURL($url);
1106                 phpCAS::traceEnd();
1107                 }
1108
1109         /**
1110          * This method is used to logout from CAS.
1111          * @params $params an array that contains the optional url and service parameters that will be passed to the CAS server
1112          * @public
1113          */
1114         function logout($params = "") {
1115                 global $PHPCAS_CLIENT;
1116                 phpCAS::traceBegin();
1117                 if (!is_object($PHPCAS_CLIENT)) {
1118                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1119                 }
1120                 $parsedParams = array();
1121                 if ($params != "") {
1122                         if (is_string($params)) {
1123                                 phpCAS::error('method `phpCAS::logout($url)\' is now deprecated, use `phpCAS::logoutWithUrl($url)\' instead');
1124                         }
1125                         if (!is_array($params)) {
1126                                 phpCAS::error('type mismatched for parameter $params (should be `array\')');
1127                         }
1128                         foreach ($params as $key => $value) {
1129                                 if ($key != "service" && $key != "url") {
1130                                         phpCAS::error('only `url\' and `service\' parameters are allowed for method `phpCAS::logout($params)\'');
1131                                 }
1132                                 $parsedParams[$key] = $value;
1133                         }
1134                 }
1135                 $PHPCAS_CLIENT->logout($parsedParams);
1136                 // never reached
1137                 phpCAS::traceEnd();
1138         }
1139
1140         /**
1141          * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1142          * @param $service a URL that will be transmitted to the CAS server
1143          */
1144         function logoutWithRedirectService($service) {
1145                 global $PHPCAS_CLIENT;
1146                 phpCAS::traceBegin();
1147                 if ( !is_object($PHPCAS_CLIENT) ) {
1148                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1149                 }
1150                 if (!is_string($service)) {
1151                         phpCAS::error('type mismatched for parameter $service (should be `string\')');
1152                 }
1153                 $PHPCAS_CLIENT->logout(array("service" => $service));
1154                 // never reached
1155                 phpCAS::traceEnd();
1156         }
1157
1158         /**
1159          * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1160          * @param $url a URL that will be transmitted to the CAS server
1161          */
1162         function logoutWithUrl($url) {
1163                 global $PHPCAS_CLIENT;
1164                 phpCAS::traceBegin();
1165                 if ( !is_object($PHPCAS_CLIENT) ) {
1166                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1167                 }
1168                 if (!is_string($url)) {
1169                         phpCAS::error('type mismatched for parameter $url (should be `string\')');
1170                 }
1171                 $PHPCAS_CLIENT->logout(array("url" => $url));
1172                 // never reached
1173                 phpCAS::traceEnd();
1174         }
1175
1176         /**
1177          * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1178          * @param $service a URL that will be transmitted to the CAS server
1179          * @param $url a URL that will be transmitted to the CAS server
1180          */
1181         function logoutWithRedirectServiceAndUrl($service, $url) {
1182                 global $PHPCAS_CLIENT;
1183                 phpCAS::traceBegin();
1184                 if ( !is_object($PHPCAS_CLIENT) ) {
1185                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1186                 }
1187                 if (!is_string($service)) {
1188                         phpCAS::error('type mismatched for parameter $service (should be `string\')');
1189                 }
1190                 if (!is_string($url)) {
1191                         phpCAS::error('type mismatched for parameter $url (should be `string\')');
1192                 }
1193                 $PHPCAS_CLIENT->logout(array("service" => $service, "url" => $url));
1194                 // never reached
1195                 phpCAS::traceEnd();
1196         }
1197
1198         /**
1199          * Set the fixed URL that will be used by the CAS server to transmit the PGT.
1200          * When this method is not called, a phpCAS script uses its own URL for the callback.
1201          *
1202          * @param $url the URL
1203          */
1204         function setFixedCallbackURL($url='')
1205                 {
1206                 global $PHPCAS_CLIENT;
1207                 phpCAS::traceBegin();
1208                 if ( !is_object($PHPCAS_CLIENT) ) {
1209                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1210                 }
1211                 if ( !$PHPCAS_CLIENT->isProxy() ) {
1212                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1213                 }
1214                 if ( gettype($url) != 'string' ) {
1215                         phpCAS::error('type mismatched for parameter $url (should be `string\')');
1216                 }
1217                 $PHPCAS_CLIENT->setCallbackURL($url);
1218                 phpCAS::traceEnd();
1219                 }
1220
1221         /**
1222          * Set the fixed URL that will be set as the CAS service parameter. When this
1223          * method is not called, a phpCAS script uses its own URL.
1224          *
1225          * @param $url the URL
1226          */
1227         function setFixedServiceURL($url)
1228                 {
1229                 global $PHPCAS_CLIENT;
1230                 phpCAS::traceBegin();
1231                 if ( !is_object($PHPCAS_CLIENT) ) {
1232                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1233                 }
1234                 if ( gettype($url) != 'string' ) {
1235                         phpCAS::error('type mismatched for parameter $url (should be `string\')');
1236                 }
1237                 $PHPCAS_CLIENT->setURL($url);
1238                 phpCAS::traceEnd();
1239                 }
1240
1241         /**
1242          * Get the URL that is set as the CAS service parameter.
1243          */
1244         function getServiceURL()
1245                 {
1246                 global $PHPCAS_CLIENT;
1247                 if ( !is_object($PHPCAS_CLIENT) ) {
1248                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1249                 }
1250                 return($PHPCAS_CLIENT->getURL());
1251                 }
1252
1253         /**
1254          * Retrieve a Proxy Ticket from the CAS server.
1255          */
1256         function retrievePT($target_service,&$err_code,&$err_msg)
1257                 {
1258                 global $PHPCAS_CLIENT;
1259                 if ( !is_object($PHPCAS_CLIENT) ) {
1260                         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1261                 }
1262                 if ( gettype($target_service) != 'string' ) {
1263                         phpCAS::error('type mismatched for parameter $target_service(should be `string\')');
1264                 }
1265                 return($PHPCAS_CLIENT->retrievePT($target_service,$err_code,$err_msg));
1266                 }
1267
1268         /**
1269          * Set the certificate of the CAS server.
1270          *
1271          * @param $cert the PEM certificate
1272          */
1273         function setCasServerCert($cert)
1274                 {
1275                 global $PHPCAS_CLIENT;
1276                 phpCAS::traceBegin();
1277                 if ( !is_object($PHPCAS_CLIENT) ) {
1278                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1279                 }
1280                 if ( gettype($cert) != 'string' ) {
1281                         phpCAS::error('type mismatched for parameter $cert (should be `string\')');
1282                 }
1283                 $PHPCAS_CLIENT->setCasServerCert($cert);
1284                 phpCAS::traceEnd();
1285                 }
1286
1287         /**
1288          * Set the certificate of the CAS server CA.
1289          *
1290          * @param $cert the CA certificate
1291          */
1292         function setCasServerCACert($cert)
1293                 {
1294                 global $PHPCAS_CLIENT;
1295                 phpCAS::traceBegin();
1296                 if ( !is_object($PHPCAS_CLIENT) ) {
1297                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1298                 }
1299                 if ( gettype($cert) != 'string' ) {
1300                         phpCAS::error('type mismatched for parameter $cert (should be `string\')');
1301                 }
1302                 $PHPCAS_CLIENT->setCasServerCACert($cert);
1303                 phpCAS::traceEnd();
1304                 }
1305
1306         /**
1307          * Set no SSL validation for the CAS server.
1308          */
1309         function setNoCasServerValidation()
1310                 {
1311                 global $PHPCAS_CLIENT;
1312                 phpCAS::traceBegin();
1313                 if ( !is_object($PHPCAS_CLIENT) ) {
1314                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1315                 }
1316                 $PHPCAS_CLIENT->setNoCasServerValidation();
1317                 phpCAS::traceEnd();
1318                 }
1319
1320         /** @} */
1321
1322   /**
1323    * Change CURL options.
1324    * CURL is used to connect through HTTPS to CAS server
1325    * @param $key the option key
1326    * @param $value the value to set
1327    */
1328    function setExtraCurlOption($key, $value)
1329                 {
1330                   global $PHPCAS_CLIENT;
1331                   phpCAS::traceBegin();
1332                   if ( !is_object($PHPCAS_CLIENT) ) {
1333                         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1334                   }
1335                   $PHPCAS_CLIENT->setExtraCurlOption($key, $value);
1336                   phpCAS::traceEnd();
1337                 }
1338
1339 }
1340
1341 // ########################################################################
1342 // DOCUMENTATION
1343 // ########################################################################
1344
1345 // ########################################################################
1346 //  MAIN PAGE
1347
1348 /**
1349  * @mainpage
1350  *
1351  * The following pages only show the source documentation.
1352  *
1353  */
1354
1355 // ########################################################################
1356 //  MODULES DEFINITION
1357
1358 /** @defgroup public User interface */
1359
1360 /** @defgroup publicInit Initialization
1361  *  @ingroup public */
1362
1363 /** @defgroup publicAuth Authentication
1364  *  @ingroup public */
1365
1366 /** @defgroup publicServices Access to external services
1367  *  @ingroup public */
1368
1369 /** @defgroup publicConfig Configuration
1370  *  @ingroup public */
1371
1372 /** @defgroup publicLang Internationalization
1373  *  @ingroup publicConfig */
1374
1375 /** @defgroup publicOutput HTML output
1376  *  @ingroup publicConfig */
1377
1378 /** @defgroup publicPGTStorage PGT storage
1379  *  @ingroup publicConfig */
1380
1381 /** @defgroup publicDebug Debugging
1382  *  @ingroup public */
1383
1384
1385 /** @defgroup internal Implementation */
1386
1387 /** @defgroup internalAuthentication Authentication
1388  *  @ingroup internal */
1389
1390 /** @defgroup internalBasic CAS Basic client features (CAS 1.0, Service Tickets)
1391  *  @ingroup internal */
1392
1393 /** @defgroup internalProxy CAS Proxy features (CAS 2.0, Proxy Granting Tickets)
1394  *  @ingroup internal */
1395
1396 /** @defgroup internalPGTStorage PGT storage
1397  *  @ingroup internalProxy */
1398
1399 /** @defgroup internalPGTStorageDB PGT storage in a database
1400  *  @ingroup internalPGTStorage */
1401
1402 /** @defgroup internalPGTStorageFile PGT storage on the filesystem
1403  *  @ingroup internalPGTStorage */
1404
1405 /** @defgroup internalCallback Callback from the CAS server
1406  *  @ingroup internalProxy */
1407
1408 /** @defgroup internalProxied CAS proxied client features (CAS 2.0, Proxy Tickets)
1409  *  @ingroup internal */
1410
1411 /** @defgroup internalConfig Configuration
1412  *  @ingroup internal */
1413
1414 /** @defgroup internalOutput HTML output
1415  *  @ingroup internalConfig */
1416
1417 /** @defgroup internalLang Internationalization
1418  *  @ingroup internalConfig
1419  *
1420  * To add a new language:
1421  * - 1. define a new constant PHPCAS_LANG_XXXXXX in CAS/CAS.php
1422  * - 2. copy any file from CAS/languages to CAS/languages/XXXXXX.php
1423  * - 3. Make the translations
1424  */
1425
1426 /** @defgroup internalDebug Debugging
1427  *  @ingroup internal */
1428
1429 /** @defgroup internalMisc Miscellaneous
1430  *  @ingroup internal */
1431
1432 // ########################################################################
1433 //  EXAMPLES
1434
1435 /**
1436  * @example example_simple.php
1437  */
1438  /**
1439   * @example example_proxy.php
1440   */
1441   /**
1442    * @example example_proxy2.php
1443    */
1444    /**
1445     * @example example_lang.php
1446     */
1447     /**
1448      * @example example_html.php
1449      */
1450      /**
1451       * @example example_file.php
1452       */
1453       /**
1454        * @example example_db.php
1455        */
1456        /**
1457         * @example example_service.php
1458         */
1459         /**
1460          * @example example_session_proxy.php
1461          */
1462          /**
1463           * @example example_session_service.php
1464           */
1465           /**
1466            * @example example_gateway.php
1467            */
1468
1469
1470
1471 ?>