How to write database class definitions:

The general idea is to provide MidCOM with a way to hook into every database interaction between the component and the Midgard core.

Since PHP does not allow for multiple inheritance (which would be really useful here), a decorator pattern is used, which connects the class you actually use in your component and the original MgdSchema class while at the same time routing all function calls through midcom_core_dbaobject.

The class loader does not require much information when registering classes: An example declaration looks like this:

Array
(
    'midgard_article' => 'midcom_db_article'
)

The key is the MgdSchema class name from that you want to use. The class specified must exist.

The value is the name of the MidCOM base class you intend to create. It is checked for basic validity against the PHP restrictions on symbol naming, but the class itself is not checked for existence. You must declare the class as listed at all times, as typecasting and detection is done using this metadata property in the core.

Inherited class requirements

The classes you inherit from the intermediate stub classes must at this time satisfy one requirement: You have to declare the midcom and mgdschema classnames:

class midcom_db_article
    extends midcom_core_dbaobject
{
     public $__midcom_class_name__ = __CLASS__;
     public $__mgdschema_class_name__ = 'midgard_article';

package midcom.services

 Methods

_create_class_definition_filename (string $component, $filename)

Little helper which converts a component / filename combination into a fully qualified path/filename.

The filename is assigned to the $_class_definition_filename member variable of this class.

Parameters

$component

stringThe name of the component for which the class file has to be loaded. The path must resolve with the component loader unless you use 'midcom' to load MidCOM core class definition files.

$filename

_read_class_definition_file ()

This helper function loads a class definition file from the disk and returns its contents.

The source must be stored in the $_class_definition_filename member.

It will translate component and filename into a full path and delivers the contents verbatim.

Returns

stringThe contents of the file.

_validate_class_definition_list (array $definition_list)

This helper function validates a class definition list for correctness.

Where possible, missing elements are completed with sensible defaults.

Parameters

$definition_list

arrayA reference to the definition list to verify.

get_component_classes ($component)

Parameters

$component

get_component_for_class (string $classname)

Get component name associated with a class name to get its DBA classes defined

Parameters

$classname

stringClass name to load a component for

Returns

stringcomponent name if found for the class, false otherwise

get_mgdschema_class_name_for_midcom_class (string $classname)

Get an MgdSchema class name for a MidCOM DBA class name

Parameters

$classname

stringThe MidCOM DBA classname to check

Returns

stringThe corresponding MidCOM DBA class name, false otherwise.

get_midcom_class_name_for_mgdschema_object (object $object)

Get a MidCOM DB class name for a MgdSchema Object.

Parameters

$object

object&$object The object to check

Returns

stringThe corresponding MidCOM DB class name, false otherwise.

get_midgard_classes ()

is_mgdschema_object (object $object)

Simple helper to check whether we are dealing with a MgdSchema or MidCOM DBA object or a subclass thereof.

Parameters

$object

objectThe object to check

Returns

booleantrue if this is a MgdSchema object, false otherwise.

is_midcom_db_object (object $object)

Simple helper to check whether we are dealing with a MidCOM Database object or a subclass thereof.

Parameters

$object

object&$object The object to check

Returns

booleantrue if this is a MidCOM Database object, false otherwise.

load_classes ($component, $filename, $definition_list)

This is the main class loader function.

It takes a component/filename pair as arguments, the first specifying the place to look for the latter.

For example, if you call load_classes('net.nehmer.static', 'my_classes.inc'), it will look in the directory MIDCOM_ROOT/net/nehmer/static/config/my_classes.inc. The magic component 'midcom' goes for the MIDCOM_ROOT/midcom/config directory and is reserved for MidCOM core classes and compatibility classes.

Parameters

$component

$filename

$definition_list

load_component_for_class (string $classname)

Load a component associated with a class name to get its DBA classes defined

Parameters

$classname

stringClass name to load a component for

Returns

booleantrue if a component was found for the class, false otherwise

load_mgdschema_class_handler (string $classname)

This function is required by the DBA interface layer and should normally not be used outside of it.

Its purpose is to ensure that the component providing a certain DBA class instance is actually loaded. This is necessary, as the class descriptions are loaded during system startup now, but the full-blown DBA class is not available at that point (for performance reasons). It will load the components in question when requested by any operation in the system that might have to convert to a yet unloaded class, mainly this covers the type conversion of arbitrary objects retrieved by the GUID object getter.

Parameters

$classname

stringThe name of the MidCOM DBA class that must be available.

Returns

booleanIndicating success. False is returned only if you are requesting unknown classes and the like. Component loading failure will result in an HTTP 500, as always.

_register_loaded_classes (array $definitions, string $component)

Simple helper that adds a list of classes to the loaded classes listing.

This creates a mapping of which class is handled by which component. The generic by-GUID loader and the class conversion tools in the dbfactory require this information to be able to load the required components on-demand.

Parameters

$definitions

array&$definitions The list of classes which have been loaded along with the meta information.

$component

stringThe component name of the classes to add

 Properties

 

string $_class_definition_filename

The filename of the class definition currently being read.
 

Array $_mgdschema_class_handler

A mapping storing which component handles which class.

This is used to ensure that all MidCOM DBA main classes are loaded when casting MgdSchema objects to DBA objects. Especially important for the generic by-GUID object getter.

 

Array $_midgard_classes

List of all midgard classes which have been loaded.

This list only contains the class definitions that have been used to construct the actual helper classes.