4 * Copyright © 2003-2010, The ESUP-Portail consortium & the JA-SIG Collaborative.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
10 * * Redistributions of source code must retain the above copyright notice,
11 * this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the documentation
14 * and/or other materials provided with the distribution.
15 * * Neither the name of the ESUP-Portail consortium & the JA-SIG
16 * Collaborative nor the names of its contributors may be used to endorse or
17 * promote products derived from this software without specific prior
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 // hack by Vangelis Haniotakis to handle the absence of $_SERVER['REQUEST_URI'] in IIS
35 if (!isset($_SERVER['REQUEST_URI'])) {
36 $_SERVER['REQUEST_URI'] = $_SERVER['SCRIPT_NAME'] . '?' . $_SERVER['QUERY_STRING'];
40 // another one by Vangelis Haniotakis also to make phpCAS work with PHP5
42 if (version_compare(PHP_VERSION
, '5', '>=') && !(function_exists('domxml_new_doc'))) {
43 require_once (dirname(__FILE__
) . '/CAS/domxml-php4-to-php5.php');
48 * Interface class of the phpCAS library
53 // ########################################################################
55 // ########################################################################
57 // ------------------------------------------------------------------------
59 // ------------------------------------------------------------------------
62 * phpCAS version. accessible for the user by phpCAS::getVersion().
64 define('PHPCAS_VERSION', '1.1.3');
66 // ------------------------------------------------------------------------
68 // ------------------------------------------------------------------------
77 define("CAS_VERSION_1_0", '1.0');
81 define("CAS_VERSION_2_0", '2.0');
83 // ------------------------------------------------------------------------
85 // ------------------------------------------------------------------------
90 define("SAML_VERSION_1_1", 'S1');
93 * XML header for SAML POST
95 define("SAML_XML_HEADER", '<?xml version="1.0" encoding="UTF-8"?>');
98 * SOAP envelope for SAML POST
100 define("SAML_SOAP_ENV", '<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/>');
103 * SOAP body for SAML POST
105 define("SAML_SOAP_BODY", '<SOAP-ENV:Body>');
110 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">');
111 define("SAMLP_REQUEST_CLOSE", '</samlp:Request>');
114 * SAMLP artifact tag (for the ticket)
116 define("SAML_ASSERTION_ARTIFACT", '<samlp:AssertionArtifact>');
121 define("SAML_ASSERTION_ARTIFACT_CLOSE", '</samlp:AssertionArtifact>');
126 define("SAML_SOAP_BODY_CLOSE", '</SOAP-ENV:Body>');
129 * SOAP envelope close
131 define("SAML_SOAP_ENV_CLOSE", '</SOAP-ENV:Envelope>');
136 define("SAML_ATTRIBUTES", 'SAMLATTRIBS');
140 * @addtogroup publicPGTStorage
143 // ------------------------------------------------------------------------
145 // ------------------------------------------------------------------------
147 * Default path used when storing PGT's to file
149 define("CAS_PGT_STORAGE_FILE_DEFAULT_PATH", '/tmp');
151 * phpCAS::setPGTStorageFile()'s 2nd parameter to write plain text files
153 define("CAS_PGT_STORAGE_FILE_FORMAT_PLAIN", 'plain');
155 * phpCAS::setPGTStorageFile()'s 2nd parameter to write xml files
157 define("CAS_PGT_STORAGE_FILE_FORMAT_XML", 'xml');
159 * Default format used when storing PGT's to file
161 define("CAS_PGT_STORAGE_FILE_DEFAULT_FORMAT", CAS_PGT_STORAGE_FILE_FORMAT_PLAIN
);
163 // ------------------------------------------------------------------------
164 // SERVICE ACCESS ERRORS
165 // ------------------------------------------------------------------------
167 * @addtogroup publicServices
172 * phpCAS::service() error code on success
174 define("PHPCAS_SERVICE_OK", 0);
176 * phpCAS::service() error code when the PT could not retrieve because
177 * the CAS server did not respond.
179 define("PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE", 1);
181 * phpCAS::service() error code when the PT could not retrieve because
182 * the response of the CAS server was ill-formed.
184 define("PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE", 2);
186 * phpCAS::service() error code when the PT could not retrieve because
187 * the CAS server did not want to.
189 define("PHPCAS_SERVICE_PT_FAILURE", 3);
191 * phpCAS::service() error code when the service was not available.
193 define("PHPCAS_SERVICE_NOT AVAILABLE", 4);
196 // ------------------------------------------------------------------------
198 // ------------------------------------------------------------------------
200 * @addtogroup publicLang
204 define("PHPCAS_LANG_ENGLISH", 'english');
205 define("PHPCAS_LANG_FRENCH", 'french');
206 define("PHPCAS_LANG_GREEK", 'greek');
207 define("PHPCAS_LANG_GERMAN", 'german');
208 define("PHPCAS_LANG_JAPANESE", 'japanese');
209 define("PHPCAS_LANG_SPANISH", 'spanish');
210 define("PHPCAS_LANG_CATALAN", 'catalan');
215 * @addtogroup internalLang
220 * phpCAS default language (when phpCAS::setLang() is not used)
222 define("PHPCAS_LANG_DEFAULT", PHPCAS_LANG_ENGLISH
);
225 // ------------------------------------------------------------------------
227 // ------------------------------------------------------------------------
229 * @addtogroup publicDebug
234 * The default directory for the debug file under Unix.
236 define('DEFAULT_DEBUG_DIR', '/tmp/');
239 // ------------------------------------------------------------------------
241 // ------------------------------------------------------------------------
243 * @addtogroup internalMisc
248 * This global variable is used by the interface class phpCAS.
252 $GLOBALS['PHPCAS_CLIENT'] = null;
255 * This global variable is used to store where the initializer is called from
256 * (to print a comprehensive error in case of multiple calls).
260 $GLOBALS['PHPCAS_INIT_CALL'] = array (
268 * This global variable is used to store where the method checking
269 * the authentication is called from (to print comprehensive errors)
273 $GLOBALS['PHPCAS_AUTH_CHECK_CALL'] = array (
282 * This global variable is used to store phpCAS debug mode.
286 $GLOBALS['PHPCAS_DEBUG'] = array (
294 // ########################################################################
296 // ########################################################################
298 // include client class
299 include_once (dirname(__FILE__
) . '/CAS/client.php');
301 // ########################################################################
303 // ########################################################################
307 * The phpCAS class is a simple container for the phpCAS library. It provides CAS
308 * authentication for web applications written in PHP.
311 * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>
313 * \internal All its methods access the same object ($PHPCAS_CLIENT, declared
314 * at the end of CAS/client.php).
319 // ########################################################################
321 // ########################################################################
324 * @addtogroup publicInit
329 * phpCAS client initializer.
330 * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
331 * called, only once, and before all other methods (except phpCAS::getVersion()
332 * and phpCAS::setDebug()).
334 * @param $server_version the version of the CAS server
335 * @param $server_hostname the hostname of the CAS server
336 * @param $server_port the port the CAS server is running on
337 * @param $server_uri the URI the CAS server is responding on
338 * @param $start_session Have phpCAS start PHP sessions (default true)
340 * @return a newly created CASClient object
342 function client($server_version, $server_hostname, $server_port, $server_uri, $start_session = true) {
343 global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
345 phpCAS
:: traceBegin();
346 if (is_object($PHPCAS_CLIENT)) {
347 phpCAS
:: error($PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . $PHPCAS_INIT_CALL['file'] . ':' . $PHPCAS_INIT_CALL['line'] . ')');
349 if (gettype($server_version) != 'string') {
350 phpCAS
:: error('type mismatched for parameter $server_version (should be `string\')');
352 if (gettype($server_hostname) != 'string') {
353 phpCAS
:: error('type mismatched for parameter $server_hostname (should be `string\')');
355 if (gettype($server_port) != 'integer') {
356 phpCAS
:: error('type mismatched for parameter $server_port (should be `integer\')');
358 if (gettype($server_uri) != 'string') {
359 phpCAS
:: error('type mismatched for parameter $server_uri (should be `string\')');
362 // store where the initializer is called from
363 $dbg = phpCAS
:: backtrace();
364 $PHPCAS_INIT_CALL = array (
366 'file' => $dbg[0]['file'],
367 'line' => $dbg[0]['line'],
368 'method' => __CLASS__
. '::' . __FUNCTION__
371 // initialize the global object $PHPCAS_CLIENT
372 $PHPCAS_CLIENT = new CASClient($server_version, FALSE /*proxy*/
373 , $server_hostname, $server_port, $server_uri, $start_session);
374 phpCAS
:: traceEnd();
378 * phpCAS proxy initializer.
379 * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
380 * called, only once, and before all other methods (except phpCAS::getVersion()
381 * and phpCAS::setDebug()).
383 * @param $server_version the version of the CAS server
384 * @param $server_hostname the hostname of the CAS server
385 * @param $server_port the port the CAS server is running on
386 * @param $server_uri the URI the CAS server is responding on
387 * @param $start_session Have phpCAS start PHP sessions (default true)
389 * @return a newly created CASClient object
391 function proxy($server_version, $server_hostname, $server_port, $server_uri, $start_session = true) {
392 global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
394 phpCAS
:: traceBegin();
395 if (is_object($PHPCAS_CLIENT)) {
396 phpCAS
:: error($PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . $PHPCAS_INIT_CALL['file'] . ':' . $PHPCAS_INIT_CALL['line'] . ')');
398 if (gettype($server_version) != 'string') {
399 phpCAS
:: error('type mismatched for parameter $server_version (should be `string\')');
401 if (gettype($server_hostname) != 'string') {
402 phpCAS
:: error('type mismatched for parameter $server_hostname (should be `string\')');
404 if (gettype($server_port) != 'integer') {
405 phpCAS
:: error('type mismatched for parameter $server_port (should be `integer\')');
407 if (gettype($server_uri) != 'string') {
408 phpCAS
:: error('type mismatched for parameter $server_uri (should be `string\')');
411 // store where the initialzer is called from
412 $dbg = phpCAS
:: backtrace();
413 $PHPCAS_INIT_CALL = array (
415 'file' => $dbg[0]['file'],
416 'line' => $dbg[0]['line'],
417 'method' => __CLASS__
. '::' . __FUNCTION__
420 // initialize the global object $PHPCAS_CLIENT
421 $PHPCAS_CLIENT = new CASClient($server_version, TRUE /*proxy*/
422 , $server_hostname, $server_port, $server_uri, $start_session);
423 phpCAS
:: traceEnd();
427 // ########################################################################
429 // ########################################################################
432 * @addtogroup publicDebug
437 * Set/unset debug mode
439 * @param $filename the name of the file used for logging, or FALSE to stop debugging.
441 function setDebug($filename = '') {
442 global $PHPCAS_DEBUG;
444 if ($filename != FALSE && gettype($filename) != 'string') {
445 phpCAS
:: error('type mismatched for parameter $dbg (should be FALSE or the name of the log file)');
448 if (empty ($filename)) {
449 if (preg_match('/^Win.*/', getenv('OS'))) {
450 if (isset ($_ENV['TMP'])) {
451 $debugDir = $_ENV['TMP'] . '/';
453 if (isset ($_ENV['TEMP'])) {
454 $debugDir = $_ENV['TEMP'] . '/';
459 $debugDir = DEFAULT_DEBUG_DIR
;
461 $filename = $debugDir . 'phpCAS.log';
464 if (empty ($PHPCAS_DEBUG['unique_id'])) {
465 $PHPCAS_DEBUG['unique_id'] = substr(strtoupper(md5(uniqid(''))), 0, 4);
468 $PHPCAS_DEBUG['filename'] = $filename;
470 phpCAS
:: trace('START phpCAS-' . PHPCAS_VERSION
. ' ******************');
475 * @addtogroup internalDebug
480 * This method is a wrapper for debug_backtrace() that is not available
481 * in all PHP versions (>= 4.3.0 only)
483 function backtrace() {
484 if (function_exists('debug_backtrace')) {
485 return debug_backtrace();
487 // poor man's hack ... but it does work ...
493 * Logs a string in debug mode.
495 * @param $str the string to write
501 global $PHPCAS_DEBUG;
503 if ($PHPCAS_DEBUG['filename']) {
504 for ($i = 0; $i < $PHPCAS_DEBUG['indent']; $i++
) {
507 error_log($PHPCAS_DEBUG['unique_id'] . ' ' . $indent_str . $str . "\n", 3, $PHPCAS_DEBUG['filename']);
513 * This method is used by interface methods to print an error and where the function
514 * was originally called from.
516 * @param $msg the message to print
520 function error($msg) {
521 $dbg = phpCAS
:: backtrace();
525 if (is_array($dbg)) {
526 for ($i = 1; $i < sizeof($dbg); $i++
) {
527 if (is_array($dbg[$i])) {
528 if ($dbg[$i]['class'] == __CLASS__
) {
529 $function = $dbg[$i]['function'];
530 $file = $dbg[$i]['file'];
531 $line = $dbg[$i]['line'];
536 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";
537 phpCAS
:: trace($msg);
538 phpCAS
:: traceExit();
543 * This method is used to log something in debug mode.
545 function trace($str) {
546 $dbg = phpCAS
:: backtrace();
547 phpCAS
:: log($str . ' [' . basename($dbg[1]['file']) . ':' . $dbg[1]['line'] . ']');
551 * This method is used to indicate the start of the execution of a function in debug mode.
553 function traceBegin() {
554 global $PHPCAS_DEBUG;
556 $dbg = phpCAS
:: backtrace();
558 if (!empty ($dbg[2]['class'])) {
559 $str .= $dbg[2]['class'] . '::';
561 $str .= $dbg[2]['function'] . '(';
562 if (is_array($dbg[2]['args'])) {
563 foreach ($dbg[2]['args'] as $index => $arg) {
567 $str .= str_replace("\n", "", var_export($arg, TRUE));
570 $str .= ') [' . basename($dbg[2]['file']) . ':' . $dbg[2]['line'] . ']';
572 $PHPCAS_DEBUG['indent']++
;
576 * This method is used to indicate the end of the execution of a function in debug mode.
578 * @param $res the result of the function
580 function traceEnd($res = '') {
581 global $PHPCAS_DEBUG;
583 $PHPCAS_DEBUG['indent']--;
584 $dbg = phpCAS
:: backtrace();
586 $str .= '<= ' . str_replace("\n", "", var_export($res, TRUE));
591 * This method is used to indicate the end of the execution of the program
593 function traceExit() {
594 global $PHPCAS_DEBUG;
596 phpCAS
:: log('exit()');
597 while ($PHPCAS_DEBUG['indent'] > 0) {
599 $PHPCAS_DEBUG['indent']--;
604 // ########################################################################
605 // INTERNATIONALIZATION
606 // ########################################################################
608 * @addtogroup publicLang
613 * This method is used to set the language used by phpCAS.
614 * @note Can be called only once.
616 * @param $lang a string representing the language.
618 * @sa PHPCAS_LANG_FRENCH, PHPCAS_LANG_ENGLISH
620 function setLang($lang) {
621 global $PHPCAS_CLIENT;
622 if (!is_object($PHPCAS_CLIENT)) {
623 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
625 if (gettype($lang) != 'string') {
626 phpCAS
:: error('type mismatched for parameter $lang (should be `string\')');
628 $PHPCAS_CLIENT->setLang($lang);
632 // ########################################################################
634 // ########################################################################
641 * This method returns the phpCAS version.
643 * @return the phpCAS version.
645 function getVersion() {
646 return PHPCAS_VERSION
;
650 // ########################################################################
652 // ########################################################################
654 * @addtogroup publicOutput
659 * This method sets the HTML header used for all outputs.
661 * @param $header the HTML header.
663 function setHTMLHeader($header) {
664 global $PHPCAS_CLIENT;
665 if (!is_object($PHPCAS_CLIENT)) {
666 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
668 if (gettype($header) != 'string') {
669 phpCAS
:: error('type mismatched for parameter $header (should be `string\')');
671 $PHPCAS_CLIENT->setHTMLHeader($header);
675 * This method sets the HTML footer used for all outputs.
677 * @param $footer the HTML footer.
679 function setHTMLFooter($footer) {
680 global $PHPCAS_CLIENT;
681 if (!is_object($PHPCAS_CLIENT)) {
682 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
684 if (gettype($footer) != 'string') {
685 phpCAS
:: error('type mismatched for parameter $footer (should be `string\')');
687 $PHPCAS_CLIENT->setHTMLFooter($footer);
691 // ########################################################################
693 // ########################################################################
695 * @addtogroup publicPGTStorage
700 * This method is used to tell phpCAS to store the response of the
701 * CAS server to PGT requests onto the filesystem.
703 * @param $format the format used to store the PGT's (`plain' and `xml' allowed)
704 * @param $path the path where the PGT's should be stored
706 function setPGTStorageFile($format = '', $path = '') {
707 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
709 phpCAS
:: traceBegin();
710 if (!is_object($PHPCAS_CLIENT)) {
711 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
713 if (!$PHPCAS_CLIENT->isProxy()) {
714 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
716 if ($PHPCAS_AUTH_CHECK_CALL['done']) {
717 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'] . ')');
719 if (gettype($format) != 'string') {
720 phpCAS
:: error('type mismatched for parameter $format (should be `string\')');
722 if (gettype($path) != 'string') {
723 phpCAS
:: error('type mismatched for parameter $format (should be `string\')');
725 $PHPCAS_CLIENT->setPGTStorageFile($format, $path);
726 phpCAS
:: traceEnd();
731 // ########################################################################
732 // ACCESS TO EXTERNAL SERVICES
733 // ########################################################################
735 * @addtogroup publicServices
740 * This method is used to access an HTTP[S] service.
742 * @param $url the service to access.
743 * @param $err_code an error code Possible values are PHPCAS_SERVICE_OK (on
744 * success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE, PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE,
745 * PHPCAS_SERVICE_PT_FAILURE, PHPCAS_SERVICE_NOT AVAILABLE.
746 * @param $output the output of the service (also used to give an error
747 * message on failure).
749 * @return TRUE on success, FALSE otherwise (in this later case, $err_code
750 * gives the reason why it failed and $output contains an error message).
752 function serviceWeb($url, & $err_code, & $output) {
753 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
755 phpCAS
:: traceBegin();
756 if (!is_object($PHPCAS_CLIENT)) {
757 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
759 if (!$PHPCAS_CLIENT->isProxy()) {
760 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
762 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
763 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()');
765 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
766 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');
768 if (gettype($url) != 'string') {
769 phpCAS
:: error('type mismatched for parameter $url (should be `string\')');
772 $res = $PHPCAS_CLIENT->serviceWeb($url, $err_code, $output);
774 phpCAS
:: traceEnd($res);
779 * This method is used to access an IMAP/POP3/NNTP service.
781 * @param $url a string giving the URL of the service, including the mailing box
782 * for IMAP URLs, as accepted by imap_open().
783 * @param $service a string giving for CAS retrieve Proxy ticket
784 * @param $flags options given to imap_open().
785 * @param $err_code an error code Possible values are PHPCAS_SERVICE_OK (on
786 * success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE, PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE,
787 * PHPCAS_SERVICE_PT_FAILURE, PHPCAS_SERVICE_NOT AVAILABLE.
788 * @param $err_msg an error message on failure
789 * @param $pt the Proxy Ticket (PT) retrieved from the CAS server to access the URL
790 * on success, FALSE on error).
792 * @return an IMAP stream on success, FALSE otherwise (in this later case, $err_code
793 * gives the reason why it failed and $err_msg contains an error message).
795 function serviceMail($url, $service, $flags, & $err_code, & $err_msg, & $pt) {
796 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
798 phpCAS
:: traceBegin();
799 if (!is_object($PHPCAS_CLIENT)) {
800 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
802 if (!$PHPCAS_CLIENT->isProxy()) {
803 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
805 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
806 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()');
808 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
809 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');
811 if (gettype($url) != 'string') {
812 phpCAS
:: error('type mismatched for parameter $url (should be `string\')');
815 if (gettype($flags) != 'integer') {
816 phpCAS
:: error('type mismatched for parameter $flags (should be `integer\')');
819 $res = $PHPCAS_CLIENT->serviceMail($url, $service, $flags, $err_code, $err_msg, $pt);
821 phpCAS
:: traceEnd($res);
826 // ########################################################################
828 // ########################################################################
830 * @addtogroup publicAuth
835 * Set the times authentication will be cached before really accessing the CAS server in gateway mode:
836 * - -1: check only once, and then never again (until you pree login)
838 * - n: check every "n" time
840 * @param $n an integer.
842 function setCacheTimesForAuthRecheck($n) {
843 global $PHPCAS_CLIENT;
844 if (!is_object($PHPCAS_CLIENT)) {
845 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
847 if (gettype($n) != 'integer') {
848 phpCAS
:: error('type mismatched for parameter $header (should be `string\')');
850 $PHPCAS_CLIENT->setCacheTimesForAuthRecheck($n);
854 * This method is called to check if the user is authenticated (use the gateway feature).
855 * @return TRUE when the user is authenticated; otherwise FALSE.
857 function checkAuthentication() {
858 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
860 phpCAS
:: traceBegin();
861 if (!is_object($PHPCAS_CLIENT)) {
862 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
865 $auth = $PHPCAS_CLIENT->checkAuthentication();
867 // store where the authentication has been checked and the result
868 $dbg = phpCAS
:: backtrace();
869 $PHPCAS_AUTH_CHECK_CALL = array (
871 'file' => $dbg[0]['file'],
872 'line' => $dbg[0]['line'],
873 'method' => __CLASS__
. '::' . __FUNCTION__
,
876 phpCAS
:: traceEnd($auth);
881 * This method is called to force authentication if the user was not already
882 * authenticated. If the user is not authenticated, halt by redirecting to
885 function forceAuthentication() {
886 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
888 phpCAS
:: traceBegin();
889 if (!is_object($PHPCAS_CLIENT)) {
890 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
893 $auth = $PHPCAS_CLIENT->forceAuthentication();
895 // store where the authentication has been checked and the result
896 $dbg = phpCAS
:: backtrace();
897 $PHPCAS_AUTH_CHECK_CALL = array (
899 'file' => $dbg[0]['file'],
900 'line' => $dbg[0]['line'],
901 'method' => __CLASS__
. '::' . __FUNCTION__
,
906 phpCAS
:: trace('user is not authenticated, redirecting to the CAS server');
907 $PHPCAS_CLIENT->forceAuthentication();
909 phpCAS
:: trace('no need to authenticate (user `' . phpCAS
:: getUser() . '\' is already authenticated)');
912 phpCAS
:: traceEnd();
917 * This method is called to renew the authentication.
919 function renewAuthentication() {
920 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
922 phpCAS
:: traceBegin();
923 if (!is_object($PHPCAS_CLIENT)) {
924 phpCAS
:: error('this method should not be called before' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
927 // store where the authentication has been checked and the result
928 $dbg = phpCAS
:: backtrace();
929 $PHPCAS_AUTH_CHECK_CALL = array (
931 'file' => $dbg[0]['file'],
932 'line' => $dbg[0]['line'],
933 'method' => __CLASS__
. '::' . __FUNCTION__
,
937 $PHPCAS_CLIENT->renewAuthentication();
938 phpCAS
:: traceEnd();
942 * This method has been left from version 0.4.1 for compatibility reasons.
944 function authenticate() {
945 phpCAS
:: error('this method is deprecated. You should use ' . __CLASS__
. '::forceAuthentication() instead');
949 * This method is called to check if the user is authenticated (previously or by
950 * tickets given in the URL).
952 * @return TRUE when the user is authenticated.
954 function isAuthenticated() {
955 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
957 phpCAS
:: traceBegin();
958 if (!is_object($PHPCAS_CLIENT)) {
959 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
962 // call the isAuthenticated method of the global $PHPCAS_CLIENT object
963 $auth = $PHPCAS_CLIENT->isAuthenticated();
965 // store where the authentication has been checked and the result
966 $dbg = phpCAS
:: backtrace();
967 $PHPCAS_AUTH_CHECK_CALL = array (
969 'file' => $dbg[0]['file'],
970 'line' => $dbg[0]['line'],
971 'method' => __CLASS__
. '::' . __FUNCTION__
,
974 phpCAS
:: traceEnd($auth);
979 * Checks whether authenticated based on $_SESSION. Useful to avoid
981 * @return true if authenticated, false otherwise.
982 * @since 0.4.22 by Brendan Arnold
984 function isSessionAuthenticated() {
985 global $PHPCAS_CLIENT;
986 if (!is_object($PHPCAS_CLIENT)) {
987 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
989 return ($PHPCAS_CLIENT->isSessionAuthenticated());
993 * This method returns the CAS user's login name.
994 * @warning should not be called only after phpCAS::forceAuthentication()
995 * or phpCAS::checkAuthentication().
997 * @return the login name of the authenticated user
1000 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
1001 if (!is_object($PHPCAS_CLIENT)) {
1002 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
1004 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
1005 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::forceAuthentication() or ' . __CLASS__
. '::isAuthenticated()');
1007 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
1008 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');
1010 return $PHPCAS_CLIENT->getUser();
1014 * This method returns the CAS user's login name.
1015 * @warning should not be called only after phpCAS::forceAuthentication()
1016 * or phpCAS::checkAuthentication().
1018 * @return the login name of the authenticated user
1020 function getAttributes() {
1021 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
1022 if (!is_object($PHPCAS_CLIENT)) {
1023 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
1025 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
1026 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::forceAuthentication() or ' . __CLASS__
. '::isAuthenticated()');
1028 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
1029 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');
1031 return $PHPCAS_CLIENT->getAttributes();
1034 * Handle logout requests.
1036 function handleLogoutRequests($check_client = true, $allowed_clients = false) {
1037 global $PHPCAS_CLIENT;
1038 if (!is_object($PHPCAS_CLIENT)) {
1039 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
1041 return ($PHPCAS_CLIENT->handleLogoutRequests($check_client, $allowed_clients));
1045 * This method returns the URL to be used to login.
1046 * or phpCAS::isAuthenticated().
1048 * @return the login name of the authenticated user
1050 function getServerLoginURL() {
1051 global $PHPCAS_CLIENT;
1052 if (!is_object($PHPCAS_CLIENT)) {
1053 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
1055 return $PHPCAS_CLIENT->getServerLoginURL();
1059 * Set the login URL of the CAS server.
1060 * @param $url the login URL
1061 * @since 0.4.21 by Wyman Chan
1063 function setServerLoginURL($url = '') {
1064 global $PHPCAS_CLIENT;
1065 phpCAS
:: traceBegin();
1066 if (!is_object($PHPCAS_CLIENT)) {
1067 phpCAS
:: error('this method should only be called after
1068 ' . __CLASS__
. '::client()');
1070 if (gettype($url) != 'string') {
1071 phpCAS
:: error('type mismatched for parameter $url (should be
1074 $PHPCAS_CLIENT->setServerLoginURL($url);
1075 phpCAS
:: traceEnd();
1079 * Set the serviceValidate URL of the CAS server.
1080 * Used only in CAS 1.0 validations
1081 * @param $url the serviceValidate URL
1082 * @since 1.1.0 by Joachim Fritschi
1084 function setServerServiceValidateURL($url = '') {
1085 global $PHPCAS_CLIENT;
1086 phpCAS
:: traceBegin();
1087 if (!is_object($PHPCAS_CLIENT)) {
1088 phpCAS
:: error('this method should only be called after
1089 ' . __CLASS__
. '::client()');
1091 if (gettype($url) != 'string') {
1092 phpCAS
:: error('type mismatched for parameter $url (should be
1095 $PHPCAS_CLIENT->setServerServiceValidateURL($url);
1096 phpCAS
:: traceEnd();
1100 * Set the proxyValidate URL of the CAS server.
1101 * Used for all CAS 2.0 validations
1102 * @param $url the proxyValidate URL
1103 * @since 1.1.0 by Joachim Fritschi
1105 function setServerProxyValidateURL($url = '') {
1106 global $PHPCAS_CLIENT;
1107 phpCAS
:: traceBegin();
1108 if (!is_object($PHPCAS_CLIENT)) {
1109 phpCAS
:: error('this method should only be called after
1110 ' . __CLASS__
. '::client()');
1112 if (gettype($url) != 'string') {
1113 phpCAS
:: error('type mismatched for parameter $url (should be
1116 $PHPCAS_CLIENT->setServerProxyValidateURL($url);
1117 phpCAS
:: traceEnd();
1121 * Set the samlValidate URL of the CAS server.
1122 * @param $url the samlValidate URL
1123 * @since 1.1.0 by Joachim Fritschi
1125 function setServerSamlValidateURL($url = '') {
1126 global $PHPCAS_CLIENT;
1127 phpCAS
:: traceBegin();
1128 if (!is_object($PHPCAS_CLIENT)) {
1129 phpCAS
:: error('this method should only be called after
1130 ' . __CLASS__
. '::client()');
1132 if (gettype($url) != 'string') {
1133 phpCAS
:: error('type mismatched for parameter $url (should be
1136 $PHPCAS_CLIENT->setServerSamlValidateURL($url);
1137 phpCAS
:: traceEnd();
1141 * This method returns the URL to be used to login.
1142 * or phpCAS::isAuthenticated().
1144 * @return the login name of the authenticated user
1146 function getServerLogoutURL() {
1147 global $PHPCAS_CLIENT;
1148 if (!is_object($PHPCAS_CLIENT)) {
1149 phpCAS
:: error('this method should not be called before ' . __CLASS__
. '::client() or ' . __CLASS__
. '::proxy()');
1151 return $PHPCAS_CLIENT->getServerLogoutURL();
1155 * Set the logout URL of the CAS server.
1156 * @param $url the logout URL
1157 * @since 0.4.21 by Wyman Chan
1159 function setServerLogoutURL($url = '') {
1160 global $PHPCAS_CLIENT;
1161 phpCAS
:: traceBegin();
1162 if (!is_object($PHPCAS_CLIENT)) {
1163 phpCAS
:: error('this method should only be called after
1164 ' . __CLASS__
. '::client()');
1166 if (gettype($url) != 'string') {
1167 phpCAS
:: error('type mismatched for parameter $url (should be
1170 $PHPCAS_CLIENT->setServerLogoutURL($url);
1171 phpCAS
:: traceEnd();
1175 * This method is used to logout from CAS.
1176 * @params $params an array that contains the optional url and service parameters that will be passed to the CAS server
1179 function logout($params = "") {
1180 global $PHPCAS_CLIENT;
1181 phpCAS
:: traceBegin();
1182 if (!is_object($PHPCAS_CLIENT)) {
1183 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1185 $parsedParams = array ();
1186 if ($params != "") {
1187 if (is_string($params)) {
1188 phpCAS
:: error('method `phpCAS::logout($url)\' is now deprecated, use `phpCAS::logoutWithUrl($url)\' instead');
1190 if (!is_array($params)) {
1191 phpCAS
:: error('type mismatched for parameter $params (should be `array\')');
1193 foreach ($params as $key => $value) {
1194 if ($key != "service" && $key != "url") {
1195 phpCAS
:: error('only `url\' and `service\' parameters are allowed for method `phpCAS::logout($params)\'');
1197 $parsedParams[$key] = $value;
1200 $PHPCAS_CLIENT->logout($parsedParams);
1202 phpCAS
:: traceEnd();
1206 * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1207 * @param $service a URL that will be transmitted to the CAS server
1209 function logoutWithRedirectService($service) {
1210 global $PHPCAS_CLIENT;
1211 phpCAS
:: traceBegin();
1212 if (!is_object($PHPCAS_CLIENT)) {
1213 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1215 if (!is_string($service)) {
1216 phpCAS
:: error('type mismatched for parameter $service (should be `string\')');
1218 $PHPCAS_CLIENT->logout(array (
1219 "service" => $service
1222 phpCAS
:: traceEnd();
1226 * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1227 * @param $url a URL that will be transmitted to the CAS server
1229 function logoutWithUrl($url) {
1230 global $PHPCAS_CLIENT;
1231 phpCAS
:: traceBegin();
1232 if (!is_object($PHPCAS_CLIENT)) {
1233 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1235 if (!is_string($url)) {
1236 phpCAS
:: error('type mismatched for parameter $url (should be `string\')');
1238 $PHPCAS_CLIENT->logout(array (
1242 phpCAS
:: traceEnd();
1246 * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1247 * @param $service a URL that will be transmitted to the CAS server
1248 * @param $url a URL that will be transmitted to the CAS server
1250 function logoutWithRedirectServiceAndUrl($service, $url) {
1251 global $PHPCAS_CLIENT;
1252 phpCAS
:: traceBegin();
1253 if (!is_object($PHPCAS_CLIENT)) {
1254 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1256 if (!is_string($service)) {
1257 phpCAS
:: error('type mismatched for parameter $service (should be `string\')');
1259 if (!is_string($url)) {
1260 phpCAS
:: error('type mismatched for parameter $url (should be `string\')');
1262 $PHPCAS_CLIENT->logout(array (
1263 "service" => $service,
1267 phpCAS
:: traceEnd();
1271 * Set the fixed URL that will be used by the CAS server to transmit the PGT.
1272 * When this method is not called, a phpCAS script uses its own URL for the callback.
1274 * @param $url the URL
1276 function setFixedCallbackURL($url = '') {
1277 global $PHPCAS_CLIENT;
1278 phpCAS
:: traceBegin();
1279 if (!is_object($PHPCAS_CLIENT)) {
1280 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
1282 if (!$PHPCAS_CLIENT->isProxy()) {
1283 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
1285 if (gettype($url) != 'string') {
1286 phpCAS
:: error('type mismatched for parameter $url (should be `string\')');
1288 $PHPCAS_CLIENT->setCallbackURL($url);
1289 phpCAS
:: traceEnd();
1293 * Set the fixed URL that will be set as the CAS service parameter. When this
1294 * method is not called, a phpCAS script uses its own URL.
1296 * @param $url the URL
1298 function setFixedServiceURL($url) {
1299 global $PHPCAS_CLIENT;
1300 phpCAS
:: traceBegin();
1301 if (!is_object($PHPCAS_CLIENT)) {
1302 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
1304 if (gettype($url) != 'string') {
1305 phpCAS
:: error('type mismatched for parameter $url (should be `string\')');
1307 $PHPCAS_CLIENT->setURL($url);
1308 phpCAS
:: traceEnd();
1312 * Get the URL that is set as the CAS service parameter.
1314 function getServiceURL() {
1315 global $PHPCAS_CLIENT;
1316 if (!is_object($PHPCAS_CLIENT)) {
1317 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
1319 return ($PHPCAS_CLIENT->getURL());
1323 * Retrieve a Proxy Ticket from the CAS server.
1325 function retrievePT($target_service, & $err_code, & $err_msg) {
1326 global $PHPCAS_CLIENT;
1327 if (!is_object($PHPCAS_CLIENT)) {
1328 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::proxy()');
1330 if (gettype($target_service) != 'string') {
1331 phpCAS
:: error('type mismatched for parameter $target_service(should be `string\')');
1333 return ($PHPCAS_CLIENT->retrievePT($target_service, $err_code, $err_msg));
1337 * Set the certificate of the CAS server.
1339 * @param $cert the PEM certificate
1341 function setCasServerCert($cert) {
1342 global $PHPCAS_CLIENT;
1343 phpCAS
:: traceBegin();
1344 if (!is_object($PHPCAS_CLIENT)) {
1345 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1347 if (gettype($cert) != 'string') {
1348 phpCAS
:: error('type mismatched for parameter $cert (should be `string\')');
1350 $PHPCAS_CLIENT->setCasServerCert($cert);
1351 phpCAS
:: traceEnd();
1355 * Set the certificate of the CAS server CA.
1357 * @param $cert the CA certificate
1359 function setCasServerCACert($cert) {
1360 global $PHPCAS_CLIENT;
1361 phpCAS
:: traceBegin();
1362 if (!is_object($PHPCAS_CLIENT)) {
1363 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1365 if (gettype($cert) != 'string') {
1366 phpCAS
:: error('type mismatched for parameter $cert (should be `string\')');
1368 $PHPCAS_CLIENT->setCasServerCACert($cert);
1369 phpCAS
:: traceEnd();
1373 * Set no SSL validation for the CAS server.
1375 function setNoCasServerValidation() {
1376 global $PHPCAS_CLIENT;
1377 phpCAS
:: traceBegin();
1378 if (!is_object($PHPCAS_CLIENT)) {
1379 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1381 $PHPCAS_CLIENT->setNoCasServerValidation();
1382 phpCAS
:: traceEnd();
1388 * Change CURL options.
1389 * CURL is used to connect through HTTPS to CAS server
1390 * @param $key the option key
1391 * @param $value the value to set
1393 function setExtraCurlOption($key, $value) {
1394 global $PHPCAS_CLIENT;
1395 phpCAS
:: traceBegin();
1396 if (!is_object($PHPCAS_CLIENT)) {
1397 phpCAS
:: error('this method should only be called after ' . __CLASS__
. '::client() or' . __CLASS__
. '::proxy()');
1399 $PHPCAS_CLIENT->setExtraCurlOption($key, $value);
1400 phpCAS
:: traceEnd();
1405 // ########################################################################
1407 // ########################################################################
1409 // ########################################################################
1415 * The following pages only show the source documentation.
1419 // ########################################################################
1420 // MODULES DEFINITION
1422 /** @defgroup public User interface */
1424 /** @defgroup publicInit Initialization
1425 * @ingroup public */
1427 /** @defgroup publicAuth Authentication
1428 * @ingroup public */
1430 /** @defgroup publicServices Access to external services
1431 * @ingroup public */
1433 /** @defgroup publicConfig Configuration
1434 * @ingroup public */
1436 /** @defgroup publicLang Internationalization
1437 * @ingroup publicConfig */
1439 /** @defgroup publicOutput HTML output
1440 * @ingroup publicConfig */
1442 /** @defgroup publicPGTStorage PGT storage
1443 * @ingroup publicConfig */
1445 /** @defgroup publicDebug Debugging
1446 * @ingroup public */
1448 /** @defgroup internal Implementation */
1450 /** @defgroup internalAuthentication Authentication
1451 * @ingroup internal */
1453 /** @defgroup internalBasic CAS Basic client features (CAS 1.0, Service Tickets)
1454 * @ingroup internal */
1456 /** @defgroup internalProxy CAS Proxy features (CAS 2.0, Proxy Granting Tickets)
1457 * @ingroup internal */
1459 /** @defgroup internalPGTStorage PGT storage
1460 * @ingroup internalProxy */
1462 /** @defgroup internalPGTStorageFile PGT storage on the filesystem
1463 * @ingroup internalPGTStorage */
1465 /** @defgroup internalCallback Callback from the CAS server
1466 * @ingroup internalProxy */
1468 /** @defgroup internalProxied CAS proxied client features (CAS 2.0, Proxy Tickets)
1469 * @ingroup internal */
1471 /** @defgroup internalConfig Configuration
1472 * @ingroup internal */
1474 /** @defgroup internalOutput HTML output
1475 * @ingroup internalConfig */
1477 /** @defgroup internalLang Internationalization
1478 * @ingroup internalConfig
1480 * To add a new language:
1481 * - 1. define a new constant PHPCAS_LANG_XXXXXX in CAS/CAS.php
1482 * - 2. copy any file from CAS/languages to CAS/languages/XXXXXX.php
1483 * - 3. Make the translations
1486 /** @defgroup internalDebug Debugging
1487 * @ingroup internal */
1489 /** @defgroup internalMisc Miscellaneous
1490 * @ingroup internal */
1492 // ########################################################################
1496 * @example example_simple.php
1499 * @example example_proxy.php
1502 * @example example_proxy2.php
1505 * @example example_lang.php
1508 * @example example_html.php
1511 * @example example_file.php
1514 * @example example_db.php
1517 * @example example_service.php
1520 * @example example_session_proxy.php
1523 * @example example_session_service.php
1526 * @example example_gateway.php
1529 * @example example_custom_urls.php