Piwik 2.8.0 compatibility: Added missing abstract methods to Auth.
[piwik-CASLogin.git] / CAS / CAS.php
1 <?php
2
3 /**
4  * Licensed to Jasig under one or more contributor license
5  * agreements. See the NOTICE file distributed with this work for
6  * additional information regarding copyright ownership.
7  *
8  * Jasig licenses this file to you under the Apache License,
9  * Version 2.0 (the "License"); you may not use this file except in
10  * compliance with the License. You may obtain a copy of the License at:
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  *
20  *
21  *
22  * Interface class of the phpCAS library
23  * PHP Version 5
24  *
25  * @file     CAS/CAS.php
26  * @category Authentication
27  * @package  PhpCAS
28  * @author   Pascal Aubry <pascal.aubry@univ-rennes1.fr>
29  * @author   Olivier Berger <olivier.berger@it-sudparis.eu>
30  * @author   Brett Bieber <brett.bieber@gmail.com>
31  * @author   Joachim Fritschi <jfritschi@freenet.de>
32  * @author   Adam Franco <afranco@middlebury.edu>
33  * @license  http://www.apache.org/licenses/LICENSE-2.0  Apache License 2.0
34  * @link     https://wiki.jasig.org/display/CASC/phpCAS
35  * @ingroup public
36  */
37
38
39 //
40 // hack by Vangelis Haniotakis to handle the absence of $_SERVER['REQUEST_URI']
41 // in IIS
42 //
43 if (php_sapi_name() != 'cli') {
44     if (!isset($_SERVER['REQUEST_URI'])) {
45         $_SERVER['REQUEST_URI'] = $_SERVER['SCRIPT_NAME'] . '?' . $_SERVER['QUERY_STRING'];
46     }
47 }
48
49 // Add a E_USER_DEPRECATED for php versions <= 5.2
50 if (!defined('E_USER_DEPRECATED')) {
51     define('E_USER_DEPRECATED', E_USER_NOTICE);
52 }
53
54
55 // ########################################################################
56 //  CONSTANTS
57 // ########################################################################
58
59 // ------------------------------------------------------------------------
60 //  CAS VERSIONS
61 // ------------------------------------------------------------------------
62
63 /**
64  * phpCAS version. accessible for the user by phpCAS::getVersion().
65  */
66 define('PHPCAS_VERSION', '1.3.2');
67
68 /**
69  * @addtogroup public
70  * @{
71  */
72
73 /**
74  * CAS version 1.0
75  */
76 define("CAS_VERSION_1_0", '1.0');
77 /*!
78  * CAS version 2.0
79 */
80 define("CAS_VERSION_2_0", '2.0');
81
82 // ------------------------------------------------------------------------
83 //  SAML defines
84 // ------------------------------------------------------------------------
85
86 /**
87  * SAML protocol
88  */
89 define("SAML_VERSION_1_1", 'S1');
90
91 /**
92  * XML header for SAML POST
93  */
94 define("SAML_XML_HEADER", '<?xml version="1.0" encoding="UTF-8"?>');
95
96 /**
97  * SOAP envelope for SAML POST
98  */
99 define("SAML_SOAP_ENV", '<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/>');
100
101 /**
102  * SOAP body for SAML POST
103  */
104 define("SAML_SOAP_BODY", '<SOAP-ENV:Body>');
105
106 /**
107  * SAMLP request
108  */
109 define("SAMLP_REQUEST", '<samlp:Request xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"  MajorVersion="1" MinorVersion="1" RequestID="_192.168.16.51.1024506224022" IssueInstant="2002-06-19T17:03:44.022Z">');
110 define("SAMLP_REQUEST_CLOSE", '</samlp:Request>');
111
112 /**
113  * SAMLP artifact tag (for the ticket)
114  */
115 define("SAML_ASSERTION_ARTIFACT", '<samlp:AssertionArtifact>');
116
117 /**
118  * SAMLP close
119  */
120 define("SAML_ASSERTION_ARTIFACT_CLOSE", '</samlp:AssertionArtifact>');
121
122 /**
123  * SOAP body close
124  */
125 define("SAML_SOAP_BODY_CLOSE", '</SOAP-ENV:Body>');
126
127 /**
128  * SOAP envelope close
129  */
130 define("SAML_SOAP_ENV_CLOSE", '</SOAP-ENV:Envelope>');
131
132 /**
133  * SAML Attributes
134  */
135 define("SAML_ATTRIBUTES", 'SAMLATTRIBS');
136
137 /** @} */
138 /**
139  * @addtogroup publicPGTStorage
140  * @{
141  */
142 // ------------------------------------------------------------------------
143 //  FILE PGT STORAGE
144 // ------------------------------------------------------------------------
145 /**
146  * Default path used when storing PGT's to file
147  */
148 define("CAS_PGT_STORAGE_FILE_DEFAULT_PATH", session_save_path());
149 /** @} */
150 // ------------------------------------------------------------------------
151 // SERVICE ACCESS ERRORS
152 // ------------------------------------------------------------------------
153 /**
154  * @addtogroup publicServices
155  * @{
156  */
157
158 /**
159  * phpCAS::service() error code on success
160  */
161 define("PHPCAS_SERVICE_OK", 0);
162 /**
163  * phpCAS::service() error code when the PT could not retrieve because
164  * the CAS server did not respond.
165  */
166 define("PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE", 1);
167 /**
168  * phpCAS::service() error code when the PT could not retrieve because
169  * the response of the CAS server was ill-formed.
170  */
171 define("PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE", 2);
172 /**
173  * phpCAS::service() error code when the PT could not retrieve because
174  * the CAS server did not want to.
175  */
176 define("PHPCAS_SERVICE_PT_FAILURE", 3);
177 /**
178  * phpCAS::service() error code when the service was not available.
179  */
180 define("PHPCAS_SERVICE_NOT_AVAILABLE", 4);
181
182 // ------------------------------------------------------------------------
183 // SERVICE TYPES
184 // ------------------------------------------------------------------------
185 /**
186  * phpCAS::getProxiedService() type for HTTP GET
187  */
188 define("PHPCAS_PROXIED_SERVICE_HTTP_GET", 'CAS_ProxiedService_Http_Get');
189 /**
190  * phpCAS::getProxiedService() type for HTTP POST
191  */
192 define("PHPCAS_PROXIED_SERVICE_HTTP_POST", 'CAS_ProxiedService_Http_Post');
193 /**
194  * phpCAS::getProxiedService() type for IMAP
195  */
196 define("PHPCAS_PROXIED_SERVICE_IMAP", 'CAS_ProxiedService_Imap');
197
198
199 /** @} */
200 // ------------------------------------------------------------------------
201 //  LANGUAGES
202 // ------------------------------------------------------------------------
203 /**
204  * @addtogroup publicLang
205  * @{
206  */
207
208 define("PHPCAS_LANG_ENGLISH", 'CAS_Languages_English');
209 define("PHPCAS_LANG_FRENCH", 'CAS_Languages_French');
210 define("PHPCAS_LANG_GREEK", 'CAS_Languages_Greek');
211 define("PHPCAS_LANG_GERMAN", 'CAS_Languages_German');
212 define("PHPCAS_LANG_JAPANESE", 'CAS_Languages_Japanese');
213 define("PHPCAS_LANG_SPANISH", 'CAS_Languages_Spanish');
214 define("PHPCAS_LANG_CATALAN", 'CAS_Languages_Catalan');
215
216 /** @} */
217
218 /**
219  * @addtogroup internalLang
220  * @{
221  */
222
223 /**
224  * phpCAS default language (when phpCAS::setLang() is not used)
225  */
226 define("PHPCAS_LANG_DEFAULT", PHPCAS_LANG_ENGLISH);
227
228 /** @} */
229 // ------------------------------------------------------------------------
230 //  DEBUG
231 // ------------------------------------------------------------------------
232 /**
233  * @addtogroup publicDebug
234  * @{
235  */
236
237 /**
238  * The default directory for the debug file under Unix.
239  */
240 define('DEFAULT_DEBUG_DIR', '/tmp/');
241
242 /** @} */
243
244 // include the class autoloader
245 require_once dirname(__FILE__) . '/CAS/Autoload.php';
246
247 /**
248  * The phpCAS class is a simple container for the phpCAS library. It provides CAS
249  * authentication for web applications written in PHP.
250  *
251  * @ingroup public
252  * @class phpCAS
253  * @category Authentication
254  * @package  PhpCAS
255  * @author   Pascal Aubry <pascal.aubry@univ-rennes1.fr>
256  * @author   Olivier Berger <olivier.berger@it-sudparis.eu>
257  * @author   Brett Bieber <brett.bieber@gmail.com>
258  * @author   Joachim Fritschi <jfritschi@freenet.de>
259  * @author   Adam Franco <afranco@middlebury.edu>
260  * @license  http://www.apache.org/licenses/LICENSE-2.0  Apache License 2.0
261  * @link     https://wiki.jasig.org/display/CASC/phpCAS
262  */
263
264 class phpCAS
265 {
266
267     /**
268      * This variable is used by the interface class phpCAS.
269      *
270      * @hideinitializer
271      */
272     private static $_PHPCAS_CLIENT;
273
274     /**
275      * This variable is used to store where the initializer is called from
276      * (to print a comprehensive error in case of multiple calls).
277      *
278      * @hideinitializer
279      */
280     private static $_PHPCAS_INIT_CALL;
281
282     /**
283      * This variable is used to store phpCAS debug mode.
284      *
285      * @hideinitializer
286      */
287     private static $_PHPCAS_DEBUG;
288
289
290     // ########################################################################
291     //  INITIALIZATION
292     // ########################################################################
293
294     /**
295      * @addtogroup publicInit
296      * @{
297      */
298
299     /**
300      * phpCAS client initializer.
301      *
302      * @param string $server_version  the version of the CAS server
303      * @param string $server_hostname the hostname of the CAS server
304      * @param string $server_port     the port the CAS server is running on
305      * @param string $server_uri      the URI the CAS server is responding on
306      * @param bool   $changeSessionID Allow phpCAS to change the session_id (Single
307      * Sign Out/handleLogoutRequests is based on that change)
308      *
309      * @return a newly created CAS_Client object
310      * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
311      * called, only once, and before all other methods (except phpCAS::getVersion()
312      * and phpCAS::setDebug()).
313      */
314     public static function client($server_version, $server_hostname,
315         $server_port, $server_uri, $changeSessionID = true
316     ) {
317         phpCAS :: traceBegin();
318         if (is_object(self::$_PHPCAS_CLIENT)) {
319             phpCAS :: error(self::$_PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . self::$_PHPCAS_INIT_CALL['file'] . ':' . self::$_PHPCAS_INIT_CALL['line'] . ')');
320         }
321         if (gettype($server_version) != 'string') {
322             phpCAS :: error('type mismatched for parameter $server_version (should be `string\')');
323         }
324         if (gettype($server_hostname) != 'string') {
325             phpCAS :: error('type mismatched for parameter $server_hostname (should be `string\')');
326         }
327         if (gettype($server_port) != 'integer') {
328             phpCAS :: error('type mismatched for parameter $server_port (should be `integer\')');
329         }
330         if (gettype($server_uri) != 'string') {
331             phpCAS :: error('type mismatched for parameter $server_uri (should be `string\')');
332         }
333
334         // store where the initializer is called from
335         $dbg = debug_backtrace();
336         self::$_PHPCAS_INIT_CALL = array (
337             'done' => true,
338             'file' => $dbg[0]['file'],
339             'line' => $dbg[0]['line'],
340             'method' => __CLASS__ . '::' . __FUNCTION__
341         );
342
343         // initialize the object $_PHPCAS_CLIENT
344         self::$_PHPCAS_CLIENT = new CAS_Client(
345             $server_version, false, $server_hostname, $server_port, $server_uri,
346             $changeSessionID
347         );
348         phpCAS :: traceEnd();
349     }
350
351     /**
352      * phpCAS proxy initializer.
353      *
354      * @param string $server_version  the version of the CAS server
355      * @param string $server_hostname the hostname of the CAS server
356      * @param string $server_port     the port the CAS server is running on
357      * @param string $server_uri      the URI the CAS server is responding on
358      * @param bool   $changeSessionID Allow phpCAS to change the session_id (Single
359      * Sign Out/handleLogoutRequests is based on that change)
360      *
361      * @return a newly created CAS_Client object
362      * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
363      * called, only once, and before all other methods (except phpCAS::getVersion()
364      * and phpCAS::setDebug()).
365      */
366     public static function proxy($server_version, $server_hostname,
367         $server_port, $server_uri, $changeSessionID = true
368     ) {
369         phpCAS :: traceBegin();
370         if (is_object(self::$_PHPCAS_CLIENT)) {
371             phpCAS :: error(self::$_PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . self::$_PHPCAS_INIT_CALL['file'] . ':' . self::$_PHPCAS_INIT_CALL['line'] . ')');
372         }
373         if (gettype($server_version) != 'string') {
374             phpCAS :: error('type mismatched for parameter $server_version (should be `string\')');
375         }
376         if (gettype($server_hostname) != 'string') {
377             phpCAS :: error('type mismatched for parameter $server_hostname (should be `string\')');
378         }
379         if (gettype($server_port) != 'integer') {
380             phpCAS :: error('type mismatched for parameter $server_port (should be `integer\')');
381         }
382         if (gettype($server_uri) != 'string') {
383             phpCAS :: error('type mismatched for parameter $server_uri (should be `string\')');
384         }
385
386         // store where the initialzer is called from
387         $dbg = debug_backtrace();
388         self::$_PHPCAS_INIT_CALL = array (
389             'done' => true,
390             'file' => $dbg[0]['file'],
391             'line' => $dbg[0]['line'],
392             'method' => __CLASS__ . '::' . __FUNCTION__
393         );
394
395         // initialize the object $_PHPCAS_CLIENT
396         self::$_PHPCAS_CLIENT = new CAS_Client(
397             $server_version, true, $server_hostname, $server_port, $server_uri,
398             $changeSessionID
399         );
400         phpCAS :: traceEnd();
401     }
402
403     /** @} */
404     // ########################################################################
405     //  DEBUGGING
406     // ########################################################################
407
408     /**
409      * @addtogroup publicDebug
410      * @{
411      */
412
413     /**
414      * Set/unset debug mode
415      *
416      * @param string $filename the name of the file used for logging, or false
417      * to stop debugging.
418      *
419      * @return void
420      */
421     public static function setDebug($filename = '')
422     {
423         if ($filename != false && gettype($filename) != 'string') {
424             phpCAS :: error('type mismatched for parameter $dbg (should be false or the name of the log file)');
425         }
426         if ($filename === false) {
427             self::$_PHPCAS_DEBUG['filename'] = false;
428
429         } else {
430             if (empty ($filename)) {
431                 if (preg_match('/^Win.*/', getenv('OS'))) {
432                     if (isset ($_ENV['TMP'])) {
433                         $debugDir = $_ENV['TMP'] . '/';
434                     } else {
435                         $debugDir = '';
436                     }
437                 } else {
438                     $debugDir = DEFAULT_DEBUG_DIR;
439                 }
440                 $filename = $debugDir . 'phpCAS.log';
441             }
442
443             if (empty (self::$_PHPCAS_DEBUG['unique_id'])) {
444                 self::$_PHPCAS_DEBUG['unique_id'] = substr(strtoupper(md5(uniqid(''))), 0, 4);
445             }
446
447             self::$_PHPCAS_DEBUG['filename'] = $filename;
448             self::$_PHPCAS_DEBUG['indent'] = 0;
449
450             phpCAS :: trace('START phpCAS-' . PHPCAS_VERSION . ' ******************');
451         }
452     }
453
454
455     /**
456      * Logs a string in debug mode.
457      *
458      * @param string $str the string to write
459      *
460      * @return void
461      * @private
462      */
463     public static function log($str)
464     {
465         $indent_str = ".";
466
467
468         if (!empty(self::$_PHPCAS_DEBUG['filename'])) {
469             // Check if file exists and modifiy file permissions to be only
470             // readable by the webserver
471             if (!file_exists(self::$_PHPCAS_DEBUG['filename'])) {
472                 touch(self::$_PHPCAS_DEBUG['filename']);
473                 // Chmod will fail on windows
474                 @chmod(self::$_PHPCAS_DEBUG['filename'], 0600);
475             }
476             for ($i = 0; $i < self::$_PHPCAS_DEBUG['indent']; $i++) {
477
478                 $indent_str .= '|    ';
479             }
480             // allow for multiline output with proper identing. Usefull for
481             // dumping cas answers etc.
482             $str2 = str_replace("\n", "\n" . self::$_PHPCAS_DEBUG['unique_id'] . ' ' . $indent_str, $str);
483             error_log(self::$_PHPCAS_DEBUG['unique_id'] . ' ' . $indent_str . $str2 . "\n", 3, self::$_PHPCAS_DEBUG['filename']);
484         }
485
486     }
487
488     /**
489      * This method is used by interface methods to print an error and where the
490      * function was originally called from.
491      *
492      * @param string $msg the message to print
493      *
494      * @return void
495      * @private
496      */
497     public static function error($msg)
498     {
499         $dbg = debug_backtrace();
500         $function = '?';
501         $file = '?';
502         $line = '?';
503         if (is_array($dbg)) {
504             for ($i = 1; $i < sizeof($dbg); $i++) {
505                 if (is_array($dbg[$i]) && isset($dbg[$i]['class']) ) {
506                     if ($dbg[$i]['class'] == __CLASS__) {
507                         $function = $dbg[$i]['function'];
508                         $file = $dbg[$i]['file'];
509                         $line = $dbg[$i]['line'];
510                     }
511                 }
512             }
513         }
514         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";
515         phpCAS :: trace($msg);
516         phpCAS :: traceEnd();
517
518         throw new CAS_GracefullTerminationException(__CLASS__ . "::" . $function . '(): ' . $msg);
519     }
520
521     /**
522      * This method is used to log something in debug mode.
523      *
524      * @param string $str string to log
525      *
526      * @return void
527      */
528     public static function trace($str)
529     {
530         $dbg = debug_backtrace();
531         phpCAS :: log($str . ' [' . basename($dbg[0]['file']) . ':' . $dbg[0]['line'] . ']');
532     }
533
534     /**
535      * This method is used to indicate the start of the execution of a function in debug mode.
536      *
537      * @return void
538      */
539     public static function traceBegin()
540     {
541         $dbg = debug_backtrace();
542         $str = '=> ';
543         if (!empty ($dbg[1]['class'])) {
544             $str .= $dbg[1]['class'] . '::';
545         }
546         $str .= $dbg[1]['function'] . '(';
547         if (is_array($dbg[1]['args'])) {
548             foreach ($dbg[1]['args'] as $index => $arg) {
549                 if ($index != 0) {
550                     $str .= ', ';
551                 }
552                 if (is_object($arg)) {
553                     $str .= get_class($arg);
554                 } else {
555                     $str .= str_replace(array("\r\n", "\n", "\r"), "", var_export($arg, true));
556                 }
557             }
558         }
559         if (isset($dbg[1]['file'])) {
560             $file = basename($dbg[1]['file']);
561         } else {
562             $file = 'unknown_file';
563         }
564         if (isset($dbg[1]['line'])) {
565             $line = $dbg[1]['line'];
566         } else {
567             $line = 'unknown_line';
568         }
569         $str .= ') [' . $file . ':' . $line . ']';
570         phpCAS :: log($str);
571         if (!isset(self::$_PHPCAS_DEBUG['indent'])) {
572             self::$_PHPCAS_DEBUG['indent'] = 0;
573         } else {
574             self::$_PHPCAS_DEBUG['indent']++;
575         }
576     }
577
578     /**
579      * This method is used to indicate the end of the execution of a function in
580      * debug mode.
581      *
582      * @param string $res the result of the function
583      *
584      * @return void
585      */
586     public static function traceEnd($res = '')
587     {
588         if (empty(self::$_PHPCAS_DEBUG['indent'])) {
589             self::$_PHPCAS_DEBUG['indent'] = 0;
590         } else {
591             self::$_PHPCAS_DEBUG['indent']--;
592         }
593         $dbg = debug_backtrace();
594         $str = '';
595         if (is_object($res)) {
596             $str .= '<= ' . get_class($res);
597         } else {
598             $str .= '<= ' . str_replace(array("\r\n", "\n", "\r"), "", var_export($res, true));
599         }
600
601         phpCAS :: log($str);
602     }
603
604     /**
605      * This method is used to indicate the end of the execution of the program
606      *
607      * @return void
608      */
609     public static function traceExit()
610     {
611         phpCAS :: log('exit()');
612         while (self::$_PHPCAS_DEBUG['indent'] > 0) {
613             phpCAS :: log('-');
614             self::$_PHPCAS_DEBUG['indent']--;
615         }
616     }
617
618     /** @} */
619     // ########################################################################
620     //  INTERNATIONALIZATION
621     // ########################################################################
622     /**
623     * @addtogroup publicLang
624     * @{
625     */
626
627     /**
628      * This method is used to set the language used by phpCAS.
629      *
630      * @param string $lang string representing the language.
631      *
632      * @return void
633      *
634      * @sa PHPCAS_LANG_FRENCH, PHPCAS_LANG_ENGLISH
635      * @note Can be called only once.
636      */
637     public static function setLang($lang)
638     {
639         if (!is_object(self::$_PHPCAS_CLIENT)) {
640             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
641         }
642         if (gettype($lang) != 'string') {
643             phpCAS :: error('type mismatched for parameter $lang (should be `string\')');
644         }
645         self::$_PHPCAS_CLIENT->setLang($lang);
646     }
647
648     /** @} */
649     // ########################################################################
650     //  VERSION
651     // ########################################################################
652     /**
653     * @addtogroup public
654     * @{
655     */
656
657     /**
658      * This method returns the phpCAS version.
659      *
660      * @return the phpCAS version.
661      */
662     public static function getVersion()
663     {
664         return PHPCAS_VERSION;
665     }
666
667     /** @} */
668     // ########################################################################
669     //  HTML OUTPUT
670     // ########################################################################
671     /**
672     * @addtogroup publicOutput
673     * @{
674     */
675
676     /**
677      * This method sets the HTML header used for all outputs.
678      *
679      * @param string $header the HTML header.
680      *
681      * @return void
682      */
683     public static function setHTMLHeader($header)
684     {
685         if (!is_object(self::$_PHPCAS_CLIENT)) {
686             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
687         }
688         if (gettype($header) != 'string') {
689             phpCAS :: error('type mismatched for parameter $header (should be `string\')');
690         }
691         self::$_PHPCAS_CLIENT->setHTMLHeader($header);
692     }
693
694     /**
695      * This method sets the HTML footer used for all outputs.
696      *
697      * @param string $footer the HTML footer.
698      *
699      * @return void
700      */
701     public static function setHTMLFooter($footer)
702     {
703         if (!is_object(self::$_PHPCAS_CLIENT)) {
704             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
705         }
706         if (gettype($footer) != 'string') {
707             phpCAS :: error('type mismatched for parameter $footer (should be `string\')');
708         }
709         self::$_PHPCAS_CLIENT->setHTMLFooter($footer);
710     }
711
712     /** @} */
713     // ########################################################################
714     //  PGT STORAGE
715     // ########################################################################
716     /**
717     * @addtogroup publicPGTStorage
718     * @{
719     */
720
721     /**
722      * This method can be used to set a custom PGT storage object.
723      *
724      * @param CAS_PGTStorage $storage a PGT storage object that inherits from the
725      * CAS_PGTStorage class
726      *
727      * @return void
728      */
729     public static function setPGTStorage($storage)
730     {
731         phpCAS :: traceBegin();
732         if (!is_object(self::$_PHPCAS_CLIENT)) {
733             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
734         }
735         if (!self::$_PHPCAS_CLIENT->isProxy()) {
736             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
737         }
738         if (self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
739             phpCAS :: error('this method should only be called before ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() (called at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ')');
740         }
741         if ( !($storage instanceof CAS_PGTStorage) ) {
742             phpCAS :: error('type mismatched for parameter $storage (should be a CAS_PGTStorage `object\')');
743         }
744         self::$_PHPCAS_CLIENT->setPGTStorage($storage);
745         phpCAS :: traceEnd();
746     }
747
748     /**
749      * This method is used to tell phpCAS to store the response of the
750      * CAS server to PGT requests in a database.
751      *
752      * @param string $dsn_or_pdo     a dsn string to use for creating a PDO
753      * object or a PDO object
754      * @param string $username       the username to use when connecting to the
755      * database
756      * @param string $password       the password to use when connecting to the
757      * database
758      * @param string $table          the table to use for storing and retrieving
759      * PGT's
760      * @param string $driver_options any driver options to use when connecting
761      * to the database
762      *
763      * @return void
764      */
765     public static function setPGTStorageDb($dsn_or_pdo, $username='',
766         $password='', $table='', $driver_options=null
767     ) {
768         phpCAS :: traceBegin();
769         if (!is_object(self::$_PHPCAS_CLIENT)) {
770             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
771         }
772         if (!self::$_PHPCAS_CLIENT->isProxy()) {
773             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
774         }
775         if (self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
776             phpCAS :: error('this method should only be called before ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() (called at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ')');
777         }
778         if (gettype($username) != 'string') {
779             phpCAS :: error('type mismatched for parameter $username (should be `string\')');
780         }
781         if (gettype($password) != 'string') {
782             phpCAS :: error('type mismatched for parameter $password (should be `string\')');
783         }
784         if (gettype($table) != 'string') {
785             phpCAS :: error('type mismatched for parameter $table (should be `string\')');
786         }
787         self::$_PHPCAS_CLIENT->setPGTStorageDb($dsn_or_pdo, $username, $password, $table, $driver_options);
788         phpCAS :: traceEnd();
789     }
790
791     /**
792      * This method is used to tell phpCAS to store the response of the
793      * CAS server to PGT requests onto the filesystem.
794      *
795      * @param string $path the path where the PGT's should be stored
796      *
797      * @return void
798      */
799     public static function setPGTStorageFile($path = '')
800     {
801         phpCAS :: traceBegin();
802         if (!is_object(self::$_PHPCAS_CLIENT)) {
803             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
804         }
805         if (!self::$_PHPCAS_CLIENT->isProxy()) {
806             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
807         }
808         if (self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
809             phpCAS :: error('this method should only be called before ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() (called at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ')');
810         }
811         if (gettype($path) != 'string') {
812             phpCAS :: error('type mismatched for parameter $path (should be `string\')');
813         }
814         self::$_PHPCAS_CLIENT->setPGTStorageFile($path);
815         phpCAS :: traceEnd();
816     }
817     /** @} */
818     // ########################################################################
819     // ACCESS TO EXTERNAL SERVICES
820     // ########################################################################
821     /**
822     * @addtogroup publicServices
823     * @{
824     */
825
826     /**
827      * Answer a proxy-authenticated service handler.
828      *
829      * @param string $type The service type. One of
830      * PHPCAS_PROXIED_SERVICE_HTTP_GET; PHPCAS_PROXIED_SERVICE_HTTP_POST;
831      * PHPCAS_PROXIED_SERVICE_IMAP
832      *
833      * @return CAS_ProxiedService
834      * @throws InvalidArgumentException If the service type is unknown.
835      */
836     public static function getProxiedService ($type)
837     {
838         phpCAS :: traceBegin();
839         if (!is_object(self::$_PHPCAS_CLIENT)) {
840             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
841         }
842         if (!self::$_PHPCAS_CLIENT->isProxy()) {
843             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
844         }
845         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
846             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()');
847         }
848         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
849             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
850         }
851         if (gettype($type) != 'string') {
852             phpCAS :: error('type mismatched for parameter $type (should be `string\')');
853         }
854
855         $res = self::$_PHPCAS_CLIENT->getProxiedService($type);
856
857         phpCAS :: traceEnd();
858         return $res;
859     }
860
861     /**
862      * Initialize a proxied-service handler with the proxy-ticket it should use.
863      *
864      * @param CAS_ProxiedService $proxiedService Proxied Service Handler
865      *
866      * @return void
867      * @throws CAS_ProxyTicketException If there is a proxy-ticket failure.
868      *          The code of the Exception will be one of:
869      *                  PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE
870      *                  PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE
871      *                  PHPCAS_SERVICE_PT_FAILURE
872      */
873     public static function initializeProxiedService (CAS_ProxiedService $proxiedService)
874     {
875         if (!is_object(self::$_PHPCAS_CLIENT)) {
876             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
877         }
878         if (!self::$_PHPCAS_CLIENT->isProxy()) {
879             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
880         }
881         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
882             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()');
883         }
884         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
885             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
886         }
887
888         self::$_PHPCAS_CLIENT->initializeProxiedService($proxiedService);
889     }
890
891     /**
892      * This method is used to access an HTTP[S] service.
893      *
894      * @param string $url       the service to access.
895      * @param string &$err_code an error code Possible values are
896      * PHPCAS_SERVICE_OK (on success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE,
897      * PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE, PHPCAS_SERVICE_PT_FAILURE,
898      * PHPCAS_SERVICE_NOT_AVAILABLE.
899      * @param string &$output   the output of the service (also used to give an
900      * error message on failure).
901      *
902      * @return bool true on success, false otherwise (in this later case,
903      * $err_code gives the reason why it failed and $output contains an error
904      * message).
905      */
906     public static function serviceWeb($url, & $err_code, & $output)
907     {
908         phpCAS :: traceBegin();
909         if (!is_object(self::$_PHPCAS_CLIENT)) {
910             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
911         }
912         if (!self::$_PHPCAS_CLIENT->isProxy()) {
913             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
914         }
915         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
916             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()');
917         }
918         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
919             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
920         }
921         if (gettype($url) != 'string') {
922             phpCAS :: error('type mismatched for parameter $url (should be `string\')');
923         }
924
925         $res = self::$_PHPCAS_CLIENT->serviceWeb($url, $err_code, $output);
926
927         phpCAS :: traceEnd($res);
928         return $res;
929     }
930
931     /**
932      * This method is used to access an IMAP/POP3/NNTP service.
933      *
934      * @param string $url       a string giving the URL of the service,
935      * including the mailing box for IMAP URLs, as accepted by imap_open().
936      * @param string $service   a string giving for CAS retrieve Proxy ticket
937      * @param string $flags     options given to imap_open().
938      * @param string &$err_code an error code Possible values are
939      * PHPCAS_SERVICE_OK (on success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE,
940      * PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE, PHPCAS_SERVICE_PT_FAILURE,
941      * PHPCAS_SERVICE_NOT_AVAILABLE.
942      * @param string &$err_msg  an error message on failure
943      * @param string &$pt       the Proxy Ticket (PT) retrieved from the CAS
944      * server to access the URL on success, false on error).
945      *
946      * @return object IMAP stream on success, false otherwise (in this later
947      * case, $err_code gives the reason why it failed and $err_msg contains an
948      * error message).
949      */
950     public static function serviceMail($url, $service, $flags, & $err_code, & $err_msg, & $pt)
951     {
952         phpCAS :: traceBegin();
953         if (!is_object(self::$_PHPCAS_CLIENT)) {
954             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
955         }
956         if (!self::$_PHPCAS_CLIENT->isProxy()) {
957             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
958         }
959         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
960             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()');
961         }
962         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
963             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
964         }
965         if (gettype($url) != 'string') {
966             phpCAS :: error('type mismatched for parameter $url (should be `string\')');
967         }
968
969         if (gettype($flags) != 'integer') {
970             phpCAS :: error('type mismatched for parameter $flags (should be `integer\')');
971         }
972
973         $res = self::$_PHPCAS_CLIENT->serviceMail($url, $service, $flags, $err_code, $err_msg, $pt);
974
975         phpCAS :: traceEnd($res);
976         return $res;
977     }
978
979     /** @} */
980     // ########################################################################
981     //  AUTHENTICATION
982     // ########################################################################
983     /**
984     * @addtogroup publicAuth
985     * @{
986     */
987
988     /**
989      * Set the times authentication will be cached before really accessing the
990      * CAS server in gateway mode:
991      * - -1: check only once, and then never again (until you pree login)
992      * - 0: always check
993      * - n: check every "n" time
994      *
995      * @param int $n an integer.
996      *
997      * @return void
998      */
999     public static function setCacheTimesForAuthRecheck($n)
1000     {
1001         if (!is_object(self::$_PHPCAS_CLIENT)) {
1002             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1003         }
1004         if (gettype($n) != 'integer') {
1005             phpCAS :: error('type mismatched for parameter $n (should be `integer\')');
1006         }
1007         self::$_PHPCAS_CLIENT->setCacheTimesForAuthRecheck($n);
1008     }
1009
1010     /**
1011      * Set a callback function to be run when a user authenticates.
1012      *
1013      * The callback function will be passed a $logoutTicket as its first
1014      * parameter, followed by any $additionalArgs you pass. The $logoutTicket
1015      * parameter is an opaque string that can be used to map the session-id to
1016      * logout request in order to support single-signout in applications that
1017      * manage their own sessions (rather than letting phpCAS start the session).
1018      *
1019      * phpCAS::forceAuthentication() will always exit and forward client unless
1020      * they are already authenticated. To perform an action at the moment the user
1021      * logs in (such as registering an account, performing logging, etc), register
1022      * a callback function here.
1023      *
1024      * @param string $function       Callback function
1025      * @param array  $additionalArgs optional array of arguments
1026      *
1027      * @return void
1028      */
1029     public static function setPostAuthenticateCallback ($function, array $additionalArgs = array())
1030     {
1031         if (!is_object(self::$_PHPCAS_CLIENT)) {
1032             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1033         }
1034
1035         self::$_PHPCAS_CLIENT->setPostAuthenticateCallback($function, $additionalArgs);
1036     }
1037
1038     /**
1039      * Set a callback function to be run when a single-signout request is
1040      * received. The callback function will be passed a $logoutTicket as its
1041      * first parameter, followed by any $additionalArgs you pass. The
1042      * $logoutTicket parameter is an opaque string that can be used to map a
1043      * session-id to the logout request in order to support single-signout in
1044      * applications that manage their own sessions (rather than letting phpCAS
1045      * start and destroy the session).
1046      *
1047      * @param string $function       Callback function
1048      * @param array  $additionalArgs optional array of arguments
1049      *
1050      * @return void
1051      */
1052     public static function setSingleSignoutCallback ($function, array $additionalArgs = array())
1053     {
1054         if (!is_object(self::$_PHPCAS_CLIENT)) {
1055             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1056         }
1057
1058         self::$_PHPCAS_CLIENT->setSingleSignoutCallback($function, $additionalArgs);
1059     }
1060
1061     /**
1062      * This method is called to check if the user is already authenticated
1063      * locally or has a global cas session. A already existing cas session is
1064      * determined by a cas gateway call.(cas login call without any interactive
1065      * prompt)
1066      *
1067      * @return true when the user is authenticated, false when a previous
1068      * gateway login failed or the function will not return if the user is
1069      * redirected to the cas server for a gateway login attempt
1070      */
1071     public static function checkAuthentication()
1072     {
1073         phpCAS :: traceBegin();
1074         if (!is_object(self::$_PHPCAS_CLIENT)) {
1075             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1076         }
1077
1078         $auth = self::$_PHPCAS_CLIENT->checkAuthentication();
1079
1080         // store where the authentication has been checked and the result
1081         self::$_PHPCAS_CLIENT->markAuthenticationCall($auth);
1082
1083         phpCAS :: traceEnd($auth);
1084         return $auth;
1085     }
1086
1087     /**
1088      * This method is called to force authentication if the user was not already
1089      * authenticated. If the user is not authenticated, halt by redirecting to
1090      * the CAS server.
1091      *
1092      * @return bool Authentication
1093      */
1094     public static function forceAuthentication()
1095     {
1096         phpCAS :: traceBegin();
1097         if (!is_object(self::$_PHPCAS_CLIENT)) {
1098             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1099         }
1100
1101         $auth = self::$_PHPCAS_CLIENT->forceAuthentication();
1102
1103         // store where the authentication has been checked and the result
1104         self::$_PHPCAS_CLIENT->markAuthenticationCall($auth);
1105
1106         /*              if (!$auth) {
1107          phpCAS :: trace('user is not authenticated, redirecting to the CAS server');
1108         self::$_PHPCAS_CLIENT->forceAuthentication();
1109         } else {
1110         phpCAS :: trace('no need to authenticate (user `' . phpCAS :: getUser() . '\' is already authenticated)');
1111         }*/
1112
1113         phpCAS :: traceEnd();
1114         return $auth;
1115     }
1116
1117     /**
1118      * This method is called to renew the authentication.
1119      *
1120      * @return void
1121      **/
1122     public static function renewAuthentication()
1123     {
1124         phpCAS :: traceBegin();
1125         if (!is_object(self::$_PHPCAS_CLIENT)) {
1126             phpCAS :: error('this method should not be called before' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1127         }
1128         $auth = self::$_PHPCAS_CLIENT->renewAuthentication();
1129
1130         // store where the authentication has been checked and the result
1131         self::$_PHPCAS_CLIENT->markAuthenticationCall($auth);
1132
1133         //self::$_PHPCAS_CLIENT->renewAuthentication();
1134         phpCAS :: traceEnd();
1135     }
1136
1137     /**
1138      * This method is called to check if the user is authenticated (previously or by
1139      * tickets given in the URL).
1140      *
1141      * @return true when the user is authenticated.
1142      */
1143     public static function isAuthenticated()
1144     {
1145         phpCAS :: traceBegin();
1146         if (!is_object(self::$_PHPCAS_CLIENT)) {
1147             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1148         }
1149
1150         // call the isAuthenticated method of the $_PHPCAS_CLIENT object
1151         $auth = self::$_PHPCAS_CLIENT->isAuthenticated();
1152
1153         // store where the authentication has been checked and the result
1154         self::$_PHPCAS_CLIENT->markAuthenticationCall($auth);
1155
1156         phpCAS :: traceEnd($auth);
1157         return $auth;
1158     }
1159
1160     /**
1161      * Checks whether authenticated based on $_SESSION. Useful to avoid
1162      * server calls.
1163      *
1164      * @return bool true if authenticated, false otherwise.
1165      * @since 0.4.22 by Brendan Arnold
1166      */
1167     public static function isSessionAuthenticated()
1168     {
1169         if (!is_object(self::$_PHPCAS_CLIENT)) {
1170             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1171         }
1172         return (self::$_PHPCAS_CLIENT->isSessionAuthenticated());
1173     }
1174
1175     /**
1176      * This method returns the CAS user's login name.
1177      *
1178      * @return string the login name of the authenticated user
1179      * @warning should not be called only after phpCAS::forceAuthentication()
1180      * or phpCAS::checkAuthentication().
1181      * */
1182     public static function getUser()
1183     {
1184         if (!is_object(self::$_PHPCAS_CLIENT)) {
1185             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1186         }
1187         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
1188             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1189         }
1190         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
1191             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
1192         }
1193         return self::$_PHPCAS_CLIENT->getUser();
1194     }
1195
1196     /**
1197      * Answer attributes about the authenticated user.
1198      *
1199      * @warning should not be called only after phpCAS::forceAuthentication()
1200      * or phpCAS::checkAuthentication().
1201      *
1202      * @return array
1203      */
1204     public static function getAttributes()
1205     {
1206         if (!is_object(self::$_PHPCAS_CLIENT)) {
1207             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1208         }
1209         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
1210             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1211         }
1212         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
1213             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
1214         }
1215         return self::$_PHPCAS_CLIENT->getAttributes();
1216     }
1217
1218     /**
1219      * Answer true if there are attributes for the authenticated user.
1220      *
1221      * @warning should not be called only after phpCAS::forceAuthentication()
1222      * or phpCAS::checkAuthentication().
1223      *
1224      * @return bool
1225      */
1226     public static function hasAttributes()
1227     {
1228         if (!is_object(self::$_PHPCAS_CLIENT)) {
1229             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1230         }
1231         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
1232             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1233         }
1234         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
1235             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
1236         }
1237         return self::$_PHPCAS_CLIENT->hasAttributes();
1238     }
1239
1240     /**
1241      * Answer true if an attribute exists for the authenticated user.
1242      *
1243      * @param string $key attribute name
1244      *
1245      * @return bool
1246      * @warning should not be called only after phpCAS::forceAuthentication()
1247      * or phpCAS::checkAuthentication().
1248      */
1249     public static function hasAttribute($key)
1250     {
1251         if (!is_object(self::$_PHPCAS_CLIENT)) {
1252             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1253         }
1254         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
1255             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1256         }
1257         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
1258             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
1259         }
1260         return self::$_PHPCAS_CLIENT->hasAttribute($key);
1261     }
1262
1263     /**
1264      * Answer an attribute for the authenticated user.
1265      *
1266      * @param string $key attribute name
1267      *
1268      * @return mixed string for a single value or an array if multiple values exist.
1269      * @warning should not be called only after phpCAS::forceAuthentication()
1270      * or phpCAS::checkAuthentication().
1271      */
1272     public static function getAttribute($key)
1273     {
1274         if (!is_object(self::$_PHPCAS_CLIENT)) {
1275             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1276         }
1277         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCalled()) {
1278             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1279         }
1280         if (!self::$_PHPCAS_CLIENT->wasAuthenticationCallSuccessful()) {
1281             phpCAS :: error('authentication was checked (by ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerMethod() . '() at ' . self::$_PHPCAS_CLIENT->getAuthenticationCallerFile() . ':' . self::$_PHPCAS_CLIENT->getAuthenticationCallerLine() . ') but the method returned false');
1282         }
1283         return self::$_PHPCAS_CLIENT->getAttribute($key);
1284     }
1285
1286     /**
1287      * Handle logout requests.
1288      *
1289      * @param bool  $check_client    additional safety check
1290      * @param array $allowed_clients array of allowed clients
1291      *
1292      * @return void
1293      */
1294     public static function handleLogoutRequests($check_client = true, $allowed_clients = false)
1295     {
1296         if (!is_object(self::$_PHPCAS_CLIENT)) {
1297             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1298         }
1299         return (self::$_PHPCAS_CLIENT->handleLogoutRequests($check_client, $allowed_clients));
1300     }
1301
1302     /**
1303      * This method returns the URL to be used to login.
1304      * or phpCAS::isAuthenticated().
1305      *
1306      * @return the login name of the authenticated user
1307      */
1308     public static function getServerLoginURL()
1309     {
1310         if (!is_object(self::$_PHPCAS_CLIENT)) {
1311             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1312         }
1313         return self::$_PHPCAS_CLIENT->getServerLoginURL();
1314     }
1315
1316     /**
1317      * Set the login URL of the CAS server.
1318      *
1319      * @param string $url the login URL
1320      *
1321      * @return void
1322      * @since 0.4.21 by Wyman Chan
1323      */
1324     public static function setServerLoginURL($url = '')
1325     {
1326         phpCAS :: traceBegin();
1327         if (!is_object(self::$_PHPCAS_CLIENT)) {
1328             phpCAS :: error('this method should only be called after' . __CLASS__ . '::client()');
1329         }
1330         if (gettype($url) != 'string') {
1331             phpCAS :: error('type mismatched for parameter $url (should be `string`)');
1332         }
1333         self::$_PHPCAS_CLIENT->setServerLoginURL($url);
1334         phpCAS :: traceEnd();
1335     }
1336
1337     /**
1338      * Set the serviceValidate URL of the CAS server.
1339      * Used only in CAS 1.0 validations
1340      *
1341      * @param string $url the serviceValidate URL
1342      *
1343      * @return void
1344      */
1345     public static function setServerServiceValidateURL($url = '')
1346     {
1347         phpCAS :: traceBegin();
1348         if (!is_object(self::$_PHPCAS_CLIENT)) {
1349             phpCAS :: error('this method should only be called after' . __CLASS__ . '::client()');
1350         }
1351         if (gettype($url) != 'string') {
1352             phpCAS :: error('type mismatched for parameter $url (should be `string`)');
1353         }
1354         self::$_PHPCAS_CLIENT->setServerServiceValidateURL($url);
1355         phpCAS :: traceEnd();
1356     }
1357
1358     /**
1359      * Set the proxyValidate URL of the CAS server.
1360      * Used for all CAS 2.0 validations
1361      *
1362      * @param string $url the proxyValidate URL
1363      *
1364      * @return void
1365      */
1366     public static function setServerProxyValidateURL($url = '')
1367     {
1368         phpCAS :: traceBegin();
1369         if (!is_object(self::$_PHPCAS_CLIENT)) {
1370             phpCAS :: error('this method should only be called after' . __CLASS__ . '::client()');
1371         }
1372         if (gettype($url) != 'string') {
1373             phpCAS :: error('type mismatched for parameter $url (should be `string`)');
1374         }
1375         self::$_PHPCAS_CLIENT->setServerProxyValidateURL($url);
1376         phpCAS :: traceEnd();
1377     }
1378
1379     /**
1380      * Set the samlValidate URL of the CAS server.
1381      *
1382      * @param string $url the samlValidate URL
1383      *
1384      * @return void
1385      */
1386     public static function setServerSamlValidateURL($url = '')
1387     {
1388         phpCAS :: traceBegin();
1389         if (!is_object(self::$_PHPCAS_CLIENT)) {
1390             phpCAS :: error('this method should only be called after' . __CLASS__ . '::client()');
1391         }
1392         if (gettype($url) != 'string') {
1393             phpCAS :: error('type mismatched for parameter $url (should be`string\')');
1394         }
1395         self::$_PHPCAS_CLIENT->setServerSamlValidateURL($url);
1396         phpCAS :: traceEnd();
1397     }
1398
1399     /**
1400      * This method returns the URL to be used to login.
1401      * or phpCAS::isAuthenticated().
1402      *
1403      * @return the login name of the authenticated user
1404      */
1405     public static function getServerLogoutURL()
1406     {
1407         if (!is_object(self::$_PHPCAS_CLIENT)) {
1408             phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1409         }
1410         return self::$_PHPCAS_CLIENT->getServerLogoutURL();
1411     }
1412
1413     /**
1414      * Set the logout URL of the CAS server.
1415      *
1416      * @param string $url the logout URL
1417      *
1418      * @return void
1419      * @since 0.4.21 by Wyman Chan
1420      */
1421     public static function setServerLogoutURL($url = '')
1422     {
1423         phpCAS :: traceBegin();
1424         if (!is_object(self::$_PHPCAS_CLIENT)) {
1425             phpCAS :: error(
1426                 'this method should only be called after' . __CLASS__ . '::client()'
1427             );
1428         }
1429         if (gettype($url) != 'string') {
1430             phpCAS :: error(
1431                 'type mismatched for parameter $url (should be `string`)'
1432             );
1433         }
1434         self::$_PHPCAS_CLIENT->setServerLogoutURL($url);
1435         phpCAS :: traceEnd();
1436     }
1437
1438     /**
1439      * This method is used to logout from CAS.
1440      *
1441      * @param string $params an array that contains the optional url and
1442      * service parameters that will be passed to the CAS server
1443      *
1444      * @return void
1445      */
1446     public static function logout($params = "")
1447     {
1448         phpCAS :: traceBegin();
1449         if (!is_object(self::$_PHPCAS_CLIENT)) {
1450             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1451         }
1452         $parsedParams = array ();
1453         if ($params != "") {
1454             if (is_string($params)) {
1455                 phpCAS :: error('method `phpCAS::logout($url)\' is now deprecated, use `phpCAS::logoutWithUrl($url)\' instead');
1456             }
1457             if (!is_array($params)) {
1458                 phpCAS :: error('type mismatched for parameter $params (should be `array\')');
1459             }
1460             foreach ($params as $key => $value) {
1461                 if ($key != "service" && $key != "url") {
1462                     phpCAS :: error('only `url\' and `service\' parameters are allowed for method `phpCAS::logout($params)\'');
1463                 }
1464                 $parsedParams[$key] = $value;
1465             }
1466         }
1467         self::$_PHPCAS_CLIENT->logout($parsedParams);
1468         // never reached
1469         phpCAS :: traceEnd();
1470     }
1471
1472     /**
1473      * This method is used to logout from CAS. Halts by redirecting to the CAS
1474      * server.
1475      *
1476      * @param service $service a URL that will be transmitted to the CAS server
1477      *
1478      * @return void
1479      */
1480     public static function logoutWithRedirectService($service)
1481     {
1482         phpCAS :: traceBegin();
1483         if (!is_object(self::$_PHPCAS_CLIENT)) {
1484             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1485         }
1486         if (!is_string($service)) {
1487             phpCAS :: error('type mismatched for parameter $service (should be `string\')');
1488         }
1489         self::$_PHPCAS_CLIENT->logout(array ( "service" => $service ));
1490         // never reached
1491         phpCAS :: traceEnd();
1492     }
1493
1494     /**
1495      * This method is used to logout from CAS. Halts by redirecting to the CAS
1496      * server.
1497      *
1498      * @param string $url a URL that will be transmitted to the CAS server
1499      *
1500      * @return void
1501      * @deprecated The url parameter has been removed from the CAS server as of
1502      * version 3.3.5.1
1503      */
1504     public static function logoutWithUrl($url)
1505     {
1506         trigger_error('Function deprecated for cas servers >= 3.3.5.1', E_USER_DEPRECATED);
1507         phpCAS :: traceBegin();
1508         if (!is_object(self::$_PHPCAS_CLIENT)) {
1509             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1510         }
1511         if (!is_string($url)) {
1512             phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1513         }
1514         self::$_PHPCAS_CLIENT->logout(array ( "url" => $url ));
1515         // never reached
1516         phpCAS :: traceEnd();
1517     }
1518
1519     /**
1520      * This method is used to logout from CAS. Halts by redirecting to the CAS
1521      * server.
1522      *
1523      * @param string $service a URL that will be transmitted to the CAS server
1524      * @param string $url     a URL that will be transmitted to the CAS server
1525      *
1526      * @return void
1527      *
1528      * @deprecated The url parameter has been removed from the CAS server as of
1529      * version 3.3.5.1
1530      */
1531     public static function logoutWithRedirectServiceAndUrl($service, $url)
1532     {
1533         trigger_error('Function deprecated for cas servers >= 3.3.5.1', E_USER_DEPRECATED);
1534         phpCAS :: traceBegin();
1535         if (!is_object(self::$_PHPCAS_CLIENT)) {
1536             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1537         }
1538         if (!is_string($service)) {
1539             phpCAS :: error('type mismatched for parameter $service (should be `string\')');
1540         }
1541         if (!is_string($url)) {
1542             phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1543         }
1544         self::$_PHPCAS_CLIENT->logout(
1545             array (
1546                 "service" => $service,
1547                 "url" => $url
1548             )
1549         );
1550         // never reached
1551         phpCAS :: traceEnd();
1552     }
1553
1554     /**
1555      * Set the fixed URL that will be used by the CAS server to transmit the
1556      * PGT. When this method is not called, a phpCAS script uses its own URL
1557      * for the callback.
1558      *
1559      * @param string $url the URL
1560      *
1561      * @return void
1562      */
1563     public static function setFixedCallbackURL($url = '')
1564     {
1565         phpCAS :: traceBegin();
1566         if (!is_object(self::$_PHPCAS_CLIENT)) {
1567             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1568         }
1569         if (!self::$_PHPCAS_CLIENT->isProxy()) {
1570             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1571         }
1572         if (gettype($url) != 'string') {
1573             phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1574         }
1575         self::$_PHPCAS_CLIENT->setCallbackURL($url);
1576         phpCAS :: traceEnd();
1577     }
1578
1579     /**
1580      * Set the fixed URL that will be set as the CAS service parameter. When this
1581      * method is not called, a phpCAS script uses its own URL.
1582      *
1583      * @param string $url the URL
1584      *
1585      * @return void
1586      */
1587     public static function setFixedServiceURL($url)
1588     {
1589         phpCAS :: traceBegin();
1590         if (!is_object(self::$_PHPCAS_CLIENT)) {
1591             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1592         }
1593         if (gettype($url) != 'string') {
1594             phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1595         }
1596         self::$_PHPCAS_CLIENT->setURL($url);
1597         phpCAS :: traceEnd();
1598     }
1599
1600     /**
1601      * Get the URL that is set as the CAS service parameter.
1602      *
1603      * @return string Service Url
1604      */
1605     public static function getServiceURL()
1606     {
1607         if (!is_object(self::$_PHPCAS_CLIENT)) {
1608             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1609         }
1610         return (self::$_PHPCAS_CLIENT->getURL());
1611     }
1612
1613     /**
1614      * Retrieve a Proxy Ticket from the CAS server.
1615      *
1616      * @param string $target_service Url string of service to proxy
1617      * @param string &$err_code      error code
1618      * @param string &$err_msg       error message
1619      *
1620      * @return string Proxy Ticket
1621      */
1622     public static function retrievePT($target_service, & $err_code, & $err_msg)
1623     {
1624         if (!is_object(self::$_PHPCAS_CLIENT)) {
1625             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1626         }
1627         if (gettype($target_service) != 'string') {
1628             phpCAS :: error('type mismatched for parameter $target_service(should be `string\')');
1629         }
1630         return (self::$_PHPCAS_CLIENT->retrievePT($target_service, $err_code, $err_msg));
1631     }
1632
1633     /**
1634      * Set the certificate of the CAS server CA and if the CN should be properly
1635      * verified.
1636      *
1637      * @param string $cert        CA certificate file name
1638      * @param bool   $validate_cn Validate CN in certificate (default true)
1639      *
1640      * @return void
1641      */
1642     public static function setCasServerCACert($cert, $validate_cn = true)
1643     {
1644         phpCAS :: traceBegin();
1645         if (!is_object(self::$_PHPCAS_CLIENT)) {
1646             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1647         }
1648         if (gettype($cert) != 'string') {
1649             phpCAS :: error('type mismatched for parameter $cert (should be `string\')');
1650         }
1651         if (gettype($validate_cn) != 'boolean') {\r
1652             phpCAS :: error('type mismatched for parameter $validate_cn (should be `boolean\')');\r
1653         }
1654         self::$_PHPCAS_CLIENT->setCasServerCACert($cert, $validate_cn);
1655         phpCAS :: traceEnd();
1656     }
1657
1658     /**
1659      * Set no SSL validation for the CAS server.
1660      *
1661      * @return void
1662      */
1663     public static function setNoCasServerValidation()
1664     {
1665         phpCAS :: traceBegin();
1666         if (!is_object(self::$_PHPCAS_CLIENT)) {
1667             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1668         }
1669         phpCAS :: trace('You have configured no validation of the legitimacy of the cas server. This is not recommended for production use.');
1670         self::$_PHPCAS_CLIENT->setNoCasServerValidation();
1671         phpCAS :: traceEnd();
1672     }
1673
1674
1675     /**
1676      * Disable the removal of a CAS-Ticket from the URL when authenticating
1677      * DISABLING POSES A SECURITY RISK:
1678      * We normally remove the ticket by an additional redirect as a security
1679      * precaution to prevent a ticket in the HTTP_REFERRER or be carried over in
1680      * the URL parameter
1681      *
1682      * @return void
1683      */
1684     public static function setNoClearTicketsFromUrl()
1685     {
1686         phpCAS :: traceBegin();
1687         if (!is_object(self::$_PHPCAS_CLIENT)) {
1688             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1689         }
1690         self::$_PHPCAS_CLIENT->setNoClearTicketsFromUrl();
1691         phpCAS :: traceEnd();
1692     }
1693
1694     /** @} */
1695
1696     /**
1697      * Change CURL options.
1698      * CURL is used to connect through HTTPS to CAS server
1699      *
1700      * @param string $key   the option key
1701      * @param string $value the value to set
1702      *
1703      * @return void
1704      */
1705     public static function setExtraCurlOption($key, $value)
1706     {
1707         phpCAS :: traceBegin();
1708         if (!is_object(self::$_PHPCAS_CLIENT)) {
1709             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1710         }
1711         self::$_PHPCAS_CLIENT->setExtraCurlOption($key, $value);
1712         phpCAS :: traceEnd();
1713     }
1714
1715     /**
1716      * If you want your service to be proxied you have to enable it (default
1717      * disabled) and define an accepable list of proxies that are allowed to
1718      * proxy your service.
1719      *
1720      * Add each allowed proxy definition object. For the normal CAS_ProxyChain
1721      * class, the constructor takes an array of proxies to match. The list is in
1722      * reverse just as seen from the service. Proxies have to be defined in reverse
1723      * from the service to the user. If a user hits service A and gets proxied via
1724      * B to service C the list of acceptable on C would be array(B,A). The definition
1725      * of an individual proxy can be either a string or a regexp (preg_match is used)
1726      * that will be matched against the proxy list supplied by the cas server
1727      * when validating the proxy tickets. The strings are compared starting from
1728      * the beginning and must fully match with the proxies in the list.
1729      * Example:
1730      *          phpCAS::allowProxyChain(new CAS_ProxyChain(array(
1731      *                          'https://app.example.com/'
1732      *                  )));
1733      *          phpCAS::allowProxyChain(new CAS_ProxyChain(array(
1734      *                          '/^https:\/\/app[0-9]\.example\.com\/rest\//',
1735      *                          'http://client.example.com/'
1736      *                  )));
1737      *
1738      * For quick testing or in certain production screnarios you might want to
1739      * allow allow any other valid service to proxy your service. To do so, add
1740      * the "Any" chain:
1741      *          phpcas::allowProxyChain(new CAS_ProxyChain_Any);
1742      * THIS SETTING IS HOWEVER NOT RECOMMENDED FOR PRODUCTION AND HAS SECURITY
1743      * IMPLICATIONS: YOU ARE ALLOWING ANY SERVICE TO ACT ON BEHALF OF A USER
1744      * ON THIS SERVICE.
1745      *
1746      * @param CAS_ProxyChain_Interface $proxy_chain A proxy-chain that will be
1747      * matched against the proxies requesting access
1748      *
1749      * @return void
1750      */
1751     public static function allowProxyChain(CAS_ProxyChain_Interface $proxy_chain)
1752     {
1753         phpCAS :: traceBegin();
1754         if (!is_object(self::$_PHPCAS_CLIENT)) {
1755             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1756         }
1757         if (self::$_PHPCAS_CLIENT->getServerVersion() !== CAS_VERSION_2_0) {
1758             phpCAS :: error('this method can only be used with the cas 2.0 protool');
1759         }
1760         self::$_PHPCAS_CLIENT->getAllowedProxyChains()->allowProxyChain($proxy_chain);
1761         phpCAS :: traceEnd();
1762     }
1763
1764     /**
1765      * Answer an array of proxies that are sitting in front of this application.
1766      * This method will only return a non-empty array if we have received and
1767      * validated a Proxy Ticket.
1768      *
1769      * @return array
1770      * @access public
1771      * @since 6/25/09
1772      */
1773     public static function getProxies ()
1774     {
1775         if ( !is_object(self::$_PHPCAS_CLIENT) ) {
1776             phpCAS::error('this method should only be called after '.__CLASS__.'::client()');
1777         }
1778
1779         return(self::$_PHPCAS_CLIENT->getProxies());
1780     }
1781
1782     // ########################################################################
1783     // PGTIOU/PGTID and logoutRequest rebroadcasting
1784     // ########################################################################
1785
1786     /**
1787      * Add a pgtIou/pgtId and logoutRequest rebroadcast node.
1788      *
1789      * @param string $rebroadcastNodeUrl The rebroadcast node URL. Can be
1790      * hostname or IP.
1791      *
1792      * @return void
1793      */
1794     public static function addRebroadcastNode($rebroadcastNodeUrl)
1795     {
1796         phpCAS::traceBegin();
1797         phpCAS::log('rebroadcastNodeUrl:'.$rebroadcastNodeUrl);
1798         if (!is_object(self::$_PHPCAS_CLIENT)) {
1799             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1800         }
1801         if ( !(bool)preg_match("/^(http|https):\/\/([A-Z0-9][A-Z0-9_-]*(?:\.[A-Z0-9][A-Z0-9_-]*)+):?(\d+)?\/?/i", $rebroadcastNodeUrl)) {
1802             phpCAS::error('type mismatched for parameter $rebroadcastNodeUrl (should be `url\')');
1803         }
1804         self::$_PHPCAS_CLIENT->addRebroadcastNode($rebroadcastNodeUrl);
1805         phpCAS::traceEnd();
1806     }
1807
1808     /**
1809      * This method is used to add header parameters when rebroadcasting
1810      * pgtIou/pgtId or logoutRequest.
1811      *
1812      * @param String $header Header to send when rebroadcasting.
1813      *
1814      * @return void
1815      */
1816     public static function addRebroadcastHeader($header)
1817     {
1818         phpCAS :: traceBegin();
1819         if (!is_object(self::$_PHPCAS_CLIENT)) {
1820             phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1821         }
1822         self::$_PHPCAS_CLIENT->addRebroadcastHeader($header);
1823         phpCAS :: traceEnd();
1824     }
1825 }
1826
1827 // ########################################################################
1828 // DOCUMENTATION
1829 // ########################################################################
1830
1831 // ########################################################################
1832 //  MAIN PAGE
1833
1834 /**
1835  * @mainpage
1836  *
1837  * The following pages only show the source documentation.
1838  *
1839  */
1840
1841 // ########################################################################
1842 //  MODULES DEFINITION
1843
1844 /** @defgroup public User interface */
1845
1846 /** @defgroup publicInit Initialization
1847  *  @ingroup public */
1848
1849 /** @defgroup publicAuth Authentication
1850  *  @ingroup public */
1851
1852 /** @defgroup publicServices Access to external services
1853  *  @ingroup public */
1854
1855 /** @defgroup publicConfig Configuration
1856  *  @ingroup public */
1857
1858 /** @defgroup publicLang Internationalization
1859  *  @ingroup publicConfig */
1860
1861 /** @defgroup publicOutput HTML output
1862  *  @ingroup publicConfig */
1863
1864 /** @defgroup publicPGTStorage PGT storage
1865  *  @ingroup publicConfig */
1866
1867 /** @defgroup publicDebug Debugging
1868  *  @ingroup public */
1869
1870 /** @defgroup internal Implementation */
1871
1872 /** @defgroup internalAuthentication Authentication
1873  *  @ingroup internal */
1874
1875 /** @defgroup internalBasic CAS Basic client features (CAS 1.0, Service Tickets)
1876  *  @ingroup internal */
1877
1878 /** @defgroup internalProxy CAS Proxy features (CAS 2.0, Proxy Granting Tickets)
1879  *  @ingroup internal */
1880
1881 /** @defgroup internalSAML CAS SAML features (SAML 1.1)
1882  *  @ingroup internal */
1883
1884 /** @defgroup internalPGTStorage PGT storage
1885  *  @ingroup internalProxy */
1886
1887 /** @defgroup internalPGTStorageDb PGT storage in a database
1888  *  @ingroup internalPGTStorage */
1889
1890 /** @defgroup internalPGTStorageFile PGT storage on the filesystem
1891  *  @ingroup internalPGTStorage */
1892
1893 /** @defgroup internalCallback Callback from the CAS server
1894  *  @ingroup internalProxy */
1895
1896 /** @defgroup internalProxyServices Proxy other services
1897  *  @ingroup internalProxy */
1898
1899 /** @defgroup internalService CAS client features (CAS 2.0, Proxied service)
1900  *  @ingroup internal */
1901
1902 /** @defgroup internalConfig Configuration
1903  *  @ingroup internal */
1904
1905 /** @defgroup internalBehave Internal behaviour of phpCAS
1906  *  @ingroup internalConfig */
1907
1908 /** @defgroup internalOutput HTML output
1909  *  @ingroup internalConfig */
1910
1911 /** @defgroup internalLang Internationalization
1912  *  @ingroup internalConfig
1913  *
1914  * To add a new language:
1915  * - 1. define a new constant PHPCAS_LANG_XXXXXX in CAS/CAS.php
1916  * - 2. copy any file from CAS/languages to CAS/languages/XXXXXX.php
1917  * - 3. Make the translations
1918  */
1919
1920 /** @defgroup internalDebug Debugging
1921  *  @ingroup internal */
1922
1923 /** @defgroup internalMisc Miscellaneous
1924  *  @ingroup internal */
1925
1926 // ########################################################################
1927 //  EXAMPLES
1928
1929 /**
1930  * @example example_simple.php
1931  */
1932 /**
1933  * @example example_service.php
1934  */
1935 /**
1936  * @example example_service_that_proxies.php
1937  */
1938 /**
1939  * @example example_service_POST.php
1940  */
1941 /**
1942  * @example example_proxy_serviceWeb.php
1943  */
1944 /**
1945  * @example example_proxy_serviceWeb_chaining.php
1946  */
1947 /**
1948  * @example example_proxy_POST.php
1949  */
1950 /**
1951  * @example example_proxy_GET.php
1952  */
1953 /**
1954  * @example example_lang.php
1955  */
1956 /**
1957  * @example example_html.php
1958  */
1959 /**
1960  * @example example_pgt_storage_file.php
1961  */
1962 /**
1963  * @example example_pgt_storage_db.php
1964  */
1965 /**
1966  * @example example_gateway.php
1967  */
1968 /**
1969  * @example example_logout.php
1970  */
1971 /**
1972  * @example example_rebroadcast.php
1973  */
1974 /**
1975  * @example example_custom_urls.php
1976  */
1977 /**
1978  * @example example_advanced_saml11.php
1979  */
1980 ?>