Project-Id-Version: Trac 0.12
Report-Msgid-Bugs-To: trac-dev@googlegroups.com
POT-Creation-Date: 2008-01-30 09:20+0100
PO-Revision-Date: 2010-07-19 23:05+0200
Last-Translator: Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
Language-Team: en_US <trac-dev@googlegroups.com>
Plural-Forms: nplurals=2; plural=(n != 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Generated-By: Babel 0.9.6

Warning: Can't synchronize with repository "(default)" (Unsupported version control system "git": Can't find an appropriate component, maybe the corresponding plugin was not enabled? ). Look in the Trac log for more information.
Last modified 5 years ago Last modified on 01/04/13 16:24:28

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

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 Getting Started). 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?

Contribute

You are more than welcome by contributing your changes back the phTagr.

If you like to contribute code changes it is highly recommended to use phtagr's source directly from GitHub. See HowToInstallFromGit and HowToMigrateToGit for getting phtagr running using git. Please use current Git master and send a pull request at GitHub (see their pull request doc)

If you are not able to send a pull request send a patch file of your changes to support at phtagr.org via email. And if you are not able to send a patch file file you can send your complete file with changes to support at phtagr.org via email.

Git Branching

With git you developing new features on a separate branch an your forked repository. The advantage is that a branch can easily merged to a master and can be updated from the master. A rough workflow look like

  • Create a fork from xemle/phtagr. See githubs doc Fork a repo
  • Open a branch by git checkout -b new-feature
  • Push your changes to your branch of your repository
  • Open a pull request to contribute your changes
  • Merge from time to time your fork and branch with the upstream repository xemle/phtagr

To get an idea have a look at Git branching model

Git Commit Message

Commit messages should have following format (see A Note About Git Commit Messages for details):

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

Source

To debug phtagr's source or your changes see DebugWithNetbeans

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

  • phtagr (or app) - phtagr files
    • cakephp - CakePHP framework files
    • Config - config files. Mainly config/core.php and config/database.php
    • Model - Model files like Media, User, Group, etc
      • Behavior - Helpers for Models with specific behavior like Cipher, Type, Flag, etc.
    • Controller - Handles all the logic
      • Component - Helpers for controllers like FileManager, FilterManager, QueryBuilder, etc.
    • Views - View files of the controllers
      • Helper - Helpers for the views like ExplorerMenu, Cloud, Option, etc.
      • Element - Little parts of pages are handled in elements.
    • Vendor - 3rd party files like kcaptcha, phpThumb
    • Plugin - 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 View/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->request->params['passed']. Special parameters with the structure name:value are named parameters and are stored in $this->request->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->request->data is also available in the view as $this->request->data. Named variables could be set via $this->set() method. Or data could be stored in a special parameter array in $this->request->params - which is used in special cases.

class ExplorerController extrends AppController {
  function storage() {
    // View: $this->request->data
    $this->request->data = 'Special variable';
    // View: $foo
    $this->set('foo', 'Named variable for the view');
    // View: $this->params array.
    $this->request->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->request->data)) {
      $media = $this->Media->findById($this->request->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: Saving Your Data, Retrieving Your Data

Enhanced debugging output with debug_kit plugin

The debug_kit plugin adds nice debug information to cakePHP applications.

According to the README of debug_kit:

  • Copy the files in this directory into Plugin/DebugKit
  • Enable plugin at Config/bootstrap.php
     CakePlugin::load('DebugKit');
    
  • Include the toolbar component in your Controller/AppController.php:
     var $components = array('DebugKit.Toolbar');
    
  • Set debug mode to at least 1. (in Config/core.php)