This class is a Factory that is responsible for loading and establishing the interface to a MidCOM Component.

Working with components

Normally, two things are important when you deal with other components:

First, if you want to list other components, or for example check whether they are available, you should use the component manifest listing, known as $manifests. It gives you all meta-information about the components.

This should actually suffice for most normal operations.

If you develop framework tools (like administration interfaces), you will also need access to the component interface class, which can be obtained by get_component_class(). This class is derived from the component interface baseclass and should give you everything you need to work with the component and its information itself.

Other then that, you should not have to deal with the components, perhaps with the only exception of is_loaded() and load() to ensure other components are loaded in case you need them and they are not a pure-code library.

Loading components

When the component loader receives a request it roughly works in three stages:

  1. Verify that the given component is valid in terms of the MidCOM Specification. This will check the existence of all required SnippetDirs.
  2. Load all Snippets related with the MidCOM Interface Concept Classes and instantiate the MidCOM and Component concept classes, initialize the Component. Check whether all required concept classes exist.
  3. Return the various interface concepts upon each request from the framework.

Stage 1 will do all basic sanity checking possible before loading any snippets. It will check for the existence of all defined sub-SnippetDirs that are required for the system to work. If anything is missing, step 1 fails and the componentloader refuses to load the component.

Stage 2 will then load the interfaces.php file from the midcom directory. The existence of all required Interface classes is then checked. If this check is successful, the concrete classes of the various interface concepts are instantiated and stored internally. The component is initialized by the call to MIDCOM::initialize() which should load everything necessary.

Stage 3 is the final stage where the loader stays in memory in order to return references (!) to the loaded component's Interface Classes upon request.

In case you need an instance of the component loader to verify or transform component paths, use the function midcom::get('componentloader'), which returns a reference to the loader.

package midcom.helper
see \global\midcom_application::get_component_loader()

 Methods

get_all_manifest_customdata (string $component, boolean $showempty)

This small helper builds a complete set of custom data associated with a given component identifier.

In case a given component does not have the key set and the boolean parameter is set to true, an empty array is added implicitly.

Parameters

$component

stringThe custom data component index to look for.

$showempty

booleanSet this flag to true to get an (empty) entry for all components which don't have customdata applicable to the component index given. This is disabled by default.

Returns

ArrayAll found component data indexed by known components.

get_component_dependencies (string $component)

Get list of component and its dependencies depend on

Parameters

$component

stringName of a component

Returns

arrayList of dependencies

get_component_icon ($component, $provide_fallback)

Parameters

$component

$provide_fallback

get_component_version ($component)

Parameters

$component

get_interface_class (string $path)

Returns a reference to an instance of the specified component's interface class.

The component is given in $path as a MidCOM path. Such an instance will be cached by the framework so that only one instance is always active for each component. Missing components will be dynamically loaded into memory.

Parameters

$path

stringThe component name.

Returns

\midcom_baseclasses_components_interfaceA reference to the concept class in question or null if the class in question does not yet support the new Interface system.

is_core_component (string $component)

Checks if component is a part of the default MidCOM distribution or an external component

Parameters

$component

stringComponent to check

is_installed (string $path)

Returns true if the component identified by the MidCOM path $url is installed.

Parameters

$path

stringThe component to be queried.

Returns

booleantrue if it is loaded, false otherwise.

is_loaded (string $path)

Returns true if the component identified by the MidCOM path $url is already loaded and available for usage.

Parameters

$path

stringThe component to be queried.

Returns

booleantrue if it is loaded, false otherwise.

list_loaded_components ()

Retrieve a list of all loaded components.

The Array will contain an unsorted collection of MidCOM Paths.

Returns

ArrayList of loaded components

load (string $path)

This function will invoke _load directly.

If the loading process is unsuccessful, it will throw midcom_error.

Parameters

$path

stringThe component to load explicitly.

load_all_manifests ()

This function is called during system startup and loads all component manifests.

The list of manifests to load is determined using a find shell call and is cached using the memcache cache module.

This method is executed during system startup by the framework. Other parts of the system must not access it.

load_graceful (string $path)

This function will invoke _load directly.

If the loading process is unsuccessful, false is returned.

Parameters

$path

stringThe component to load explicitly.

Returns

booleanIndicating success.

load_library (string $path)

This will load the pure-code library denoted by $path.

It will return true if the component truly was a pure-code library, false otherwise. If the component loader cannot load the component, midcom_error will be thrown.

Common example:

midcom::get('componentloader')->load_library('midcom.helper.datamanager2');

Parameters

$path

stringThe name of the code library to load.

Returns

booleanIndicates whether the library was successfully loaded.

path_to_prefix (string $path)

Helper, converting a component path (net.nehmer.blog) to a class prefix (net_nehmer_blog).

Parameters

$path

stringInput string.

Returns

stringConverted string.

path_to_snippetpath (string $component_name)

Helper, converting a component path (net.nehmer.blog) to a snippetpath (/net/nehmer/blog).

Parameters

$component_name

stringInput string.

Returns

stringConverted string.

process_pending_notifies ()

This function processes all pending notifies and flushes the pending list.

It is called automatically during MidCOM shutdown at the end of the request.

All Notifies for objects which can't be refreshed will be ignored silently (but logged of course). Deleted objects are of course not refreshed.

This function can only be called once during a request.

register_component ($name, $path)

Parameters

$name

$path

trigger_watches (int $operation, mixed $object)

This is called by the framework whenever watchable events occur.

The object referenced by $object may be null where appropriate for the operation in question, it is not taken by reference.

Call this only if the operation in question has completed successfully.

The component handlers can safely assume that it is only called once per object and operation at the end of the request.

This latter fact is important to understand: Watches are not executed immediately, instead, they are collected throughout the request and executed during midcom_application::finish() exactly once per instance. The instance is refreshed before it is actually sent to the watchers using a refresh member function unless the object has been deleted, then there will be no refresh attempt.

An instance in this respect is a unique combination of class type and guid values.

A watchable object must therefore have the following properties:

  • string $guid The guid identifying the object.
  • boolean refresh() A method used to refresh the object against its datasource.

So, two instances are equal if and only if they are of the same class and have the same $guid property value.

Parameters

$operation

intThe operation that has occurred.

$object

mixedThe object on which the operation occurred. The system will do is_a checks against any registered class restriction on the watch. The object is not taken by-reference but refreshed before actually executing the hook at the end of the request.

validate_url (string $path)

Will validate the given MidCOM Path $path for syntactical correctness.

Currently this is a RegEx check that checks for invalid characters in $path, so validate_url does explicitly not check whether the referenced component does exist and whether it is structurally valid.

Parameters

$path

stringThe path to be checked.

Returns

booleanTrue if valid, false otherwise.

_get_manifests ()

This function is called from the class manifest loader in case of a cache miss.
todo investigate if we should unset the package.xml part of the arrays and serialize them

_load (string $path)

This function will load the component specified by the MidCOM path $path.

If the component could not be loaded successfully due to integrity errors (missing SnippetDirs, Classes, etc.), it will return false.

Parameters

$path

stringThe component to load.

Returns

booleanIndicating success.

_register_manifest (\midcom_core_manifest $manifest)

Register manifest data.

All default privileges are made known to ACL, the watches are registered

Parameters

$manifest

\midcom_core_manifestthe manifest object to load.

 Properties

 

array $manifests

This lists all available components in the systems in the form of their manifests, indexed by the component name.

Whenever possible you should refer to this listing to gain information about the components available.

This information is loaded during startup.

see \midcom_core_manifest
 

array $_component_paths

Mapping for components paths not included in the main midcom directory hierarchy
 

array $_interface_classes

This is a part of the component cache.

It stores references to the interface classes of the different loaded components, indexed by their MidCOM Path.

see \midcom_baseclasses_components_interface
 

Array $_loaded

This indexed array stores the MidCOM paths of all loaded components.

Its elements are used as keys for the cache storage.

 

array $_tried_to_load

This array contains a list of components that were tried to be loaded.

The components are added to this list even if the system only tried to load it and failed. This way we protect against duplicate class errors and the like if a defective class is tried to be loaded twice.

The array maps component names to loading results. The loading result is either false or true as per the result of the load call.

 

array $_watch_notifications

This is an array containing a list of watches that need to be executed at the end of any given request.

The array is indexed by artificial keys constructed out of the watched object's class type and guid values. The array always contains the object instance in the first element, and all components that need to be notified in the subsequent keys.

 

array $_watches

This array contains all registered MidCOM operation watches.

They are indexed by operation and map to components / libraries which have registered to classes. Values consist of an array whose first element is the component and subsequent elements are the types involved (so a single count means all objects).