DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:coding_style

Coding Style

DokuWiki is a very old project and coding styles vary within the code.

The official coding style to apply to all new code is PSR-12.

When editing existing code you're encouraged to update the coding style. When you do, it is recommended to do code reformatting in a commit separate from your code changes.

Brackets and Indentations

You should indent your code by 4 spaces to mark logical blocks. Please do not use tabs. Some ancient code may still use 2 spaces; you should stick to this or change the whole file to 4 spaces.

Opening brackets should start on the same line as the keyword, closing bracket should be aligned below the first letter of the starting keyword. E.g.:

if ($foo == "bar") {
    call_bar();
} elseif ($foo == "baz") {
    call_baz();
} else {
    call_other();
}

Refer to PSR-12 for more details.

Line Endings

Lines should end with a single linefeed character (UNIX style). Please try to avoid trailing whitespace. Have a look at our page about Vim to see how to set up Vim to spot these easily. IntelliJ Idea will also help with keeping a consistent style.

Commenting

Each function and class should have a PHPDocumentor style comment, giving at least the function's purpose. Parameter and return value descriptions are encouraged but only mandatory if they are not obvious.

Author lines are optional, since we track authorship in git anyway.

Example:

/**
 * 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)
{
    ...
}

These comments are used for the autogenerated API Docs.

PHP Closing Tags

You should omit PHP's closing tags (?>) in all files to avoid premature output. This may sound strange but is actually mentioned in the PHP manual:

Note: The closing tag of a PHP block at the end of a file is optional, and in some cases omitting it is helpful when using include() or require(), so unwanted whitespace will not occur at the end of files, and you will still be able to add headers to the response later. It is also handy if you use output buffering, and would not like to see added unwanted whitespace at the end of the parts generated by the included files.

Visibility and Type Hints

Please do not use private but use protected instead. You never know when a subclass may want to overwrite functionality. Eg. some plugin might want to provide new functionality based on your plugin.

When using type hints be aware of the minimal supported PHP version for DokuWiki and don't use features not available in it.

In general be wary of overusing type hinting, especially in all public facing APIs. Changing it changes method signatures which has effects on all inheriting classes. A simple type hint change may break swathes of plugins with signature violations. As a rule of thumb, try sticking to object type hints and otherwise rely mostly on doc strings and PHP's duck typing.

Checking for Coding Style Violations

Code styles can be checked with PHP_CodeSniffer. A configuration file is located in the _test directory.

Setup

Install via composer:

  cd _test
  composer install

Usage

You can use PHP_CodeSniffer to check a single file or an entire directory including subdirectories using the following commands.

  # Check a single file
  cd _test
  composer check ../path/to/myfile.php
  
  # Check all files in a directory
  cd _test
  composer check ../path/to/directory
devel/coding_style.txt · Last modified: 2023-11-13 21:13 by andi

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki