MIDAS3-Developper's Guide

From MIDAS Wiki

Jump to: navigation, search

< Back

MIDAS3 is currently under development.

Contents

Download

MIDAS3 is currently hosted on GIT at

 http://public.kitware.com/MIDAS/Midas3.git

Installation

Please see the Installation page: Installation

Introduction

The lasted version of MIDAS is based on the Zend Framework.

To contribute, please read the quick start guide of the Framework: [1]

Architecture

 core
 --configs
 --constant
 --controllers
 ----components
 --layouts
 --models
 ----base
 ----cassandra
 ----dao
 ----pdo
 --views
 ----helpers
 ----partial
 library
 --MIDAS
 --Zend
 --Cassandra
 log
 public
 --css
 --images
 --js
 sql
 tests
 translation

Repertories

  • configs

It contains the config files of the application. The main files are:

    • application.ini
    • core.ini
    • database.ini

You can create local files. The local files won't be erased if you pull the git repertory. (ex: core.local.ini, application.local.ini)

These files are split in 4 categories:

    • global: will be loaded all the time
    • production: will be loaded if the environment is set to production
    • developpment: will be loaded if the environment is development
    • testing: will be loaded if you use phpunit (run tests)
  • constants

Contains the constants of the application

  • controllers

Contains the controllers of the application (MVC model). All the controllers extend the class AppController located in the application directory. (see [2])

  • components

These classes are used mainly in the controllers. They contain tools shared by the application.

  • layouts

Contains the layouts of the application (see [3])

  • models

Contains the Daos and the Models.

  • base

This repertory contains the common methods between Cassandra and Pdo models.

  • cassandra

This repertory contains the Models using Cassandra database system.

  • pdo

This repertory contains the Models using PDO system (MySQL, PostgresSql...).

  • dao

Midas 3 uses Data Access Objects ([4])

  • views

Contains Views (see [5])

  • helpers

The helpers are classes which allow the developer to create classes which will be directly accessible in the views.

  • library

Contains the libraries of the application.

  • log

Where the log are saved.

  • public

Contains all the files that the browser can access directly (images, javascript...).

  • sql

All the sql scripts.

  • tests

See Testing

  • translation

MIDAS3 is multilingual. It uses csv files.

Debug

Logs

Midas 3 uses actively logs. (see [6])

The logs will be saved in the repertory /log

If your application is in debug mode (config application.ini) the minimal log level is INFO

If your application isn't in debug mode (config application.ini) the minimal log level is WARN

Midas 3 will also log directly in your console browser if you install FirePHP+FireBug (firefox) or webug (chrome).

To use the logger:

 $this->getLogger()->info("message");
 $this->getLogger()->warn("message");

Debug function

Zend implement a function that will format the content of a variable and display it:

 Zend_Debug::dump($var);

Debugger

Midas 3 works with the debugger Xdebug.

  • Install Xdebug [7] and [8]
  • Add the remote option (in your php.ini)
 xdebug.remote_enable=On
 xdebug.remote_host="localhost"
 xdebug.remote_port=9000
 xdebug.remote_handler="dbgp"
  • Connect your debugger to xdebug (for example, netbeans: [9])

Errors Handler

Midas 3 uses this feature of Zend. (see [10] and [11] If you throw an exeption, the user will end in the ErrorController

 throw new Zend_Exception("Message");

Elements

Controllers

First see: [12]

All the controllers extend the class AppController. You can create global method in this class.

Usefull things to know:

  • Pass a variable to a the view : $this->view->variable = "foo";
  • Set a layout : $this->_helper->layout->setLayout('foobaz');
  • Disable the layout : $this->_helper->layout->disableLayout();
  • Import and use elements:
 class FooController extends AppController
   {
   public $_models=array('Item','Folder','ItemRevision','Assetstore'); //import some models
   public $_daos=array('Item','Folder','ItemRevision','Bitstream','Assetstore'); //import some daos
   public $_components=array('Test');//import some components

   function IndexAction()
     {
     $itemDao = new ItemDao(); //create a dao
     $this->Folder->getName(); //use Folder Model
     $this->Component->Test->foo(); //use the component Test
     }
   }
  • You can implement an init() method. This method will be called before the action methods.
  • Usefull methods:
    • $this->getLogger(): return the logger object
    • $this->isDebug() : true if the debug mode is enable
    • $this->getEnvironment() : return the environment
    • $this->_getParam('name'): return a get/post param
    • $this->render('foo'): render a view;
    • $this->_forward($action, $controller = null, $module = null, array $params = null) : forward to a different action
    • $this->_redirect($url, array $options = array()): redirect to a different url

Component

Here is a simple component

 <?php
 class TestComponent extends AppComponent
  {
  function test()
   {
   return "Component Test";
   }
  }
 ?>

All the components extend the class AppComponent. You can create global method in this class.

Layout

The default layout is layout.pthml

Models

The model is a representation of the data for an abstracted concept in midas3 (for example, an Item or Folder), specifying the relationships between the given model and other models, along with methods to create, read, update, and delete (CRUD) the model.

Parts of the model definition are at a level of abstraction above any storage mechanism (ModelBase, ModelDAO), and parts of the model definition deal with implementation details for a specific storage type (PDO).

To create a model, you must create a ModelBase, ModelDAO, and at least one implementation of a storage type (e.g., PDO or cassandra).

What follows is an example model taken from the Item model in the Midas3 core.

ModelBase class

The Item model in the core involves the following classes:

in midas3/core/models/base/ItemModelBase.php:

 abstract class ItemModelBase extends AppModel

in midas3/core/models/AppModel.php:

 class AppModel extends MIDASModel

in midas3/core/models/MIDASModel.php:

 class MIDASModel


MIDASModel provides useful high-level functions available to its extending classes, such as save, create, delete, and load, but are abstracted above any particular storage mechanism.

 $this->getLogger()            // return logger object
 $this->initDao($name, $data)  // return the dao $name containing the data set in the array $data 
                               // you use this to set a dao after a sql request)
 $this->link($var, $daoParent, $daoSon)
                               // create a relation between 2 element using the table description.
                               // The $var is the name of the relation.
 $this->removeLink($var, $daoParent, $daoSon) 
                               // remove a relation
 $this->findBy($var,$value)
                               // return an array of DAOs found in the Database where their $var=$value
 $this->getBy($var,$value)     // return a DAOs found in the Database where their $var=$value (first element)
 $this->save($dao)             // save or update a dao
 $this->delete($dao)           // delete a dao
 $this->compareDao($dao1,$dao2)// return true if the 2 dao are equals
 $this->load($key)             // return a dao based of its primary $key

ItemModelBase should define all global methods for this model, but not include any implementation details specific to any storage mechanism (e.g., no sql at this level).

When you create a modelbase, the first thing to do is to describe the associated table:

  • first, set the table name in the variable $_name
  • then set the primary key column name in the variable $_key
  • finally, you have to describe the table in the variable $_mainData
    • You set all the columns of the table:
 'item_id'=> array('type'=>MIDAS_DATA),
    • Then you set all the relations with this tables.

Many to Many

 'folders' =>  array('type'=>MIDAS_MANY_TO_MANY, 'model'=>'Folder', 'table' => 'item2folder', 'parent_column'=> 'item_id', 'child_column' => 'folder_id'),

for example:

 $this->_name = 'item';
 $this->_key = 'item_id';
 $this->_mainData = array(
     'item_id' =>  array('type' => MIDAS_DATA),
     'name' =>  array('type' => MIDAS_DATA),
     ... (removed for brevity) ...,
     'folders' =>  array('type' => MIDAS_MANY_TO_MANY, 'model' => 'Folder', 'table' => 'item2folder', 'parent_column' => 'item_id', 'child_column' => 'folder_id'),
     'revisions' =>  array('type' => MIDAS_ONE_TO_MANY, 'model' => 'ItemRevision', 'parent_column' => 'item_id', 'child_column' => 'item_id'),
     ... (removed for brevity) ...,
     );

The Item model has a storage name (table name in sql rdbms) of item, with a key of item_id.

The Item model has a relationship to the Folder model, since it is of type MIDAS_MANY_TO_MANY there is a many to many relationship of Items to Folders, specified by the join table item2folder, with the Item linked by the item_id to the Folder linked by the folder_id column.

The MIDAS_X_TO_Y specifies the relationship between the current model X, and the related model Y. parent_column is the column specifying the id of the current model, child_column is the column specifying the id of the related model.

Through this specification, the ItemDAO will automagically have the method getFolders(), which will return all for the Folders defined for an Item.

ModelDAO class

You must create a DAO class for your model. For example, the Item model in the core involves the following classes:

in midas3/core/models/dao/ItemDao.php:

 class ItemDao extends AppDao
   {
   public $_model = 'Item';
   }

in midas3/core/models/GlobalDao.php:

 class AppDao extends MIDAS_GlobalDao

in midas3/core/models/AppDao.php:

 class MIDAS_GlobalDao

MIDAS_GlobalDao uses the description of the table located in the modelbase to work. The dao generates "magic functions" to provide getters and setters for your dao-s. For example, the ItemDao will have the methods:

 getItemId();            // return item_id value
 setItemId($value);      // set the item_id
 getName();              // return the name
 setName($value);        // set the name
 getFolders();           // return an array of FolderDao-s

MIDAS_GlobalDao provides useful functions available to its extending classes:

 $this->getLogger();     // return logger object
 $this->getModel();      // return the model linked with this dao
 $this->getModel($name); // return the model $name
 $this->getKey();        // return the key value

ModelPDO class

For a model you will need at least one concrete implementation class specific to a storage mechanism, such as a PDO class.

PDO classes are used for sql based rdbms such as mysql or postgresql.

For example:

in midas3/core/models/pdo/ItemModel.php

 class ItemModel extends ItemModelBase

A PDO class is the appropriate level to define custom model functionality that uses any sql.

See here for the documentation to create a select query: [13]


Views

Please see [14]

Usefull method/variable:

  • $this->webroot :path of the application
  • $this->t($text): translate some text

Helper See [15]

Partial A partial is a view import.

Translate

We wanted MIDAS to be multilingual. For now, the language of the website is a config file. When you create a view, please always call the translate function : <?php echo $this->t('Some text') ?> It will show "Some text" unless you set a different language in the config file.

The translations are saved in cvs files in the translation repertory.

Registry

"A registry is a container for storing objects and values in the application space. By storing the value in a registry, the same object is always available throughout your application. This mechanism is an alternative to using global storage." http://framework.zend.com/manual/en/zend.registry.using.html

Here is the list of available objects:

Configuration

  • Zend_Registry::get('configGlobal'): Configuration set in the file application.ini (global part)
  • Zend_Registry::get('configCore'): Configuration set in the file core.ini
  • Zend_Registry::get('config'): Configuration set in the file application.ini (current environment part)
  • Zend_Registry::get('configDatabase'): Configuration set in the file database.ini (current environment part)
  • Zend_Registry::get('configsModules'): Modules' Configurations
  • Zend_Registry::get('modulesEnable'): List of the enabled modules

Application variables (you shoud use them)

  • Zend_Registry::get('userSession'): User session
  • Zend_Registry::get('notifier'): Notifier (Callbacks and Events between modules)
  • Zend_Registry::get('logger'): Logger object (Zend_Registry::get('logger')->info('message'))

Core (you shouldn't use them)

  • Zend_Registry::get('dbAdapter'): Database object. This object allows you to query the database (Zend_Registry::get('dbAdapter')->query('Select * from'))
  • Zend_Registry::get('models'): List of loaded models
  • Zend_Registry::get('components'): List of loaded components
  • Zend_Registry::get('forms'): List of loaded forms
  • Zend_Registry::get('translater'): Core Translater object. see http://framework.zend.com/manual/en/zend.translate.using.html
  • Zend_Registry::get('translatersModules'): List of Module's translater objects

Loading Models and Components from Modules

Sometimes you may wish to use models or components that live in other modules. The $_models = ... syntax won't work here. Instead, we have the ModelLoader and ComponentLoader classes to help.

MIDAS_ModelLoader

This class lets you access models that live in any module. This class is included globally, so you can call it from any of your code for free:

 $modelLoader = new MIDAS_ModelLoader();

If we wanted to load the core item model, we would then call:

 $itemModel = $modelLoader->loadModel('Item');

And if we then wanted to load the user api model from the api module, we just pass the module name as the optional second parameter to the loadModel function:

 $userApiModel = $modelLoader->loadModel('Userapi', 'api');
 $apiKey = $userApiModel->getByAppAndUser('Default', $userDao)->getApikey();

MIDAS_ComponentLoader

This class works just like the model loader, but it loads components:

 $componentLoader = new MIDAS_ComponentLoader();
 $authenticationComponent = $componentLoader->loadComponent('Authentication', 'api');
Personal tools