PrivateContent Plugin

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_fieldsarray of database columns. Useful to detect extra fields and metas
(string) $validation_errorsstatic resource for methods using validator - contains HTML code with errors
(string) $wp_sync_errorstatic resource for WP sync errors printing - contains a string
(int) [protected] $user_idstatic 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:

keyvaluedefault
(int/array) user_idspecific user ID or IDs array to fetch (by default queries every user)false
(int) limitquery limit (related to users) - default 100 (use -1 to fetch any)100
(int) offsetquery offset (related to users)0
(int/bool) statususer status (1 = active / 2 = disabled / 3 = pending) - by default uses false to fetch anyfalse
(int/array) categoriesPrivateContent user category IDsfalse
(array) to_getusers data to fetch. Could be a fixed field or a meta key - by default is everythingarray()
(string) orderbyhow to sort query results - Could be a fixed field or a meta keyid
(string) ordersorting method (ASC / DESC)ASC
(array) searcharray of associative arrays('key'=>$field_key, 'operator'=>'=', 'val'=>$value) queried users must match.
Supported operators (=, !=, >, <, >=, <=, IN, NOT IN, LIKE)
array
(string) custom_searchcustom WHERE parameters to customize the search. Is added to the dynamically created codefalse
(string) search_operatoroperator to use for merging conditions (AND / OR)AND
(bool) countif true returns only query rows countfalse
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) $catsuser 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_iduser ID to match
(array) $argsget_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_iduser ID to match
(string) $fieldfield 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) $indexindex relative to the value stored in database (could be a fixed field or a meta key)
(mixed) $datafetched data related to the index
(bool) $ignore_dateswhether 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) $dataregistration data - see table below to know more
(int) $statusnew user's status (1=active, 2=disabled, 3=pending)
(bool) $allow_wp_sync_failwhether 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).

keynotes
(string) nameuser's name - max length 150 characters
(string) surnameuser's surname - max length 150 characters
(string) (mandatory) usernameuser's username - max length 150 characters
(string) teluser's telephone - max length 20 characters
(string) emailuser's email. Must be a valid e-mail with max length of 255 characters.
If WP-sync enabled is mandatory
(string) (mandatory) pswuser's password
(int) disable_pvt_page0 to enable user's private page, 1 to disable
(array) (mandatory) categoriesuser 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'		=> '[email protected]',
    'psw'       => 'myPassw0rd&',
	'categories'=> array(2,4)
);
$result = $pc_users->insert_user($data, 3, true);

if(!$result) {
	// an error occurred - check related properties	
    var_dump($pc_users->validation_errors, $pc_users->wp_sync_error);
}
else {
	// user successfully created and placed 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_iduser ID to update
(array) $dataUser 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'		=> '[email protected]',
	'surname' 	=> 'testing'
);
$result = $pc_users->update_user(5, $data);

if(!$result) {
	// an error occurred
    var_dump($pc_users->validation_errors);
} 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_iduser 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_iduser 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) $emailemail to check
(int) $user_idUser 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) $usernamethe 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_idthe 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) $subjvariable used to target anuser via id or username
Return Values
(int)the user id or zero

Let's get in touch!

Features list