Nooku Framework

This wiki has been updated for version 0.7-alpha4

1. Introduction

KService merges the KFactory and KIdentifier packages and completes the Nooku Framework's SOA (Service Oriented Architecture) with the introduction of a service container.

A Service Container (or dependency injection container) standardizes and centralizes the way objects are constructed. The container makes your life easier, is super fast, and emphasizes an architecture that promotes reusable and decoupled code.

KService allows you to create objects based on identifiers. Even if the class doesn't exist KService will create a default object for you. This makes creating extensions very easy as you can specialise a class at any point during your development cycle.

Example : $obj = KService::get('com://site/harbour.view.boats');

2. Identifiers conventions

Identifiers are URL's, or uniform resource locators and follow the RFC 1738 (http://www.ietf.org/rfc/rfc1738.txt)

type:[//application/]package.path.name. 

Examples : - koowa:controller.service - com://admin/articles.model.articles - com://site/articles.model.articles - mod://site/banners.html - plg:system.koowa

In templates you can make use of the @service([...]) alias to get an object from the service container.

KService::get can be used instead of $this->getService for getting an object from the service container within an object that doesn't implement KObjectServiceable, e.g. the entry point file of a component which instantiates the dispatcher. In any other circumstances, $this->getService should be used instead.

2.1 Using get() and tmp()

When you use get(), KService will only create a new object if it doesn't already exist in the object store, and also store it in the object store afterwards. Use tmp() will avoid the object store all together. It wont use an existing object with your identifier, nor save it afterwards.

This looks like a small difference on the outside, but it's important to know when to use each.

Examples:

• get()

  • KFactory::get('admin::com.harbour.model.boats')->limit(10)->getList()
  • KFactory::get('admin::com.harbour.model.boats')->getList()
  • In this example, both calls return the same list, as the first call store the list in the object. And the second call fetch the same model instance, with the list intact.

• tmp()

  • KFactory::tmp('admin::com.harbour.model.boats')->limit(10)->getList()
  • KFactory::tmp('admin::com.harbour.model.boats')->getList()
  • The default value to the limit state are 20, so the first call will return a list with 10 items, but the second will be 20 items. This is because you're creating two separate instances of the boats model object, so the states set in the first call, wont affect the second call.

2.2 Using mix()

When using mix(), the factory will register a list of mixins for an identifier or a list of identifiers. From then on any object with its identifier registered with KFactory mixin will be mixed by the associated mixins.

KFactory::mix('admin::com.harbour.model.boat', 'admin::com.harbour.mixin.engine');
$boat = KFactory::tmp('admin::com.harbor.model.boat');

$boat is mixed with admin::com.harbour.mixin.engine mixin

For more about mixins see the KMixin package documentation. (TODO : add link)

2.3 Using identify()

The identify function accepts various types of parameters and returns a valid identifier. Parameters can either be an object that implements KFactoryIdentifiable, or a KIndentifierInterface, or valid identifier string. Function will also check for identifier mappings (see map()) and return the mapped identifier.

The function is very handy to get a valid identifier from an string, objec, etc. You can basically pass this anything and he will return you either an exception or a valid KIndentifier object. In Koowa this is use for setters that are setting an object in a class. For example :

/**
 * Method to set a table object attached to the model
 *
 * @param       object|string   A KTable object or a table identifier
 * @throws      KDatabaseRowsetException  If the identifier is not a table identifier
 * @return      KModelTable
 */
 public function setTable($table)
 {
    $identifier = KFactory::identify($table);

    if($identifier->path[0] != 'table') {
        throw new KModelException('Identifier: '.$identifier.' is not a table identifier');
     }

     $this->_table = $identifier;
    return $this;
 }