rfc:consistent_function_names

This is an old revision of the document!


PHP RFC: Consistent Function Names

Introduction

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

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.

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.

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 for 3 classes of functions, plus a few class/interface methods.

  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 <- OLDNAME(New Alias)

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

  • bc_add <- bcadd
  • bc_comp <- bccomp
  • bc_div <- bcdiv
  • bc_mod <- bcmod
  • bc_mul <- bcmul
  • bc_pow <- bcpow
  • bc_pow_mod <- bcpowmod
  • bc_scale <- bcscale
  • bc_sqrt <- bcsqrt
  • bc_sub <- bcsub
  • gettext_bind_text_domain_codeset <- bind_textdomain_codeset
  • gettext_bind_text_domain <- bindtextdomain
  • gettext_dc <- dcgettext
  • gettext_dcn <- dcngettext
  • gettext_d <- dgettext
  • gettext_dn <- dngettext
  • gettext_n <- ngettext
  • gettext_text_domain <- textdomain
  • bz_close <- bzclose
  • bz_compress <- bzcompress
  • bz_decompress <- bzdecompress
  • bz_errno <- bzerrno
  • bz_error <- bzerror
  • bz_errstr <- bzerrstr
  • bz_flush <- bzflush
  • bz_open <- bzopen
  • bz_read <- bzread
  • bz_write <- bzwrite
  • gz_close <- gzclose
  • gz_compress <- gzcompress
  • gz_decode <- gzdecode
  • gz_deflate <- gzdeflate
  • gz_encode <- gzencode
  • gz_eof <- gzeof
  • gz_file <- gzfile
  • gz_getc <- gzgetc
  • gz_gets <- gzgets
  • gz_getss <- gzgetss
  • gz_inflate <- gzinflate
  • gz_open <- gzopen
  • gz_passthru <- gzpassthru
  • gz_puts <- gzputs
  • gz_read <- gzread
  • gz_rewind <- gzrewind
  • gz_seek <- gzseek
  • gz_tell <- gztell
  • gz_uncompress <- gzuncompress
  • gz_write <- gzwrite
  • gz_read_file <- readgzfile
  • gd_image_size <- getimagesize
  • gd_image_size_from_string <- getimagesizefromstring
  • gd_type_to_extension <- image_type_to_extension
  • gd_type_to_mime_type <- image_type_to_mime_type
  • gd_2wbmp <- image2wbmp
  • gd_affine <- imageaffine
  • gd_affine_matrix_concat <- imageaffinematrixconcat
  • gd_affine_matrix_get <- imageaffinematrixget
  • gd_alpha_blending <- imagealphablending
  • gd_antialias <- imageantialias
  • gd_arc <- imagearc
  • gd_char <- imagechar
  • gd_charup <- imagecharup
  • gd_color_allocate <- imagecolorallocate
  • gd_color_allocate_alpha <- imagecolorallocatealpha
  • gd_color_at <- imagecolorat
  • gd_color_closest <- imagecolorclosest
  • gd_color_closest_alpha <- imagecolorclosestalpha
  • gd_color_closest_hwb <- imagecolorclosesthwb
  • gd_color_deallocate <- imagecolordeallocate
  • gd_color_exact <- imagecolorexact
  • gd_color_exact_alpha <- imagecolorexactalpha
  • gd_color_match <- imagecolormatch
  • gd_color_resolve <- imagecolorresolve
  • gd_color_resolve_alpha <- imagecolorresolvealpha
  • gd_color_set <- imagecolorset
  • gd_colors_for_index <- imagecolorsforindex
  • gd_colors_total <- imagecolorstotal
  • gd_color_transparent <- imagecolortransparent
  • gd_convolution <- imageconvolution
  • gd_copy <- imagecopy
  • gd_copy_merge <- imagecopymerge
  • gd_copy_merge_gray <- imagecopymergegray
  • gd_copy_resampled <- imagecopyresampled
  • gd_copy_resized <- imagecopyresized
  • gd_create <- imagecreate
  • gd_create_from_gd2 <- imagecreatefromgd2
  • gd_create_from_gd2_part <- imagecreatefromgd2part
  • gd_create_from_gd <- imagecreatefromgd
  • gd_create_from_gif <- imagecreatefromgif
  • gd_create_from_jpeg <- imagecreatefromjpeg
  • gd_create_from_png <- imagecreatefrompng
  • gd_create_from_string <- imagecreatefromstring
  • gd_create_from_wbmp <- imagecreatefromwbmp
  • gd_create_from_webp <- imagecreatefromwebp
  • gd_create_from_xbm <- imagecreatefromxbm
  • gd_create_from_xpm <- imagecreatefromxpm
  • gd_create_true_color <- imagecreatetruecolor
  • gd_crop <- imagecrop
  • gd_crop_auto <- imagecropauto
  • gd_dashed_line <- imagedashedline
  • gd_destroy <- imagedestroy
  • gd_ellipse <- imageellipse
  • gd_fill <- imagefill
  • gd_filled_arc <- imagefilledarc
  • gd_filled_ellipse <- imagefilledellipse
  • gd_filled_polygon <- imagefilledpolygon
  • gd_filled_rectangle <- imagefilledrectangle
  • gd_fill_to_border <- imagefilltoborder
  • gd_filter <- imagefilter
  • gd_flip <- imageflip
  • gd_font_height <- imagefontheight
  • gd_font_width <- imagefontwidth
  • gd_ft_bbox <- imageftbbox
  • gd_ft_text <- imagefttext
  • gd_gamma_correct <- imagegammacorrect
  • gd_raw2 <- imagegd2
  • gd_raw <- imagegd
  • gd_gif <- imagegif
  • gd_grab_screen <- imagegrabscreen
  • gd_grab_window <- imagegrabwindow
  • gd_interlace <- imageinterlace
  • gd_is_true_color <- imageistruecolor
  • gd_jpeg <- imagejpeg
  • gd_layer_effect <- imagelayereffect
  • gd_line <- imageline
  • gd_load_font <- imageloadfont
  • gd_palette_copy <- imagepalettecopy
  • gd_palette_to_true_color <- imagepalettetotruecolor
  • gd_png <- imagepng
  • gd_polygon <- imagepolygon
  • gd_ps_bbox <- imagepsbbox
  • gd_ps_encode_font <- imagepsencodefont
  • gd_ps_extend_font <- imagepsextendfont
  • gd_ps_free_font <- imagepsfreefont
  • gd_ps_load_font <- imagepsloadfont
  • gd_ps_slant_font <- imagepsslantfont
  • gd_ps_text <- imagepstext
  • gd_rectangle <- imagerectangle
  • gd_rotate <- imagerotate
  • gd_save_alpha <- imagesavealpha
  • gd_scale <- imagescale
  • gd_set_brush <- imagesetbrush
  • gd_set_interpolation <- imagesetinterpolation
  • gd_set_pixel <- imagesetpixel
  • gd_set_style <- imagesetstyle
  • gd_set_thickness <- imagesetthickness
  • gd_set_tile <- imagesettile
  • gd_string <- imagestring
  • gd_string_up <- imagestringup
  • gd_width <- imagesx
  • gd_height <- imagesy
  • gd_true_color_to_palette <- imagetruecolortopalette
  • gd_ttf_bbox <- imagettfbbox
  • gd_ttf_text <- imagettftext
  • gd_types <- imagetypes
  • gd_wbmp <- imagewbmp
  • gd_webp <- imagewebp
  • gd_xbm <- imagexbm
  • gd_iptc_embed <- iptcembed
  • gd_iptc_parse <- iptcparse
  • gd_jpeg2wbmp <- jpeg2wbmp
  • gd_png2wbmp <- png2wbmp
  • mb_decode_mime_header <- mb_decode_mimeheader
  • mb_decode_numeric_entity <- mb_decode_numericentity
  • mb_encode_mime_header <- mb_encode_mimeheader
  • mb_encode_numeric_entity <- mb_encode_numericentity
  • mb_mail <- mb_send_mail (There is mail() as standard function)

Socket Functions

  • socket_get_peer_name <- socket_getpeername
  • socket_get_sock_name <- socket_getsockname
  • socket_recv_from <- socket_recvfrom
  • socket_recv_msg <- socket_recvmsg
  • socket_send_msg <- socket_sendmsg
  • socket_send_to <- socket_sendto
  • socket_errstr <- socket_strerror (Adjust to accord with other names. errstr/errno abbreviations are used by various functions/classes. e.g. bz_errstr(), MySQLi::$errno)
  • sapi_request_headers <- getallheaders (Categorized as apache function, but available for CLI and FCGI also)
  • apache_virtual <- virtual
  • apache_get_env <- apache_getenv
  • apache_set_env <- apache_setenv

Date/Time Functions

  • date_format <- date (Return formatted date string of timestamp)
  • date_get <- getdate (Return array date)
  • date_check <- checkdate
  • time_part <- idate (Retrieve part of date information as int according to format)
  • time <- time (The same as it is now. Return int timestamp)
  • time_make <- mktime (Return timestamp from number of int parameters)
  • time_format <- strftime (Return local time string according to format/locale)
  • time_utc <- gmdate (Return array GMT/UTC timestamp)
  • time_utc_make <- gmmktime (Return GMT/UTC timestamp from array)
  • time_utc_format <- gmstrftime (Return GMT/UTC time string according to format/locale)
  • time_get <- gettimeofday (Return array time of day)
  • time_local <- localtime (Return localtime() result array. More info than time_get/gettimeofday)
  • time_micro <- microtime (Return microtime resolution time)
  • time_parse <- strptime (Parse time string generated by time_format/strftime. Return timestamp)
  • time_from_string <- strtotime (Parse string time and return timestamp. Return timestamp)
  • Directory related : Prefixed by “dir_” It's supposed to be named as “dir module”. Note: These functions changes “directory entry” information.
  • dir_rename <- rename (Rename is actually a directory operation. e.g File deletion/rename is controlled by current dir permission)
  • dir_delete <- rmdir
  • dir_create <- mkdir
  • dir_chown<- chown
  • dir_chmod <- chmod
  • dir_chgrp <- chgrp
  • dir_name <- dirname
  • dir_glob <- glob
  • dir_set <- chdir
  • dir_chroot <- chroot
  • dir_get <- getcwd
  • dir_open <- opendir
  • dir_close <- closedir
  • dir_read <- readdir
  • dir_rewind <- rewinddir
  • dir_scan <- scandir

Function Handling Functions

  • http://php.net/manual/en/ref.funchand.php - All of function handling functions are prefixed by “function_” by these.
  • function_declared <- get_defined_functions (There are get_defined_constants()/get_defined_vars(), but class/interface/trait use get_declared_classes/interfaces/traits())
  • function_create <- create_function (There is function_exists())
  • function_arg <- func_get_arg
  • function_args <- func_get_args
  • function_num_args <- func_num_args
  • function_call_user <- call_user_func
  • function_call_user_array <- call_user_func_array
  • function_shutdown_register <- register_shutdown_function
  • function_tick_register <- register_tick_function
  • function_tick_unregister <- unregister_tick_function
  • function_static_call_array <- forward_static_call_array
  • function_static_call <- forward_static_call

Command Execution Functions

  • exec <- exec (exec() remains as it is)
  • exec_passthru <- passthru (Named after exec())
  • exec_shell <- shell_exec
  • exec_system <- system
  • exec_escape_arg <- escapeshellarg
  • exec_escape_cmd <- escapeshellcmd
  • HTML related:
  • html_entities <- htmlentities
  • html_escape <- htmlspecialchars (Rename it with real meaning)
  • html_escape_decode <- htmlspecialchars_decode
  • html_nl2br <- nl2br
  • html_strip_tags <- strip_tags
  • html_translation_table <- get_html_translation_table
  • Locate related:
  • locale_conv <- localeconv
  • locale_set <- setlocale
  • locale_info <- nl_langinfo
  • “string” function but no “str_” prefix
  • str_cslashes <- addcslashes
  • str_cslashes_strip <- stripcslashes
  • str_slashes <- addslashes
  • str_slashes_strip <- stripslashes
  • str_chop <- chop
  • str_count_chars <- count_chars
  • str_chunk_split <- chunk_split
  • str_explode <- explode
  • str_implode <- implode
  • str_money_format <- money_format
  • str_number_format <- number_format
  • str_levenshtein <- levenshtein
  • str_metaphone <- metaphone
  • str_parse <- parse_str
  • str_quote_meta <- quotemeta
  • str_similar_text <- similar_text
  • str_soundex <- soundex
  • str_sscanf <- sscanf
  • str_rtrim <- rtrim
  • str_trim <- trim
  • str_ltrim <- ltrim
  • str_lc_first <- lcfirst
  • str_uc_first <- ucfirst
  • str_uc_words <- ucwords
  • str_word_wrap <- wordwrap
  • Comparison:
  • str_cmp <- strcmp
  • str_ncmp <- strncmp
  • str_case_cmp <- strcasecmp
  • str_ncase_cmp <- strncasecmp
  • str_nat_cmp <- strnatcmp
  • str_nat_case_cmp <- strnatcasecmp
  • Conversion:
  • str_to_lower <- strtolower
  • str_to_upper <- strtoupper
  • Misc:
  • str_get_csv <- str_getcsv
  • Named after libc:
  • ord <- ord (Keep as it is now)
  • chr <- chr (Keep as it is now. str_chr() is strstr() alias.)
  • str_chr <- strchr
  • str_cmp <- strcmp
  • str_coll <- strcoll
  • str_cspn <- strcspn
  • str_ipos <- stripos
  • str_istr <- stristr
  • str_len <- strlen
  • str_pbrk <- strpbrk
  • str_pos <- strpos
  • str_rchr <- strrchr
  • str_rev <- strrev
  • str_ripos <- strripos
  • str_rpos <- strrpos
  • str_spn <- strspn
  • str_str <- strstr
  • str_tok <- strtok
  • str_tr <- strtr
  • mb_str_cut <- mb_strcut
  • mb_str_trim_width <- mb_strimwidth
  • mb_str_ipos <- mb_stripos
  • mb_str_istr <- mb_stristr
  • mb_str_len <- mb_strlen
  • mb_str_pos <- mb_strpos
  • mb_str_rchr <- mb_strrchr
  • mb_str_richr <- mb_strrichr
  • mb_str_ripos <- mb_strripos
  • mb_str_rpos <- mb_strrpos
  • mb_str_str <- mb_strstr
  • mb_str_to_lower <- mb_strtolower
  • mb_str_to_upper <- mb_strtoupper
  • mb_str_width <- mb_strwidth
  • grapheme_str_ipos <- grapheme_stripos
  • grapheme_str_istr <- grapheme_stristr
  • grapheme_str_len <- grapheme_strlen
  • grapheme_str_pos <- grapheme_strpos
  • grapheme_str_ripos <- grapheme_strripos
  • grapheme_str_rpos <- grapheme_strrpos
  • grapheme_str_str <- grapheme_strstr
  • array_sort <- sort (Sort values)
  • array_sort_reverse <- rsort (Reverse sort values)
  • array_sort_user <- usort (User sort values)
  • array_sort_assoc <- asort (Keep key and sort)
  • array_sort_assoc_reverse <- arsort (Keep key and reverse sort)
  • array_sort_assoc_user <- uasort (Keep key and user sort)
  • array_sort_key <- ksort (Sort keys)
  • array_sort_key_reverse <- krsort (Reverse sort keys)
  • array_sort_key_user <- uksort (User key sort)
  • array_sort_natural <- natsort (Natural sort)
  • array_sort_natural_case <- natcasesort (Natural sort without case)
  • array_in <- in_array
  • array_range <- range (Create array of range)
  • array_shuffle <- shuffle (Randomize values)
  • path_base_name <- basename
  • path_info <- pathinfo
  • realpath related : Could be as it is now?
  • realpath <- realpath
  • realpath_cache_get <- realpath_cache_get
  • realpath_cache_size <- realpath_cache_size
  • This is one of exception
  • file_read <- readfile (This could be file_read() or file_passthru(). If rename fopen()/etc with “file_” prefix, file_read() may conflict with fread() file_passthru() may conflict with fpassthru().)
  • pipe_close <- pclose
  • pipe_open <- popen
  • file_atime <- fileatime
  • file_ctime <- filectime
  • file_group <- filegroup
  • file_inode <- fileinode
  • file_mtime <- filemtime
  • file_owner <- fileowner
  • file_perms <- fileperms
  • file_size <- filesize
  • file_type <- filetype
  • file_name_match <- fnmatch
  • file_temp_name <- tempnam
  • file_copy <- copy
  • file_stat <- stat
  • file_stat_clear_cache <- clearstatcache
  • file_delete <- unlink (There is dummy “delete()” function entry for unlink(). Unlink is a directory operation in fact, but made it as file_delete(). There will be dir_delete())
  • f*() : Examples are fopen(), fread(). These functions are for file(stream) resource. “f” prefix functions are kept, there should be “ftemp(tmpfile)”,“frewind(rewind)” because these operates with file(stream) resource.
  • fopen <- fopen
  • fclose <- fclose
  • feof <- feof
  • fflush <- fflush
  • fgetc <- fgetc
  • fget_csv <- fgetcsv
  • fgets <- fgets
  • fgetss <- fgetss
  • fpassthru <- fpassthru
  • fput_csv <- fputcsv
  • fputs <- fputs
  • fread <- fread
  • fscanf <- fscanf
  • fseek <- fseek
  • fstat <- fstat
  • ftell <- ftell
  • ftruncate <- ftruncate
  • fwrite <- fwrite
  • frewind <- rewind (This one is exception that does not have “f” prefix, but operates with file handle)
  • ftemp <- tmpfile (This one is exception that does not have “f” prefix, but returns file handle)

Other Standard Functions

  • time_sleep <- sleep
  • time_nano_sleep <- time_nanosleep
  • time_micro_sleep <- usleep
  • time_unique_id <- uniqid (uniqid() is microtime() based)
  • sys_get_load_avg <- sys_getloadavg
  • php_strip_white_space <- php_strip_whitespace
  • url_decode <- urldecode
  • url_encode <- urlencode
  • url_raw_decode <- rawurldecode
  • url_raw_encode <- rawurlencode
  • url_parse <- parse_url
  • url_build_query <- http_build_query (Make it URL function)
  • url_meta_tags <- get_meta_tags (Get meta tags from URL/file)
  • url_headers <- get_headers (Get headers from URL)
  • php_credits <- phpcredits
  • php_info <- phpinfo
  • php_version <- phpversion
  • get_opt <- getopt
  • get_env <- getenv (This could be “env_get”)
  • put_env <- putenv (This could be “env_set”)
  • Following get_() may be prefixed by “php_” rather than “get_”.
  • get_last_mod <- getlastmod (Return main script timestamp.)
  • get_my_gid <- getmygid (“my_” prefix used because they return info about current script.)
  • get_my_inode <- getmyinode
  • get_my_pid <- getmypid
  • get_my_uid <- getmyuid
  • get_rusage <- getrusage
  • bool_val <- boolval
  • double_val <- doubleval
  • float_val <- floatval
  • int_val <- intval
  • str_val <- strval
  • type_get <- gettype
  • type_set <- settype
  • type_resource <- get_resource_type (Get resource type)
  • is_set <- isset (There are number of is_*(). e.g.is_int()/is_string()/etc)
  • http://php.net/manual/en/ref.classobj.php - Most of Class/interface/trait related functions are prefixed by “class_”/“interface_”/“trait_”.
  • class_called <- get_called_class (Get late static binding class name. There are class_exists()/class_alias())
  • class_methods <- get_class_methods
  • class_vars <- get_class_vars (Get class property)
  • class_get <- get_class (Get class name of an object)
  • class_parent <- get_parent_class
  • class_object_vars <- get_object_vars (Get instance property)
  • class_declared <- get_declared_classes
  • interface_declared <- get_declared_interfaces (There is interface_exists())
  • trait_declared <- get_declared_traits (There is trait_exists())
  • method_exists <- method_exists (Keep as it is now. There are class/trait/interface/function_exists())
  • property_exists <- property_exists (Keep as it is now)
  • http://php.net/manual/en/book.info.php - PHP related function are prefixed by “php_”.
  • php_extension_loaded <- extension_loaded
  • php_extension_loaded_all <- get_loaded_extensions (Like ini_get_all())
  • php_extension_functions <- get_extension_funcs
  • php_dl <- dl
  • php_cfg_var <- get_cfg_var (Get value from configuration(INI) file including non-INI value)
  • php_current_user <- get_current_user (Owner of current PHP script file)
  • php_defined_constants <- get_defined_constants (There is get_defined_vars())
  • php_include_path_get <- get_include_path (Like ini_get/set/restore(). ini_set/get/restore() can do the same. Deprecate all them? or only have php_include_path() does both get/set?)
  • php_include_path_set <- set_include_path
  • php_include_path_restore <- restore_include_path
  • php_included_files <- get_included_files
  • php_required_files <- get_required_files
  • php_time_limit <- set_time_limit (“_set” may be omitted. It changes “max_execution_time” INI. ini_set() can do the same. Deprecate?)

Methods

  • StdClass::__setState() <- StdClass::__set_state()
  • SessionIdInterface::createSid() <- SessionIdInterface::create_sid()

Backward Incompatible Changes

  • New function names may have name collisions with user's scripts.

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.

  • Parameter order inconsistency. This may be addressed by “default namespace” in other RFC.
  • Return type inconsistency. Most severe inconsistency is “wrong number of parameters returns NULL”. This may be addressed by “INI switch” in other RFC.
  • Constant name inconsistency.
  • Class and method names. Only “__set_state()” and “create_sid()” methods are addressed.

Future Scope

  • Use of namespace to clean up global namespace at all.
  • New APIs that replace old APIs.
  • Parameter order inconsistency.
  • Return type inconsistency.
  • Constant name inconsistency.
  • Class inconsistency.

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

  • function_arg — Return an item from the argument list
  • function_args — Returns an array comprising a function's argument list
  • function_num_args — Returns the number of arguments passed to the function
  • function_exists — Return TRUE if the given function has been defined
  • function_declared — Returns an array of all defined functions
  • function_call_user_array — Call a callback with an array of parameters
  • function_call_user — Call the callback given by the first parameter
  • function_create — Create an anonymous (lambda-style) function
  • function_shutdown_register — Register a function for execution on shutdown
  • function_static_call_array — Call a static method and pass the arguments as array
  • function_static_call — Call a static method
  • function_tick_register — Register a function for execution on each tick
  • function_tick_unregister — De-register a function for execution on each tick

Classes/Object Functions

  • __autoload — Attempt to load undefined class
  • call_user_method_array — Call a user method given with an array of parameters [deprecated]
  • call_user_method — Call a user method on an specific object [deprecated]
  • class_alias — Creates an alias for a class (Aliases should not be listed, but they should be searchable)
  • class_called — the “Late Static Binding” class name
  • class_declared — Returns an array with the name of the defined classes
  • class_exists — Checks if the class has been defined
  • class_get — Returns the name of the class of an object
  • class_methods — Gets the class methods' names
  • class_object_vars — Gets the properties of the given object
  • class_parent — Retrieves the parent class name for object or class
  • class_vars — Get the default properties of the class
  • interface_declared — Returns an array of all declared interfaces
  • interface_exists — Checks if the interface has been defined
  • is_a — Checks if the object is of this class or has this class as one of its parents
  • is_subclass_of — Checks if the object has this class as one of its parents
  • method_exists — Checks if the class method exists
  • property_exists — Checks if the object or class has a property
  • trait_declared — Returns an array of all declared traits
  • trait_exists — Checks if the trait exists

PHP Options and Information

  • assert_options — Set/get the various assert flags
  • assert — Checks if assertion is FALSE
  • cli_get_process_title — Returns the current process title
  • cli_set_process_title — Sets the process title
  • gc_collect_cycles — Forces collection of any existing garbage cycles
  • gc_disable — Deactivates the circular reference collector
  • gc_enable — Activates the circular reference collector
  • gc_enabled — Returns status of the circular reference collector
  • get_magic_quotes_gpc — Gets the current configuration setting of magic_quotes_gpc [Deprecated]
  • get_magic_quotes_runtime — Gets the current active configuration setting of magic_quotes_runtime [Deprecated]
  • get_env — Gets the value of an environment variable
  • get_last_mod — Gets time of last page modification
  • get_my_gid — Get PHP script owner's GID
  • get_my_inode — Gets the inode of the current script
  • get_my_pid — Gets PHP's process ID
  • get_my_uid — Gets PHP script owner's UID
  • get_opt — Gets options from the command line argument list
  • get_rusage — Gets the current resource usages
  • ini_alter — Alias of ini_set (Aliases should not be listed, but they should be searchable)
  • ini_get_all — Gets all configuration options
  • ini_get — Gets the value of a configuration option
  • ini_restore — Restores the value of a configuration option
  • ini_set — Sets the value of a configuration option
  • magic_quotes_runtime — Alias of set_magic_quotes_runtime [Deprecated] (Aliases should not be listed, but they should be searchable)
  • main — Dummy for main
  • memory_get_peak_usage — Returns the peak of memory allocated by PHP
  • memory_get_usage — Returns the amount of memory allocated to PHP
  • php_dl — Loads a PHP extension at runtime
  • php_cfg_var — Gets the value of a PHP configuration option
  • php_credits — Prints out the credits for PHP
  • php_current_user — Gets the name of the owner of the current PHP script
  • php_defined_constants — Returns an associative array with the names of all the constants and their values
  • php_extension_funcions — Returns an array with the names of the functions of a module
  • php_extension_loaded — Find out whether an extension is loaded
  • php_extension_loaded_all — Returns an array with the names of all modules compiled and loaded
  • php_included_files — Returns an array with the names of included or required files
  • php_include_path_get — Gets the current include_path configuration option
  • php_include_path_set — Sets the include_path configuration option
  • php_include_path_restore — Restores the value of the include_path configuration option
  • php_info — Outputs information about PHP's configuration
  • php_ini_loaded_file — Retrieve a path to the loaded php.ini file
  • php_ini_scanned_files — Return a list of .ini files parsed from the additional ini dir
  • php_logo_guid — Gets the logo guid
  • php_required_files — Alias of get_included_files (Aliases should not be listed, but they should be searchable)
  • php_sapi_name — Returns the type of interface between web server and PHP
  • php_time_limit — Limits the maximum execution time
  • php_uname — Returns information about the operating system PHP is running on
  • php_version — Gets the current PHP version
  • put_env — Sets the value of an environment variable
  • set_magic_quotes_runtime — Sets the current active configuration setting of magic_quotes_runtime [Deprecated]
  • sys_get_temp_dir — Returns directory path used for temporary files
  • version_compare — Compares two “PHP-standardized” version number strings
  • zend_logo_guid — Gets the Zend guid
  • zend_thread_id — Returns a unique identifier for the current thread
  • zend_version — Gets the version of the current Zend engine

Variable handling

  • bool_val — Get the boolean value of a variable
  • debug_zval_dump — Dumps a string representation of an internal zend value to output
  • double_val — Alias of floatval (Aliases should not be listed, but they should be searchable)
  • empty — Determine whether a variable is empty
  • float_val — Get float value of a variable
  • import_request_variables — Import GET/POST/Cookie variables into the global scope
  • int_val — Get the integer value of a variable
  • is_array — Finds whether a variable is an array
  • is_bool — Finds out whether a variable is a boolean
  • is_callable — Verify that the contents of a variable can be called as a function
  • is_double — Alias of is_float (Aliases should not be listed, but they should be searchable)
  • is_float — Finds whether the type of a variable is float
  • is_int — Find whether the type of a variable is integer
  • is_integer — Alias of is_int (Aliases should not be listed, but they should be searchable)
  • is_long — Alias of is_int (Aliases should not be listed, but they should be searchable)
  • is_null — Finds whether a variable is NULL
  • is_numeric — Finds whether a variable is a number or a numeric string
  • is_object — Finds whether a variable is an object
  • is_real — Alias of is_float (Aliases should not be listed, but they should be searchable)
  • is_resource — Finds whether a variable is a resource
  • is_scalar — Finds whether a variable is a scalar
  • is_string — Find whether the type of a variable is string
  • is_set — Determine if a variable is set and is not NULL
  • php_defined_vars — Returns an array of all defined variables
  • print_r — Prints human-readable information about a variable
  • serialize — Generates a storable representation of a value
  • str_val — Get string value of a variable
  • type_get — Get the type of a variable
  • type_set — Set the type of a variable
  • type_resource — Returns the resource type
  • unserialize — Creates a PHP value from a stored representation
  • unset — Unset a given variable
  • var_dump — Dumps information about a variable
  • var_export — Outputs or returns a parsable string representation of a variable

Program execution Functions

  • exec — Execute an external program
  • exec_escape_arg — Escape a string to be used as a shell argument
  • exec_escape_cmd — Escape shell metacharacters
  • exec_passthru — Execute an external program and display raw output
  • exec_shell — Execute command via shell and return the complete output as a string
  • exec_system — Execute an external program and display the output
  • proc_close — Close a process opened by proc_open and return the exit code of that process
  • proc_get_status — Get information about a process opened by proc_open
  • proc_nice — Change the priority of the current process
  • proc_open — Execute a command and open file pointers for input/output
  • proc_terminate — Kills a process opened by proc_open

String Functions

  • bin2hex — Convert binary data into hexadecimal representation
  • chr — Return a specific character
  • convert_cyr_string — Convert from one Cyrillic character set to another
  • convert_uudecode — Decode a uuencoded string
  • convert_uuencode — Uuencode a string
  • crc32 — Calculates the crc32 polynomial of a string
  • crypt — One-way string hashing
  • echo — Output one or more strings
  • fprintf — Write a formatted string to a stream
  • hebrev — Convert logical Hebrew text to visual text
  • hebrevc — Convert logical Hebrew text to visual text with newline conversion
  • hex2bin — Decodes a hexadecimally encoded binary string
  • html_entity_decode — Convert all HTML entities to their applicable characters
  • html_entities — Convert all applicable characters to HTML entities
  • html_escape_decode — Convert special HTML entities back to characters
  • html_escape — Convert special characters to HTML entities
  • html_nl2br — Inserts HTML line breaks before all newlines in a string
  • html_translation_table — Returns the translation table used by htmlspecialchars and htmlentities
  • locale_conv — Get numeric formatting information
  • locale_set — Set locale information
  • locale_info — Query language and locale information
  • md5_file — Calculates the md5 hash of a given file
  • md5 — Calculate the md5 hash of a string
  • ord — Return ASCII value of character
  • print — Output a string
  • printf — Output a formatted string
  • quoted_printable_decode — Convert a quoted-printable string to an 8 bit string
  • quoted_printable_encode — Convert a 8 bit string to a quoted-printable string
  • sha1_file — Calculate the sha1 hash of a file
  • sha1 — Calculate the sha1 hash of a string
  • sprintf — Return a formatted string
  • str_case_cmp — Binary safe case-insensitive string comparison
  • str_chr — Alias of strstr (Aliases should not be listed, but they should be searchable)
  • str_chop — Alias of str_rtrim (Aliases should not be listed, but they should be searchable)
  • str_chunk_split — Split a string into smaller chunks
  • str_cmp — Binary safe string comparison
  • str_count_chars — Return information about characters used in a string
  • str_coll — Locale based string comparison
  • str_cspn — Find length of initial segment not matching mask
  • str_cslash_strip — Un-quote string quoted with addcslashes
  • str_cslash — Quote string with slashes in a C style
  • str_explode — Split a string by string
  • str_get_csv — Parse a CSV string into an array
  • str_implode — Join array elements with a string
  • str_ipos — Find the position of the first occurrence of a case-insensitive substring in a string
  • str_ireplace — Case-insensitive version of str_replace.
  • str_istr — Case-insensitive strstr
  • str_join — Alias of implode (Aliases should not be listed, but they should be searchable)
  • str_lc_first — Make a string's first character lowercase
  • str_len — Get string length
  • str_levenshtein — Calculate Levenshtein distance between two strings
  • str_ltrim — Strip whitespace (or other characters) from the beginning of a string
  • str_metaphone — Calculate the metaphone key of a string
  • str_money_format — Formats a number as a currency string
  • str_number_format — Format a number with grouped thousands
  • str_parse — Parses the string into variables
  • str_quotemeta — Quote meta characters
  • str_rtrim — Strip whitespace (or other characters) from the end of a string
  • str_similar_text — Calculate the similarity between two strings
  • str_soundex — Calculate the soundex key of a string
  • str_sscanf — Parses input from a string according to a format
  • str_nat_case_cmp — Case insensitive string comparisons using a “natural order” algorithm
  • str_nat_cmp — String comparisons using a “natural order” algorithm
  • str_ncase_cmp — Binary safe case-insensitive string comparison of the first n characters
  • str_ncmp — Binary safe string comparison of the first n characters
  • str_pad — Pad a string to a certain length with another string
  • str_pbrk — Search a string for any of a set of characters
  • str_pos — Find the position of the first occurrence of a substring in a string
  • str_repeat — Repeat a string
  • str_replace — Replace all occurrences of the search string with the replacement string
  • str_rot13 — Perform the rot13 transform on a string
  • str_rchr — Find the last occurrence of a character in a string
  • str_rev — Reverse a string
  • str_ripos — Find the position of the last occurrence of a case-insensitive substring in a string
  • str_rpos — Find the position of the last occurrence of a substring in a string
  • str_shuffle — Randomly shuffles a string
  • str_split — Convert a string to an array
  • str_spn — Finds the length of the initial segment of a string consisting entirely of characters contained within a given mask.
  • str_str — Find the first occurrence of a string
  • str_slashes_strip — Un-quotes a quoted string
  • str_slashes — Quote string with slashes
  • str_strip_tags — Strip HTML and PHP tags from a string
  • str_tok — Tokenize string
  • str_to_lower — Make a string lowercase
  • str_to_upper — Make a string uppercase
  • str_tr — Translate characters or replace substrings
  • str_trim — Strip whitespace (or other characters) from the beginning and end of a string
  • str_uc_first — Make a string's first character uppercase
  • str_uc_words — Uppercase the first character of each word in a string
  • str_word_count — Return information about words used in a string
  • str_word_wrap — Wraps a string to a given number of characters
  • substr_compare — Binary safe comparison of two strings from an offset, up to length characters
  • substr_count — Count the number of substring occurrences
  • substr_replace — Replace text within a portion of a string
  • substr — Return part of a string
  • vfprintf — Write a formatted string to a stream
  • vprintf — Output a formatted string
  • vsprintf — Return a formatted string

Filesystem Functions

  • delete — See file_delete, dir_delete or unset
  • dir_glob — Find pathnames matching a pattern
  • dir_create — Makes directory
  • dir_delete — Removes directory
  • dir_name — Returns parent directory's path
  • dir_rename — Renames a file or directory
  • disk_free_space — Returns available space on filesystem or disk partition
  • disk_total_space — Returns the total size of a filesystem or disk partition
  • diskfreespace — Alias of disk_free_space (Aliases should not be listed, but they should be searchable)
  • fclose — Closes an open file pointer
  • feof — Tests for end-of-file on a file pointer
  • fgetc — Gets character from file pointer
  • fgets — Gets line from file pointer
  • fgetss — Gets line from file pointer and strip HTML tags
  • file_atime — Gets last access time of file
  • file_chgrp — Changes file group
  • file_chmod — Changes file mode
  • file_chown — Changes file owner
  • file_copy — Copies file
  • file_ctime — Gets inode change time of file
  • file_delete — Deletes a file
  • file_exists — Checks whether a file or directory exists
  • fflush — Flushes the output to a file
  • file_get_contents — Reads entire file into a string
  • file_get_csv — Gets line from file pointer and parse for CSV fields
  • file_group — Gets file group
  • file_inode — Gets file inode
  • file_mtime — Gets file modification time
  • file_owner — Gets file owner
  • file_perms — Gets file permissions
  • file_put_contents — Write a string to a file
  • file_name_match — Match filename against a pattern
  • file_passthru — Output all remaining data on a file pointer
  • file_put_csv — Format line as CSV and write to file pointer
  • file_puts — Alias of fwrite (Aliases should not be listed, but they should be searchable)
  • file_size — Gets file size
  • file_temp_name — Create file with unique file name
  • file_touch — Sets access and modification time of file
  • file_type — Gets file type
  • file_umask — Changes the current umask
  • file_write — Binary-safe file write
  • file — Reads entire file into an array
  • flock — Portable advisory file locking
  • fopen — Opens file or URL
  • fread — Binary-safe file read
  • frewind — Rewind the position of a file pointer
  • fscanf — Parses input from a file according to a format
  • fseek — Seeks on a file pointer
  • fstat — Gets information about a file using an open file pointer
  • ftell — Returns the current position of the file read/write pointer
  • ftemp — Creates a temporary file
  • ftruncate — Truncates a file to a given length
  • is_dir — Tells whether the filename is a directory
  • is_executable — Tells whether the filename is executable
  • is_file — Tells whether the filename is a regular file
  • is_link — Tells whether the filename is a symbolic link
  • is_readable — Tells whether a file exists and is readable
  • is_uploaded_file — Tells whether the file was uploaded via HTTP POST
  • is_writable — Tells whether the filename is writable
  • is_writeable — Alias of is_writable (Aliases should not be listed, but they should be searchable)
  • link_chgrp — Changes group ownership of symlink
  • link_chown — Changes user ownership of symlink
  • link_info — Gets information about a link
  • link_read — Returns the target of a symbolic link
  • link_stat — Gives information about a file or symbolic link
  • link_symbolic — Creates a symbolic link
  • link — Create a hard link
  • move_uploaded_file — Moves an uploaded file to a new location
  • parse_ini_file — Parse a configuration file
  • parse_ini_string — Parse a configuration string (This is string function. Or make them ini function? ini_string()/ini_file() )
  • path_base_name — Returns trailing name component of path
  • path_info — Returns information about a file path
  • pipe_close — Closes process file pointer
  • pipe_open — Opens process file pointer
  • read_file — Outputs a file
  • realpath_cache_get — Get realpath cache entries
  • realpath_cache_size — Get realpath cache size
  • realpath — Returns canonicalized absolute pathname
  • set_file_buffer — Alias of stream_set_write_buffer (This is kind of deprecated function. User should use stream function)
  • stat_clear_cache — Clears file status cache
  • stat — Gives information about a file

References

Links to external references, discussions or RFCs

Rejected Features

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

rfc/consistent_function_names.1425532296.txt.gz · Last modified: 2017/09/22 13:28 (external edit)