You are browsing the documentation for iTop 2.7 which is not the current version.

Consider browsing to iTop 3.1 documentation

🔙 Back

DBSearch

abstract api

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:

Public methods

__construct

api public

DBSearch constructor.
public __construct()

Parameters

none

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)

Throws

  • \CoreException
  • \CoreWarning

See also

DBSearch::AddCondition_ReferencedBy()

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)

AddConditionExpression

api abstract public

add $oExpression as a AND
abstract public AddConditionExpression($oExpression)

Parameters

types name default description
\Expression $oExpression

Returns

mixed

AllowAllData

api abstract public

whether or not some information should be hidden to the current user.
abstract public AllowAllData()

Parameters

none

Returns

mixed

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

Throws

\OQLException

See also

DBSearch::ToOQL()

MergeConditionExpression

api abstract public

add $oExpression as a OR
abstract public MergeConditionExpression($oExpression)

Parameters

types name default description
\Expression $oExpression

Returns

mixed

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

Throws

  • \ArchivedObjectException
  • \CoreException

See also

DBSearch::unserialize()

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

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

🔙 Back

2_7_0/customization/api/objects-manipulation/dbsearch.txt · Last modified: 2020/04/15 15:23 (external edit)
Back to top
Contact us