FANDOM


shortcut: CC/PHP

Script error


This page describes the coding conventions used within files of the MediaWiki codebase written in PHP. See also the general conventions that apply to all program languages, including PHP. If you would like a short checklist to help you review your commits, try using the pre-commit checklist.



To help developers fix code with an inadequately spacey style, a tool called stylize.php has been created, which uses PHP's tokenizer extension to add spaces at the relevant places. It's recommended to run this over new files committed to Git, but not so much for fixing current files.



The git repository https://github.com/wikimedia/mediawiki-tools-codesniffer.git contains the PHP CodeSniffer settings for MediaWiki code.



Template:TOC



Code structure Edit

Assignment expressions Edit

Using assignment as an expression is surprising to the reader and looks like an error. Do not write code like this:



if ( $a = foo() ) {
 
  bar();
 
}



Space is cheap, and you're a fast typist, so instead use:



$a = foo();
 
if ( $a ) {
 
  bar();
 
}



Using assignment in a Template:Phpi clause used to be legitimate, for iteration:



$res = $dbr->query( 'SELECT * FROM some_table' );
 
while ( $row = $dbr->fetchObject( $res ) ) {
 
  showRow( $row );
 
}



This is unnecessary in new code; instead use:



$res = $dbr->query( 'SELECT * FROM some_table' );
 
foreach ( $res as $row ) {
 
  showRow( $row );
 
}



Spaces Edit

MediaWiki favors a heavily-spaced style for optimum readability. 



Put spaces on either side of binary operators, for example:



// No:
 
$a=$b+$c;
 
 
 
 
// Yes:
 
$a = $b + $c;



Put spaces next to parentheses on the inside, except where the parentheses are empty. Do not put a space following a function name.



$a = getFoo( $b );
 
$c = getBar();



Control structures Template:Phpi, Template:Phpi, Template:Phpi, Template:Phpi, Template:Phpi, Template:Phpi etc. should be followed by a space:



// Yes
 
if ( isFoo() ) {
 
$a = 'foo';
 
}
 
 
 
 
// No
 
if( isFoo() ) {
 
$a = 'foo';
 
}



When type casting, do not use a space within or after the cast operator:

// Yes
 
(int)$foo;
 
 
 
 
// No
 
(int) $bar;
 
( int )$bar;
 
( int ) $bar;



In comments there should be one space between the Template:Phpi or Template:Phpi character and the comment.

// Yes: Proper inline comment
 
//No: Missing space
 
/***** Do not comment like this ***/



To help developers fix code with an inadequately spacey style, a tool called stylize.php has been created, which uses PHP's tokenizer extension to enforce most whitespace conventions automatically.



Ternary operator Edit

The Template:Php can be used profitably if the expressions are very short and obvious:



$wiki = isset( $this->mParams['wiki'] ) ? $this->mParams['wiki'] : false;



But if you're considering a multi-line expression with a ternary operator, please consider using an Template:Phpi block instead. Remember, disk space is cheap, code readability is everything, "if" is English and ?: is not.



Since MediaWiki requires PHP Template:MW stable php requirement or later, use of the shorthand ternary operator (?:), introduced in PHP 5.3, is allowed.



String literals Edit

For simple string literals, single quotes are slightly faster for PHP to parse than double quotes. Also for people using a qwerty keyboard, they are easier to type, since it avoids the need to press shift. For these reasons, single quotes are preferred in cases where they are equivalent to double quotes.



However, do not be afraid of using PHP's double-quoted string interpolation feature:

Template:Phpi  This has slightly better performance characteristics than the equivalent using the concatenation (dot) operator, and it looks nicer too.



Heredoc-style strings are sometimes useful:



$s = <<<EOT
 
<div class="mw-some-class">
 
$boxContents
 
</div>
 
EOT;



Some authors like to use END as the ending token, which is also the name of a PHP function. This leads to IRC conversations like the following:




<Simetrical><span class="Apple-tab-span" style="white-space:pre"> </span>vim also has ridiculously good syntax highlighting.

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>it breaks when you write <<<END in PHP

<Simetrical><span class="Apple-tab-span" style="white-space:pre"> </span>TimStarling, but if you write <<<HTML it syntax-highlights as HTML!

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>I have to keep changing it to ENDS so it looks like a string again

<brion-codereview><span class="Apple-tab-span" style="white-space:pre"> </span>fix the bug in vim then!

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>brion-codereview: have you ever edited a vim syntax script file?

<brion-codereview><span class="Apple-tab-span" style="white-space:pre"> </span>hehehe

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>http://tstarling.com/stuff/php.vim

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>that's half of it...

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>here's the other half: http://tstarling.com/stuff/php-syntax.vim

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>1300 lines of sparsely-commented code in a vim-specific language

<TimStarling><span class="Apple-tab-span" style="white-space:pre"> </span>which turns out to depend for its operation on all kinds of subtle inter-pass effects

<werdnum><span class="Apple-tab-span" style="white-space:pre"> </span>TimStarling: it looks like some franken-basic language.



Functions and parameters Edit

Avoid passing huge numbers of parameters to functions or constructors:

//Constructor for Block.php as of 1.17. *DON'T* do this!
 
function __construct( $address = '', $user = 0, $by = 0, $reason = '',
 
$timestamp = 0, $auto = 0, $expiry = '', $anonOnly = 0, $createAccount = 0, $enableAutoblock = 0,
 
$hideName = 0, $blockEmail = 0, $allowUsertalk = 0
 
) {
 
...
 
}



It quickly becomes impossible to remember the order of parameters, and you will inevitably end up having to hardcode all the defaults in callers just to customise a parameter at the end of the list. If you are tempted to code a function like this, consider passing an associative array of named parameters instead.



In general, using boolean parameters is discouraged in functions. In Template:Phpi, without looking up the documentation for Template:Phpi, it is impossible to know what those parameters are meant to indicate. Much better is to either use class constants, and make a generic flag parameter:



$myResult = MyClass::getSomething( $input, MyClass::FROM_DB | MyClass::PUBLIC_ONLY );



Or to make your function accept an array of named parameters:



$myResult = MyClass::getSomething( $input, array( 'fromDB', 'publicOnly' ) );



Try not to repurpose variables over the course of a function, and avoid modifying the parameters passed to a function (unless they're passed by reference and that's the whole point of the function, obviously).



C borrowings Edit

The PHP language was designed by people who love C and wanted to bring souvenirs from that language into PHP. But PHP has some important differences from C.



In C, constants are implemented as preprocessor macros and are fast. In PHP, they are implemented by doing a runtime hashtable lookup for the constant name, and are slower than just using a string literal. In most places where you would use an enum or enum-like set of macros in C, you can use string literals in PHP.



PHP has three special literals for which upper-/lower-/mixed-case is insignificant in the language (since PHP 5.1.3), but for which our convention is always lowercase : Template:Phpi, Template:Phpi and Template:Phpi.



Use Template:Phpi not Template:Phpi. They have subtly different meanings:



// This:
 
if ( $foo == 'bar' ) {
 
echo 'Hello world';
 
} else if ( $foo == 'Bar' ) {
 
echo 'Hello world';
 
} else if ( $baz == $foo ) {
 
echo 'Hello baz';
 
} else {
 
echo 'Eh?';
 
}
 
 
 
 
// Is actually equivalent to:
 
if ( $foo == 'bar' ) {
 
echo 'Hello world';
 
} else {
 
if ( $foo == 'Bar' ) {
 
echo 'Hello world';
 
} else {
 
if ( $baz == $foo ) {
 
echo 'Hello baz';
 
} else {
 
echo 'Eh?';
 
}
 
}
 
}



And the latter has poorer performance.



Alternative syntax for control structures Edit

PHP offers an alternative syntax for control structures using colons and keywords such as "endif", "endwhile", etc.:



if ( $foo == $bar ):
 
  echo "<div>Hello world</div>";
 
endif;



This syntax should be avoided, as it prevents many text editors from automatically matching and folding braces. Standard syntax should be used instead:



if ( $foo == $bar ) {
 
  echo "<div>Hello world</div>";
 
}



Naming Edit

Use lowerCamelCase when naming functions or variables. For example:
private function doSomething( $userPrefs, $editSummary )
Use UpperCamelCase when naming classes: Template:Phpi. Use uppercase with underscores for global and class constants: Template:Phpi, Template:Phpi. Other variables are usually lowercase or lowerCamelCase; avoid using underscores in variable names.



There are also some prefixes used in different places:



Functions Edit

  • wf (wiki functions) – top-level functions, e.g.
    function wfFuncname() { ... }



  • ef (extension functions) = global functions in extensions, although "in most cases modern style puts hook functions as static methods on a class, leaving few or no raw top-level functions to be so named." (-- brion in Manual_talk:Coding_conventions#ef_prefix_9510)



Verb phrases are preferred: use Template:Phpi instead of Template:Phpi.



Variables Edit

  • Global declarations should be at the beginning of a function so dependencies can be determined without having to read the whole function.



It is common to work with an instance of the Database class; we have a naming convention for these which helps keep track of the nature of the server to which we are connected. This is of particular importance in replicated environments, such as Wikimedia and other large wikis; in development environments there is usually no difference between the two types, which can conceal subtle errors.



  • Template:Phpi – a Database object for writing (a master connection)
  • Template:Phpi – a Database object for non-concurrency-sensitive reading (this may be a read-only slave, slightly behind master state, so don't ever try to write to the database with it, or get an "authoritative" answer to important queries like permissions and block status)



The following may be seen in old code but are discouraged in new code:



  • $wp – Post variables (submitted via form fields), e.g. Template:Phpi
  • $m – object member variables: Template:Phpi. This is discouraged in new code, but try to stay consistent within a class.



Pitfalls Edit

    • Template:Phpi is inverted conversion to boolean with error suppression.
      • Only use it when you really want to suppress errors. Otherwise just use Template:Phpi (boolean conversion, see below).
      • Do not use it to test if a string is empty, because PHP considers '0' and similar expressions to be empty.
      • Do not use it to test if an array is empty, unless you simultaneously want to check if the variable is unset. Using Template:Phpi or Template:Phpi (boolean conversion) works the same way without error suppression.
  • Do not use the 'goto' syntax introduced in 5.3. PHP may have introduced the feature, but that does not mean we should use it.



Equality operators Edit

Be careful with double-equals comparison operators. Triple-equals (Template:Phpi) is generally more intuitive and should be preferred unless you have a reason to use double-equals (Template:Phpi).



  • To check if two scalars that are supposed to be numeric are equal, use "==", e.g. (5 == "5") is true.
  • To check if two variables are both of type 'string' and are the same sequence of characters, use "===", e.g. ("1.e6" === "1.0e6") is false.
  • To check if two scalars that should be treated as strings are equal as strings, use strcmp(), e.g. strcmp(13,"13") is 0.



Comments and documentation Edit

It is essential that your code be well documented so that other developers and bug fixers can easily navigate the logic of your code. New classes, methods, and member variables should include comments providing brief descriptions of their functionality (unless it is obvious). In addition, new methods should have their return value and parameters documented using Doxygen conventions.



The Doxygen documentation style is used (it is very similar to PHPDoc for the subset that we use) to produce auto-generated documentation from code comments (see Manual:mwdocgen.php). A code documentation example: giving a description of a function or method, the parameters it takes (using @param), and what the function returns (using @return), or the @ingroup or @author tags.



Use @ rather than \ as the escape character (i.e. use @param rather than \param) – both styles work in Doxygen, but for backwards and future compatibility MediaWiki uses has chosen the @param style as convention).



Use /** to begin the comments, instead of the Qt-style formatting /*!.



The format for parameters is:

@param type $paramName description of this parameter



Multiple types can be listed by separating with a pipe character:



@param datatype1|datatype2 $paramName description of this parameter



For every public interface (method, class, variable, whatever) you add or change, a @since tag should be provided, so people extending the code via this interface know they are breaking compatibility with older versions of the code.



class Foo {
 
 
 
 
/**
 
* @var array $bar: Description here
 
* @example array( 'foo' => Bar, 'quux' => Bar, .. )
 
*/
 
protected $bar;
 
 
 
 
/**
 
* Short decription here, following by documentation of the parameters.
 
*
 
* @since 1.42
 
*
 
* @param FooContext $context context for decoding Foos
 
* @param array|string $options Optionally pass extra options. Either a string or an array of strings.
 
* @return Foo|null: New instance of Foo or null of quuxification failed.
 
*
 
* Some example:
 
* @code
 
* ...
 
* @endcode
 
*/
 
public function makeQuuxificatedFoo( FooContext $context = null, $options = array() ) {
 
/* .. */
 
}
 
 
 
 
}



PHPDoc was used at the very beginning but got replaced with Doxygen for performance reason. We should probably drop PHPDoc compatibility.



FIXME usually means something is bad or broken. TODO means that improvements are needed; it does not necessarily mean that the person adding the comment is going to do it. HACK means that a quick but inelegant, awkward or otherwise suboptimal solution to an immediate problem was made, and that eventually a more thorough rewrite of the code should be done.



@var: documenting class membersEdit

There is a 'bug' in Doxygen[1] which affects MediaWiki's documentation: using @var to specify the class members' type only works if the variable name is appended:



/**
 
* Some explanation about the variable
 
*
 
* @var string $msg
 
*/
 
protected $msg;




If you don't append the variable name Doxygen will ignore the entire comment block and it will not be included in the docs.



Source file headers Edit

In order to be compliant with most licenses you should have something similar to the following (specific to GPLv2 applications) at the top of every source file.

<?php
 
/**
 
* This file is part of the CentralNotice Extension to MediaWiki
 
* https://www.mediawiki.org/wiki/Extension:CentralNotice
 
*
 
* @section LICENSE
 
* This program is free software; you can redistribute it and/or modify
 
* it under the terms of the GNU General Public License as published by
 
* the Free Software Foundation; either version 2 of the License, or
 
* (at your option) any later version.
 
*
 
* This program is distributed in the hope that it will be useful,
 
* but WITHOUT ANY WARRANTY; without even the implied warranty of
 
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 
* GNU General Public License for more details.
 
*
 
* You should have received a copy of the GNU General Public License along
 
* with this program; if not, write to the Free Software Foundation, Inc.,
 
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
* http://www.gnu.org/copyleft/gpl.html
 
* 
 
* @file
 
*/



Integration Edit

There are a few pieces of code in the MediaWiki codebase which are intended to be standalone and easily portable to other applications; examples include the UTF normalisation in /includes/normal and the libraries in /includes/libs. Apart from these, code should be integrated into the rest of the MediaWiki environment, and should allow other areas of the codebase to integrate with it in return.



Global objects Edit

Main article: Manual:RequestContext.php



Do not access the PHP superglobals Template:Phpi, Template:Phpi, etc, directly; use Template:Phpi instead; there are various functions depending on what type of value you want. You can get a Template:Phpi from the nearest Template:Phpi, or if absolutely necessary Template:Phpi. Equally, do not access Template:Phpi directly; use Template:Phpi if you want to get the IP address of the current user.



Static methods and properties Edit

Static methods and properties are useful for programmers because they act like globals without polluting the global namespace. However, they make subclassing and reuse more difficult for other developers. Generally, you should avoid introducing static functions and properties when you can, especially if the sole purpose is to just save typing. 



For example, lots of developers would prefer to write something like:

Foo::bar();

This is because it is shorter and takes less keystrokes. However, by doing this you've made the Foo class much harder to subclass and reuse. Instead of introducing a static method, you could just type:

$f = new Foo();
 
$f->bar();

Remember, shorter does not always mean better, and you should take the time to design your classes in a way that makes them easy to reuse.



Late static binding Edit

In PHP 5.3, a new feature called "Late Static Binding" (LSB) was added to help work around this perceived lack of functionality in static functions. However, the usefulness of LSB is debatable among MediaWiki developers and should be avoided for the time being.



Classes Edit

Encapsulate your code in an object-oriented class, or add functionality to existing classes; do not add new global functions or variables. Try to be mindful of the distinction between 'backend' classes, which represent entities in the database (eg User, Block, Revision, etc), and 'frontend' classes, which represent pages or interfaces visible to the user (SpecialPage, Article, ChangesList, etc. Even if your code is not obviously object-oriented, you can put it in a static class (eg IP or Html).



As a holdover from PHP 4's lack of private class members and methods, older code will be marked with comments such as Template:Phpi to indicate the intention; respect this as if it were enforced by the interpreter.



Mark new code with proper visibility modifiers, including Template:Phpi if appropriate, but do not add visibility to existing code without first checking, testing and refactoring as required. It's generally a good idea to avoid visibility changes unless you're making changes to the function which would break old uses of it anyway.



Error handling Edit

Don't suppress errors with PHP's @ operator, for any reason ever. It's broken when E_STRICT is enabled and it causes an unlogged, unexplained error if there is a fatal, which is hard to support.



The proper method of handling errors is to actually handle the errors. For example, if you are thinking of using an error suppression operator to suppress an invalid array index warning, you should instead perform an isset() check on the array index before trying to access it. When possible, always prevent PHP errors rather than catching and handling them afterward. It makes the code more understandable and avoids dealing with slow error suppression methods.



If and only if there is a situation where you are expecting an unavoidable PHP warning, you may use wfSuppressWarnings() and wfRestoreWarnings() instead of the @ operator. This is for cases where:



  1. It is impossible to anticipate the error that is about to occur; and
  1. You are planning on handling the error in an appropriate manner after it occurs.



An example of this is opening a file with fopen(). You can anticipate the error by calling file_exists() and is_readable(), but it is possible the file will have been deleted in between the check and the actual fopen() call. In this case, your code should be ready to handle the case that the file will fail to open, and you can use wfSuppressWarnings() to prevent PHP from being noisy. Note that using wfSuppressWarnings() and wfRestoreWarnings() are slow. They are much slower than using the @ operator, since it involves at least four function calls and reference counting, rather than just an opcode.



When your code encounters a sudden error, you should throw a MWException (or an appropriate subclass) rather than using PHP's trigger_error. The exception handler will display this as nicely as possible to the end user and wiki administrator, and also provides a stack trace to developers.



ReferencesEdit

  1. Bug 626105 - @var in php is not documented



Template:Conventions navigation