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() — whether or not some information should be hidden to the current user.
-
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
whether or not some information should be hidden to the current user.
abstract public AllowAllData()
Parameters
none
Returns
mixed
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
2_7_0/customization/api/objects-manipulation/dbsearch.txt
· Last modified: 2020/04/15 15:23 by 127.0.0.1