Documentation

GetList

CDBResult CUser::GetList(
 mixed &by = "timestamp_x",
string &order = "desc",
array filter = array(),
array arParams=array() )

The method returns a list of users as the CDBResult class object. Static method.

Parameters

ParameterDescription Available fr om version
byReference to the variable with the name of the sorting field. Can have the following values:
  • id - user ID
  • active - user is active
  • last_login - last authorization date
  • login - login name
  • email - e-mail address
  • name - name
  • ntopcount - page wise navigation parameter; limits the number of returned elements
  • last_name - last name
  • timestamp_x - modification date
  • date_register - registration date
  • personal_profession - position
  • personal_www - web page
  • personal_icq - ICQ number
  • personal_gender - gender ("M" - male; "F" - female)
  • personal_birthday - date of birth
  • personal_photo - ID of the photo image
  • personal_phone - phone number
  • personal_fax - fax number
  • personal_mobile - mobile number
  • personal_pager - pager number
  • personal_street - street
  • personal_mailbox - mailbox
  • personal_city - city
  • personal_state - state or region
  • personal_zip - zip code
  • personal_country - country code
  • personal_notes - additional notes
  • work_company - company name
  • work_department - department
  • work_position - position
  • work_www - company web site
  • work_phone - wok phone
  • work_fax - work fax
  • work_pager - work pager number
  • work_street - company street
  • work_mailbox - company mailbox
  • work_city - company city
  • work_state - company state or region
  • work_zip - company zip code.
  • work_country - company country code.
  • work_profile - company profile
  • work_notes - additional notes comments.
  • admin_notes - administrator comments

Starting fr om kernel version 11.0.13 the array type ("field1"=>"asc", "field2"=>"desc") can be passed in the parameter for multiple sorting. Array keys' values are matching with the listed above.

Đ¾rderReference to the variable containing the sort order; can have the following values:
  • asc - by ascension
  • desc - by descension

When using the array in the by parameter, this parameter is ignored. The values with nulls do not work, for example: desc,nulls.

filterAn array used by the method to filter users. The following entry names are possible:
  • 1ID - by user ID;
  • XML_ID - by user XML_ID;
  • TIMESTAMP_1 - lower bound of the modification date range (""from"");
  • TIMESTAMP_2 - upper bound of the modification date range (""to"");
  • LAST_LOGIN_1 - lower bound of the last login date range (""from"");
  • LAST_LOGIN_2 - upper bound of the last login date range (""to"");
  • LAST_ACTIVITY - last activity interval in seconds;
  • ACTIVE - active state flag (Y|N);
  • 1LOGIN_EQUAL - login (strict match);
  • 1LOGIN - login (loose match - substring);
  • 1NAME - first and last names;
  • 1EMAIL - e-mail address;
  • 1COUNTRY_ID - country ID. It is used for backward compatibility. Presently, filtering by WORK_COUNTRY is performed when this parameter is used;
  • GROUPS_ID - by groups (array of user group ID's);
  • PERSONAL_BIRTHDAY_1 - lower bound of the birth date range (""from"");
  • PERSONAL_BIRTHDAY_2 - upper bound of the birth date range (""to"");
  • 1KEYWORDS - by the following fields (marked with *);
  • 1* PERSONAL_PROFESSION - position;
  • 1* PERSONAL_WWW - web site;
  • 1* PERSONAL_ICQ - ICQ number;
  • 1* PERSONAL_GENDER - gender ("M" - male; "F" - female);
  • 1* PERSONAL_PHOTO - ID of the photo image (table b_file);
  • 1* PERSONAL_PHONE - phone number;
  • 1* PERSONAL_FAX - fax number;
  • 1* PERSONAL_MOBILE - mobile number;
  • 1* PERSONAL_PAGER - pager number;
  • 1* PERSONAL_STREET - street;
  • 1* PERSONAL_MAILBOX - mailbox;
  • 1* PERSONAL_CITY - city;
  • 1* PERSONAL_STATE - state or region;
  • 1* PERSONAL_ZIP - zip code;
  • 1* PERSONAL_COUNTRY - country code (stored in the files \bitrix\modules\main\lang\en\tools.php, \bitrix\modules\main\lang\en\tools.php)
  • 1* PERSONAL_NOTES - additional notes
  • 1* WORK_COMPANY - company name
  • 1* WORK_DEPARTMENT - department
  • 1* WORK_POSITION - position
  • 1* WORK_WWW - company web site
  • 1* WORK_PHONE - work phone
  • 1* WORK_FAX - work fax
  • 1* WORK_PAGER - work pager
  • 1* WORK_STREET - company street
  • 1* WORK_MAILBOX - company mailbox
  • 1* WORK_CITY - company city
  • 1* WORK_STATE - company state or region
  • 1* WORK_ZIP - company zip code
  • 1* WORK_COUNTRY - company country code (stored in files \bitrix\modules\main\lang\en\tools.php, \bitrix\modules\main\lang\en\tools.php)
  • 1* WORK_PROFILE - company profile
  • 1* WORK_NOTES - additional comments on company
  • 1* ADMIN_NOTES - administrator comments (available for viewing and editing for the site administrator only).
1 - those fields allow for complex logic. Complex conditions for this field are applied only if the following is specified: ID. When the !ID and >ID are specified, complex conditions will not be operational.
* - search by "KEYWORDS" is in fact search by fields marked with "*"
arParametersArray with additional method parameters. Can contain the following keys:

SELECT - array with user fields IDs for selection specified in the result, for example array("UF_TEXT_1", "UF_STRUCTURE"). To specify the selection fr om all fields, use the the following mask: array("UF_*").

NAV_PARAMS - array with navigation parameters; can be used to limit the selection size. For example: array("nPageSize"=>"20"). When specifying NAV_PARAMS, list of results is generated with size lim it. This list includes page number within page wise navigation (for mysql the selection is performed with the lim it specified). In the kernel version 11.0.14, the "nTopCount" parameter can be specified in the array to lim it selection by the number of entries.

FIELDS (from the kernel version 11.0.13) - array with field IDs for the selection. If it is not specified or empty, then all fields are selected. Possible values:

ID PERSONAL_WWW PERSONAL_ZIP IS_ONLINE
ACTIVE PERSONAL_ICQ PERSONAL_COUNTRY WORK_CITY
LAST_LOGIN PERSONAL_GENDER PERSONAL_NOTES WORK_STATE
LOGIN PERSONAL_PHOTO WORK_COMPANY WORK_ZIP
EMAIL PERSONAL_PHONE WORK_DEPARTMENT WORK_COUNTRY
NAME PERSONAL_FAX WORK_POSITION WORK_PROFILE
LAST_NAME PERSONAL_MOBILE WORK_WWW WORK_NOTES
SECOND_NAME PERSONAL_PAGER WORK_PHONE ADMIN_NOTES
TIMESTAMP_X PERSONAL_STREET WORK_FAX XML_ID
PERSONAL_BIRTHDAY PERSONAL_MAILBOX WORK_PAGER PASSWORD
DATE_REGISTER PERSONAL_CITY WORK_STREET LOGIN_ATTEMPTS
PERSONAL_PROFESSION PERSONAL_STATE WORK_MAILBOX STORED_HASH
CHECKWORD_TIME EXTERNAL_AUTH_ID CONFIRM_CODE TITLE
LAST_ACTIVITY_DATE AUTO_TIME_ZONE TIME_ZONE LID
CHECKWORD

See Also

Examples of use

<?
$filter = Array
(
"ID" => "1 | 2",
"TIMESTAMP_1" => "04.02.2004", // in the current site format
"TIMESTAMP_2" => "04.02.2005",
"LAST_LOGIN_1" => "01.02.2004",
"ACTIVE" => "Y",
"LOGIN" => "nessy | admin",
"NAME" => "John & Harrington",
"EMAIL" => "mail@server.com | mail@server.com",
"KEYWORDS" => "www.bitrix24.com",
"PERSONAL_PROFESSION" => "system engineer",
"PERSONAL_GENDER" => "M",
"PERSONAL_COUNTRY" => "4 | 1", // US or UK
"ADMIN_NOTES" => "\"UID = 145\"",
"GROUPS_ID" => Array(1,4,10)
);
$rsUsers = CUser::GetList(($by="personal_country"), ($order="desc"), $filter); // select users
$is_filtered = $rsUsers->is_filtered; // is selection filtered ?
$rsUsers->NavStart(50); // paginate by 50 records
echo $rsUsers->NavPrint(GetMessage("PAGES")); // display paginated output
while($rsUsers->NavNext(true, "f_")) :
echo "[".$f_ID."] (".$f_LOGIN.") ".$f_NAME." ".$f_LAST_NAME."<br>";
endwhile;
?>

Example Non-operational call, because doth parameters are passed via the value:

$rsUsers = CUser::GetList(array('sort' => 'asc'), 'sort');

Example of operational call:

$order = array('sort' => 'asc');
$tmp = 'sort'; // parameter will be ignored by the method, but it must be 
$rsUsers = CUser::GetList($order, $tmp);

To filter users with unfilled "City" field (for other text fields - similarly):

$filter = array("PERSONAL_CITY" => " ~_% ");


© «Bitrix24», 2001-2022
Up