CAS.php

Go to the documentation of this file.

<?php

/*
 * Copyright © 2003-2010, The ESUP-Portail consortium & the JA-SIG Collaborative.
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 *     * Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright notice,
 *       this list of conditions and the following disclaimer in the documentation
 *       and/or other materials provided with the distribution.
 *     * Neither the name of the ESUP-Portail consortium & the JA-SIG
 *       Collaborative nor the names of its contributors may be used to endorse or
 *       promote products derived from this software without specific prior
 *       written permission.

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

//
// hack by Vangelis Haniotakis to handle the absence of $_SERVER['REQUEST_URI'] in IIS
//
if (!$_SERVER['REQUEST_URI']) {
        $_SERVER['REQUEST_URI'] = $_SERVER['SCRIPT_NAME'] . '?' . $_SERVER['QUERY_STRING'];
}

//
// another one by Vangelis Haniotakis also to make phpCAS work with PHP5
// patch smeyer (not required)
if (version_compare(PHP_VERSION, '5', '>=') && !(function_exists('domxml_new_doc'))) {
        require_once (dirname(__FILE__) . '/CAS/domxml-php4-to-php5.php');
}

// ########################################################################
//  CONSTANTS
// ########################################################################

// ------------------------------------------------------------------------
//  CAS VERSIONS
// ------------------------------------------------------------------------

define('PHPCAS_VERSION', '1.1.2');

// ------------------------------------------------------------------------
//  CAS VERSIONS
// ------------------------------------------------------------------------
define("CAS_VERSION_1_0", '1.0');
define("CAS_VERSION_2_0", '2.0');

// ------------------------------------------------------------------------
//  SAML defines
// ------------------------------------------------------------------------

define("SAML_VERSION_1_1", 'S1');

define("SAML_XML_HEADER", '<?xml version="1.0" encoding="UTF-8"?>');

define("SAML_SOAP_ENV", '<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/>');

define("SAML_SOAP_BODY", '<SOAP-ENV:Body>');

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">');
define("SAMLP_REQUEST_CLOSE", '</samlp:Request>');

define("SAML_ASSERTION_ARTIFACT", '<samlp:AssertionArtifact>');

define("SAML_ASSERTION_ARTIFACT_CLOSE", '</samlp:AssertionArtifact>');

define("SAML_SOAP_BODY_CLOSE", '</SOAP-ENV:Body>');

define("SAML_SOAP_ENV_CLOSE", '</SOAP-ENV:Envelope>');

define("SAML_ATTRIBUTES", 'SAMLATTRIBS');

// ------------------------------------------------------------------------
//  FILE PGT STORAGE
// ------------------------------------------------------------------------
define("CAS_PGT_STORAGE_FILE_DEFAULT_PATH", '/tmp');
define("CAS_PGT_STORAGE_FILE_FORMAT_PLAIN", 'plain');
define("CAS_PGT_STORAGE_FILE_FORMAT_XML", 'xml');
define("CAS_PGT_STORAGE_FILE_DEFAULT_FORMAT", CAS_PGT_STORAGE_FILE_FORMAT_PLAIN);
// ------------------------------------------------------------------------
//  DATABASE PGT STORAGE
// ------------------------------------------------------------------------
define("CAS_PGT_STORAGE_DB_DEFAULT_DATABASE_TYPE", 'mysql');
define("CAS_PGT_STORAGE_DB_DEFAULT_HOSTNAME", 'localhost');
define("CAS_PGT_STORAGE_DB_DEFAULT_PORT", '');
define("CAS_PGT_STORAGE_DB_DEFAULT_DATABASE", 'phpCAS');
define("CAS_PGT_STORAGE_DB_DEFAULT_TABLE", 'pgt');

// ------------------------------------------------------------------------
// SERVICE ACCESS ERRORS
// ------------------------------------------------------------------------
define("PHPCAS_SERVICE_OK", 0);
define("PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE", 1);
define("PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE", 2);
define("PHPCAS_SERVICE_PT_FAILURE", 3);
define("PHPCAS_SERVICE_NOT AVAILABLE", 4);

// ------------------------------------------------------------------------
//  LANGUAGES
// ------------------------------------------------------------------------
define("PHPCAS_LANG_ENGLISH", 'english');
define("PHPCAS_LANG_FRENCH", 'french');
define("PHPCAS_LANG_GREEK", 'greek');
define("PHPCAS_LANG_GERMAN", 'german');
define("PHPCAS_LANG_JAPANESE", 'japanese');
define("PHPCAS_LANG_SPANISH", 'spanish');
define("PHPCAS_LANG_CATALAN", 'catalan');

define("PHPCAS_LANG_DEFAULT", PHPCAS_LANG_ENGLISH);

// ------------------------------------------------------------------------
//  DEBUG
// ------------------------------------------------------------------------
define('DEFAULT_DEBUG_DIR', '/tmp/');

// ------------------------------------------------------------------------
//  MISC
// ------------------------------------------------------------------------
$GLOBALS['PHPCAS_CLIENT'] = null;

$GLOBALS['PHPCAS_INIT_CALL'] = array (
        'done' => FALSE,
        'file' => '?',
        'line' => -1,
        'method' => '?'
);

$GLOBALS['PHPCAS_AUTH_CHECK_CALL'] = array (
        'done' => FALSE,
        'file' => '?',
        'line' => -1,
        'method' => '?',
        'result' => FALSE
);

$GLOBALS['PHPCAS_DEBUG'] = array (
        'filename' => FALSE,
        'indent' => 0,
        'unique_id' => ''
);

// ########################################################################
//  CLIENT CLASS
// ########################################################################

// include client class
include_once (dirname(__FILE__) . '/CAS/client.php');

// ########################################################################
//  INTERFACE CLASS
// ########################################################################

class phpCAS {

        // ########################################################################
        //  INITIALIZATION
        // ########################################################################

        function client($server_version, $server_hostname, $server_port, $server_uri, $start_session = true) {
                global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;

                phpCAS :: traceBegin();
                if (is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error($PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . $PHPCAS_INIT_CALL['file'] . ':' . $PHPCAS_INIT_CALL['line'] . ')');
                }
                if (gettype($server_version) != 'string') {
                        phpCAS :: error('type mismatched for parameter $server_version (should be `string\')');
                }
                if (gettype($server_hostname) != 'string') {
                        phpCAS :: error('type mismatched for parameter $server_hostname (should be `string\')');
                }
                if (gettype($server_port) != 'integer') {
                        phpCAS :: error('type mismatched for parameter $server_port (should be `integer\')');
                }
                if (gettype($server_uri) != 'string') {
                        phpCAS :: error('type mismatched for parameter $server_uri (should be `string\')');
                }

                // store where the initializer is called from
                $dbg = phpCAS :: backtrace();
                $PHPCAS_INIT_CALL = array (
                        'done' => TRUE,
                        'file' => $dbg[0]['file'],
                        'line' => $dbg[0]['line'],
                        'method' => __CLASS__ . '::' . __FUNCTION__
                );

                // initialize the global object $PHPCAS_CLIENT
                $PHPCAS_CLIENT = new CASClient($server_version, FALSE /*proxy*/
                , $server_hostname, $server_port, $server_uri, $start_session);
                phpCAS :: traceEnd();
        }

        function proxy($server_version, $server_hostname, $server_port, $server_uri, $start_session = true) {
                global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;

                phpCAS :: traceBegin();
                if (is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error($PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . $PHPCAS_INIT_CALL['file'] . ':' . $PHPCAS_INIT_CALL['line'] . ')');
                }
                if (gettype($server_version) != 'string') {
                        phpCAS :: error('type mismatched for parameter $server_version (should be `string\')');
                }
                if (gettype($server_hostname) != 'string') {
                        phpCAS :: error('type mismatched for parameter $server_hostname (should be `string\')');
                }
                if (gettype($server_port) != 'integer') {
                        phpCAS :: error('type mismatched for parameter $server_port (should be `integer\')');
                }
                if (gettype($server_uri) != 'string') {
                        phpCAS :: error('type mismatched for parameter $server_uri (should be `string\')');
                }

                // store where the initialzer is called from
                $dbg = phpCAS :: backtrace();
                $PHPCAS_INIT_CALL = array (
                        'done' => TRUE,
                        'file' => $dbg[0]['file'],
                        'line' => $dbg[0]['line'],
                        'method' => __CLASS__ . '::' . __FUNCTION__
                );

                // initialize the global object $PHPCAS_CLIENT
                $PHPCAS_CLIENT = new CASClient($server_version, TRUE /*proxy*/
                , $server_hostname, $server_port, $server_uri, $start_session);
                phpCAS :: traceEnd();
        }

        // ########################################################################
        //  DEBUGGING
        // ########################################################################

        function setDebug($filename = '') {
                global $PHPCAS_DEBUG;

                if ($filename != FALSE && gettype($filename) != 'string') {
                        phpCAS :: error('type mismatched for parameter $dbg (should be FALSE or the name of the log file)');
                }

                if (empty ($filename)) {
                        if (preg_match('/^Win.*/', getenv('OS'))) {
                                if (isset ($_ENV['TMP'])) {
                                        $debugDir = $_ENV['TMP'] . '/';
                                } else
                                        if (isset ($_ENV['TEMP'])) {
                                                $debugDir = $_ENV['TEMP'] . '/';
                                        } else {
                                                $debugDir = '';
                                        }
                        } else {
                                $debugDir = DEFAULT_DEBUG_DIR;
                        }
                        $filename = $debugDir . 'phpCAS.log';
                }

                if (empty ($PHPCAS_DEBUG['unique_id'])) {
                        $PHPCAS_DEBUG['unique_id'] = substr(strtoupper(md5(uniqid(''))), 0, 4);
                }

                $PHPCAS_DEBUG['filename'] = $filename;

                phpCAS :: trace('START phpCAS-' . PHPCAS_VERSION . ' ******************');
        }

        function backtrace() {
                if (function_exists('debug_backtrace')) {
                        return debug_backtrace();
                } else {
                        // poor man's hack ... but it does work ...
                        return array ();
                }
        }

        function log($str) {
                $indent_str = ".";
                global $PHPCAS_DEBUG;

                if ($PHPCAS_DEBUG['filename']) {
                        for ($i = 0; $i < $PHPCAS_DEBUG['indent']; $i++) {
                                $indent_str .= '|    ';
                        }
                        error_log($PHPCAS_DEBUG['unique_id'] . ' ' . $indent_str . $str . "\n", 3, $PHPCAS_DEBUG['filename']);
                }

        }

        function error($msg) {
                $dbg = phpCAS :: backtrace();
                $function = '?';
                $file = '?';
                $line = '?';
                if (is_array($dbg)) {
                        for ($i = 1; $i < sizeof($dbg); $i++) {
                                if (is_array($dbg[$i])) {
                                        if ($dbg[$i]['class'] == __CLASS__) {
                                                $function = $dbg[$i]['function'];
                                                $file = $dbg[$i]['file'];
                                                $line = $dbg[$i]['line'];
                                        }
                                }
                        }
                }
                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";
                phpCAS :: trace($msg);
                phpCAS :: traceExit();
                exit ();
        }

        function trace($str) {
                $dbg = phpCAS :: backtrace();
                phpCAS :: log($str . ' [' . basename($dbg[1]['file']) . ':' . $dbg[1]['line'] . ']');
        }

        function traceBegin() {
                global $PHPCAS_DEBUG;

                $dbg = phpCAS :: backtrace();
                $str = '=> ';
                if (!empty ($dbg[2]['class'])) {
                        $str .= $dbg[2]['class'] . '::';
                }
                $str .= $dbg[2]['function'] . '(';
                if (is_array($dbg[2]['args'])) {
                        foreach ($dbg[2]['args'] as $index => $arg) {
                                if ($index != 0) {
                                        $str .= ', ';
                                }
                                $str .= str_replace("\n", "", var_export($arg, TRUE));
                        }
                }
                $str .= ') [' . basename($dbg[2]['file']) . ':' . $dbg[2]['line'] . ']';
                phpCAS :: log($str);
                $PHPCAS_DEBUG['indent']++;
        }

        function traceEnd($res = '') {
                global $PHPCAS_DEBUG;

                $PHPCAS_DEBUG['indent']--;
                $dbg = phpCAS :: backtrace();
                $str = '';
                $str .= '<= ' . str_replace("\n", "", var_export($res, TRUE));
                phpCAS :: log($str);
        }

        function traceExit() {
                global $PHPCAS_DEBUG;

                phpCAS :: log('exit()');
                while ($PHPCAS_DEBUG['indent'] > 0) {
                        phpCAS :: log('-');
                        $PHPCAS_DEBUG['indent']--;
                }
        }

        // ########################################################################
        //  INTERNATIONALIZATION
        // ########################################################################
        function setLang($lang) {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                if (gettype($lang) != 'string') {
                        phpCAS :: error('type mismatched for parameter $lang (should be `string\')');
                }
                $PHPCAS_CLIENT->setLang($lang);
        }

        // ########################################################################
        //  VERSION
        // ########################################################################
        function getVersion() {
                return PHPCAS_VERSION;
        }

        // ########################################################################
        //  HTML OUTPUT
        // ########################################################################
        function setHTMLHeader($header) {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                if (gettype($header) != 'string') {
                        phpCAS :: error('type mismatched for parameter $header (should be `string\')');
                }
                $PHPCAS_CLIENT->setHTMLHeader($header);
        }

        function setHTMLFooter($footer) {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                if (gettype($footer) != 'string') {
                        phpCAS :: error('type mismatched for parameter $footer (should be `string\')');
                }
                $PHPCAS_CLIENT->setHTMLFooter($footer);
        }

        // ########################################################################
        //  PGT STORAGE
        // ########################################################################
        function setPGTStorageFile($format = '', $path = '') {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_CLIENT->isProxy()) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if ($PHPCAS_AUTH_CHECK_CALL['done']) {
                        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'] . ')');
                }
                if (gettype($format) != 'string') {
                        phpCAS :: error('type mismatched for parameter $format (should be `string\')');
                }
                if (gettype($path) != 'string') {
                        phpCAS :: error('type mismatched for parameter $format (should be `string\')');
                }
                $PHPCAS_CLIENT->setPGTStorageFile($format, $path);
                phpCAS :: traceEnd();
        }

        function setPGTStorageDB($user, $password, $database_type = '', $hostname = '', $port = 0, $database = '', $table = '') {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_CLIENT->isProxy()) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if ($PHPCAS_AUTH_CHECK_CALL['done']) {
                        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'] . ')');
                }
                if (gettype($user) != 'string') {
                        phpCAS :: error('type mismatched for parameter $user (should be `string\')');
                }
                if (gettype($password) != 'string') {
                        phpCAS :: error('type mismatched for parameter $password (should be `string\')');
                }
                if (gettype($database_type) != 'string') {
                        phpCAS :: error('type mismatched for parameter $database_type (should be `string\')');
                }
                if (gettype($hostname) != 'string') {
                        phpCAS :: error('type mismatched for parameter $hostname (should be `string\')');
                }
                if (gettype($port) != 'integer') {
                        phpCAS :: error('type mismatched for parameter $port (should be `integer\')');
                }
                if (gettype($database) != 'string') {
                        phpCAS :: error('type mismatched for parameter $database (should be `string\')');
                }
                if (gettype($table) != 'string') {
                        phpCAS :: error('type mismatched for parameter $table (should be `string\')');
                }
                $PHPCAS_CLIENT->setPGTStorageDB($user, $password, $database_type, $hostname, $port, $database, $table);
                phpCAS :: traceEnd();
        }

        // ########################################################################
        // ACCESS TO EXTERNAL SERVICES
        // ########################################################################
        function serviceWeb($url, & $err_code, & $output) {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_CLIENT->isProxy()) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
                        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()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
                        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');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be `string\')');
                }

                $res = $PHPCAS_CLIENT->serviceWeb($url, $err_code, $output);

                phpCAS :: traceEnd($res);
                return $res;
        }

        function serviceMail($url, $service, $flags, & $err_code, & $err_msg, & $pt) {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_CLIENT->isProxy()) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
                        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()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
                        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');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be `string\')');
                }

                if (gettype($flags) != 'integer') {
                        phpCAS :: error('type mismatched for parameter $flags (should be `integer\')');
                }

                $res = $PHPCAS_CLIENT->serviceMail($url, $service, $flags, $err_code, $err_msg, $pt);

                phpCAS :: traceEnd($res);
                return $res;
        }

        // ########################################################################
        //  AUTHENTICATION
        // ########################################################################
        function setCacheTimesForAuthRecheck($n) {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                if (gettype($n) != 'integer') {
                        phpCAS :: error('type mismatched for parameter $header (should be `string\')');
                }
                $PHPCAS_CLIENT->setCacheTimesForAuthRecheck($n);
        }

        function checkAuthentication() {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }

                $auth = $PHPCAS_CLIENT->checkAuthentication();

                // store where the authentication has been checked and the result
                $dbg = phpCAS :: backtrace();
                $PHPCAS_AUTH_CHECK_CALL = array (
                        'done' => TRUE,
                        'file' => $dbg[0]['file'],
                        'line' => $dbg[0]['line'],
                        'method' => __CLASS__ . '::' . __FUNCTION__,
                        'result' => $auth
                );
                phpCAS :: traceEnd($auth);
                return $auth;
        }

        function forceAuthentication() {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }

                $auth = $PHPCAS_CLIENT->forceAuthentication();

                // store where the authentication has been checked and the result
                $dbg = phpCAS :: backtrace();
                $PHPCAS_AUTH_CHECK_CALL = array (
                        'done' => TRUE,
                        'file' => $dbg[0]['file'],
                        'line' => $dbg[0]['line'],
                        'method' => __CLASS__ . '::' . __FUNCTION__,
                        'result' => $auth
                );

                if (!$auth) {
                        phpCAS :: trace('user is not authenticated, redirecting to the CAS server');
                        $PHPCAS_CLIENT->forceAuthentication();
                } else {
                        phpCAS :: trace('no need to authenticate (user `' . phpCAS :: getUser() . '\' is already authenticated)');
                }

                phpCAS :: traceEnd();
                return $auth;
        }

        function renewAuthentication() {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }

                // store where the authentication has been checked and the result
                $dbg = phpCAS :: backtrace();
                $PHPCAS_AUTH_CHECK_CALL = array (
                        'done' => TRUE,
                        'file' => $dbg[0]['file'],
                        'line' => $dbg[0]['line'],
                        'method' => __CLASS__ . '::' . __FUNCTION__,
                        'result' => $auth
                );

                $PHPCAS_CLIENT->renewAuthentication();
                phpCAS :: traceEnd();
        }

        function authenticate() {
                phpCAS :: error('this method is deprecated. You should use ' . __CLASS__ . '::forceAuthentication() instead');
        }

        function isAuthenticated() {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;

                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }

                // call the isAuthenticated method of the global $PHPCAS_CLIENT object
                $auth = $PHPCAS_CLIENT->isAuthenticated();

                // store where the authentication has been checked and the result
                $dbg = phpCAS :: backtrace();
                $PHPCAS_AUTH_CHECK_CALL = array (
                        'done' => TRUE,
                        'file' => $dbg[0]['file'],
                        'line' => $dbg[0]['line'],
                        'method' => __CLASS__ . '::' . __FUNCTION__,
                        'result' => $auth
                );
                phpCAS :: traceEnd($auth);
                return $auth;
        }

        function isSessionAuthenticated() {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                return ($PHPCAS_CLIENT->isSessionAuthenticated());
        }

        function getUser() {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
                        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');
                }
                return $PHPCAS_CLIENT->getUser();
        }

        function getAttributes() {
                global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
                }
                if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
                        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');
                }
                return $PHPCAS_CLIENT->getAttributes();
        }
        function handleLogoutRequests($check_client = true, $allowed_clients = false) {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                return ($PHPCAS_CLIENT->handleLogoutRequests($check_client, $allowed_clients));
        }

        function getServerLoginURL() {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                return $PHPCAS_CLIENT->getServerLoginURL();
        }

        function setServerLoginURL($url = '') {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after
                                                        ' . __CLASS__ . '::client()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be
                                                `string\')');
                }
                $PHPCAS_CLIENT->setServerLoginURL($url);
                phpCAS :: traceEnd();
        }

        function setServerServiceValidateURL($url = '') {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after
                                                        ' . __CLASS__ . '::client()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be
                                                `string\')');
                }
                $PHPCAS_CLIENT->setServerServiceValidateURL($url);
                phpCAS :: traceEnd();
        }

        function setServerProxyValidateURL($url = '') {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after
                                                        ' . __CLASS__ . '::client()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be
                                                `string\')');
                }
                $PHPCAS_CLIENT->setServerProxyValidateURL($url);
                phpCAS :: traceEnd();
        }

        function setServerSamlValidateURL($url = '') {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after
                                                        ' . __CLASS__ . '::client()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be
                                                `string\')');
                }
                $PHPCAS_CLIENT->setServerSamlValidateURL($url);
                phpCAS :: traceEnd();
        }

        function getServerLogoutURL() {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
                }
                return $PHPCAS_CLIENT->getServerLogoutURL();
        }

        function setServerLogoutURL($url = '') {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after
                                                        ' . __CLASS__ . '::client()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be
                                                `string\')');
                }
                $PHPCAS_CLIENT->setServerLogoutURL($url);
                phpCAS :: traceEnd();
        }

        function logout($params = "") {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                $parsedParams = array ();
                if ($params != "") {
                        if (is_string($params)) {
                                phpCAS :: error('method `phpCAS::logout($url)\' is now deprecated, use `phpCAS::logoutWithUrl($url)\' instead');
                        }
                        if (!is_array($params)) {
                                phpCAS :: error('type mismatched for parameter $params (should be `array\')');
                        }
                        foreach ($params as $key => $value) {
                                if ($key != "service" && $key != "url") {
                                        phpCAS :: error('only `url\' and `service\' parameters are allowed for method `phpCAS::logout($params)\'');
                                }
                                $parsedParams[$key] = $value;
                        }
                }
                $PHPCAS_CLIENT->logout($parsedParams);
                // never reached
                phpCAS :: traceEnd();
        }

        function logoutWithRedirectService($service) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                if (!is_string($service)) {
                        phpCAS :: error('type mismatched for parameter $service (should be `string\')');
                }
                $PHPCAS_CLIENT->logout(array (
                        "service" => $service
                ));
                // never reached
                phpCAS :: traceEnd();
        }

        function logoutWithUrl($url) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                if (!is_string($url)) {
                        phpCAS :: error('type mismatched for parameter $url (should be `string\')');
                }
                $PHPCAS_CLIENT->logout(array (
                        "url" => $url
                ));
                // never reached
                phpCAS :: traceEnd();
        }

        function logoutWithRedirectServiceAndUrl($service, $url) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                if (!is_string($service)) {
                        phpCAS :: error('type mismatched for parameter $service (should be `string\')');
                }
                if (!is_string($url)) {
                        phpCAS :: error('type mismatched for parameter $url (should be `string\')');
                }
                $PHPCAS_CLIENT->logout(array (
                        "service" => $service,
                        "url" => $url
                ));
                // never reached
                phpCAS :: traceEnd();
        }

        function setFixedCallbackURL($url = '') {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (!$PHPCAS_CLIENT->isProxy()) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be `string\')');
                }
                $PHPCAS_CLIENT->setCallbackURL($url);
                phpCAS :: traceEnd();
        }

        function setFixedServiceURL($url) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (gettype($url) != 'string') {
                        phpCAS :: error('type mismatched for parameter $url (should be `string\')');
                }
                $PHPCAS_CLIENT->setURL($url);
                phpCAS :: traceEnd();
        }

        function getServiceURL() {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                return ($PHPCAS_CLIENT->getURL());
        }

        function retrievePT($target_service, & $err_code, & $err_msg) {
                global $PHPCAS_CLIENT;
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
                }
                if (gettype($target_service) != 'string') {
                        phpCAS :: error('type mismatched for parameter $target_service(should be `string\')');
                }
                return ($PHPCAS_CLIENT->retrievePT($target_service, $err_code, $err_msg));
        }

        function setCasServerCert($cert) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                if (gettype($cert) != 'string') {
                        phpCAS :: error('type mismatched for parameter $cert (should be `string\')');
                }
                $PHPCAS_CLIENT->setCasServerCert($cert);
                phpCAS :: traceEnd();
        }

        function setCasServerCACert($cert) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                if (gettype($cert) != 'string') {
                        phpCAS :: error('type mismatched for parameter $cert (should be `string\')');
                }
                $PHPCAS_CLIENT->setCasServerCACert($cert);
                phpCAS :: traceEnd();
        }

        function setNoCasServerValidation() {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                $PHPCAS_CLIENT->setNoCasServerValidation();
                phpCAS :: traceEnd();
        }

        function setExtraCurlOption($key, $value) {
                global $PHPCAS_CLIENT;
                phpCAS :: traceBegin();
                if (!is_object($PHPCAS_CLIENT)) {
                        phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
                }
                $PHPCAS_CLIENT->setExtraCurlOption($key, $value);
                phpCAS :: traceEnd();
        }

}

// ########################################################################
// DOCUMENTATION
// ########################################################################

// ########################################################################
//  MAIN PAGE

// ########################################################################
//  MODULES DEFINITION

// ########################################################################
//  EXAMPLES

?>