Userland Naming Guide

The following is a guide for how to best choose names for identifiers in userland PHP code. When choosing names for any code that creates symbols in the global namespace, it is important to take into account the following guidelines to prevent future versions of PHP from clashing with user symbols.

Global Namespace

Here is an overview of code constructs that go into the global namespace:

• functions
• classes
• interfaces
• traits
• enumerations
• constants (not class constants)
• variables defined outside of functions and methods

Rules

The following list gives an overview of which rights the PHP project reserves for itself, when choosing names for new internal identifiers. The definitive guide is the official PHP coding standards:

• PHP owns the top-level namespace but tries to find decent descriptive names and avoid any obvious clashes.
• Function names use underscores between words, class names use PascalCase, and method names use camelCase.

• PHP will prefix any global symbols of an extension with the name of the extension. (In the past, there have been numerous exceptions to this rule, so some existing names are not prefixed.) Examples:

  • curl_exec()
  • mysqli_query()
  • PREG_SPLIT_DELIM_CAPTURE
  • new DOMDocument()
  • strpos() (example of a past mistake)
  • new SplFileObject()

• Iterators and Exceptions are however simply postfixed with "Iterator" and "Exception." Examples:

  • ArrayIterator
  • LogicException

• PHP reserves all symbols starting with __ as magical. It is recommended not to create symbols starting with __ in PHP, unless the intent is to use documented magical functionality. Examples:

  • __get()
  • __construct()

Tips

In order to write future-proof code, it is recommended not to place many variables, functions or classes in the global namespace. This will prevent naming conflicts with third-party code as well as possible future additions to the language.

One common way to prevent naming conflicts of functions and classes is to add them to their own dedicated namespace.

<?php

namespace MyProject;

function my_function()
{
    return true;
}

\MyProject\my_function();

?>

Keeping track of the namespaces already in use is still necessary, but once a namespace has been chosen, all functions and classes can be added to it without having to think about conflicts again.

It is considered best practice to limit the number of variables added to the global scope in order to prevent naming conflicts with third-party code.