173 lines
7.0 KiB
PHP
173 lines
7.0 KiB
PHP
<?php
|
|
/*
|
|
* Copyright (C) 2024 Xibo Signage Ltd
|
|
*
|
|
* Xibo - Digital Signage - https://xibosignage.com
|
|
*
|
|
* This file is part of Xibo.
|
|
*
|
|
* Xibo 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, either version 3 of the License, or
|
|
* any later version.
|
|
*
|
|
* Xibo 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 Xibo. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
namespace Xibo\Event;
|
|
|
|
use Xibo\Support\Exception\ConfigurationException;
|
|
|
|
/**
|
|
* Interface for managing schedule criteria types, metrics, conditions, and values.
|
|
*
|
|
* Allows the addition of types, metrics, conditions, and values in a chained manner:
|
|
* - Start with `addType()` to add a new type. Call `addType()` multiple times to add multiple types.
|
|
* - Follow with `addMetric()` to add metrics under the specified type. Call `addMetric()` multiple times to add
|
|
* multiple metrics to the current type.
|
|
* - Optionally, call `addCondition()` after `addMetric()` to specify a set of conditions for the metric. If not called,
|
|
* the system will automatically apply default conditions, which include all supported conditions.
|
|
* - Conclude with `addValues()` immediately after `addMetric()` or `addCondition()` to specify a set of values for the
|
|
* metric. Each metric can have one set of values.
|
|
*
|
|
* The added criteria are then parsed and displayed in the Schedule Criteria Form, enabling users to configure
|
|
* scheduling conditions based on the specified parameters.
|
|
*/
|
|
interface ScheduleCriteriaRequestInterface
|
|
{
|
|
/**
|
|
* Adds a new type to the criteria.
|
|
*
|
|
* **Important Notes:**
|
|
* - If the type already exists, the existing type is selected to allow method
|
|
* chaining.
|
|
*
|
|
* Example usage:
|
|
* ```
|
|
* $event->addType('weather', 'Weather Data')
|
|
* ->addMetric('temp', 'Temperature')
|
|
* ->addCondition([
|
|
* 'eq' => 'Equal to',
|
|
* 'gt' => 'Greater than'
|
|
* ])
|
|
* ->addValues('dropdown', [
|
|
* 'active' => 'Active',
|
|
* 'inactive' => 'Inactive'
|
|
* ]);
|
|
* ```
|
|
*
|
|
* @param string $id Unique identifier for the type.
|
|
* @param string $type Name of the type.
|
|
* @return self Returns the current instance for method chaining.
|
|
*/
|
|
public function addType(string $id, string $type): self;
|
|
|
|
/**
|
|
* Adds a new metric to the current type.
|
|
*
|
|
* **Important Notes:**
|
|
* - If the metric already exists, it sets the metric as the current metric for chaining instead.
|
|
* - `addType` must be called before this method to define the current type.
|
|
*
|
|
* **Example Usage:**
|
|
* ```
|
|
* $event->addType('weather', 'Weather Data')
|
|
* ->addMetric('temp', 'Temperature')
|
|
* ->addCondition([
|
|
* 'eq' => 'Equal to',
|
|
* 'gt' => 'Greater than'
|
|
* ])
|
|
* ->addValues('dropdown', [
|
|
* 'active' => 'Active',
|
|
* 'inactive' => 'Inactive'
|
|
* ]);
|
|
* ```
|
|
*
|
|
* @param string $id Unique identifier for the metric.
|
|
* @param string $name Name of the metric.
|
|
* @return self Returns the current instance for method chaining.
|
|
* @throws ConfigurationException If the current type is not set.
|
|
*/
|
|
public function addMetric(string $id, string $name): self;
|
|
|
|
/**
|
|
* Add conditions to the current metric.
|
|
*
|
|
* This method allows you to specify conditions for the current metric.
|
|
* The list of accepted conditions includes:
|
|
* - 'set' => 'Is set'
|
|
* - 'lt' => 'Less than'
|
|
* - 'lte' => 'Less than or equal to'
|
|
* - 'eq' => 'Equal to'
|
|
* - 'neq' => 'Not equal to'
|
|
* - 'gte' => 'Greater than or equal to'
|
|
* - 'gt' => 'Greater than'
|
|
* - 'contains' => 'Contains'
|
|
* - 'ncontains' => 'Not contains'
|
|
*
|
|
* **Important Notes:**
|
|
* - The `addMetric` method **must** be called before using `addCondition`.
|
|
* - If this method is **not called** for a metric, the system will automatically
|
|
* provide the default conditions, which include **all the accepted conditions** listed above.
|
|
* - New conditions will be merged if they already exist under the same type and metric, avoiding duplicates.
|
|
*
|
|
* Example usage:
|
|
* ```
|
|
* $event->addType('weather', 'Weather Data')
|
|
* ->addMetric('temp', 'Temperature')
|
|
* ->addCondition([
|
|
* 'eq' => 'Equal to',
|
|
* 'gt' => 'Greater than'
|
|
* ])
|
|
* ->addValues('dropdown', [
|
|
* 'active' => 'Active',
|
|
* 'inactive' => 'Inactive'
|
|
* ]);
|
|
* ```
|
|
*
|
|
* @param array $conditions An associative array of conditions, where the key is the condition ID and the value is
|
|
* its name.
|
|
* @return $this Returns the current instance for method chaining.
|
|
* @throws ConfigurationException If the current metric is not set.
|
|
*/
|
|
public function addCondition(array $conditions): self;
|
|
|
|
/**
|
|
* Add values to the current metric. The input type must be either "dropdown", "string", "date", or "number".
|
|
*
|
|
* For "dropdown" input type, provide an array of values. For other input types ("string", "date", "number"),
|
|
* the values array should be empty "[]".
|
|
* The values array should be formatted such that the index is the id and the value is the title/name of the value.
|
|
*
|
|
* **Important Notes:**
|
|
* - The `addMetric` method **must** be called before using `addValues`.
|
|
* - If values already exist for the same type and metric, new values will be merged, avoiding duplicates.
|
|
*
|
|
* Example usage:
|
|
* ```
|
|
* $event->addType('weather', 'Weather Data')
|
|
* ->addMetric('temp', 'Temperature')
|
|
* ->addCondition([
|
|
* 'eq' => 'Equal to',
|
|
* 'gt' => 'Greater than'
|
|
* ])
|
|
* ->addValues('dropdown', [
|
|
* 'active' => 'Active',
|
|
* 'inactive' => 'Inactive'
|
|
* ]);
|
|
* ```
|
|
*
|
|
* @param string $inputType Type of input for the values ("dropdown", "string", "date", "number").
|
|
* @param array $values Array of values, which should be empty for input types other than "dropdown".
|
|
* @return self Returns the current instance for method chaining.
|
|
* @throws ConfigurationException If the current type or metric is not set.
|
|
*/
|
|
public function addValues(string $inputType, array $values): self;
|
|
}
|