PrivateContent

API Documentation

Users Management class

Introduction

PHP class used to manage users: search, insertion, editing, deletion.
Is instantiated in website and reachable through php global pc_users.

Located in classes folder.

Properties
(array) $fixed_fields array of database columns. Useful to detect extra fields and metas
(string) $validation_errors static resource for methods using validator - contains HTML code with errors
(string) $wp_sync_error static resource for WP sync errors printing - contains a string
(int) [protected] $user_id static resource storing currently managed user ID for sequential operations
(bool) $wp_user_sync; flag to understand if wp-user-sync is enabled
get_users()

Method used to perform searches in users database to retrieve basic data and/or meta-data or simply to count results

Usage
get_users($args = array())
Parameters

Only one parameter containing an associative array of data.

When nothing is specified, first 100 users - id sorted - are searched. Search retrieves basic data + all metas.
Is a quite big query to perform depending on your database. Try to be as specific as possible.

$args associative array keys => values:

key value default
(int/array) user_id specific user ID or IDs array to fetch (by default queries every user) false
(int) limit query limit (related to users) - default 100 (use -1 to fetch any) 100
(int) offset query offset (related to users) 0
(int/bool) status user status (1 = active / 2 = disabled / 3 = pending) - by default uses false to fetch any false
(int/array) categories PrivateContent user category IDs false
(array) to_get users data to fetch. Could be a fixed field or a meta key - by default is everything array()
(string) orderby how to sort query results - Could be a fixed field or a meta key id
(string) order sorting method (ASC / DESC) ASC
(array) search array of associative arrays('key'=>$field_key, 'operator'=>'=', 'val'=>$value) queried users must match.
Supported operators (=, !=, >, <, >=, <=, IN, NOT IN, LIKE)
array
(string) custom_search custom WHERE parameters to customize the search. Is added to the dynamically created code false
(string) search_operator operator to use for merging conditions (AND / OR) AND
(bool) count if true returns only query rows count false
Return Values
(array) array of associative arrays (key => val) containing matched users and queried data (id is always included)
(int) query row count - only if count parameter is set to true
Example
<?php
// search first 4 active users with an e-mail - getting only few data - and print them 
global $pc_users;
$args = array(
	'limit' 	=> 4,
	'status' 	=> 1,
	'to_get'	=> array('name', 'username', 'email'),
	'search'	=> array(
		array('key' => 'email', 'operator' => '!=', 'val' => '')
	)
);
$users = $pc_users->get_users($args);

if(empty($users)) {
	// no users found	
}
else {
	foreach($users as $u) {
		echo '

'. $u['id'] .'

'; echo '

'. $u['name'] .'

'; echo '

'. $u['username'] .'

'; echo '

'. $u['email'] .'

'; } } ?>
categories_query()

Method used to create query part to search for user categories

Usage
categories_query($cats)
Parameters
(array) $cats user categories ID array
Return Values
(string) WHERE condition part related to these categories
get_user()

Method used to get a specific user's data

Usage
get_user($user_id, $args = array())
Parameters
(int) $user_id user ID to match
(array) $args get_users query args (except user_id index)
Return Values
(bool/array) false if user is not found otherwise associative data array for the user
Example
<?php
// get only few data for user = 5 and print them 
global $pc_users;
$args = array(
	'to_get'	=> array('name', 'username', 'email'),
);
$user = $pc_users->get_user(5, $args);


echo '

'. $user['name'] .'

'; echo '

'. $user['username'] .'

'; echo '

'. $user['email'] .'

'; ?>
get_user_field()

Method used to get a specific user's field

Usage
get_user_field($user_id, $field)
Parameters
(int) $user_id user ID to match
(string) $field field name to retreve - could be basic data or meta data
Return Values
(bool/mixed) false if user is not found otherwise the field value
Example
<?php
// get username for user ID = 5 
global $pc_users;
$username = $pc_users->get_user_field(5, 'username');
?>
data_to_human()

Method used to print fetched data. Get user category names, implodes arrays, renders dates and single-option checks.

Usage
data_to_human($index, $data, $ignore_dates = false)
Parameters
(string) $index index relative to the value stored in database (could be a fixed field or a meta key)
(mixed) $data fetched data related to the index
(bool) $ignore_dates whether to ignore insert and registration dates
Return Values
(string) value string ready to be printed
Example
<?php
// print user categories
global $pc_users;

$cats = $pc_users->get_user_field(5, 'categories');
echo 'Categories: '. $pc_users->data_to_human('categories', $cats);
?>
insert_user()

Method used to insert a user into PrivateContent database.
Performs also data validation on passed values as specified in registered PrivateContent fields.
Eventually performs also meta-data insertion.

Usage
insert_user($data, $status = 1, $allow_wp_sync_fail = false)
Parameters
(array) $data registration data - see table below to know more
(int) $status new user's status (1=active, 2=disabled, 3=pending)
(bool) $allow_wp_sync_fail whether to allow registration also if WP user sync fails

$data is an associative array, containing user's fixed data and meta data.
The function already performs validation. Here are specifications (pay attention to mandatory ones).

key notes
(string) name user's name - max length 150 characters
(string) surname user's surname - max length 150 characters
(string) (mandatory) username user's username - max length 150 characters
(string) tel user's telephone - max length 20 characters
(string) email user's email. Must be a valid e-mail with max length of 255 characters.
If WP-sync enabled is mandatory
(string) (mandatory) psw user's password
(bool) disable_pvt_page user's password
(bool) disable_pvt_page flag to disable user's private page - by default is 0 (page enabled)
(array) (mandatory) categories user categories. Use IDs
Return Values
(int) newly inserted user ID
(bool) false if problems are found
(and you should check $validation_errors and $wp_sync_error properties)
Example
<?php
// insert a new user checking the answer
global $pc_users;
$data = array(
	'name' 		=> 'test',
	'username' 	=> 'lcweb',
	'email'		=> 'test@lcweb.it',
	'categories'=> array(2,4)
);
$result = $pc_users->insert_user($data, 3, true);

if(!$result) {
	// an error occurred - check related properties	
}
else {
	// user successfully created and put in pending status	
}
?>
update_user()

Method used to update a user into PrivateContent database.
Performs also data validation on passed values as specified in registered PrivateContent fields.
Eventually performs also meta data update.

Usage
update_user($user_id, $data)
Parameters
(int) $user_id user ID to update
(array) $data User data. Associative array containing fixed fields and meta data. Check insert_user to know more.
Plus, you can use status key
Return Values
(bool) true is successfully updated otherwise false
Example
<?php
// update user 5 - setting new email and surname
global $pc_users;
$data = array(
	'email'		=> 'test2@lcweb.it',
	'surname' 	=> 'testing'
);
$result = $pc_users->update_user(5, $data);

if(!$result) {
	// an error occurred - check related properties	
} else {
	// user successfully updated
}
?>
change_status()

Method used to update status for oe or more users

Usage
change_status($users_id, $new_status)
Parameters
(int/array) $user_id user ID to update or array of user IDs
(int) $new_status/th>

new status (1 = active / 2 = disabled / 3 = pending)
Return Values
(int) number of users with changed status (zero could mean user already had that status)
Example
<?php
// set two users in disabled status
global $pc_users;
$pc_users->change_status(array(5, 6), 2);
?>
delete_user()

Method used to delete a user.
Totally remove user and its meta data + private page content + eventual WP user sync

Usage
delete_user($user_id)
Parameters
(int) $user_id user ID to remove
Return Values
(bool) true if user has been deleted otherwise false
Example
<?php
// delete user #5
global $pc_users;

if($pc_users->delete_user(5)) {
	// user successfully deleted
}
?>
user_mail_exists()

Method used to check if an e-mail is already in database. Useful to avoid doubled values.

Usage
user_mail_exists($email, $user_id = false)
Parameters
(string) $email email to check
(int) $user_id User ID to exclude from query (useful to update user's email)
Return Values
(int) user ID having same e-mail
(bool) true is unique
encrypt_psw()

Documentation in progress ..

username_to_id()

Method used to get user ID from username.

Usage
username_to_id($username)
Parameters
(int) $username the user username
Return Values
(int) matched user ID
(bool) false if user not found
id_to_username()

Method used to get user username from ID.

Usage
id_to_username($user_id)
Parameters
(int) $user_id the user ID
Return Values
(string) matched user username
(bool) false if user not found
check_user_id()

Method used to check a user ID ans be sure it exists in database.
This is a protected method. Use only in class extensions.

Usage
check_user_id($subj)
Parameters
(int/string) $subj variable used to target anuser via id or username
Return Values
(int) the user id or zero