Documentation: shared/surfer.php

Class Surfer - What we know about the current surfer

This module uses cookies to control user login, logout, and access to protected resources.

When users enter this server and sign on, their related profile is saved into session data. This module is able to change and retrieve these data.

The security model is quite simple. The community as defined by this system is made of:

associates, that are allowed to do anything on the server
members, that may contribute to the content of the server and may access articles with restricted access.
subscribers, that may read and contribute to the public pages of the server
all other web surfers that may not be identified by the system

YACS saves the address of the surfer host, as reported by the network sub-system, in session data. This address is checked on each capability check (eg, Surfer::is_logged()) to prevent risks related to cookie steal.

During the login process the root path (e.g., /yacs/) is saved in session data. This session attribute is checked afterwards to evaluate actual surfer capability. Therefore, even if several YACS instances are installed at the same host, cross-authentication is blocked. For example, if you have two separate installations at /yacs/ and at /yacs_demo/, users authenticating as associates at the demo site would not be considered as being associates at the main instance.

On load, and if the surfer is not an associate, this script will strip any HTML tag from the $_REQUEST array. Note that special HTML characters encoded as Unicode numerical entities are correctly unmasked, to prevent related code injections. (Thanks to Mordread on this).

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com
Vincent Noël

Testeurs:

Mordread Wallas
Anatoly

Reste à faire:

adjust Surfer::is_logged and Surfer::get_id throughout the code

assigned_sections() - List sections assigned to this surfer

function assigned_sections($id=NULL, $maximum=21)

$id=NULL - int id of the surfer to consider
$maximum=21 - int maximum number of sections to return
returns array ids of managed sections

If a member is acting as a managing editor for some sections, this function returns ids of these sections.

For subscribers, this function will return the list of accessible sections.

build_user_menu() - Build the navigation menu for this surfer

function build_user_menu($type = 'submenu')

$type = 'submenu' - string the type of each link
returns a list of $url => array($prefix, $label, $suffix, $type) to be used with Skin::build_list()

This function has to be called from the template, once the skin has been loaded.

Voir aussi:

skins/skin_skeleton.php

check_default_editor() - Set default attributes for this surfer

function check_default_editor($fields)

$fields - array attributes to check
returns updated attributes

This function is called before writing records in the database, to ensure attributes 'edit_name', 'edit_id', 'edit_address' and 'edit_date' have been properly set.

Voir aussi:

from_GMT() - Adjust a time stamp to surfer time zone

function &from_GMT($stamp)

$stamp - string a time stamp in GMT zone
returns string a time stamp in surfer time zone

get_capability() - Get the capability of the current surfer, if known

function get_capability()

returns char either 'A', 'M', 'S' or '?'

get_editor() - Get the preferred editor

function get_editor($name='description', $value='')

$name='description' - string the name of the editing field
$value='' - string content to be put in the editor
returns string to be inserted in the XHTML flow

Provides XHTML snippet to invoke one of the available editors, based on user preference.

Curently YACS supports following choices:

'yacs' - the default, plain, code-based textarea
'fckeditor' - the WYSIWYG, open-source, Internet standard

Voir aussi:

FCKEditor

get_email_address() - Get the e-mail address of the current surfer, if known

function get_email_address()

returns string a valid address, or NULL

get_gmt_offset() - Get offset to GMT

function get_gmt_offset()

returns the number of hours (-12 ... +12)

Voir aussi:

skins/skin_skeleton.php

get_handle() - Get the handle of a managed page

function get_handle()

returns string target handle, or NULL

When an anonymous surfer provides the handle of a page, this is recorded in session data. This functions allows to retrieve this handle and then, to identify which resource the surfer may interact with.

get_id() - Get the id of the current surfer, if known

function get_id()

returns a positive integer or 0

get_name() - Get the name of the current surfer, if known

function get_name()

returns string user short name, or NULL

This function will remove mention of originating server for shadow records.

get_robot_stopper() - Ask surfer to replicate random data

function get_robot_stopper()

returns array to be inserted in the form, or NULL

This function complements a web form to stop anonymous robots.

If the global parameter 'users_without_robot_check' is set to 'Y', or if the surfer has been authenticated, this function returns NULL.

In every other cases, the function returns an array to be inserted in current form

Example of usage:

if($field = Surfer::get_robot_stopper())
    $fields[] = $field;

Data submitted through the form can be checked using function Surfer::may_be_a_robot().

is_associate() - Is the current user an associate?

function is_associate($capability='?')

$capability='?' - string specific capability, '?', 'M' or 'A'
returns true or false

The additional parameter allows for user empowerment on a per-transaction basis.

is_crawler() - Is the surfer a software robot?

function is_crawler()

returns TRUE or FALSE

is_creator() - Is the current surfer the creator of one item?

function is_creator($id)

$id - string the id of the original poster
returns true or false

To control that a surfer is the actual creator of one article, following code may be used:

// load the article from the database, including the editors list
$item =& Articles::get($id);

// check that the current surfer is a valid editor
include '../shared/surfer.php';
if(Surfer::is_creator($item['create_id']) {
  ...
}

is_editor() - Is the current surfer part of the editors list?

function is_editor($editors)

$editors - string the list of editor ids (e.g., '23, 45, 78, marc')
returns true or false

This function seeks the list to locate the id of the current surfer. The list is made of user ids separated by space or comma characters.

Members are allowed to alter the part of the server they are in charge of. For example, one associate can create a section or an article and designate some members as valid editors for this item. This is done explicitly by altering the 'editors' field in the related table.

To control that a surfer is a valid editor for one article, following code may be used:

// load the article from the database, including the editors list
$item =& Articles::get($id);

// check that the current surfer is a valid editor
include '../shared/surfer.php';
if(Surfer::is_editor($item['editors']) {
  ...
}

is_logged() - Has the current surfer been authenticated?

function is_logged()

returns true or false

is_member() - Is the current user a member?

function is_member($capability='?')

$capability='?' - string specific capability, '?', 'M' or 'A'
returns true or false

The additional parameter allows for user empowerment on a per-transaction basis.

may_be_a_robot() - Check salt and pepper

function may_be_a_robot()

returns FALSE if salt and pepper are equals, TRUE otherwise

This function helps to stop robots, by checking outcome of user challenge.

It has to be used in cuonjonction with Surfer::get_robot_stopper().

may_handle() - Back door to some resource

function may_handle($handle='', $item, $poster)

$handle='' - string the secret handle, if any
$item - array attributes of the target resource
$poster - array attributes of resource poster
returns TRUE or FALSE

This function checks the provided handle against the secret one, and either authenticate the surfer as resource poster, or only restore poster data in surfer session.

may_upload() - Check upload capability

function may_upload()

returns TRUE if the surfer is allowed to upload files, FALSE otherwise

This function checks surfer overall capability against the parameter users_without_uploads set in the configuration panel for users.

Voir aussi:

users/configure.php

reset() - Kill the current session

function reset()

Voir aussi:

PHP: session_destroy

set() - Save user information as session data

function set($fields, $offset=0)

$fields - array session attributes
$offset=0 - int offset to GMT, if any

This function copies user attributes in session storage area.

Following named attributes from the provided array are copied in session storage area:

$fields['id'] - id of the logged surfer
$fields['nick_name'] - nick name of the logged surfer
$fields['email'] - email address
$fields['editor'] - preferred on-line editor
$fields['capability'] - 'A'ssociate or 'M'ember

We also remember the IP address of the authenticating workstation, and the root path of the instance that has validated the surfer.

track() - Remember surfer data

function track($fields)

$fields - array session attributes

This function is used to track anonymous surfers.

Following named attributes from the provided array are copied in session storage area:

$fields['edit_name'] - nick name of the logged surfer
$fields['edit_address'] - email address
$fields['handle'] - handle of one object that the surfer may manage

strip_tags() - Strip all HTML tags

function strip_tags($input, $allowed_tags='')

$input - a string or an array
$allowed_tags='' - string of allowed tags, if any
returns a clean string or array

Voir aussi:

Unicode 1.1

to_GMT() - Adjust a time stamp to GMT

function &to_GMT($stamp)

$stamp - string a time stamp in surfer time zone
returns string a time stamp in GMT zone