Documentation: users/users.php

Class Users - The database abstraction layer for users

YACS has been designed to address needs of small to mid-size communities. The idea behind this concept is that addressing security concerns is becoming complex on a large scale. In order to avoid this complexity, and related management overhead, we have selected to base YACS on a very small set of user profiles:

* associates - These users are the webmasters of the community. In YACS, all associates are considered as being equivalent. Therefore, associates have to trust each other to operate the community smoothly. One consequence of this equivalence is that the number of associates should be kept as small as possible, otherwise your system may be in trouble.

* member - These users are interested into your community. They have extended reading access rights. With YACS, they are able to submit new articles, to post images, to upload files, and to share on interesting links.

* subscriber - They are coming to your server on a more or less regular basis. Some of them are only interested into receiving information through e-mail messages. At YACS, authenticated subscribers are allowed to submit new articles, to post images, to upload files, and to share on interesting links.

* anonymous - All other people on earth (more precisely, most of them) are consider as honest readers of public information shared by a YACS community.

These profiles, while simple, may support different community patterns.

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

Reste à faire:

include interests in full-text search

authenticate() - Authenticate using network credentials

function authenticate()

returns array one user record matching credentials, or NULL

For authentication on protected page this function use basic HTTP authentication, as described in RFC2617.

On some Apache servers PHP is running as CGI, meaning that Apache variables $_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'] are empty, and the credentials are not transmitted to the function.

In this case you can try to modify the .htaccess file and add following text:

<IfModule mod_rewrite.c>
	RewriteEngine on
	RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization},L]
</IfModule>

This directive states, if mod_rewrite is available, that credentials get from the HTTP header Authorization are put into the $_SERVER['REMOTE_USER'] variable.

From there you can decode base64 credentials, and split the string to retrieve user name and password, as explained from RFC2617 on HTTP Authentication.

This function does exactly that. If $_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'] are empty, it attempts to rebuild them by using $_SERVER['REMOTE_USER']. Of course, this works only if the mod_rewrite module is available, and if you have changed the file .htaccess as explained above.

Voir aussi:

HTTP Authentication: Basic and Digest Access Authentication

delete() - Delete one user

function delete($id)

$id - the id of the user to delete
returns an error message, if any

Voir aussi:

users/delete.php

get() - Get one user by id

function &get($id)

$id - int the id of the user
returns the resulting $item array, with at least keys: 'id', 'full_name', 'description', etc.

Actually this function locate one user profile by looking at: id, nick name, email address, and profile handle.

Voir aussi:

get_link() - Build a pretty link to a user page

function get_link($name, $email, $id)

$name - the user name, or the server title
$email - the email address, maybe null, or a web address
$id - the user id, maybe null
returns a pretty link to insert in the HTML page

YACS has been designed to track people who submit or change information, and this small function is aiming to shape tracking data.

Most of the time it will build a nice link to the user profile of the involved community member. At other time it will link to the external server that has provided published information.

Pseudo code:

If there is a user profile for this id
 return a link to the related page
else if the user is not logged and if email addresses have to be protected
 return the name string without any link (protected from spam)
else if a web address has been provided
 return a http: link to it
else if an email address has been provided
 return a mailto: link to it
else
 return the name string without any link

Voir aussi:

feeds/feeds.php

get_options() - Get users as options of a <SELECT> field

function get_options($anchor)

$anchor - string a valid anchor to an existing user (e.g., 'user:12')
returns the HTML to insert in the page

get_url() - Get the url to view a user

function get_url($id, $action='view')

$id - int the id of the user profile to view
$action='view' - string the expected action ('view', 'print', 'edit', 'delete', ...)
returns an anchor to the viewing script

By default, a relative URL will be provided (e.g. 'users/view.php?id=512'), which may be not processed correctly by search engines. If the parameter 'with_friendly_urls' has been set to 'Y' in the configuration panel, this function will return an URL parsable by search engines (e.g. 'users/view.php/512').

Voir aussi:

control/configure.php

click() - Stamp last click

function click()

This function is used to track present surfers. Errors are not reported, if any

increment_posts() - Increment the posts counter - errors are not reported, if any

function increment_posts($id)

$id - the id of the user to update

This function increment the number of posts, and record the date of the last post

Voir aussi:

check_presence() - Check is the user is currently on-line

function check_presence($id, $variant='web')

$id - the id of the user to update
$variant='web' - the presence variant, if any

list_associates_by_posts() - List associates

function &list_associates_by_posts($offset=0, $count=10, $variant='compact')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='compact' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Note that compared to list_by_posts(), this function lists all associates, even those who haven't subscribed to newsletters.

Example:

include_once 'users/users.php';
$items = Users::list_associates_by_posts(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

Voir aussi:

letters/new.php

list_by_date() - List newest members

function &list_by_date($offset=0, $count=10, $variant='compact')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='compact' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The list is ordered by creation date rather than by edition date to better reflect the 'oldiness' of members.

Example:

include_once 'users/users.php';
$items = Users::list_by_date(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

You can also display the newest user separately, using Users::get_newest() In this case, skip the very first user in the list by using Users::list_by_date(1, 10)

Voir aussi:

list_by_login_date() - List inactive members

function &list_by_login_date($offset=0, $count=10, $variant='dates')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='dates' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The list is ordered by login date.

Voir aussi:

users/review.php

list_by_name() - List users by name

function &list_by_name($offset=0, $count=10, $variant='full')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='full' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

To build a simple box of the users in your main index page, just use Users::list_by_name(0, 10)

list_by_post_date() - List inactive members

function &list_by_post_date($offset=0, $count=10, $variant='dates')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='dates' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The list is ordered by post date.

Voir aussi:

users/review.php

list_by_posts() - List most contributing users

function &list_by_posts($offset=0, $count=10, $variant='compact')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='compact' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Profiles are sorted by decreasing number of posts and decreasing edition dates

Example:

include_once 'users/users.php';
$items = Users::list_by_posts(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

Only users matching following criteria are returned:

user is visible (active='Y')
user is restricted (active='R'), but surfer is a logged member
user is restricted (active='N'), but surfer is an associate

If the variant is 'mail', then users who have not subscribed explicitly to newsletters won't be listed.

Voir aussi:

list_members_by_posts() - List members

function &list_members_by_posts($offset=0, $count=10, $variant='compact')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='compact' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Example:

include_once 'users/users.php';
$items = Users::list_members_by_posts(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

If the variant is 'mail', then users who have not subscribed explicitly to newsletters won't be listed.

Voir aussi:

letters/new.php

list_present() - List present members

function &list_present($offset=0, $count=10, $variant='compact')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='compact' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The list is ordered by date of last click, and is limited to users that have clicked during the last 15 minutes.

Voir aussi:

users/index.php

list_selected() - List selected users

function &list_selected(&$result, $layout='compact', $capability='?')

&$result - resource result of database query
$layout='compact' - string 'full', etc or object, i.e., an instance of Layout_Interface
$capability='?' - string '?' or 'A', to support editors and to impersonate associates, where applicable
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Accept following variants:

'raw'
'compact'
'email' to build list of recipients

login() - Login

function login($name, $password)

$name - string the nickname or the email address of the user
$password - string the submitted password
returns the record of the authenticated surfer, or NULL

The script checks provided name and password against the local database.

If no record matches, and if the provided name explicitly mentions some origin server (e.g., 'john@foo.bar'), then this server is asked to authenticate the user. This is done by transmitting the user name and the password to the origin server, through a XML-RPC call (drupal.login at services/xml_rpc.php). On success the origin server will provide the original id for the user profile. Else a null id will be returned.

On successful remote authentication the surfer will be considered as logged, either as a member (default case), or as a subscriber (for closed communities).

On successful remote authentication a 'shadow' user profile will be created locally, using another id, and a copy of the authentication url saved in the password field. Also the user description explicitly references the original user profile. This local record may be referenced in pages published locally.

This means that on subsequent visits the 'shadow' profile will be retrieved, and the origin server will be sollicitated again for credentials validation. As a consequence the validity of login data is always checked by the server that actually stores the original user profile. If the user profile is modified or is deleted this change will be taken into account on next login.

This script also allows for a last resort password. When a webmaster has lost his password, and if there is no other associate to help, he can modify manually the file shared/parameters.include.php to add a parameter $context['last_resort_password'], followed by a long passphrase of at least seven characters. For example:

$context['last_resort_password'] = 'a quite long passphrase, to be used 1 time';

Then he can authenticate normally, using this password, and any name.

Voir aussi:

lookup() - Get the id of one user knowing his/her nick name

function lookup($nick_name)

$nick_name - string the nick name looked for
returns string either 'user:<id>', or NULL

mail_to_watchers() - Post an electronic message to watchers of one article

function mail_to_watchers($target, $poster, $subject, $message)

$target - string reference to the watched object (e.g., 'article:123')
$poster - string poster mail address
$subject - string title
$message - string the message itself
returns string either a null string, or some text describing an error to be inserted into the html response

This script sends one mail message to each watcher, except to the article initial poster, and except to the current surfer.

Voir aussi:

articles/articles.php

post() - Post a new user profile

function post($fields)

$fields - array an array of fields
returns the id of the new article, or FALSE on error

Voir aussi:

put() - Put an updated user profile in the database

function put($fields, $user=NULL)

$fields - array an array of fields
$user=NULL - array previous values of this record, if any
returns string either a null string, or some text describing an error to be inserted into the html response

If present, only the password is changed. Or other fields except the password are modified.

To change a password, set fields 'id', 'password' and 'confirm'

Voir aussi:

search() - Search for some keywords in all users

function &search($pattern, $offset=0, $count=10, $variant='search')

$pattern - the search string
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='search' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Voir aussi: