MidCOM DBA level wrapper for the Midgard Query Builder.

This class must be used anyplace within MidCOM instead of the real midgard_query_builder object within the MidCOM Framework. This wrapper is required for the correct operation of many MidCOM services.

It essentially wraps the calls to {@link midcom_helper__dbfactory::new_query_builder()}.

Normally you should never have to create an instance of this type directly, instead use the get_new_qb() method available in the MidCOM DBA API or the midcom_helper__dbfactory::new_query_builder() method which is still available.

If you have to do create the instance manually however, do not forget to call the {@link initialize()} function after construction, or the creation callbacks will fail.

package midcom

 Methods

__construct (string $classname)

The constructor wraps the class resolution into the MidCOM DBA system.

Currently, Midgard requires the actual MgdSchema base classes to be used when dealing with the QB, so we internally note the corresponding class information to be able to do correct typecasting later.

todo remove baseclass resolution, Midgard core can handle extended classnames correctly nowadays

Parameters

$classname

stringThe classname which should be queried.

count ()

Returns the number of elements matching the current query.

Due to ACL checking we must first execute the full query

Returns

intThe number of records found by the last query.

count_unchecked ()

This is a mapping to the real count function of the Midgard Query Builder.

It is mainly intended when speed is important over accuracy, as it bypasses access control to get a fast impression of how many objects are available in a given query. It should always be kept in mind that this is a preliminary number, not a final one.

Use this function with care. The information you obtain in general is negligible, but a creative mind might nevertheless be able to take advantage of it.

Returns

intThe number of records matching the constraints without taking access control or visibility into account.

execute ()

execute_unchecked ()

Runs a query where limit and offset is taken into account <i>prior</i> to execution in the core.

This is useful in cases where you can safely assume read privileges on all objects, and where you would otherwise have to deal with huge resultsets.

Be aware that this might lead to empty resultsets "in the middle" of the actual full resultset when read privileges are missing.

see \execute()

execute_windowed ()

This function will execute the Querybuilder and call the appropriate callbacks from the class it is associated to.

This way, class authors have full control over what is actually returned to the application.

The calling sequence of all event handlers of the associated class is like this:

  1. boolean _on_prepare_exec_query_builder(&$this) is called before the actual query execution. Return false to abort the operation.
  2. The query is executed.
  3. void _on_process_query_result(&$result) is called after the successful execution of the query. You may remove any unwanted entries from the resultset at this point.

Returns

ArrayThe result of the query builder or null on any error. Note, that empty resultsets will return an empty array.

get_result (int $key, string $mode)

Get result by its index

Parameters

$key

intRequested index in result set

$mode

stringExecution mode: normal (default), unchecked, notwindowed

Returns

mixedFalse on failure (key does not exist), object given to constructor on success

include_deleted ()

Include deleted objects (metadata.deleted is true) in query results.

Note: this may cause all kinds of weird behavior with the DBA helpers

initialize ()

The initialization routine executes the _on_prepare_new_querybuilder callback on the class.

This cannot be done in the constructor due to the reference to $this that is used.

toggle_read_only (bool $toggle)

Sets read-only mode for underlying midgard_query_builder instance.

If $toggle is true, all objects returned with execute method have read-only properties, which can not be set, and all intances are created with better performance. This method is dedicated for resultsets which are not meant to be updated or edited.

If underlying midgard_query_buidler doesn't provide read-only toggle, this method does nothing.

Parameters

$toggle

boolenables or disables query builder read-only mode.

_reset ()

Resets some internal variables for re-execute

_check_groups ()

_execute_and_check_privileges (boolean $false_on_empty_mgd_resultset)

Executes the internal QB and filters objects based on ACLs and metadata

Parameters

$false_on_empty_mgd_resultset

booleanused in the moving window loop to get false in stead of empty array back from this method in case the **core** QB returns empty resultset

Returns

arrayof objects filtered by ACL and metadata visibility (or false in case of failure)

_set_limit_offset_window ($iteration)

Parameters

$iteration

 Properties

 

mixed $max_window_size

When determining window sizes for offset/limit queries use this as maximum size
 

mixed $min_window_size

When determining window sizes for offset/limit queries use this as minimum size
 

mixed $_qb_error_result

 

mixed $_window_size

Which window size to use.

Is calculated when executing for the first time