Tapir User Manger: Tapir_Auth

Tapir_Auth is the main interface between TUM and a web page. Any page that relies on authentication must create a Tapir_Auth object. To do so, one must include the appropriate files,

require "tapir-sql.php";
require "tapir-auth.php";

and pass Tapir_Auth a database connection,

$auth=new Tapir_Auth(tapir_connect_ro());

There are two authentication modes,
(1) required, and (2) optional.

If authentication is required, then TUM will require that a user be authenticated before viewing the page. If the user's browser has a permanent cookie, the user will be logged in automatically. Otherwise, we'll ask for username and password. If your site allows it, we will also offer the user the chance to create a new account or recover a forgotten password. To require authentication, execute the following statement before your page outputs any data

$auth->required();

TUM also supports optional authentication. In this case, TUM will automatically log in a user if a permanent cookie exists and will also determine the session_id and the user_id if the user is otherwise logged in. This makes it possible, for instance, to make pages that are accessable to all, but can be personalized for particular users. To implement optional authentication, execute

$auth->optional();

If either optional or required authentication is in use, the user id and session id will be logged in the Apache log file.

Tapir_Auth

Constructor:

  Tapir_Auth($conn)

    Create a new Tapir_Auth object. If supplied, $conn will be used for a database connection. Otherwise, TUM will create a read-only connection to the database.
Methods:

  required([$caps])

    Require user authentication. If the user isn't already logged in, we force the user to log in. The optional $caps is a bitmap of capabilities (privledges) that the user must have to log in: privileges are defined in the tapir-constants.php file and can be:

$TAPIR_CAP_IS_INTERNAL
$TAPIR_CAP_EDIT_USERS
$TAPIR_CAP_EMAIL_VERIFIED

required() can be called more than once to require different capabilities. WARNING: a more flexible system of user privileges is under development and this interface may change.
  optional()

    Optional user authentication. If the user is logged in (a session cookie exists) we determine the user's identity. If the user is not logged in, does nothing.

  login_url([$goto])

    Returns a URL that will allow a user to log in. If the URL $goto is specified, the user will be sent to that URL after the user logs in. Otherwise, the user will be sent back to the current page. This function can be called even if the user has not been authenticated.

  logout_url([$goto])

    Returns a URL that will allow a user to log out. If the URL $goto is specified, the user will be sent to that URL after the user logs in. Otherwise, the user will be sent back to the current page, unless the current page requires authentication, in which case the user will be sent to /. This function can be called even if the user has not been authenticated.

  redirect($url)

    Redirects the user's web browser to $url. Can be called if the user has not been authenticated, but must be called before any output has been sent.

  get_email()

    Returns the email address of the current user. If the user is not logged in, this function will force the user to log in.

  get_first_name()

    Returns the first name of the current user. If the user is not logged in, this function will force the user to log in.

  get_last_name()

    Returns the last name of the current user. If the user is not logged in, this function will force the user to log in.

  email_required()

    Require that the user have a valid email address. Equivalent to $auth->required($TAPIR_CAP_EMAIL_VERIFIED). Will force the user to pass through the email verification process if she hasn't already.

  has_permanent_token()

    Returns true if the user has a permanent token in her browser, and false otherwise.
Variables:

  $conn

    The current database connection, an instance of Tapir_Sql.

  $logged_in

    True if the user is currently logged in, false otherwise.

  $session_id

    The id of current session.

  $user_id

    The id of the current user.

  $capabilities

    The capabilities that current user posesses.