ullright code conventions
General
The ullright coding standards build on the symfony ones.
http://trac.symfony-project.org/wiki/HowToContributeToSymfony#CodingStandards
Everything in the code (variables, comments, ...) has to be written in english.
From the symfony coding standards:
Here's the golden rule: Imitate the existing code.
PHP tags
- Always use full php-tags
-
<?php die('Famous last words...');
-
- Ommit the closing tag (?>) in pure php-files (classes!) to prevent the parsing of unwanted spaces after the end tag
- Templates always use the alternative php tag syntax. php-tags should always contain a single command. the php-tags should be closed in the same line. This allows html syntax highlighting by the editor and code that is readable for a web designer.
- Bad example:
-
<?php echo '<h3>'; echo $headline; echo '</h3>; if ($user) { echo '<a href="index.php">' . $linktext . '</a>' } ?>
-
- Good example:
-
<h3><?php echo $headline ?></h3 <?php if ($user): ?> <a href="index.php"><?php echo $linktext ?></a> <?php endif ?>
-
- Bad example:
Formatting
Tab policy
Intendation: We use spaces - no tabs allowed!. Configure your editor to insert 2 spaces for one tab
Max characters per line: 80 (2-3 more chars are allowed if it makes sense)
Linewrap
Lines should be wrapped if they are too long. Indent them with one tab = two spaces
very_long_function( $param1, $param2, $param3, $param4 );
Concatenation of long strings:
$subject = $this->app_doc_caption . ': "' . $this->doc_title . '"' ;
Note that the semicolon is on a new line.
Newline policy
All files use simple UNIX linefeeds (\n) - Carriage returns (\r) are not allowed
Braces
- Braces are set using the BSD/Allman style
while($x > 10) { something(); somethingelse(); }
Naming conventions
- Normal ullright classes start with the prefix "ull" (lowercase "u")
- Normally the "ull" prefix is always written in lowercase
- Example: ullAuth.class.php
- Model classes start with the prefix "Ull" (uppercase "u")
- This is the only exception where "Ull" is written with a capital "U"
- Example: UllUser.class.php
- Applications start with "ull..." like ullWiki, ullFlow, etc
- Database columns never have a "ull" prefix, neither do variables use a "ull" prefix
- "null" like in $x = null; is always written in lower case
Structure
Methods
- Naming: method names should be as short and self-explanatory as possible
- Length: methods should be 10-20 lines long max. Longer methods should usually be refactored using "Extract method(110)" or similar. (@see "Refactoring" by Martin Fowler)
- Always use "protected" for non-public methods in classes. Use "private" only if absolutely necessary. You never know who and why wants to extend your class.
Comments
- Use comments only for non-obvious explanations (For example for a complex algorithm)
MVC Structure
- Separate the code cleanly using the MVC-pattern
- Fat model - thin controller
- Symfony actions should be short and composed of self-explanatory method calls.
- All database-related stuff should be extracted to the models.
Templates
Clean templates!
- No model calls XXXTable::foo() - Inject the variables via the action
- No sfConfig calls - Inject the variables via the action
- Alternate PHP Syntax! No braces allowed
- No hardcoded URLs. Always use url_for(). (Javascript!!!)
- No <br /> tags allowed (Exeptions: real line breaks in a paragraph). Always use semantic structure elements like <div> <p> etc and provide meaningful css ids or class names
- No direct javascript. Use "echo javascript_tag()"
Symfony specific
Actions
Use the $request parameter provided by symfony 1.1:
public function executeEdit($request) { // Print all request params for debugging purposes: var_dump($request->getParameterHolder()->getAll()); $id = $request->getParameter('id'); if ($request->isMethod('post')) { ... } }
Helpers
The status of the helpers is a bit confusing as of symfony 1.1.
For ullright and symfony 1.1 we currently use the following rules:
- Don't use any form helpers that are directly replaced by sfForm (input_tag(), ...)
- In the meantime it's ok to use helpers that don't have a replacement yet:
- form_tag()
- submit_tag()
- javascript_tag()
- link_to(), button_to(), ...
Doctrine
sfForm
Handling of javascripts and stylesheets
sfForm offers a convenient mechanismn which allows the widgets to automatically load requires stylesheets and javascripts.
Therefore it is not necessary to include the required assets in every template or globally in the layout
Definition in the widget
<?php class ullWidgetDateWrite extends sfWidgetForm { public function render($name, $value = null, $attributes = array(), $errors = array()) { // Perform rendering and use some javascript return $return; } /** * Gets the JavaScript paths associated with the widget. * * @return array An array of JavaScript paths */ public function getJavaScripts() { return array( '/ullCorePlugin/js/jq/jquery-min.js', '/ullCorePlugin/js/jq/jquery-ui-min.js' ); } /** * Gets the stylesheet paths associated with the widget. * * The array keys are files and values are the media names (separated by a ,): * * array('/path/to/file.css' => 'all', '/another/file.css' => 'screen,print') * * @return array An array of stylesheet paths */ public function getStylesheets() { return array( '/ullCorePlugin/css/jqui/jquery-ui.css' => 'all' ); } }
Loading the stylesheets and javascripts in the template
At the bottom of the template:
// template code // ... <?php use_javascripts_for_form($generator->getForm()) ?> <?php use_stylesheets_for_form($generator->getForm()) ?>
Command Line Interface CLI
ullright cron jobs
On production servers symfony tasks used as cron jobs need the environment argument.
Example: symfony ullright:user-deactivation frontend prod