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 ?>
        

 

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

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

see Doctrine Cheatcheat

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