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.
PrivateContent
API Documentation
Users Management class
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 | multidimesional array of associative array, inspired by WP_query tax_query format. - Each search block is joint with AND condition - supported operators (=, !=, >, <, >=, <=, IN, NOT IN, LIKE, NOT LIKE) Structure example:
array(
array(
'relation' => 'AND', // AND or OR
array('key'=>$field_key, 'operator'=>'=', 'val'=>$value),
array('key'=>$field_key, 'operator'=>'=', 'val'=>$value)
)
) | array |
| (string) custom_search | custom WHERE parameters to customize the search. Is added to the dynamically created code | false |
| (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 and username containing 'andrew' - 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(
'relation' => 'AND',
array('key' => 'email', 'operator' => '!=', 'val' => ''),
array('key' => 'username', 'operator' => 'LIKE', 'val' => '%andrew%'),
)
)
);
$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 |
| (int) disable_pvt_page | 0 to enable user's private page, 1 to disable |
| (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
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_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 |
|---|
