\OntologyWrapperMongoDatabase

drop()

drop()

Drop the database

This method should drop the current database.

isConnected()

isConnected() : boolean

Check if connection is open

This method returns a boolean flag indicating whether the connection is open or not.

Returns

TRUE is open.

getCollections()

getCollections() : array

Return collection names

This method should return the list of collection names of the current database, the method should return the following retults:

• NULL: The operation is not supported.
• FALSE: The database is not connected.
• array: The database collection names.

We implement the method in this class as a fall-back.

Returns

Server statistics or NULL if unsupported.

getName()

getName() : string

Return database name

This method should return the database name:

We implement the method in this class as a fall-back.

Returns

Database name.

setSequenceNumber()

setSequenceNumber(string $theSequence, integer $theNumber)

Set sequence number

This method should initialise a sequence number associated to the provided parameter. This operation is equivalent to resetting an auto-number for a database.

Once the sequence is set, the next requested sequence number will hold the value set by this method, so to start counting from 1 you should provide this value to this method.

Derived classes must implement this method.

Parameters

getSequenceNumber()

getSequenceNumber(string $theSequence) : integer

Return sequence number

This method should return a sequence number associated to the provided parameter. This operation is equivalent to requesting an auto-number for a database.

Each time a sequence number is requested, the sequence seed is updated, so use this method only when the sequence is required.

If the sequence selector is not found, a new one will be created starting with the number 1, so, if you need to start with another number, use the {@link setSequenceNumber()} before.

Derived classes must implement this method.

Parameters

Returns

Sequence number.

__construct()

__construct(mixed $theParameter, \OntologyWrapper\ConnectionObject $theParent)

Instantiate class.

The object may be instantiated as an empty object, by omitting both parameters; with a data source name in the form of a connection URL; or by providing an array of tag/value parameters which will constitute the object's offsets.

If you provide a data source name, this must be parsable by the {@link parse_url()} function, if this is not the case, you should use the parameters list.

If the first parameter was provided, the method will synchronise both the data source name and the connection parameters.

The second parameter represents the connection parent, it must be an instance derived from this class and will only be set by the constructor.

When overloading the constructor in derived classes you should always first call the parent method and then perform custom actions.

Parameters

Throws

\OntologyWrapper\Exception

collection()

collection(string $theName, boolean $doOpen) : \OntologyWrapper\CollectionObject

Return collection connection

This method can be used to return a collection connection from the current database.

The method expects a single parameter which represents the collection name, the method should return an instance of a class derived from {@link CollectionObject}.

Parameters

Returns

Collection object.

DefaultOffsets()

DefaultOffsets() : array

Return default offsets

This method will return the list of default offsets for the current class, these are the properties known to be part of the current class: since objects may feature any defined tag, this selection provides an indication of which properties one could expect.

This selection can also be used as the minimum set of properties which an object may feature.

In this class we return an empty array.

Returns

List of default offsets.

__destruct()

__destruct()

Destruct instance.

The destructor will close the connection if open.

__sleep()

__sleep()

Sleep

This method will close the connection and replace the connection resource with TRUE if the connection was open.

__wakeup()

__wakeup()

Wake up

This method will re-open the connection if it was closed by the {@link __sleep()} method.

__toString()

__toString() : string

<h4>Return global identifier</h4>

This method should return the current object's global identifier.

All derived concrete classes must implement this method.

Returns

The global identifier.

dsn()

dsn(mixed $theValue, boolean $getOld, boolean $doSync) : mixed

Manage data source name

This method can be used to manage the data source name, it accepts a parameter which represents either the data source name or the requested operation, depending on its value:

• NULL: Return the current value.
• FALSE: Delete the current value.
• other: Set the value with the provided parameter.

The second parameter is a boolean which if TRUE will return the old value when replacing or resetting; if FALSE, it will return the current value.

The last parameter is a switch that determines whether the object offsets should be synchronised: if TRUE, the object offsets will be reset and populated with the elements parsed from the data source name; if FALSE, the object offsets will not be modified. This parameter is set to FALSE by the constructor, since using all offsets may produce an invalid URL and is TRUE by default, since setting a connection URL generally means changing the parameters.

Whenever a new value is set or the value is deleted, the method will synchronise the object offsets.

Parameters

Throws

\OntologyWrapper\Exception

Returns

New or old data source name.

connection()

connection() : mixed

Return connection resource.

This method can be used to retrieve the connection resource, this method is read-only, since the connection resource should only be set by the object's connection methods.

The connection resource represents the native connection.

Returns

Connection resource.

parent()

parent() : \OntologyWrapper\ConnectionObject

Return connection parent.

This method can be used to retrieve the parent connection, this method is read-only, since the connection parent can only be set by the constructor and cannot be changed once the object has been instantiated.

The connection parent represents the connection creator as the server for a database.

Returns

Parent connection.

openConnection()

openConnection() : mixed

Open connection

This method can be used to create and open the connection.

We first check if the connection is already set: if so we do nothing.

We call the protected {@link connectionOpen()} method which will open the connection and return the connection resource which will be set in the data member, {@link mConnection}.

The method will return the connection resource.

Returns

Depends on implementation.

closeConnection()

closeConnection() : boolean

Close connection

If the connection is open, this method will close the connection and reset the {@link connection} data member.

The method will return TRUE if the connection was open and FALSE if not.

Returns

TRUE if closed, FALSE if was closed.

dictionary()

dictionary(mixed $theDictionary, boolean $getOld) : \OntologyWrapper\Dictionary

Set or return data dictionary

This method can be used to set or retrieve the object's data dictionary, which is required by all derived objects to resolve offsets.

You should set this data member as soon as the object has been instantiated, before adding offsets to it.

The method expects the following parameters:

• $theDictionary: Data dictionary or operation:
  • NULL: Return current dictionary.
  • {@link Dictionary}: Set dictionary with provided value.
• $getOld: This parameter is a boolean which if TRUE will return the old dictionary when replacing, if FALSE, it will return the current value.

The method will raise an exception if the dictionary holds any other type except the above.

Parameters

Throws

\OntologyWrapper\Exception

Returns

Object data dictionary.

reference()

reference() : mixed

Return object reference

This method will return the current object's reference. This value should uniquely identify the referenced object, making it easy to retrieve the object given this reference.

In this class, and generally in all classes, the reference of an object is its native identifier, {@link kTAG_NID}.

The method must raise an exception if the reference cannot be provided.

Throws

\OntologyWrapper\Exception

Returns

Object reference.

resolveOffset()

resolveOffset(string $theOffset, boolean $doAssert) : string

Resolve offset

This method will resolve the provided offset into a {@link Tag} serial number, this is done by using a {@link Dictionary} object stored in the current object's {@link $mDictionary} data member.

If you provide a string prefixed by the {@link kTOKEN_TAG_PREFIX} token, the method will simply return it.

All other types of offsets, except those returned by the {@link InternalOffsets()} method, will be used to locate the tag native identifier using a {@link Dictionary} object stored in the current object's {@link $mDictionary} data member; if the provided offset cannot be resolved, the method will raise an exception if the second parameter is TRUE, or NULL if the second parameter is FALSE.

The method will raise an exception if the tag cache is not set.

Parameters

Throws

\OntologyWrapper\Exception

Returns

Resolved offset.

offsetExists()

offsetExists(mixed $theOffset) : boolean

Check if an offset exists

We overload this method to call the preflight method: if it returns NULL we call the parent method; if not, we return the received value.

Parameters

Returns

TRUE the offset exists.

offsetGet()

offsetGet(mixed $theOffset) : mixed

Return a value at a given offset

We overload this method to call the preflight method: if it returns NULL we call the parent method; if not, we return the received value.

We also overload this method to handle unmatched offsets: we prevent warnings from being issued and return NULL.

Parameters

Returns

Offset value or NULL.

offsetSet()

offsetSet(string $theOffset, mixed $theValue)

Set a value at a given offset

We overload this method to call the preflight and postflight methods: if the preflight method returns NULL we call the parent method; if not, we stop.

We also overload this method to handle NULL values: in that case we delete the offset.

Parameters

offsetUnset()

offsetUnset(string $theOffset)

Reset a value at a given offset

We overload this method to call the preflight and postflight methods: if the preflight method returns NULL we call the parent method; if not, we stop.

We also overload this method to prevent warnings on unmatched offsets.

Parameters

InternalOffsets()

InternalOffsets() : array

Return internal offsets

This method will return the list of internal offsets for the current class, these offsets are not defined in the data dictionary and are private to the object. This method is used to exclude these offsets from the default offset resolution workflow.

These offsets:

• Will not be part of the offset management framework.

In this class we return:

• {@link kTAG_NID}: Native identifier.
• {@link kTAG_CLASS}: Object class name.
• {@link kTAG_TYPE}: Property type.
• {@link kTAG_LANGUAGE}: Property language.
• {@link kTAG_TEXT}: Property text.
• {@link kTAG_URL}: Property URL.
• {@link kTAG_GEOMETRY}: Shape property geometry.
• {@link kTAG_RADIUS}: Shape property radius.
• {@link kTAG_FULL_TEXT_10}: Full-text values, weight 10.
• {@link kTAG_FULL_TEXT_06}: Full-text values, weight 6.
• {@link kTAG_FULL_TEXT_03}: Full-text values, weight 3.

Returns

List of internal offsets.

ExternalOffsets()

ExternalOffsets() : array

Return external offsets

This method will return the list of external offsets for the current class. These are offsets which are managed neither by clients nor by the object itself, these will generally be managed by events triggered by other objects.

These offsets:

• Will not be part of the offset management framework.

In this class we return an empty array.

Returns

List of external offsets.

DynamicOffsets()

DynamicOffsets() : array

Return dynamic offsets

This method will return the list of dynamic offsets for the current class. These are offsets which are managed by the object itself, and should not be modified by clients.

These offsets:

• Will not be part of the offset management framework.
• Will be reset each time the object is committed.

In this class we return an empty array.

Returns

List of dynamic offsets.

UnmanagedOffsets()

UnmanagedOffsets() : array

Return unmanaged offsets

This method will return the list of offsets which should be excluded from the offset management framework.

By default we include offsets returned by:

• {@link ExternalOffsets()}: External offsets.
• {@link DynamicOffsets()}: Synamic offsets.

Note that internal offsets, {@link InternalOffsets()}, are also not managed, but since those offsets do not have a sequence number, we need to treat them separately.

Derived classes may overload this method to add custom offsets.

Returns

List of unmanaged offsets.

OffsetTypes()

OffsetTypes(\OntologyWrapper\DictionaryObject $theDictionary, mixed $theOffset, string $theType, array $theKind, mixed $theMin, mixed $theMax, string $thePattern, boolean $doAssert) : mixed

Resolve offset types

This method will resolve the provided offset into a {@link Tag} object and return in the provided reference parameters the data type, kind, range and pattern; this is done by using the provided {@link Dictionary} object.

The method expects the following parameters:

• $theDictionary: This parameter represents the data dictionary.
• $theOffset: This parameter represents the offset.
• $theType: This parameter will receive the data type of the referenced tag, if the tag could not be resolved, the value will be NULL.
• $theKind: This parameter will receive the data kind of the referenced tag, if the tag could not be resolved, the value will be an empty array; if the tag has no data kind, the parameter will hold an empty array.
• $theMin: This parameter will receive the data minimum range of the referenced tag, if the tag could not be resolved, the value will be NULL; if the tag has no minimum data range, the parameter will hold NULL.
• $theMax: This parameter will receive the data maximum range of the referenced tag, if the tag could not be resolved, the value will be NULL; if the tag has no maximum data range, the parameter will hold NULL.
• $thePattern: This parameter will receive the data pattern of the referenced tag, if the tag could not be resolved, or if the pattern is not set, the value will be NULL.
• $doAssert: If TRUE and either the offset or the tag could not be resolved, the method will raise an exception; the default is TRUE.

If the provided offset is numeric, the method will assume it is a tag sequence number, if not, the method will resolve it into a tag sequence number; if this fails and the last paraneter is TRUE, the method will raise an exception.

The method will return TRUE if the types were resolved and NULL if not.

Parameters

Returns

TRUE if the tag was resolved, or NULL.

SelectLanguageString()

SelectLanguageString(array $theStrings, string $theLanguage) : string

Return language string

This method expects the value from a property of type {@link kTYPE_LANGUAGE_STRING} or {@link kTYPE_LANGUAGE_STRINGS} and a language code, its duty is to return the string matching the language code, or the default string.

The method will perform the following steps:

• If the string matching the code is there, use it.
• If a code 0 is there, use it.
• Use the first string.

Parameters

Returns

The string in the provided language.

CastScalar()

CastScalar(mixed $theProperty, string $theType)

Cast scalar

The duty of this method is to cast the provided scalar property to the provided data type.

Parameters

CastShapeGeometry()

CastShapeGeometry(\OntologyWrapper\reference $theShape)

Cast shape geometry

The duty of this method is to verify and cast the geometry of the provided shape. The method expects the shape to have a correct root structure, that is, it must have the shape type and geometry array, this method will traverse the geometry and its structure.

Parameters

nestedOffsetGet()

nestedOffsetGet(mixed $theOffset, array $theValue, mixed $theFound) : mixed

Return a value at a given nested offset

This method is the equivalent of {@link offsetGet()} for nested offsets, the method will traverse the current value until it finds the offset, if at any level an offset is not resolved, the method will return NULL.

It is assumed that all offsets except the last one must be arrays, if that is not the case, the method will return NULL.

The provided offset must be a valid nested offset, which is a sequence of numerics separated by a period; this check must have been performed by the caller.

If at any stage of the path there is a list of structures, the result will be an array of all found values.

Note that this method will only be called if the offset exists, so it must find it.

Parameters

Returns

Offset value or NULL.

nestedOffsetSet()

nestedOffsetSet(string $theOffset, mixed $theValue, string $theRootOffset, array $theRootValue, string $theCurrentOffset, array $theCurrentValue) : array

Set a value at a given offset

This method is the equivalent of {@link offsetSet()} for nested offsets, the method will traverse the current value setting eventual missing intermediate offsets as arrays; note that if the method finds another kind of value, it will overwrite it with an empty array: it is assumed that setting an offset replaces the previous contents.

The method expects the following parameters:

• $theOffset: This parameter expects the nested offset string, when recursing, it will be passed the nested offset path array.
• $theValue: This parameter expects the value to be set at the leaf offset.
• $theRootOffset: This parameter is only used during recursion.
• $theRootValue: This parameter is only used during recursion.
• $theCurrentValue: This parameter is only used during recursion.

The method will take care of setting the the object's offset.

It is assumed that all offsets except the last one must be arrays, if that is not the case, the method will return NULL.

The provided offset must be a valid nested offset, which is a sequence of numerics separated by a period; this check must have been performed by the caller.

Parameters

Throws

\OntologyWrapper\Exception

Returns

The updated nested structure.

nestedOffsetUnset()

nestedOffsetUnset(string $theOffset, string $theRootOffset, array $theCurrentValue)

Reset a value at a given offset

This method is the equivalent of {@link offsetUnset()} for nested offsets, the method will traverse the current value until it reaches the requested offset and it will delete it, if any offset is not matched, or if any intermediate offset is not an array, the method will do nothing.

The method expects the following parameters:

• $theOffset: This parameter expects the nested offset string, when recursing, it will be passed the nested offset path array.
• $theRootOffset: This parameter is only used during recursion.
• $theCurrentValue: This parameter is only used during recursion.

The method will take care of deleting the the object's offset. If any intermediate offset holds an empry array, the method will delete it.

It is assumed that all offsets except the last one must be arrays, if that is not the case, the method will return NULL.

The provided offset must be a valid nested offset, which is a sequence of numerics separated by a period; this check must have been performed by the caller.

Parameters

arrayKeys()

arrayKeys() : array

Return object's offsets

This method has the same function as the PHP function {@link array_keys()}, it will return all the object's offset keys as an array.

Returns

List of object offsets.

arrayValues()

arrayValues() : array

Return object's offset values

This method has the same function as the PHP function {@link array_values()}, it will return all the object's offset values as an array.

Returns

List of object offset values.

Object2Array()

Object2Array(\OntologyWrapper\reference $theSource, \OntologyWrapper\reference $theDestination)

<h4>Convert object to array</h4>

This method can be used to obtain an array of arrays from a nested structure.

The method expects as the first parameter a reference to an {@link ArrayObject} or to an array, it will convert the provided parameter to an array and traverse it, converting recursively any {@link ArrayObject} instance into an array.

The method accepts the following parameters:

• $theSource: Source structure reference (read-only).
• $theDestination: Destination array reference.

Parameters

Throws

\OntologyWrapper\Exception

connectionOpen()

connectionOpen() : mixed

Open connection

This method should open the actual connection and set the {@link mConnection} data member; in this class the method is virtual.

This method expects the caller to have checked whether the connection is already open.

If the operation fails, the method should raise an exception.

Returns

The native connection.

connectionClose()

connectionClose()

Open connection

This method should close the actual connection, in this class the method is virtual.

This method expects the caller to have checked whether the connection is open.

If the operation fails, the method should raise an exception.

newServer()

newServer(mixed $theParameter, boolean $doOpen) : \OntologyWrapper\ServerObject

Return a new server instance

This method should be implemented by concrete derived classes, it expects a list of offsets or a data source name containing the necessary elements to instantiate a {@link ServerObject} instance which will be considered the current object's parent.

Derived classes must implement this method.

When implementing this method you should not forget to set the dictionary.

Parameters

Returns

Server instance.

newCollection()

newCollection(array $theOffsets, boolean $doOpen) : \OntologyWrapper\CollectionObject

Return a new collection instance

This method should be implemented by concrete derived classes, it expects a list of offsets which include database information and should use them to instantiate a {@link CollectionObject} instance.

Derived classes must implement this method.

When implementing this method you should not forget to set the dictionary.

Parameters

Returns

Collection instance.

parseDSN()

parseDSN(string $theDSN)

Parse data source name

This method will parse the provided data source name, extract the connection parameters and set them in the current object.

The method will make use of the {@link parse_url()} function and pass each key/value pair to the protected {@link loadDSNParameter()} method which has the responsibility of matching the {@link parse_url()} keys to {@link Tag} instances.

If the {@link parse_url()} function fails to parse the DSN, the method will raise an exception.

Derived classes should overload the {@link loadDSNParameter()} method.

Parameters

Throws

\OntologyWrapper\Exception

parseOffsets()

parseOffsets(array $theOffsets) : mixed

Parse connection parameters

This method will parse the provided key/value array and generate a connection URL.

The method will iterate the provided offsets and feed them to the protected {@link parseOffset()} method which will populate an array structured as the result of the {@link parse_url()} function, it will be the duty of this method to generate a data source name from that array.

Derived classes should overload the called methods and not this one.

If the resulting data source name is empty, the method will return FALSE.

Parameters

Returns

Data source name or FALSE if empty.

parseOffset()

parseOffset(\OntologyWrapper\reference $theParameters, string $theOffset, mixed $theValue)

Parse offset

This method will parse the provided offset and populate the provided parameters. The main duty is to load the offset values into the provided parameters array so to create the same result as the {@link parse_url()} function.

The resulting array can have the following elements:

• scheme: The protocol or scheme.
• host: The connection host.
• port: The connection port.
• user: The user code.
• pass: The user password.
• path: The connection path.
• query: The connection options.
• fragment: The URL fragment.

In this class we handle the following offsets:

• {@link kTAG_CONN_PROTOCOL}: The scheme.
• {@link kTAG_CONN_HOST}: The connection host.
• {@link kTAG_CONN_PORT}: The connection port.
• {@link kTAG_CONN_CODE}: The user code.
• {@link kTAG_CONN_PASS}: The user password.
• {@link kTAG_CONN_BASE}: The user pathword.
• {@link kTAG_CONN_COLL}: The user fragmentword.
• {@link kTAG_CONN_OPTS}: The connection options, query.

Derived classes can overload this method to customise the parameters.

Parameters

parseOption()

parseOption(\OntologyWrapper\reference $theParameters, string $theOption, mixed $theValue)

Parse option

This method will parse the provided option and populate the query parameters. The main duty is to load the option into the query element of the provided parameters list as the result of the {@link parse_url()} function.

In this class we load what we find.

Derived classes can overload this method to customise the options.

Parameters

loadDSNParameter()

loadDSNParameter(\OntologyWrapper\reference $theParameters, string $theKey, string $theValue)

Load connection parameters from DSN

This method will load the parameters parsed from the data source name into the current object's offsets, it expects three parameters:

• $theParameters: This array is the result of the {@link parse_url()} function on the data source name:
  • scheme: We set it in {@link kTAG_CONN_PROTOCOL}.
  • host: We set it in {@link kTAG_CONN_HOST}.
  • port: We set it in {@link kTAG_CONN_PORT}.
  • user: We set it in {@link kTAG_CONN_CODE}.
  • pass: We set it in {@link kTAG_CONN_PASS}.
  • path: We set it in {@link kTAG_CONN_BASE}.
  • fragment: We set it in {@link kTAG_CONN_COLL}.
  • query: We load the key/value pairs into {@link kTAG_CONN_OPTS} array.
• $theKey: This parameter represents the offset.
• $theValue: This parameter represents the offset value.

This is the method that derived classes may overload to customise the parameters.

Parameters

preOffsetSet()

preOffsetSet(\OntologyWrapper\reference $theOffset, \OntologyWrapper\reference $theValue) : mixed

Handle offset and value before setting it

This method can be used to manage the offset before passing it to the inherited {@link ArrayObject::OffsetSet()} method.

The method provides the offset and value as references, if the method returns NULL it means that the offset and value must be passed to the inherited {@link ArrayObject::OffsetSet()}; if the method returns any other value, this means that the inherited {@link ArrayObject::OffsetSet()} should be skipped.

In this class we do nothing.

Parameters

Returns

NULL set offset value, other, return.

postOffsetSet()

postOffsetSet(\OntologyWrapper\reference $theOffset, \OntologyWrapper\reference $theValue)

Handle offset and value after setting it

This method can be used to manage the object after calling the {@link ArrayObject::OffsetSet()} method.

In this class we do nothing.

Parameters

preOffsetUnset()

preOffsetUnset(\OntologyWrapper\reference $theOffset) : mixed

Handle offset and value before deleting it

This method can be used to manage the offset before passing it to the inherited {@link ArrayObject::OffsetUnset()} method.

The method provides the offset as reference, if the method returns NULL it means that the offset and value must be passed to the inherited {@link ArrayObject::OffsetUnset()}; if the method returns any other value, this means that the inherited {@link ArrayObject::OffsetUnset()} should be skipped.

In this class we do nothing.

Parameters

Returns

NULL delete offset value, other, return.

postOffsetUnset()

postOffsetUnset(\OntologyWrapper\reference $theOffset)

Handle offset after deleting it

This method can be used to manage the object after calling the {@link ArrayObject::OffsetUnset()} method.

In this class we do nothing.

Parameters

preOffsetExists()

preOffsetExists(\OntologyWrapper\reference $theOffset) : mixed

Handle offset before checking it

This method can be used to manage the offset before passing it to the inherited {@link ArrayObject::OffsetExists()} method.

The method provides the offset as a reference, if the method returns NULL it means that the offset must be passed to the inherited {@link ArrayObject::OffsetExists()}; if the method returns any other value, this will be returned and the inherited {@link ArrayObject::OffsetExists()} will be skipped.

In this class we do nothing.

Parameters

Returns

NULL check offset, other, return.

preOffsetGet()

preOffsetGet(\OntologyWrapper\reference $theOffset) : mixed

Handle offset before getting it

This method can be used to manage the offset before passing it to the inherited {@link ArrayObject::OffsetGet()} method.

The method provides the offset as a reference, if the method returns NULL it means that the offset must be passed to the inherited {@link ArrayObject::OffsetGet()}; if the method returns any other value, this must be returned and the inherited {@link ArrayObject::OffsetGet()} skipped.

In this class we do nothing.

Parameters

Returns

NULL get offset value, other, return.

nestedOffsetExists()

nestedOffsetExists(array $theOffset, mixed $theValue) : boolean

Check if an offset exists

This method is the equivalent of {@link offsetExists()} for nested offsets, the method will traverse the current value until it finds the offset, if at any level an offset is not resolved, the method will return FALSE.

It is assumed that all offsets except the last one must be structures, if that is not the case, the method will return FALSE.

The provided offset must be a valid nested offset, which is a sequence of numerics separated by a period; this check must have been performed by the caller.

Parameters

Returns

TRUE the offset exists.

isOffsetListType()

isOffsetListType(mixed $theOffset) : boolean

Check if offset is a list type

This method will check whether the provided offset is a list type, that is, if it has the {@link kTYPE_LIST} in its data kind, or if the root element is an array.

The method will return TRUE if the provided offset is an array.

If the offset is not a tag, the method will raise an exception.

Parameters

Returns

TRUE if the offset is an array.