Developers Guide Lines

If you want to become a phpCollab3 developer you should use Test-Driven Development and Domain Driven Design. It means that for each task you accept as yours you should:

1. write a test before everything else and this test should express the issue you're working on;
2. write the code to make the test pass;
3. refactoring your code;

The Domain-Driven Design is involved in each of this steps and it means that you should naming classes and function to express what they do. As some says “The code should speak by itself to the reader”.

This steps should be used for tasks, bugs and any other “issue” you are going to accept.

Go to the issue page and edit it adding yourself as the user that will work on that issue (“Assign to” field).

First of all: if you are new with Git, read the documentation on github and Git.

1. Download the project from github.
2. Create a new branch on your machine:

   • git branch [name of your new branch; ex: issue_3627 ]
     

3. Switch to the brand new branch:

   • git checkout [name of your new branch; ex: issue_3627 ]

4. Work on your branch.

1. symfony test:all (all tests have to pass ⇒ green bar!!!)

1. Add files that you have created/modified:

   • git add .

2. Commit your changes:

   • git commit -m '<message>'

3. Push your branch to github:

   • git push <remote_repository_name> <your_branch> (example : git push origin issue_3627 )

4. After you pushed your branch, notify “ideato” of your modification as shown in the following guide:
   • Pull Request

After your notification the branch will be merged into the master by the lead developer and the branch will be deleted.

Part of the coding standard used in phpCollab3 is based on the Symfony coding standad.

• Never use tabulations in the code. Indentation is done by steps of 2 spaces

<?php
class sfFoo
{
  public function bar()
  {
    sfCoffee::make();
  }
}

• Don't put spaces after an opening parenthesis and before a closing one.

<?php
if ($myVar == getRequestValue($name))    // correct
if ( $myVar == getRequestValue($name) )  // incorrect

• Use camelCase, not underscores, for variable, function and method names:
  • Good: function makeCoffee()
  • Bad: function MakeCoffee()
  • Bad: function make_coffee()
• Use underscores for option/argument/parameter names.
• Symfony is written in php5, so every class method or member definition should explicitly declare its visibility using the private, protected or public keywords.
• Don't end library files with the usual ?> closing tag. This is because it is not really needed, and because it can create problems in the output if you ever have white space after this tag.
• In a function body, return statements should have a blank line prior to it to increase readability.

<?php
function makeCoffee()
{
 if (false !== isSleeping() && false !== hasEnoughCafeineForToday())
 {
   canMakeCoffee();
 
   return 1;
 }
 else
 {
   cantMakeCoffee();
 }
 
 return null;
}

• Use PHP type hinting in functions and method signatures:

<?php
public function notify(sfEvent $event)
{
  // ...
}

• All function and class methods should have their ”phpdoc” own block:
  • All @… statements do not end with a dot.
  • @param lines state the type and the variable name. If the variable can have multiple types, then the mixed type must be used.
  • Ideally @… lines are vertically lined up (using spaces):

<?php
/**
* Notifies all listeners of a given event.
*
* @param  sfEvent  $event  A sfEvent instance
*
* @return sfEvent          The sfEvent instance
*/
public function notify(sfEvent $event)

• The name of all php token are lowercase

<?php 
// wrong
Class Foo
{
}
 
// right
class Foo
{
}
 
// wrong
Function foo()
{
}
 
// right 
function foo()
{
}

• Avoid evaluating variables within strings, instead opt for concatenation:

<?php
$string = 'something';
$newString = "$string is awesome!";  // bad, not awesome
$newString = $string.' is awesome!'; // better
$newString = sprintf('%s is awesome', $string); // for exception messages and strings with a lot of substitutions

• Use lowercase PHP native typed constants: false, true and null. The same goes for array().
• Use uppercase strings for user defined constants, like define('MY_CONSTANT', 'foo/bar'). Better, try to always use class constants:

<?php
class sfCoffee
{
  const HAZ_SUGAR = true;
}
var_dump(sfCoffee::HAZ_SUGAR);

• To check if a variable is null or not, use the is_null() native PHP function:

<?php
if (!is_null($coffee))
{
  echo 'I can haz coffee';
}

• When comparing a variable to a string, put the string first and use type testing when applicable:

<?php
if (1 === $variable)

• Braces always go on their own line.
• Use braces for indicating control structure body regardless of number of statements it contains.

• All one line comments should be on their own lines and in this format:

<?php
// space first, with no full stop needed