blueshoes php application framework and cms            core_auth
[ class tree: core_auth ] [ index: core_auth ] [ all elements ]

Class: Bs_CugDb

Source Location: /core/auth/cug/Bs_CugDb.class.php

Class Overview

Bs_Object
   |
   --Bs_Cug
      |
      --Bs_CugDb

CUG Class using a database. Extended from Bs_Cug, look there too.


Author(s):

Version:

  • 4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:37 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods

Class: Bs_Cug

Bs_Cug::Bs_Cug()
Constructor.
Bs_Cug::createPassword()
creates a new pronounceable password and returns it.
Bs_Cug::getLoginForm()
returns the login form as html code.
Bs_Cug::letMeIn()
tells if the session is registered, the user is logged in.
Bs_Cug::loadLoginForm()
loads a default login form if no login form has been assigned before.
Bs_Cug::loadRecoverPasswordByUsernameForm()
loads a default "recover password by username" form.
Bs_Cug::logout()
logs out the user from this cug, does *not* kill the session cause it might be needed for other things.
Bs_Cug::looksLikeHack()
let's see if this failed attempt looks like a hack.
Bs_Cug::redirect()
!!!deprecated!!! redirects to the specified page.
Bs_Cug::registerValidator()
registers a global validator function (or object method) that needs to be passed in order to successfully pass the "validate login" checks.
Bs_Cug::treatLoginForm()
treats the login form.
Bs_Cug::treatRecoverPasswordByUsernameForm()
treats the "recover password by username" form.
Bs_Cug::_logAttempt()
overwrite this method.
Bs_Cug::_validateLogin()
developer: if you subclass then overwrite this method, and make sure this gets called after you validated what you can. here we'll see if there are registered validators to call, and do the work. on the first error we stop and return.

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 76]
CUG Class using a database. Extended from Bs_Cug, look there too.

This is a subclass of Bs_Cug and customized for the use with a database. It's tested and developed for use with MySql as DB. If you want an other DB, you may need to add code or subclass this one.

Your users are organized in a DB table. Give the table name and maybe the db name in the vars $userDbName and $userTableName.

The structure of that table needs to have the following fields: 'user' 'pass'

It *may* have the following 'lifecycle' fields 'isActive' 'startDatetime' 'endDatetime'

It's a good idea to have the 'ID' field as well and it may have any other fields.

If all the lifecycle fields are there, they will be used. NOTE: Times are written in GMT, not in any local or server time.

Features: (mostly not available in Bs_Cug, only in Bs_CugDb)

  • hack detection
  • anti hack mechanism (Unix-like doubling of the timeout)
  • built-in account lifecycle
  • logging (with automatic db-table generation and uptodate check, extends it if needed)
  • checking case sensitive or not for usernames and passwords
  • registered [additional] custom validators
Todo:
  • automatic password recovery using username/email
Example user-db-table:

dependencies: Bs_Cug, Bs_MySql, Bs_TextUtil




Tags:

pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:37 $
copyright:  blueshoes.org
author:  andrej arn <at blueshoes dot org>


[ Top ]


Class Variables

$logDbName =

[line 109]

the db of the log table.



Tags:

see:  Bs_CugDb::$logTableName
access:  public

Type:   string


[ Top ]

$logTableName =

[line 118]

the db table to log to. is also used to determine if it's

a hack attempt. (history)




Tags:

see:  vars $logDbName, Bs_Cug->logAttempts, Bs_Cug->checkForHack
access:  public

Type:   string


[ Top ]

$manyFailuresErrorMsg = array(
    'en' => "<br>This was your [numFailures]. attempt that failed in a row. 
            There is no maximum number of allowed attempts. Remember that the username and password 
            may be case sensitive. Be aware that every request is logged. During your next try you have 
            to wait [timeoutNext] seconds.", 
    'de' => "<br>Dies war Ihr [numFailures]. Versucht der in Serie fehlschlug.
            Es gibt kein Maximum an erlaubten Versuchen. Achtung: Gross/Kleinschrift beim Benutzernamen 
            und Passwort spielt eine Rolle. Hinweis: Jeder Zugriff auf diese Seite wird aufgezeichnet. 
            Bei Ihrem nächsten Versuch müssen Sie [timeoutNext] warten.", 
  )

[line 135]

additional error message for users that tried to log in many times (+3) in a row and failed.



Tags:

access:  public

Type:   array


[ Top ]

$userDbName =

[line 93]

the db of the user table.



Tags:

see:  Bs_CugDb::$userTableName
access:  public

Type:   string


[ Top ]

$userTableName =

[line 101]

the db table where the users are.



Tags:

see:  Bs_CugDb::$userDbName
access:  public

Type:   string


[ Top ]

$_signupForm =

[line 128]

instance of Bs_Form by setting this var you can create custom signup forms.

otherwise use the built in form.




Tags:

see:  Bs_CugDb::setSignupForm(), _loadSignupForm()
access:  public

Type:   object


[ Top ]



Class Methods


constructor Bs_CugDb [line 146]

Bs_CugDb Bs_CugDb( string $cugName, [array $postData = NULL])

Constructor.



Parameters:

string   $cugName  
array   $postData   (default is NULL which means use $_POST. only pass something if really needed.)

[ Top ]

method checkLogDbTable [line 370]

bool checkLogDbTable( )

checks if the log db table is ok.

this is needed if an operation on it failed. maybe the table structure is not up-to-date or does not exist at all.

the needed changes will be made automatically. note that your user needs the appropriate rights (alter, create, index...)

hint: first try your query, if it fails check the table using this method. if this method returns FALSE then try your query again.




Tags:

return:  (TRUE if table was ok, FALSE if changes have/had to be made.)
throws:  bs_exception
access:  public


[ Top ]

method getDbString [line 509]

string getDbString( [string $which = 'user'])

returns the dbname-dbtable string to use in queries.

example: "dbname.dbtable" if logDbName/userDbName is set, "dbtable" if not.




Tags:

throws:  bool FALSE (if the appropriate table name is not set or empty.)
access:  public


Parameters:

string   $which   (one of 'user' (default) or 'log'.)

[ Top ]

method getNumLoginFailures [line 598]

vector getNumLoginFailures( [int $numDays = 3])

tells how many times this user failed to login in a row.

since bs4.3: when a user supplied correct login data, but the system did not let the user in because the account expired or something, that is not considered a 'failed login' here. because there is nothing the user can do. it is not a violation.

the returned vector has these elements: 0: number (int) of failed logins in a row for that user. int 0 if we dunno. 1: number (int) of hack attempts (out of these failed login attempts). 0 = dunno or none. 2: number (int) of seconds we recommend to timeout. NOTE: instead of this vector you may get a bs_exception back (see throws).




Tags:

return:  (see above)
throws:  bs_exception
access:  public


Parameters:

int   $numDays   (how many days to go back in history. default is 3. 0 means infinite.)

[ Top ]

method getOldSids [line 541]

array getOldSids( string $username, [int $numDays = 2])

returns the sid's (session id's) of session that existed for this user, before this one.

you may want to kill those sessions, for example to prevent 2 users to share the same account.




Tags:

return:  (vector, may be empty)
see:  $this->killOldSessions()
throws:  bs_exception
access:  public


Parameters:

string   $username  
int   $numDays   (how many days to look back, default is 2.)

[ Top ]

method killOldSessions [line 568]

int killOldSessions( string $username, [int $numDays = 2])

kills old sessions that existed for this user, before this one.

this is useful to prevent account-sharing.




Tags:

return:  (the number of killed sessions this time, 0-n. sessions that have been killed before are not counted.)
see:  $this->killOldSessions()
throws:  bs_exception
access:  public


Parameters:

string   $username  
int   $numDays   (how many days to look back, default is 2.)

[ Top ]

method recoverPasswordByUsername [line 665]

mixed recoverPasswordByUsername( string $username, [bool $automail = TRUE])

recovers the password for the user specified and sends it by email if desired.

examples: recoverPasswordSendEmail('tomjones');

return value:

  • no record found => bool FALSE
  • record found, no automail => hash with the keys 'user', 'pass' and 'email' (translated from $this->userFieldNames)
  • record found, with automail => bool telling if the automail worked
  • any db error => bs_exception




Tags:

return:  (see above)
throws:  bs_exception (on any db error)
access:  public


Parameters:

string   $username  
bool   $automail   (default is TRUE, tells if the new password should be mailed to the user automatically.)

[ Top ]

method resetPasswordByEmail [line 771]

void resetPasswordByEmail( mixed $email, [mixed $automail = TRUE])



Tags:



[ Top ]

method resetPasswordByUsername [line 733]

mixed resetPasswordByUsername( string $username, [bool $automail = TRUE], [string $newPassword = NULL])

resets the users password to a newly created one, and mails it to the user if that's desired (see param $automail).

example: resetPasswordByUsername('tomjones');

return value:

  • if the param $automail is TRUE then you get a bool value back telling if the sendmail worked.
  • if the param $automail is FALSE then you get the new password back (string).
  • if you get an exception, an error occured. this can occure when setting the new password, thus nothing has been done. it can also be when fetching the users email address (if param $automail is TRUE). that means the new password has already been set.




Tags:

return:  (see above)
throws:  bs_exception (on any db error, see above)
access:  public


Parameters:

string   $username  
bool   $automail   (default is TRUE, tells if the new password should be mailed to the user automatically.)
string   $newPassword   (default is NULL which means create one automatically.)

[ Top ]

method setDbObject [line 160]

void setDbObject( object &$bsDb)

sets a db object for this class.

the global bsdb object that may be set in the constructor won't be used anymore.




Tags:

access:  public


Parameters:

object   &$bsDb  

[ Top ]

method setSignupForm [line 783]

bool setSignupForm( object $form)

sets a custom form object, use this if you are not satisfied with the built in one.



Tags:

see:  var $_signupForm, _loadSignupForm()
access:  public


Parameters:

object   $form  

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:08:24 +0100 by phpDocumentor 1.2.3