$mDictionary
$mDictionary : \OntologyWrapper\Dictionary
Dictionary.
This protected data member holds the data dictionary reference.
Ontology object
Objects derived from this abstract class hold two types of data:
The main purpose of this class is to ensure that all persistent data elements are referenced, annotated and documented in an ontology.
Persistent data is stored as key/value pair elements of the inherited array, the key part of the elements we call by convention offset, these offsets, in this class, represent a reference to an object of the ontology that holds all the necessary information to identify, describe and validate the value part of the array element pairs.
This class implements the bridge between object persistent data and the ontology, ensuring that all data holds a reference to the ontology, which, itself, is implemented by objects derived from this same class: this means that the whole system is self sufficient and self documenting.
Offsets can be uniquely identified in two ways: by native identifier, which is an integer value which may change across implementations, and a global identifier, which is a sring that will not change across implementations. This class provides a transparent interface that allows referring to offsets both by their native identifier or by their global identifier. Offsets, however, will only hold the native identifier, which means that all persistent data offsets must be integers. This is because global identifiers may become large strings, which poses a problem if these are used as field names for data stored in a persistent container.
Whenever the object is provided an offset, if this is a string, it will be fed to a protected method, {@link resolveOffset()}, which will check if the string represents the global identifier of an ontology Tag object, in that case, the method will return the Tag's native integer identifier which will be used as the data offset. The class features a public method, {@link InternalOffsets()}, that returns the list of exceptions.
This means that to ensure referential integrity it is advisable to use integer constants as offsets when available, or string offsets if the integer constant is not known or available.
The resolution of these offsets is provided by a {@link Dictionary} object which records all the Tag objects of the ontology which are the entities that all offsets reference: persistent data offsets represent these Tag native identifiers, while these Tag object global identifiers are decoded by the {@link Dictionary} object to retrieve the corresponding integer native identifier.
The class declares the {@link __toString()} method as virtual, it is essential that all derived classes implement this method which should return the current object's global identifier string. The global identifier of an object can be considered its signature or unique identifier, although a global identifier not need to be unique; all objects derived from this class, just as the Tag object described above, must feature a global identifier, which may or may not coincide with their native identifier.
The class declares a method, {@link reference()}, which returns the current object's reference, this will generally be the value of the {@link kTAG_NID} offset. If the offset is not set, the method will raise an exception. This method will be put to use by derived classes: when providing an object to an offset expecting an object reference, by using this method one can be assured the provided object does have a reference.
Finally, the class features an object tracersal interface that can be used to verify and cast the object's persistent data.
$mDictionary : \OntologyWrapper\Dictionary
Dictionary.
This protected data member holds the data dictionary reference.
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:
The method will raise an exception if the dictionary holds any other type except the above.
| mixed | $theDictionary | New dictionary or NULL. |
| boolean | $getOld | TRUE get old value. |
Object data dictionary.
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.
Object reference.
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.
| string | $theOffset | Data offset. |
| boolean | $doAssert | Assert offset tag reference. |
Resolved offset.
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.
| mixed | $theOffset | Offset. |
Offset value or NULL.
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.
| string | $theOffset | Offset. |
| mixed | $theValue | Value to set at offset. |
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.
| string | $theOffset | Offset. |
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:
In this class we return:
List of internal offsets.
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:
In this class we return an empty array.
List of external offsets.
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:
In this class we return an empty array.
List of dynamic offsets.
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:
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.
List of unmanaged offsets.
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.
List of default offsets.
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:
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.
| \OntologyWrapper\DictionaryObject | $theDictionary | Data dictionary. |
| mixed | $theOffset | Offset. |
| string | $theType | Receives data type. |
| array | $theKind | Receives data kind. |
| mixed | $theMin | Receives minimum data range. |
| mixed | $theMax | Receives maximum data range. |
| string | $thePattern | Receives data pattern. |
| boolean | $doAssert | If TRUE assert offset. |
TRUE if the tag was resolved, or NULL.
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:
| array | $theStrings | Language strings property. |
| string | $theLanguage | Selected language code. |
The string in the provided language.
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.
| \OntologyWrapper\reference | $theShape | Shape. |
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.
| mixed | $theOffset | Offset. |
| array | $theValue | Current value. |
| mixed | $theFound | Found value. |
Offset value or NULL.
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:
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.
| string | $theOffset | Offset. |
| mixed | $theValue | Value to set at offset. |
| string | $theRootOffset | Receives root offset. |
| array | $theRootValue | Receives root value. |
| string | $theCurrentOffset | Receives current offset. |
| array | $theCurrentValue | Current level value. |
The updated nested structure.
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:
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.
| string | $theOffset | Offset. |
| string | $theRootOffset | Receives root offset. |
| array | $theCurrentValue | Current level value. |
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:
| \OntologyWrapper\reference | $theSource | Reference to the source structure. |
| \OntologyWrapper\reference | $theDestination | Reference to the destination array. |
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.
| \OntologyWrapper\reference | $theOffset | Offset reference. |
NULL check offset, other, return.
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.
| \OntologyWrapper\reference | $theOffset | Offset reference. |
NULL get offset value, other, return.
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.
| \OntologyWrapper\reference | $theOffset | Offset reference. |
| \OntologyWrapper\reference | $theValue | Offset value reference. |
NULL set offset value, other, return.
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.
| \OntologyWrapper\reference | $theOffset | Offset reference. |
NULL delete offset value, other, return.
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.
| array | $theOffset | Offsets path. |
| mixed | $theValue | Parent offset value. |
TRUE the offset exists.
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.
| mixed | $theOffset | Offset. |
TRUE if the offset is an array.
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.
| \OntologyWrapper\reference | $theOffset | Offset reference. |
| \OntologyWrapper\reference | $theValue | Offset value reference. |
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.
| \OntologyWrapper\reference | $theOffset | Offset reference. |