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
| Parameter | Description | Available fr om version |
|---|
| by | Reference 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.
| |
| оrder | Reference 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.
| |
| filter | An 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 "*" | |
| arParameters | Array 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" => " ~_% ");