|
There are 4 types of classes namely:
Being an MVC framework, controllers stand in between models and views in the application. They pass information on to the model when data needs to be changed and they request information from the model. The rules for naming a controller are:
application/controllers
directoryreports.php
_Controller
} e.g. Reports_Controller
Controller
classAdditional documentation on controllers can be found here: http://docs.kohanaphp.com/general/controllers
Models provide a convenient way of interacting with the database. They are a part of Kohana's ORM architecture and therefore abstract the gory details of platform-specific database calls. Kohana however doesn't force you to use models.
The rules for naming a model are:
application/models
directoryincident.php
NOT incidents.php
_Model
e.g. Incident_Model
Additional documentation on models can be found here: http://docs.kohanaphp.com/general/models
Rules for creating libraries are:
application/libraries
directoryGeocoder
Geocoder.php
_Core
appended to the class name so that it can be extended (sub-classed) in the same way as Kohana's built-in librariesAdditional documentation on libraries can be found here: http://docs.kohanaphp.com/general/libraries
Helpers are classes that are used to isolate "handy" or "useful" functionality.
Rules for creating helper classes are:
application/helpers
directorycategory.php
_Core
e.g. category_Core
Additional documentation on helpers can be found here: http://docs.kohanaphp.com/general/helpers
For the source code to be consistent, we encourage all developers to follow the coding style guidelines.
Use BSD/Allman Style bracketing. This style puts braces associated with a control statement or function definition on their own line. The exception to this rule is the opening brace for a class definition, which can be on the same line (as the class name).
if ($x > 1) { print 'Greater than 1'; } else { print 'Less than 1'; } // The opening brace for a class definition can be on the same line class SampleClass { |
Kohana uses under_score naming, not camelCase naming.
// Controller class uses _Controller suffix class Boiler_Controller extends Controller { // Model class uses _Model suffix class Plate_Model extends Model { // Regular class class Chicken { |
Function names should be in lowercase and use under_scores to separate words:
function show_contacts($foo) { $foo->bar(); } |
Variable names should lowercase and use under_score, not camelCase:
// Correct $foo = 'bar'; $long_example = 'uses underscores'; // Incorrect $hasWindowCurtains = 'No window curtains'; |
Use tabs to indent your code. The use of spaces is forbidden.
Vertical spacing (for multi-line) is done with spaces. Tabs are not good for vertical alignment because different people have different tab widths.
$text = 'This is a long text to demonstrate the guideline for indenting your ' .'code. The practice is to use TABS and not spaces. Also vertical alignment ' .'for multi-line is done with spaces because not everyone uses the same tab ' .'width.'; |
Single-line IF
should only be used when breaking normal execution (e.g. return
or continue
)
// Acceptable if ($foo == $bar) return $foo; if ($foo == $bar) continue; if ($foo == $bar) break; // Not acceptable if ($foo == $bar) $foo += 1; |
Use AND
and OR
for comparison.
// Correct if (($foo AND $bar) OR ($a AND $b)) // Incorrect if (($foo && $bar) || ($a && $b)) |
elseif
, NOT else if
// Correct elseif ($a > $b) // Incorrect else if ($a > $b) |
// Correct if ($foo == $bar) if ( ! $foo) if ( (int) $foo) // Incorrect if($foo == $bar) if (!$foo) if ( $foo == $bar ) if ((int) $foo) if (! $foo) |
Ternary operations should follow a standard format. Use parentheses around expressions only, not around variables.
// Correct $foo = ($bar == 5) ? $foo : $bar; $foo = $bar ? $foo : $bar; // Incorrect $foo = ($bar) ? $foo : $bar; |
When separating ternaries into lines, spaces should be used to line up the operators, which should at the front of successive lines:
$foo = ($foo == $bar) ? $foo : $bar; |
We use phpDocumentor, a tool for creating documentation directly from both PHP and external documentation, to keep track of all our code documentation. The documentation within the code is done using PHPDoc which is an adaptation of Javadoc for the PHP programming language.
The objective of documenting code is to makes it easier to understand and lower the barrier to entry for developers wishing to contribute to the codebase. It also facilitates painless maintenance (refactoring, bug fixes etc).
The first thing to take note of is that PHPDoc comments must be enclosed in DocBlocks. A DocBlock is a C-stlye comment that begins with a /**
and with a leading asterisk *
on each line. Any line within a DocBlock that doesn't begin with a *
will be ignored. Example:
/** * Example use of DocBlocks in PHP */ |
Secondly, DocBlocks must precede the code you are adding comments to. For example, if you wanted to document the function foo()
, you would proceed as follows:
/** * DocBlock comment for function "foo()" */ function foo() { } |