Table of Contents

PHP RFC: Consistent Function Names

Introduction

First of all, this RFC will not remove any old function names. This RFC only proposes renaming offending function names and have aliases for old names. Old names are _not_ deprecated.

There are many functions that named before naming standard in CODING_STANDARDS. Therefore, PHP has function names like phpversion() and htmlspecialchars().

We have many function names that comply IEEE 1003.1 standard names. IEEE 1003.1 is also well established names, but it has different naming. IEEE 1003.1 names can be use as aliases.

String and array function have different parameter order for needle and subject to be searched. This should be fixed also.

Without cleanups, PHP may have inconsistent API names even if PHP has new APIs for the same purpose because we care compatibility a lot. Unless we have standard confirming function names at some point, we may keep inconsistent function names forever and never have consistent function names.

Discussions

Namespace should be used

Namespace is better solution, but it is much severe BC. It requires namespace change to import whole namespace (e.g. namespace \php\7 as \;) into “\” namespace and users has to import namespace to execute old scripts. The import code breaks backward compatibility also. BC can be mitigated by having INI like 'default_namespace=“\php\5 \php\7”'.

However, namespace itself will not create new standard confirming names. Aliasing is needed anyway.

Scalar object is better

Scalar objects can be solution for cleanup old functions. Even if PHP has scalar objects, old inconsistent function names remain.

New API does not remove legacy function names. Aliasing is required to confirm the standard.

Criticism will not end

PHP may be a subject of criticism regardless of this RFC. However, criticism for basic function name inconsistencies is valid one. Languages are better to be consistent in the first place.

Besides, it seems PHP has too many name violations. Please refer to “List of functions to be renamed” section.

Effort does not worth it

If this is the only reason, please vote “yes” because I'll prepare complete patch and update all documents in English. (Help is appreciated!)

PHP has nice alias system and has no performance penalty at all. The cost is a little memory to hold function entries.

I prefer old names

You can use old names for good. Therefore, please consider new developers and avoid confusions they may have.

BC?

Most users never define “php_version()” etc. There are some new names that might be issue. Discussion is appreciated.

Creates Confusions

Any changes cause confusions. Uniform Variable Syntax brings consistent expression evaluation, but it requires to add () to have old behaviors. Fix "foreach" behavior is really nice change. It achieves consistent/predictable foreach behaviors, but older PHP behaves strangely and code works with PHP7 misbehaves in old PHPs.

This RFC will cause confusions for sure in short term. There are new consistent function names and user may wander which name should be used for old PHP compatibility. However, the confusion will disappear in the long run. Having consistent names will bring more benefits than disadvantages in the long run.

Too many aliases pollute manual

Manual and search system will be modified not to show alias functions. Aliases (old names) will be documented in original function pages. Aliases will be searchable by its name (old name).

Keep inconsistent name forever or not

Without this RFC, PHP will keep inconsistent function names even for most basic function forever. Inconsistent/unpredictable function names keep hurting PHP forever.

Proposal

Respect CODING_STANDARDS and rename functions violate the standard. All of old function names are kept and documented forever unless other RFC that proposes removal passes.

Have IEEE 1003.1 standard names as valid aliases function names that copy IEEE 1003.1 bevavors and update CONDING_STANDARDS to allow these names including names following convension. e.g. strpos/stristr. IEEE 1003.1 complied aliases should be kept as long as main function exists and the compliance is mentioned in the manual. Other well established library, e.g. libc, function name may be defined as alias of main function even if it violates PHP coding standards as long as it has module prefixes. Exception is “Standard Module” functions.

Fix array function parameter ordering issue by using IEEE parameter order. i.e. Use “int strstr ( string $haystack , mixed $needle [, int $offset= 0 ] )” order.

User Functions/Methods Naming Conventions
------------------
 
1.  Function names for user-level functions should be enclosed with in
    the PHP_FUNCTION() macro. They should be in lowercase, with words
    underscore delimited, with care taken to minimize the letter count.
    Abbreviations should not be used when they greatly decrease the
    readability of the function name itself::
 
    Good:
    'mcrypt_enc_self_test'
    'mysql_list_fields'
 
    Ok:
    'mcrypt_module_get_algo_supported_key_sizes'
    (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
    'get_html_translation_table'
    (could be 'html_get_trans_table'?)
 
    Bad:
    'hw_GetObjectByQueryCollObj'
    'pg_setclientencoding'
    'jf_n_s_i'
 
2.  If they are part of a "parent set" of functions, that parent should
    be included in the user function name, and should be clearly related
    to the parent program or function family. This should be in the form
    of ``parent_*``::
 
    A family of 'foo' functions, for example:
 
    Good:
    'foo_select_bar'
    'foo_insert_baz'
    'foo_delete_baz'
 
    Bad:
    'fooselect_bar'
    'fooinsertbaz'
    'delete_foo_baz'
 
3.  Function names used by user functions should be prefixed
    with ``_php_``, and followed by a word or an underscore-delimited list of
    words, in lowercase letters, that describes the function.  If applicable,
    they should be declared 'static'.
 
4.  Variable names must be meaningful.  One letter variable names must be
    avoided, except for places where the variable has no real meaning or
    a trivial meaning (e.g. for (i=0; i<100; i++) ...).
 
5.  Variable names should be in lowercase.  Use underscores to separate
    between words.
 
6.  Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
    or 'camel caps') naming convention, with care taken to minimize the
    letter count. The initial letter of the name is lowercase, and each
    letter that starts a new 'word' is capitalized::
 
    Good:
    'connect()'
    'getData()'
    'buildSomeWidget()'
 
    Bad:
    'get_Data()'
    'buildsomewidget'
    'getI()'
 
7.  Classes should be given descriptive names. Avoid using abbreviations where
    possible. Each word in the class name should start with a capital letter,
    without underscore delimiters (CamelCaps starting with a capital letter).
    The class name should be prefixed with the name of the 'parent set' (e.g.
    the name of the extension)::
 
    Good:
    'Curl'
    'FooBar'
 
    Bad:
    'foobar'
    'foo_bar'

This RFC proposes multiple votes.

  1. Have CODING_STANDARDS name functions.
  2. Have CODING_STANDARDS name methods
    • __set_state() - Magic method for var_export()
    • create_sid() - SessionIdInterface. This is undocumented interface.

Exception is SessionIdInterface::create_sid(), it would be simply renamed because it is undocumented interface and there will be no aliases.

List of functions to be renamed

Function names are renamed according to CODING_STANDARDS.

Old names are defined as aliases.

Format

NEW_NAME(bold) indicates it is not a simple “_” addition and/or “modname_” prefix addition.

NOTE: CORDING_STANDARDS requires module name prefix for module functions and almost strictly conforming the standard.

Functions other than Standard module

Socket Functions

Date/Time Functions

Function Handling Functions

Command Execution Functions

Other Standard Functions

Methods

Backward Incompatible Changes

Proposed PHP Version(s)

PHP 7.0

RFC Impact

To SAPIs

All modules that have non standard names.

To Existing Extensions

All modules that have non standard names. e.g. GD

To Opcache

None

New Constants

None. Constant name is not subject of this RFC.

php.ini Defaults

None.

Open Issues

Unaffected PHP Functionality

This RFC only addresses inconsistent names. These are the list of related inconsistencies.

Future Scope

Proposed Voting Choices

Requires 50%+1 majority

  1. Have CODING_STANDARDS names for functions
  2. Have CODING_STANDARDS names for methods

Patches and Tests

TBD. Patch is trivial, but it affects many places. Patch will be prepared after vote passes for review.

Implementation

After the project is implemented, this section should contain

  1. the version(s) it was merged to
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature

How Document will look like after RFC

These are example manual pages after this RFC. Deprecated function names are untouched. Aliased old function names are written in new name page.

To avoid mixed listing of function aliases, tweaks to the manual and search system may be required. Document search system shows aliased name as candidate for simple renames. Aliased search sample

Function Handling

Classes/Object Functions

PHP Options and Information

Arrays

Variable handling

Program execution Functions

String Functions

Filesystem Functions

References

Links to external references, discussions or RFCs

Rejected Features

Keep this updated with features that were discussed on the mail lists.