CIBlockElement::GetList

CIBlockResult
CIBlockElement::GetList(
 array arOrder = Array("SORT"=>"ASC"),
 array arFilter = Array(),
 mixed arGroupBy = false,
 mixed arNavStartParams = false,
 array arSelectFields = Array()
);

Returns a list of elements filtered by arFilter.

Parameters

Parameter	Description
arOrder	Optional sort order. Array of the format Array(by1=>order1[, by2=>order2 [, ..]]) where by is the field for sorting. The field can have the following values: id - element ID; sort - sort index; timestamp_x - modification date; name - name; active_from or date_active_from - date an element is active from; active_to or date_active_to - date an element is active till; status - workflow status of an element; code - element mnemonic code; iblock_id - information block ID; modified_by - ID of the last user who modified an element; active - element is active; show_counter - number of the element shows (counted by CounterInc); show_counter_start - time of the first show (counted by CounterInc); shows - average shows (shows / show duration); rand - random order; xml_id or external_id – the external ID; tags – specifies the item tags; created – by the creation time; created_date – by the date the item was created (without time); cnt – by the number of items (if using the grouping only); property_<PROPERTY_CODE> - by value of the property identified by the PROPERTY_CODE (e.g. PROPERTY_123 or PROPERTY_NEWS_SOURCE) propertysort_<PROPERTY_CODE> - by the sort index of a property variant. This key is for the list properties only; catalog_<CATALOG_FIELD>_<PRICE_TYPE> - by the field CATALOG_FIELD (can be PRICE or CURRENCY) of price of the type PRICE_TYPE (e.g. catalog_PRICE_1 or CATALOG_CURRENCY_3); PROPERTY_<PROPERTY_CODE>.<FIELD> - by the value of an element binding field. PROPERTY_CODE is a mnemonic or symbolic code of a "link to element" property. FIELD can be one of the following: ID TIMESTAMP_X MODIFIED_BY CREATED CREATED_DATE CREATED_BY IBLOCK_ID ACTIVE ACTIVE_FROM ACTIVE_TO SORT NAME SHOW_COUNTER SHOW_COUNTER_START CODE TAGS XML_ID STATUS PROPERTY_<PROPERTY_CODE>.PROPERTY_<PROPERTY_CODE2> - by the value of an element binding property. PROPERTY_CODE is a mnemonic or symbolic code of a "link to element" property. PROPERTY_CODE2 is the property code of the bound elements. HAS_PREVIEW_PICTURE and HAS_DETAIL_PICTURE – by the availability or absence of images. order – by the element sort order: asc - ascending; nulls,asc - ascending, put empty values at the beginning; asc,nulls - ascending, put empty values at the end; desc - descending; nulls,desc - descending, put empty values at the beginning; desc,nulls - descending, put empty values at the end; This key is optional. The default value is Array("sort"=>"asc")
arFilter	An array of the format Array("filter field"=>"filter value" [, ...]) where the "filtering field" can be the following: ID - by the identifier; ACTIVE - by the active state (Y\|N); passing an empty value ("ACTIVE"=>"") causes the method to return all elements disregarding their state; NAME - by name (wildcards [%_] allowed); CODE - by the mnemonic code (wildcards [%_] allowed); TAGS – by tags; XML_ID or EXTERNAL_ID - by the external ID (wildcards [%_] allowed); PREVIEW_TEXT - by the brief text (wildcards [%_] allowed); PREVIEW_TEXT_TYPE - by the brief text type (html\|text); PREVIEW_PICTURE - by the code of a preamble image; DETAIL_TEXT - by the detailed text (wildcards [%_] allowed); DETAIL_TEXT_TYPE - by the detailed text type (html\|text); DETAIL_PICTURE - by the code of a large image; CHECK_PERMISSIONS - if "Y", the selection will respect the permissions to access the information blocks. By default, the permissions are not checked. MIN_PERMISSION - minimum allowed access permission. Effective if only CHECK_PERMISSIONS is "Y". Default is "R". For the full list of access permissions, see CIBlock::SetPermission. SEARCHABLE_CONTENT - by the all available searchable content. Includes title, brief and detailed description text (wildcards [%_] allowed); SORT - by the sort weight; TIMESTAMP_X - by modification date (wildcards [%_] allowed); DATE_MODIFY_FROM – by the date/time the required elements was modified. Use this key to fetch elements modified after the time specified here in the website format. A NOT operator is possible: "!DATE_MODIFY_FROM"; DATE_MODIFY_TO - by the date/time the required elements was modified. Use this key to fetch elements modified prior the time specified here in the website format. A NOT operator is possible: "!DATE_MODIFY_TO"; MODIFIED_USER_ID or MODIFIED_BY- by the code of a user who modified an element; DATE_CREATE - by creation date; CREATED_USER_ID or CREATED_BY - by the code of a user who created an element; DATE_ACTIVE_FROM - by the date an element is active from. The date must be in the website format; DATE_ACTIVE_TO - by the date until which an element is active. The date must be in the website format; ACTIVE_DATE - a non-empty value enables sorting by fields DATE_ACTIVE_FROM and DATE_ACTIVE_TO. If the value is empty (""), no filtering is performed; IBLOCK_ID - by the information block ID; IBLOCK_CODE - by the information block mnemonic code (wildcards [%_] allowed); IBLOCK_SITE_ID or IBLOCK_LID or SITE_ID or LID - by site; IBLOCK_TYPE - by the information block type (wildcards [%_] allowed); IBLOCK_ACTIVE - by the information block active state (Y\|N); SECTION_ID - by the parent section. If the SECTION_ID key is false, an empty string "" or zero (0), only the orphan elements without parent sections will be returned. Otherwise, the method returns the elements of the specified section ID. The SECTION_ID key may be an array, in which case the method will return elements of at least one of the specified sections. A NOT operator ("!") is possible, which negates the condition; SECTION_CODE – by the parent group mnemonic code; similar to SECTION_ID; INCLUDE_SUBSECTIONS - if the SECTION_ID is specified, selects elements of all child sections of this section; SUBSECTION - specifies to return only the elements belonging to a specified subsection. The key value may be a two-element array specifying the left and right boundaries in the subsection tree. A NOT operator ("!") is possible, which negates the condition; SECTION_ACTIVE – if "Y", returns only elements of active sections. If "N", returns only elements of inactive sections. SECTION_GLOBAL_ACTIVE – similar to SECTION_ACTIVE but also checks if the parent sections are active; SHOW_COUNTER - by number of shows; SHOW_COUNTER_START - by the time of the first show; WF_COMMENTS - by the workflow comment (wildcards [%_] allowed); WF_STATUS_ID or WF_STATUS - by the workflow status; SHOW_HISTORY - if set to "Y", result will include history of elements. By default, only the published elements are selected; SHOW_NEW - if the SHOW_HISTORY is not set or not "Y" and SHOW_NEW is set to "Y", unpublished elements are also selected; WF_PARENT_ELEMENT_ID - by the code of the parent element in the workflow (for revision history); WF_NEW - by the unpublished state of an element (Y/N); WF_LOCK_STATUS - by the lock state in the workflow (red\|green\|yellow); PROPERTY_<PROPERTY_CODE> - specifies to filter by the property values. PROPERTY_CODE is the property or mnemonic code. This must be a number for list, number, bind to elements or bind to sections properties, or wildcard for other types; PROPERTY_<PROPERTY_CODE>_VALUE – for the list type properties. Specifies to filter by the list values (wildcard); the method will search by a string text rather than an ID; CATALOG_<CATALOG_FIELD>_<PRICE_TYPE> by the CATALOG_FIELD field of PRICE_TYPE price (the price type ID). CATALOG_FIELD may be: PRICE or CURRENCY. PROPERTY_<PROPERTY_CODE>.<FIELD> - specifies to filter by the field values of the bound elements. PROPERTY_CODE – is the binding property ID or mnemonic code. FIELD is a field of a bound element, can be one of the following: ACTIVE, DETAIL_TEXT_TYPE, PREVIEW_TEXT_TYPE, EXTERNAL_ID, NAME, XML_ID, TMP_ID, DETAIL_TEXT, SEARCHABLE_CONTENT, PREVIEW_TEXT, CODE, TAGS, WF_COMMENTS, ID, SHOW_COUNTER, WF_PARENT_ELEMENT_ID, WF_STATUS_ID, SORT, CREATED_BY, PREVIEW_PICTURE, DETAIL_PICTURE, IBLOCK_ID, TIMESTAMP_X, DATE_CREATE, SHOW_COUNTER_START, DATE_ACTIVE_FROM, DATE_ACTIVE_TO, ACTIVE_FROM, ACTIVE_TO, ACTIVE_DATE, DATE_MODIFY_FROM, DATE_MODIFY_TO, MODIFIED_USER_ID, MODIFIED_BY, CREATED_USER_ID, CREATED_BY. The following modifiers are possible before the field name: "!" - not equal; "<" – less than; "<=" - less than or equal; ">" - more than; ">=" - more than or equal; "><" - the value of the key is an array specifying the range of possible values (see the Remarks below). The "filter values" are a single value or an array. This parameter is optional. No filtering is performed by default. Remarks The "><" modifier can be used to match the range of values. To specify the range, pass an array whose “key=>value” pairs are the lower and higher range values. For example, the following call returns all elements whose name starts with a character "A" or "B" or is between "D" and "H": $res = CIBlockElement::GetList(Array(), Array("><NAME"=>Array(Array("A", "B"), Array("D", "H"))));
arGroupBy	If this parameter is not false, the returned items are grouped accordingly and the result array includes a CNT key returning the number of grouped elements; the arSelectFields is ignored. If the arGroupBy is an empty array, the method returns the number of elements in the CNT key. The grouping can be performed by the property values instead of the element fields. To do so, specify PROPERTY_<PROPERTY_CODE> as one of the grouping fields, the PROPERTY_CODE being a property or mnemonic code. Optional. The returned items are not grouped by default (false).
arNavStartParams	These parameters are used to implement breadcrumbs. This is achieved by passing an array of pairs "parameter=>value" with the following parameters: nTopCount - number of upper elements; bShowAll - directs to retrieve all elements; iNumPage - number of page; nPageSize - the desired number of elements per page; nElementID – the ID of an element that will be returned along with its neighbors. The number of neighbors is defined by the nPageSize key. Example: if nPageSize is 2, the maximum of 5 elements will be returned. The neighbors returned are defined by the arOrder parameter (see earlier). The following restrictions and rules apply when using the nElementID key: If an element with such ID is missing from the returned data, the result is undefined. The nElementID key cannot be used with the arGroupBy parameter. The arSelect parameter must define an "ID" key. The arOrder parameter is required. The returned elements cannot be sorted by "CATALOG_...". The returned array includes a RANK key containing the position of an element in the full selection (i.e. the one unrestricted by nElementID). This parameter is optional. The default value is false which specifies to return a full selection. If arNavStartParams is an empty array, the default limit of 10 elements takes effect.
arSelectFields	This array specifies the element fields and/or properties to retrieve. The IBLOCK_ID field must be specified for the method to fetch a correct result. Besides, a field in the format PROPERTY_<PROPERTY_CODE> also needs to be specifies, in which the PROPERTY_CODE is the ID or mnemonic code. This will return the element property values as the keys: PROPERTY_<PROPERTY_CODE>_VALUE - the value; PROPERTY_<PROPERTY_CODE>_ID - the value ID; PROPERTY_<PROPERTY_CODE>_ENUM_ID - the value ID for list types. If the "Commercial Catalog" module is installed, the method can return the element prices. To do so, specify CATALOG_GROUP_<PRICE_CODE> as one of the fields, here the PRICE_CODE is the price ID. The element fields can be selected by the "Link to elements" property values by specifying PROPERTY_<PROPERTY_CODE>.<FIELD>, here the PROPERTY_CODE is the binding property ID or mnemonic code; the FIELD is the field specified in the binding. See the notes below. The element property values can also be selected by the "Link to elements" property values. Specify the required properties in the format PROPERTY_<PROPERTY_CODE>.PROPERTY_<PROPERTY_CODE2>. Here the PROPERTY_CODE is the binding property ID or mnemonic code; the PROPERTY_CODE2 is the property of a bound element. By default, all the element fields are retrieved. Notes If a multiple property is specified in this parameter, the method will return multiple records for elements that contain more than one values of such property. To fix this problem, the information blocks may be set to store properties in individual tables. In this case, the method will return multiple values as an array. Another approach is to retrieve the properties by calling _CIBElement::GetProperties() on each iteration instead of using the arSelectFields. If this parameter specifies DETAIL_PAGE_URL, SECTION_PAGE_URL or LIST_PAGE_URL, the fields required to resolve the URL templates will be determined automatically unless grouping is in effect. To retrieve rating data for the selected elements, use the following keys in this parameter: RATING_TOTAL_VALUE, RATING_TOTAL_VOTES, RATING_TOTAL_POSITIVE_VOTES, RATING_TOTAL_NEGATIVE_VOTES, RATING_USER_VOTE_VALUE.

Return Values

Returns an instance of CIBlockResult.

Remarks

DISTINCT cannot be used to filter by blob fields in Oracle and MSSQL due to internal restrictions, which is why filters by several values of a multiple property may produce duplicate results.
The filter fields will be added to arSelectFields or arGroupBy by default if the records are grouped.

Useful filters

$arFilter = array("PROPERTY_CML2_SCAN_CODE") =>"" : returns all elements;
$arFilter = array("PROPERTY_CML2_SCAN_CODE") =>false : returns all elements with empty values;
$arFilter = array("PROPERTY_CML2_SCAN_CODE") =>"abc" : returns all elements whose scan code maches "abc" exactly;
$arFilter = array("?PROPERTY_CML2_SCAN_CODE") =>"def" : returns all elements whose scan code contains the substring "def".

$arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>"" : returns all elements whose CML2_SCAN_CODE property is not empty;
$arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>false : returns only the elements with non-empty property values;
$arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>"abc" : returns all elements whose CML2_SCAN_CODE property value is not "abc";
$arFilter = array("!?PROPERTY_CML2_SCAN_CODE") =>"def" : returns all elements whose CML2_SCAN_CODE property value does not include a "def" substring.

Using complex logic in filters

The arFilter parameter may specify nested filters in the form of an array. The nested filter array contains entries whose key is an ordinal number, and the values are the filter conditions (which can be anything including arrays).

Theoretically, there is no restriction on the level of filter nesting.

The filter condition may be set to use conjunction or disjunctions logic. That is, "AND" or "OR". "AND" specifies that all of the filter conditions must be true to pass; "OR" – one of the filter conditions must be true. To specify the logic operator, use the LOGIC key.

Example

The following code selects little ripe oranges and big unripe ones:

$arFilter = array(
  "IBLOCK_ID" => $IBLOCK_ID,
  "SECTION_CODE" => "orange",
  "INCLUDE_SUBSECTIONS" => "Y",
  //the nested filter with explicitly specified logic 
  array(
        "LOGIC" => "OR",
        0 => array("<PROPERTY_RADIUS" => 50, "=PROPERTY_CONDITION" => "Y"),
        1 => array(">=PROPERTY_RADIUS" => 50, "!=PROPERTY_CONDITION" => "Y"),
       ),
);

Fields of bound elements

ID - the element ID;
TIMESTAMP_X – the date and time an element was last modified, in the current website format;
MODIFIED_BY – the ID of a user who was the last to modify an element;
DATE_CREATE – the date and time an element was created;
CREATED_BY - the ID of a user who created an element;
IBLOCK_ID - the information block ID;
ACTIVE - the element active status (Y|N);
ACTIVE_FROM - the date and time since when an element is active, in the current website format;
ACTIVE_TO - the latest date and time when an element is active, in the current website format;
SORT - the sort order;
NAME - the element name;
PREVIEW_PICTURE - the thumbnail image ID;
PREVIEW_TEXT - the short text;
PREVIEW_TEXT_TYPE - type of the short text (html|text);
DETAIL_PICTURE - the large image ID;
DETAIL_TEXT – the detailed text;
DETAIL_TEXT_TYPE - type of the detailed text (html|text);
SHOW_COUNTER – the value of the impression counter;
SHOW_COUNTER_START – the date and time of the very first impression, in the website format;
CODE – the element symbolic code;
TAGS – the element tags;
XML_ID – the external ID;
IBLOCK_SECTION_ID – the ID of the element’s parent section (if present).

The following fields describe an information block.

IBLOCK_TYPE_ID – the information block type ID;
IBLOCK_CODE – the information block symbolic code;
IBLOCK_NAME – the information block name;
IBLOCK_EXTERNAL_ID – the information block external ID;
DETAIL_PAGE_URL – the element page URL template as specified in the information block parameters;
LIST_PAGE_URL – the elements list page URL template as specified in the information block parameters.

Examples

<?
$arSelect = Array("ID", "NAME", "DATE_ACTIVE_FROM");
$arFilter = Array("IBLOCK_ID"=>IntVal($yvalue), 
                  "ACTIVE_DATE"=>"Y", 
                  "ACTIVE"=>"Y");
$res = CIBlockElement::GetList(Array(), $arFilter, 
                               false, 
                               Array("nPageSize"=>50), 
                               $arSelect);
while ($ob = $res->GetNextElement())
{
  $arFields = $ob->GetFields();
  print_r($arFields);
}
?>

<?
// select active elements from information block $yvalue, 
// that has the property with code SRC set
// and the active state date starts from 01.01.2003.
// Group the selected elements by the active state date
$arFilter = Array(
   "IBLOCK_ID"=>IntVal($yvalue), 
   ">DATE_ACTIVE_FROM"=>date($DB->DateFormatToPHP(CLang::GetDateFormat("SHORT")), 
                             mktime(0,0,0,1,1,2003)), 
   "ACTIVE"=>"Y", 
   "!PROPERTY_SRC"=>false
   );
$res = CIBlockElement::GetList(Array("SORT"=>"ASC", "PROPERTY_PRIORITY"=>"ASC"), 
                               $arFilter, Array("DATE_ACTIVE_FROM"));
while($ar_fields = $res->GetNext())
{
    echo $ar_fields["DATE_ACTIVE_FROM"].": ".$ar_fields["CNT"]."<br>";
}
?>

<?
// Find the ID of an element with the maximum impression count across multiple information blocks.
$rs=CIBlockElement::GetList(array("show_counter"=>"desc"), array("ACTIVE"=>"Y", 
"IBLOCK_TYPE"=>"catalog"), false, array("nTopCount"=>1), array("ID")); 
while($ar=$rs->GetNext()) 
{ 
echo $ar["ID"]; 
}
?>

<?
// Show expired elements. 
$arFilter = array (
   "IBLOCK_ID" => $arResult["ID"],
   "IBLOCK_LID" => SITE_ID,
   "ACTIVE" => "Y",
   ""!DATE_ACTIVE_TO" => "date($DB-> DateFormatToPHP(CLang::GetDateFormat("SHORT")))",
   "<DATE_ACTIVE_TO" => date("d.m.Y h:i:s"),
);
?>

<?
// The date/time properties are stored in the database as strings in the format YYYY-MM-DD HH:MM:SS.
// Therefore, the date must be converted from the website format to the database format.
// The following filter will return all elements whose DATE property ranges from 01.01.2008 00:00:00 through 31.01.2008 23:59:59.
$DateFrom = "01.01.2008";
$DateTo = "31.01.2008";
$arFilter = array ( 
   ">=PROPERTY_DATE" => ConvertDateTime($DateFrom, "YYYY-MM-DD")." 00:00:00", 
   "<=PROPERTY_DATE" => ConvertDateTime($DateTo, "YYYY-MM-DD")." 23:59:59", 
);
?>

<?
// Return 5 random elements.
$rs = CIBlockElement::GetList (
   Array("RAND" => "ASC"),
   Array("IBLOCK_ID" => $IBLOCK_ID),
   false,
   Array ("nTopCount" => 5)
);
?>

<?
// Retrieve properties for each element.
$arSelect = Array("ID", "NAME", "DATE_ACTIVE_FROM","PROPERTY_*");
$arFilter = Array("IBLOCK_ID"=>IntVal($yvalue), "ACTIVE_DATE"=>"Y", "ACTIVE"=>"Y");
$res = CIBlockElement::GetList(Array(), $arFilter, false, Array("nPageSize"=>50), $arSelect);
while($ob = $res->GetNextElement()){ 
 $arFields = $ob->GetFields();  
print_r($arFields);
 $arProps = $ob->GetProperties();
print_r($arProps);
}
?>

<?
// The following code passes an array of information block ID’s to obtain elements from multiple information blocks.
$arFilter = array ( 
   "IBLOCK_ID" => array(1, 2, 3),
   ...
);
?>

<?
// Return elements whose fields DATE_ACTIVE_FROM and DATE_ACTIVE_TO are empty.
$arrFilter = array(
   "DATE_ACTIVE_FROM" => false,
   "DATE_ACTIVE_TO" => false,
);
?>

<?
// The following code shows how to use the nElementID key.
$rsPhoto = CIBlockElement::GetList(array("ID" => "DESC"), array(
               "IBLOCK_ID" => $BID,
               "ACTIVE" => "Y",
               "SECTION_GLOBAL_ACTIVE" => "Y"),
               false, array("nPageSize" => 1, "nElementID" => $ID),
               array("ID", "PROPERTY_REAL_PICTURE"));
?>