DBSearch
abstract api
An object search
DBSearch provides an API that leverage the possibility to construct a search against iTop's persisted objects. In order to do so, it let you declare the classes you want to fetch, the conditions you want to apply, ...
Note: in the ancient times of iTop, a search was named after DBObjectSearch. When the UNION has been introduced, it has been decided to:
- declare a hierarchy of search classes :
DBObjectSearch&DBUnionSearch- DBObjectSearch cope with single query (A JOIN B... WHERE...)
- DBUnionSearch cope with several queries (query1 UNION query2)
- in order to preserve forward/backward compatibility of the
existing modules
- keep the name of DBObjectSearch even if it a little bit confusing
- do not provide a type-hint for function parameters defined in the modules
- leave the statements DBObjectSearch::FromOQL in the modules, though DBSearch is more relevant
See also
API synthesis
List of the public API methods. When manipulating DBSearch, You can call those methods:
-
__construct() — DBSearch constructor.
-
AddCondition() — Add a condition
-
AddCondition_PointingTo() — Perform a join, the remote class being matched by the mean of its primary key
-
AddCondition_ReferencedBy() — Inverse operation of AddCondition_PointingTo
-
AddConditionExpression() — add $oExpression as a AND
-
AllowAllData() —
-
FromOQL() — Create a new DBSearch from the given OQL.
-
MergeConditionExpression() — add $oExpression as a OR
-
serialize() — Convert a query to a string representation
-
ToOQL() — Convert the DBSearch to an OQL representation
-
unserialize() — Convert a serialized query back to an instance of DBSearch
Public methods
__construct
api public
DBSearch constructor.
public __construct()
Parameters
none
See also
AddCondition
api abstract public
Add a condition
This is the simplest way to express a AND condition. For complex use cases, use MergeConditionExpression or AddConditionExpression instead
abstract public AddCondition($sFilterCode, $value, $sOpCode = null)
Parameters
| types | name | default | description |
|---|---|---|---|
| string | $sFilterCode | ||
| mixed | $value | ||
| string | $sOpCode | null | operator to use : '=' (default), '!=', 'IN', 'NOT IN' |
Throws
\CoreException
AddCondition_PointingTo
api abstract public
Perform a join, the remote class being matched by the mean of its primary key
The join is performed
- from the searched class, based on the $sExtKeyAttCode attribute
- against the oFilter searched class, based on its primary key Note : if several classes have already being joined (SELECT a join b ON...), the first joined class (a in the example) is considered as being the searched class.
abstract public AddCondition_PointingTo($oFilter, $sExtKeyAttCode, $iOperatorCode = TREE_OPERATOR_EQUALS, $aRealiasingMap = null)
Parameters
| types | name | default | description |
|---|---|---|---|
| \DBObjectSearch | $oFilter | ||
| string | $sExtKeyAttCode | ||
| integer | $iOperatorCode | TREE_OPERATOR_EQUALS | the comparison operator to use. For the list of all possible values, see the constant defined in core/oql/oqlquery.class.inc.php |
| array|null | $aRealiasingMap | null | array of <old-alias> ⇒ <new-alias>, for each alias that has changed in the newly attached oFilter (in case of collisions between the two filters) |
AddCondition_ReferencedBy
api abstract public
Inverse operation of AddCondition_PointingTo
The join is performed
- from the olFilter searched class, based on the $sExtKeyAttCode attribute
- against the searched class, based on its primary key Note : if several classes have already being joined (SELECT a join b ON...), the first joined class (a in the example) is considered as being the searched class.
abstract public AddCondition_ReferencedBy($oFilter, $sForeignExtKeyAttCode, $iOperatorCode = TREE_OPERATOR_EQUALS, $aRealiasingMap = null)
Parameters
| types | name | default | description |
|---|---|---|---|
| \DBObjectSearch | $oFilter | ||
| $sForeignExtKeyAttCode | |||
| integer | $iOperatorCode | TREE_OPERATOR_EQUALS | |
| array|null | $aRealiasingMap | null | array of <old-alias> ⇒ <new-alias>, for each alias that has changed in the newly attached oFilter (in case of collisions between the two filters) |
See also
AddConditionExpression
api abstract public
add $oExpression as a AND
abstract public AddConditionExpression($oExpression)
Parameters
| types | name | default | description |
|---|---|---|---|
| \Expression | $oExpression |
Returns
mixed
See also
AllowAllData
api abstract public
abstract public AllowAllData($bAllowAllData = true)
Parameters
| types | name | default | description |
|---|---|---|---|
| boolean | $bAllowAllData | true | whether or not some information should be hidden to the current user. |
See also
FromOQL
api public static
Create a new DBSearch from the given OQL.
This is the simplest way to create a DBSearch. For almost every cases, this is the easiest way.
public static FromOQL($sQuery, $aParams = null, $oMetaModel = null)
Parameters
| types | name | default | description |
|---|---|---|---|
| string | $sQuery | The OQL to convert to a DBSearch | |
| \mixed[string] | $aParams | null | array of <mixed> params index by <string> name |
| \ModelReflection|null | $oMetaModel | null | The MetaModel to use when checking the consistency of the OQL |
Returns
\DBObjectSearch|\DBUnionSearch
MergeConditionExpression
api abstract public
add $oExpression as a OR
abstract public MergeConditionExpression($oExpression)
Parameters
| types | name | default | description |
|---|---|---|---|
| \Expression | $oExpression |
Returns
mixed
See also
serialize
api public
Convert a query to a string representation
This operation can be revert back to a DBSearch using DBSearch::unserialize()
public serialize($bDevelopParams = false, $aContextParams = array())
Parameters
| types | name | default | description |
|---|---|---|---|
| boolean | $bDevelopParams | false | |
| array | $aContextParams | array() |
Returns
false|string
ToOQL
api abstract public
Convert the DBSearch to an OQL representation
abstract public ToOQL($bDevelopParams = false, $aContextParams = null, $bWithAllowAllFlag = false)
Parameters
| types | name | default | description |
|---|---|---|---|
| boolean | $bDevelopParams | false | |
| null | $aContextParams | null | |
| boolean | $bWithAllowAllFlag | false |
Returns
mixed
See also
unserialize
api public static
Convert a serialized query back to an instance of DBSearch
public static unserialize($sValue)
Parameters
| types | name | default | description |
|---|---|---|---|
| string | $sValue | Serialized OQL query |
Returns
\DBSearch
Throws
-
\ArchivedObjectException -
\CoreException -
\OQLException
latest/customization/api/objects-manipulation/dbsearch.txt
· Last modified: 2023/07/21 10:19 (external edit)