phTagr uses the flexible and easy to learn PHP framework  CakePHP 1.2 which comes with a  Model-View-Control architecture.

  1. Where to get help?
  2. Source
    1. Directories
    2. Coding Convention
    3. An example
  3. Debugging
  4. HowTo …
    1. Add a new action to a controller
    2. Get data from the controller to the view?
    3. Get data from the request?
    4. Retrieve and save data from/to a model?
    5. Enhanced debugging output with debug_kit plugin

To understand the code of phtagr it is important to understand the basic principle of MVC and CakePHP (see  Understanding-Model-View-Controller,  A-Typical-CakePHP-Request, and  Basic-Principles-of-CakePHP). However, it is quite simple to get into the code and this page will lead you to the major and important sites and hints.

Where to get help?

Source

Directories

The source has a special file structure and reflects to the MVC architecture. See also  http://book.cakephp.org/view/20/The-App-Folder

  • cake - CakePHP framework files
  • phtagr (or app) - phtagr files
    • config - config files. Mainly config/core.php and config/database.php
    • models - Model files like Media, User, Group, etc
      • behaviors - Helpers for Models with specific behavior like Cipher, Type, Flag, etc.
    • controllers - Handles all the logic
      • components - Helpers for controllers like FileManager, FilterManager, QueryBuilder, etc.
    • views - View files of the controllers
      • helpers - Helpers for the views like ExplorerMenu, Cloud, Option, etc.
      • elements - Little parts of pages are handled in elements.
    • vendors - 3rd party files like kcaptcha, phpThumb
    • plugins - extensions of phtagr. Eg. DupFinder

Coding Convention

phTagr follows basically the  coding standards of cake - except that phtagr uses to spaces instead of tabs.

An example

The plugin DupFinder is a nice example to get into the code. Its actions is limited but straightforward. See its code for details.

Debugging

While developing on phtagr it is always a good idea to increase the debug level of cake to retrieve hints and errors of missing actions, views or even typos. To see behind phtagr actions watch on its log file!

  • Enable Debug mode in config/core.php and set it to level 2: 
    Configure::write('debug', 2);
  • Watch log file in tmp/logs/logger.log 
    $> tail -f tmp/logs/logger.log

HowTo …

Add a new action to a controller

An action is defined by a function of the controller. The structure of a request is: controller/action/paramter1/parameter2/.... 

class ExplorerController extrends AppController {
  function hint($msg) {
    $this->set('hint', 'This is a hint text: $msg');
  }
}

Further the action need a view in views/controller/action.ctp. For controller ExplorerController and action hint it would be views/explorer/hint.ctp.

The parameters are passed to the action. There are also stored in $this->params['passed']. Special parameters with the structure name:value are named parameters and are stored in $this->params['named'].

Get data from the controller to the view?

There are different ways to save data for the view within the controller. The special controller variable $this->data is also available in the view as $this->data. Named variables could be set via $this->set() method. Or data could be stored in a special parameter array in $this->params - which is used in special cases. 

class ExplorerController extrends AppController {
  function storage() {
    // View: $this->data
    $this->data = 'Special variable';
    // View: $foo
    $this->set('foo', 'Named variable for the view');
    // View: $this->params array.
    $this->params['search']['help'];
  }
}

Get data from the request?

The form data is submitted to the $this->data array of the controller and can be evaluated. 

class ExplorerController extrends AppController {
  function edit() {
    if (!empty($this->data)) {
      $media = $this->Media->findById($this->data['Media']['id']);
      // further actions
    }
  }
}

Retrieve and save data from/to a model?

To use a model, the model must be listed in the $uses variable in the controller. 

class ExplorerController extrends AppController {
  $uses = array('Media', 'User');
}

Now the models Media and User could be accessed within the controller. 

  $data = $this->Media->findById($id);
  $data['Media']['name'] = 'New Name';
  $this->Media->save($data);

BTW: The data of the models are usually stored as associative arrays 

array(
  [Model] => array(
    [fieldname1] => 'value1',
    [fieldname2] => 'value2'
    ),
  [AssociatedModel] => array(
    [fieldname1] => 'value1',
    [fieldname2] => 'value2'
    )
  )

Or more precisely 

array(
  [Media] => array(
    [id] => 123,
    [name] => 'IMG_1234.JPG'
    ),
  [User] => array(
    [id] => 1,
    [username] => 'admin'
    )
  )

See also:  http://book.cakephp.org/view/75/Saving-Your-Data,  http://book.cakephp.org/view/73/Retrieving-Your-Data

Enhanced debugging output with debug_kit plugin

The  debug_kit plugin adds nice debug information to cakePHP applications.

Versions could be found at  http://thechaw.com/debug_kit/versions, eg.  debug_kit_1.1.zip

According to the README of debug_kit:

  • Copy the files in this directory into app/plugins/debug_kit
  • Include the toolbar component in your app_controller.php: 
      var $components = array('DebugKit.Toolbar');
  • Set debug mode to at least 1. (in app/config/core.php)