Zabbix

<?php

/*

** Copyright (C) 2001-2025 Zabbix SIA

**

** This program is free software: you can redistribute it and/or modify it under the terms of

** the GNU Affero General Public License as published by the Free Software Foundation, version 3.

**

** This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;

** without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

** See the GNU Affero General Public License for more details.

**

** You should have received a copy of the GNU Affero General Public License along with this program.

** If not, see <https://www.gnu.org/licenses/>.

**/

​

​

/**

 * Class containing methods for operations with histories.

 */

class CHistory extends CApiService {

​

    public const ACCESS_RULES = [

        'get' => ['min_user_type' => USER_TYPE_ZABBIX_USER],

        'clear' => ['min_user_type' => USER_TYPE_ZABBIX_ADMIN],

        'push' => ['min_user_type' => USER_TYPE_ZABBIX_USER]

    ];

​

    protected $tableName;

    protected $tableAlias = 'h';

    protected $sortColumns = ['itemid', 'clock', 'ns'];

​

    public function __construct() {

        // considering the quirky nature of the history API,

        // the parent::__construct() method should not be called.

    }

​

    /**

     * Get history data.

     *

     * @param array  $options

     * @param int    $options['history']                       History object type to return.

     * @param array  $options['hostids']                       Return only history from the given hosts.

     * @param array  $options['itemids']                       Return only history from the given items.

     * @param int    $options['time_from']                     Return only values that have been received after or at

     *                                                         the given time.

     * @param int    $options['time_till']                     Return only values that have been received before or at

     *                                                         the given time.

     * @param array  $options['filter']                        Return only those results that exactly match the given

     *                                                         filter.

     * @param int    $options['filter']['itemid']

     * @param int    $options['filter']['clock']

     * @param mixed  $options['filter']['value']

     * @param int    $options['filter']['ns']

     * @param array  $options['search']                        Return results that match the given wildcard search

     *                                                         (case-insensitive).

     * @param string $options['search']['value']

     * @param bool   $options['searchByAny']                   If set to true return results that match any of the

     *                                                         criteria given in the filter or search parameter instead

     *                                                         of all of them.

     * @param bool   $options['startSearch']                   Return results that match the given wildcard search

     *                                                         (case-insensitive).

     * @param bool   $options['excludeSearch']                 Return results that do not match the criteria given in

     *                                                         the search parameter.

     * @param bool   $options['searchWildcardsEnabled']        If set to true enables the use of "*" as a wildcard

     *                                                         character in the search parameter.

     * @param array  $options['output']                        Object properties to be returned.

     * @param bool   $options['countOutput']                   Return the number of records in the result instead of the

     *                                                         actual data.

     * @param array  $options['sortfield']                     Sort the result by the given properties. Refer to a

     *                                                         specific API get method description for a list of

     *                                                         properties that can be used for sorting. Macros are not

     *                                                         expanded before sorting.

     * @param array  $options['sortorder']                     Order of sorting. If an array is passed, each value will

     *                                                         be matched to the corresponding property given in the

     *                                                         sortfield parameter.

     * @param int    $options['limit']                         Limit the number of records returned.

     * @param bool   $options['editable']                      If set to true return only objects that the user has

     *                                                         write permissions to.

     *

     * @throws Exception

     * @return array|int    Data array or number of rows.

     */

    public function get($options = []) {

        $value_types = [ITEM_VALUE_TYPE_FLOAT, ITEM_VALUE_TYPE_STR, ITEM_VALUE_TYPE_LOG, ITEM_VALUE_TYPE_UINT64,

            ITEM_VALUE_TYPE_TEXT, ITEM_VALUE_TYPE_BINARY

        ];

​

        $api_input_rules = ['type' => API_OBJECT, 'fields' => [

            // filter

            'history' =>                ['type' => API_INT32, 'in' => implode(',', $value_types), 'default' => ITEM_VALUE_TYPE_UINT64],

            'hostids' =>                ['type' => API_IDS, 'flags' => API_ALLOW_NULL | API_NORMALIZE, 'default' => null],