MidCOM DBA Object API

1. Object construction and database retrival
2. Tree related functions
3. Persistence Management
4. Record extensions Management
1. Object parameters
2. Object attachments
3. Metadata
5. Privilege management
6. Legacy compatibility functions
7. Event handling callbacks
8. DBA-specific functions
9. Internal members and methods
1. Base class exec handlers
2. Legacy API exec handlers
3. Other private API functions
4. Internal member variables

This document describes the API of all auto-generated MidCOM DBA classes. It will divide the large API provided by MidCOM DBA into several distinct parts to make it easier for you to find what you are actually looking for.

...

Todo:

• How to create such classes?
• Add a documentation of the concrete MidCOM delivered baseclasses.

The following API reference is build on the example of the class generated for NewMidgardArticles which is called midcom_baseclasses_database_article. Be aware, that the actual implementation of that class adds some additional functions to those automatically generated, they are not outlined here.

Object construction and database retrival

With MidCOM DBA it is quite easy to retrieve objects from the database. You do not use have the get_by_id() and get_by_guid() functions explicitly. Instead you can just use the constructor to do this in a single step.

• midcom_baseclasses_database_article(mixed $id = null); - Class constructor
• object get_get_by_guid(string $guid); - Update the current object with another record
• object get_get_by_id(int $id); - Update the current object with another record
• object get_get_by_path(string $path); - Update the current object with another record
• static midcom_core_querybuilder new_query_builder (); - Get a clean QueryBuilder instance for the DBA base class, can be called statically.

Tree related functions

These functions allow you to navigate within the MidCOM content tree.

• object get_parent(); - Get the immediate parent object (cached)
• string get_parent_guid(); - Get the immediate parent object guid (cached)

Persistence Management

These functions will allow you to control the database record accociated with the current object instance. This currently includes creation, updating and removal of database entries.

• bool create(); - Create a new record
• bool delete(); - Delete an existing record
• bool update(); - Update an existing record

Record extensions Management

MidCOM DBA keeps the notion of record extensions, which can be either string-based parameters or binary large object attachments.

Object parameters

Note, that the single parameter/listparameter combo of the legacy Midgard API has been taken apart into several functions responsible for the various "operations", which makes error handling far cleaner.

• bool delete_parameter(string $domain, string $name); - Delete an existing parameter
• string get_parameter(string $domain, string $name); - Get a parameter value
• bool list_parameters(string $domain = null); - List existing parameters
• string set_parameter(string $domain, string $name, string $value); - Set a parameter value

Object attachments

As with parameters, these functions have been consolidated a bit, mainly making error handling clearer.

• midcom_baseclasses_database_attachment create_attachment(string $name, string $title, string $mimetype); - Create a new attachment
• bool delete_attachment(string $name); - Delete an existing attachment
• midcom_baseclasses_database_attachment get_attachment(string $name); - Retrieve an attachment by its name
• midcom_core_querybuilder get_attachment_qb(); - Retrieve a query builder to search for attachments
• Array list_attachments(); - List existing attachments
• resource open_attachment(string $name, string $mode = 'w'); - Open an existing attachment for file I/O

Metadata

These functions provide a quick interface to certain parts of the MidCOM Metadata Framework.

• midcom_helper_metadata & get_metadata(); - Retrieve a reference to the metadata object
• bool is_object_visible_onsite(); - Checks wether the object may be shown according to current metadata

Privilege management

For additional information about privilege management, see the documentation of the Authentication service and the privilege object.

• bool can_do(string $privilege, midcom_core_user $user = null); - Checks for a privilege.
• static bool can_do(string $privilege, midcom_core_user $user = null); - Checks for a privilege assigned to a user generally for this class.
• midcom_core_privilege create_new_privilege_object(string $name, mixed $assignee = null, int $value = MIDCOM_PRIVILEGE_ALLOW, string $classname = ''); - Factory method for creating midcom_core_privilege instances
• midcom_core_privilege get_privilege(string $privilege, mixed $assignee, string $classname = ''); - Retrieve a privilege record
• Array get_privileges(); - List privilege records
• void require_do(string $privilege, string $message = null); - Enforces a privilege.
• static void require_user_do(string $privilege, string $message = null); - Checks for a privilege assigned to a user generally for this class.
• bool set_privilege(midcom_core_privilege $privilege); - Create a new privilege record
• bool set_privilege(string $name, mixed $assignee = null, int $value = MIDCOM_PRIVILEGE_ALLOW, string $classname = ''); - Create a new privilege record
• bool unset_privilege(string $privilege, mixed $assignee, string $classname = ''); - Sets a privilege to INHERIT.
• bool unset_privilege(midcom_core_privilege $privilege); - Sets a privilege to INHERIT.
• bool unset_all_privileges(); - Sets all privileges to INHERIT.

Legacy compatibility functions

• string guid(); - Returns the GUID of the object
• int createattachment(string $name, string $title, string $mimetype); - Create a new attachment object
• bool deleteattachment(string $name); - Delete an attachment by its name
• midcom_baseclasses_database_attachment getattachment(string $name); - Get an attachment by its name
• fetchable listattachments(); - Returns a fetchable which lists all attachments
• resource openattachment(string $name, string $mode = 'w'); - Open an attachment for file I/O
• mixed parameter(string $domain, string $name, string $value); - Gets, sets or unsets a parameter
• bool serveattachment(string $name); - Serve an attachment by its name

Event handling callbacks

The functions listed here allow components to easily influence the behavoir of the object through subclassing without having to duplicate or call code from the framework itself. The framework just calls you. Just never forget to call the parent function unconditionally at the start of your event handler implementation.

• bool _on_creating(); - Called before the object is created
• void _on_created(); - Called after successful object creation
• bool _on_deleting(); - Called before the object is deleted
• void _on_deleted(); - Called after successful object deletion
• bool _on_loaded(); - Called after the object has been loaded from the database
• static bool _on_prepare_exec_query_builder(midcom_core_querybuilder &$qb); - Called before the execution of a query builder for the type
• static void _on_prepare_new_query_builder(midcom_core_querybuilder &$qb); - Called after the construction of a query builder for the type
• static void _on_process_query_result(Array &$result); - Called after the execution of a querybuilder
• bool _on_updating(); - Called before the object is updated
• void _on_updated(); - Called after successful object update

DBA-specific functions

These functions manipulate the DBA layer itselfe and are usually called statically. They are of no importance for normal object operation.

• static Array get_class_magic_default_privileges(); - Called once to retrieve default privileges for magic assignees
• string get_parent_guid_uncached(); - Determines the GUID of the parent object to populate the parent cache

Internal members and methods

Base class exec handlers

These functions warp calls to parent functions under a different name to allow the DBA wrappers to call the base class methods of the same name (without the prefix of course from the outside.

• bool __exec_create_();
• bool __exec_delete_();
• bool __exec_update_();
• bool __exec_get_by_guid($guid);
• bool __exec_get_by_id($id);
• bool __exec_get_by_path($path);

Legacy API exec handlers

As above, but for the legacy API.

• fetchable __exec_listattachments();

Other private API functions

• _load_from_database($id); - Called from the constructor, does the actual object loading

Internal member variables

• string $__table__; - Contains the name of the table where this record is stored
• string $__old_class_name__; - Contains the pre-MgdSchema Midgard class name (may be null)
• string $__new_class_name__; - Contains the MgdSchema base class name
• string $__midcom_class_name__; - Contains the MidCOM DBA base class name
• string $__midcom_generator__; - Contains the name of the class that generated the DBA baseclass
• string $__midcom_generator_version__; - Contains the version of the class that generated the DBA baseclass