phpDoc fixes, dead code cleanup (#298)

Author: kberzinch

source/CAS.php

@@ -248,6 +248,7 @@
 
 /**
  * The default directory for the debug file under Unix.
+ * @return  string directory for the debug file
  */
 function gettmpdir() {
 if (!empty($_ENV['TMP'])) { return realpath($_ENV['TMP']); }
@@ -291,6 +292,7 @@ class phpCAS
     private static $_PHPCAS_CLIENT;
 
     /**
+     * @var array
      * This variable is used to store where the initializer is called from
      * (to print a comprehensive error in case of multiple calls).
      *
@@ -299,6 +301,7 @@ class phpCAS
     private static $_PHPCAS_INIT_CALL;
 
     /**
+     * @var array
      * This variable is used to store phpCAS debug mode.
      *
      * @hideinitializer
@@ -334,7 +337,7 @@ class phpCAS
      * @param bool   $changeSessionID Allow phpCAS to change the session_id (Single
      * Sign Out/handleLogoutRequests is based on that change)
      *
-     * @return a newly created CAS_Client object
+     * @return void a newly created CAS_Client object
      * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
      * called, only once, and before all other methods (except phpCAS::getVersion()
      * and phpCAS::setDebug()).
@@ -373,12 +376,12 @@ public static function client($server_version, $server_hostname,
      *
      * @param string $server_version  the version of the CAS server
      * @param string $server_hostname the hostname of the CAS server
-     * @param string $server_port     the port the CAS server is running on
+     * @param int    $server_port     the port the CAS server is running on
      * @param string $server_uri      the URI the CAS server is responding on
      * @param bool   $changeSessionID Allow phpCAS to change the session_id (Single
      * Sign Out/handleLogoutRequests is based on that change)
      *
-     * @return a newly created CAS_Client object
+     * @return void a newly created CAS_Client object
      * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
      * called, only once, and before all other methods (except phpCAS::getVersion()
      * and phpCAS::setDebug()).
@@ -495,7 +498,7 @@ public static function setVerbose($verbose)
     /**
      * Show is verbose mode is on
      *
-     * @return boot verbose
+     * @return bool verbose
      */
     public static function getVerbose()
     {
@@ -635,7 +638,7 @@ public static function traceBegin()
      * This method is used to indicate the end of the execution of a function in
      * debug mode.
      *
-     * @param string $res the result of the function
+     * @param mixed $res the result of the function
      *
      * @return void
      */
@@ -646,7 +649,6 @@ public static function traceEnd($res = '')
         } else {
             self::$_PHPCAS_DEBUG['indent']--;
         }
-        $dbg = debug_backtrace();
         $str = '';
         if (is_object($res)) {
             $str .= '<= ' . get_class($res);
@@ -713,7 +715,7 @@ public static function setLang($lang)
     /**
      * This method returns the phpCAS version.
      *
-     * @return the phpCAS version.
+     * @return string the phpCAS version.
      */
     public static function getVersion()
     {
@@ -723,7 +725,7 @@ public static function getVersion()
     /**
      * This method returns supported protocols.
      *
-     * @return an array of all supported protocols. Use internal protocol name as array key.
+     * @return array an array of all supported protocols. Use internal protocol name as array key.
      */
     public static function getSupportedProtocols()
     {
@@ -793,8 +795,8 @@ public static function setHTMLFooter($footer)
     /**
      * This method can be used to set a custom PGT storage object.
      *
-     * @param CAS_PGTStorage $storage a PGT storage object that inherits from the
-     * CAS_PGTStorage class
+     * @param CAS_PGTStorage_AbstractStorage $storage a PGT storage object that inherits from the
+     * CAS_PGTStorage_AbstractStorage class
      *
      * @return void
      */
@@ -923,7 +925,7 @@ public static function initializeProxiedService (CAS_ProxiedService $proxiedServ
      * This method is used to access an HTTP[S] service.
      *
      * @param string $url       the service to access.
-     * @param string &$err_code an error code Possible values are
+     * @param int &$err_code an error code Possible values are
      * PHPCAS_SERVICE_OK (on success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE,
      * PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE, PHPCAS_SERVICE_PT_FAILURE,
      * PHPCAS_SERVICE_NOT_AVAILABLE.
@@ -956,15 +958,15 @@ public static function serviceWeb($url, & $err_code, & $output)
      * including the mailing box for IMAP URLs, as accepted by imap_open().
      * @param string $service   a string giving for CAS retrieve Proxy ticket
      * @param string $flags     options given to imap_open().
-     * @param string &$err_code an error code Possible values are
+     * @param int &$err_code an error code Possible values are
      * PHPCAS_SERVICE_OK (on success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE,
      * PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE, PHPCAS_SERVICE_PT_FAILURE,
      * PHPCAS_SERVICE_NOT_AVAILABLE.
      * @param string &$err_msg  an error message on failure
      * @param string &$pt       the Proxy Ticket (PT) retrieved from the CAS
      * server to access the URL on success, false on error).
      *
-     * @return object IMAP stream on success, false otherwise (in this later
+     * @return object|false IMAP stream on success, false otherwise (in this later
      * case, $err_code gives the reason why it failed and $err_msg contains an
      * error message).
      */
@@ -1047,7 +1049,7 @@ public static function setCasAttributeParserCallback($function, array $additiona
      * logs in (such as registering an account, performing logging, etc), register
      * a callback function here.
      *
-     * @param string $function       Callback function
+     * @param callable $function       Callback function
      * @param array  $additionalArgs optional array of arguments
      *
      * @return void
@@ -1068,7 +1070,7 @@ public static function setPostAuthenticateCallback ($function, array $additional
      * applications that manage their own sessions (rather than letting phpCAS
      * start and destroy the session).
      *
-     * @param string $function       Callback function
+     * @param callable $function       Callback function
      * @param array  $additionalArgs optional array of arguments
      *
      * @return void
@@ -1086,7 +1088,7 @@ public static function setSingleSignoutCallback ($function, array $additionalArg
      * determined by a cas gateway call.(cas login call without any interactive
      * prompt)
      *
-     * @return true when the user is authenticated, false when a previous
+     * @return bool true when the user is authenticated, false when a previous
      * gateway login failed or the function will not return if the user is
      * redirected to the cas server for a gateway login attempt
      */
@@ -1154,7 +1156,7 @@ public static function renewAuthentication()
      * This method is called to check if the user is authenticated (previously or by
      * tickets given in the URL).
      *
-     * @return true when the user is authenticated.
+     * @return bool true when the user is authenticated.
      */
     public static function isAuthenticated()
     {
@@ -1289,7 +1291,7 @@ public static function getAttribute($key)
      *
      * @return void
      */
-    public static function handleLogoutRequests($check_client = true, $allowed_clients = false)
+    public static function handleLogoutRequests($check_client = true, $allowed_clients = array())
     {
         phpCAS::_validateClientExists();
 
@@ -1298,9 +1300,8 @@ public static function handleLogoutRequests($check_client = true, $allowed_clien
 
     /**
      * This method returns the URL to be used to login.
-     * or phpCAS::isAuthenticated().
      *
-     * @return the login name of the authenticated user
+     * @return string the login URL
      */
     public static function getServerLoginURL()
     {
@@ -1405,10 +1406,9 @@ public static function setServerSamlValidateURL($url = '')
     }
 
     /**
-     * This method returns the URL to be used to login.
-     * or phpCAS::isAuthenticated().
+     * This method returns the URL to be used to logout.
      *
-     * @return the login name of the authenticated user
+     * @return string the URL to use to log out
      */
     public static function getServerLogoutURL()
     {
@@ -1612,7 +1612,7 @@ public static function getServiceURL()
      * Retrieve a Proxy Ticket from the CAS server.
      *
      * @param string $target_service Url string of service to proxy
-     * @param string &$err_code      error code
+     * @param int &$err_code      error code
      * @param string &$err_msg       error message
      *
      * @return string Proxy Ticket

source/CAS/AuthenticationException.php

@@ -66,7 +66,7 @@ class CAS_AuthenticationException
      * @param string     $err_msg      the error message given by the CAS server
      */
     public function __construct($client,$failure,$cas_url,$no_response,
-        $bad_response='',$cas_response='',$err_code='',$err_msg=''
+        $bad_response=false,$cas_response='',$err_code=-1,$err_msg=''
     ) {
         $messages = array();
         phpCAS::traceBegin();
@@ -91,7 +91,7 @@ public function __construct($client,$failure,$cas_url,$no_response,
                     break;
                 case CAS_VERSION_2_0:
                 case CAS_VERSION_3_0:
-                    if ( empty($err_code) ) {
+                    if ( $err_code === -1 ) {
                         phpCAS::trace($messages[] = 'Reason: no CAS error');
                     } else {
                         phpCAS::trace($messages[] = 'Reason: ['.$err_code.'] CAS error: '.$err_msg);