====== Coding Style ======

phpList follows the coding standards of PHP-FIG [[http://www.php-fig.org/psr/psr-1/|PSR-1]] and most of [[http://www.php-fig.org/psr/psr-2/|PSR-2]]. Please follow the simple style rules outlined by these standards to keep code consistent and readable.

All changes to the phpList 3 and phpList 4 codebases must adhere to the coding standards. You are only responsible for the lines that you edit.

phpList 3 does not uniformly follow the above standards as it is an older codebase not fully renewed. phpList 4 already adheres to these standards.

===== SQL Queries =====

Build the query using ''sprintf'' for the parameters and store it in a variable before actually calling the query. ((That makes it easier to debug by printing the query before it's performed)) The integer parameters can be sanitised with %d and strings by calling Sql_Escape, eg

<code>
$query = sprintf('select id,data from %s where id = %d and name = "%s"',$GLOBALS['tables'][$table],$ID,Sql_Escape($NAME));
$result = Sql_Query($query);
</code>

Explicitly mention the columns in the result set and do not use wildcards. So, that means queries like

<code>Select u.id, u.status from table u where id = X</code> and **NOT**

<code>Select * from table u where id = X</code> ((This is for security purposes.))

Also, have a look in the mysql.inc file for the functions that abstract the Mysql calls. Use the ones in there, and do not use any ''"mysql_" functions'' in the code directly.

You can use ''Sql_Verbose_Query'' to have the query be printed before being called.

All tables are referenced using the global ''$tables''. Check the ''structure.php'' file to find the database structure.

====== Language and translation ======

When you output strings, use the function ''s''. A lot of code will use ''$GLOBALS['I18N']->get('', but you can use the shortcut ''s'' instead, eg

<code>
print s('Please enter your name');
</code>

The ''s function'' can also handle additional parameters which can be used for fill out a sprintf output.

<code>
print s('phpList has sent %d out of %d messages, and will finish sending at %s',$messages_done,$total,$end_date);
</code>
((I actually need to check that this is processed correctly by POedit))

===== Obsolete coding style =====

A lot of code still has these styles, but should be redone. Try to change it whenever you touch a certain section of the code where this is used. But be careful to ensure it doesn't break anything.

  * if ($variable)
This should be changed to '' if (!empty($variable))) '' or '' if (isset($variable)) '' depending on the context. In general the first one.

  * Queries that look like ''"select something from {$tables['table']} where id = $id"''
These should be redone using the sprintf format as mentioned above.




===== Commenting =====

Each function and class should have a PHPDocumentor style comment, giving at least the function's purpose, parameters, and return variable type.

Example:

<code php>
/**
 * Check for foo in bar
 *
 * Checks if there is a foo in bar
 *
 * @author   Joe Schmoe <joe@example.com>
 * @param    string $in your input
 * @return   bool       true if foo in bar
 *
 */
function is_foo($in) {
  ...
}
</code>