# [RFC] [DISCUSSION] Consistent Function Names

- Thread: https://externals.io/message/84189
- Original archive: https://news-web.php.net/php.internals/84189
- Started by Yasuo Ohgaki on 2015-03-02T21:52:03+00:00
- Messages: 17
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #84189 — Yasuo Ohgaki — 2015-03-02T21:52:03+00:00

URL: https://externals.io/message/84189#84189

Hi all,

First of all, I have no intention to remove nor deprecate old function
names.
Old function names must exist for compatibility and should be able to use
forever.

We have CODING_STANDARDS[1] for a long time.
However, PHP has so many functions that do not confirm this. Many of
violating functions can have standard conforming names safely

This RFC[2] proposes the CODING_STANDARDS confirmed function names.
The list[3] is almost complete, but improvement can be added. For example,
get_rusage() could be sys_get_rusage() because there is `sys_getloadavg()`
already.

There would not be much opinions for independent modules like BCMath, GD.
Please take a look for others and give your comments.

Thank you!

[1] https://github.com/php/php-src/blob/master/CODING_STANDARDS
[2] https://wiki.php.net/rfc/consistent_function_names
[3]
https://wiki.php.net/rfc/consistent_function_names#list_of_functions_to_be_renamed

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84256 — Benoit Schildknecht — 2015-03-03T17:34:19+00:00

URL: https://externals.io/message/84189#84256 · In reply to: #84189

Hi,

I think the new functions must have consistent parameters order too. I  
think it is about the right time, so we'll have a cleaner and more logical  
language.

ATM, it's a real headache, we constantly have to read the documentation to  
make sure we give the arguments in the right order.

For instance
- `implode()` : "implode() can, for historical reasons, accept its  
parameters in either order. "
- strpos( $haystack, $needle )
- in_array( $needle, $haystack )

Regards.

Le Mon, 02 Mar 2015 22:52:03 +0100, Yasuo Ohgaki <yohgaki@ohgaki.net> a  
écrit:

> Hi all,
>
> First of all, I have no intention to remove nor deprecate old function
> names.
> Old function names must exist for compatibility and should be able to use
> forever.
>
> We have CODING_STANDARDS[1] for a long time.
> However, PHP has so many functions that do not confirm this. Many of
> violating functions can have standard conforming names safely
>
> This RFC[2] proposes the CODING_STANDARDS confirmed function names.
> The list[3] is almost complete, but improvement can be added. For  
> example,
> get_rusage() could be sys_get_rusage() because there is `sys_getloadavg()`
> already.
>
> There would not be much opinions for independent modules like BCMath, GD.
> Please take a look for others and give your comments.
>
> Thank you!
>
> [1] https://github.com/php/php-src/blob/master/CODING_STANDARDS
> [2] https://wiki.php.net/rfc/consistent_function_names
> [3]
> https://wiki.php.net/rfc/consistent_function_names#list_of_functions_to_be_renamed
>
> --
> Yasuo Ohgaki
> yohgaki@ohgaki.net


-- 
Utilisant le logiciel de courrier d'Opera : http://www.opera.com/mail/

---

## #84322 — Yasuo Ohgaki — 2015-03-05T08:07:19+00:00

URL: https://externals.io/message/84189#84322 · In reply to: #84256

Hi Benoit,

On Wed, Mar 4, 2015 at 2:34 AM, Benoit Schildknecht <bensor987@neuf.fr>
wrote:

> I think the new functions must have consistent parameters order too. I
> think it is about the right time, so we'll have a cleaner and more logical
> language.
>
> ATM, it's a real headache, we constantly have to read the documentation to
> make sure we give the arguments in the right order.
>
> For instance
> - `implode()` : "implode() can, for historical reasons, accept its
> parameters in either order. "
> - strpos( $haystack, $needle )
> - in_array( $needle, $haystack )
>

$needle should be 2nd argument like

int strpos  ( string $haystack  , mixed $needle  [, int $offset= 0  ] )
string stristr ( string $haystack , mixed $needle [, bool $before_needle =
false ] )

Rasmus suggested to have IEEE 1003.1 compliance. I like the idea and I'll
add
this in the RFC, probably. These are the order of parameters.

So array functions are subject to be changed.

bool in_array  ( mixed $needle  , array $haystack  [, bool $strict  ] )
Renamed to array_in() and fix order.

mixed array_search  ( mixed $needle  , array $haystack  [, bool $strict  ] )
Renamed to `array_find()` and fix order.

bool array_key_exists ( mixed $key , array $array )
Renamed to array_key_find() and fix order.

array array_keys ( array $array [, mixed $search_value [, bool $strict =
false ]] )
OK as it is now.

 `implode()` may be changed to have
string implode ( string $glue , array $pieces )
always.

If there are missing functions, please let me know.
I'll try to address.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84323 — Niklas Keller — 2015-03-05T08:29:36+00:00

URL: https://externals.io/message/84189#84323 · In reply to: #84322

If we introduce those new aliases, it should be clearly stated in the docs
which function should be used, maybe we can remove the old one in the far
future then. But the more important point is, that it's not that confusing
to users. Which one should I use? Why's there another one? We already have
that situation with `count` and `sizeof`.

Regards, Niklas

2015-03-05 9:07 GMT+01:00 Yasuo Ohgaki <yohgaki@ohgaki.net>:

> Hi Benoit,
>
> On Wed, Mar 4, 2015 at 2:34 AM, Benoit Schildknecht <bensor987@neuf.fr>
> wrote:
>
> > […]
> logical
> > […]
> to
> > […]
>
> $needle should be 2nd argument like
>
> int strpos  ( string $haystack  , mixed $needle  [, int $offset= 0  ] )
> string stristr ( string $haystack , mixed $needle [, bool $before_needle =
> false ] )
>
> Rasmus suggested to have IEEE 1003.1 compliance. I like the idea and I'll
> add
> this in the RFC, probably. These are the order of parameters.
>
> So array functions are subject to be changed.
>
> bool in_array  ( mixed $needle  , array $haystack  [, bool $strict  ] )
> Renamed to array_in() and fix order.
>
> mixed array_search  ( mixed $needle  , array $haystack  [, bool $strict  ]
> )
> Renamed to `array_find()` and fix order.
>
> bool array_key_exists ( mixed $key , array $array )
> Renamed to array_key_find() and fix order.
>
> array array_keys ( array $array [, mixed $search_value [, bool $strict =
> false ]] )
> OK as it is now.
>
> `implode()` may be changed to have
> string implode ( string $glue , array $pieces )
> always.
>
> If there are missing functions, please let me know.
> I'll try to address.
>
> Regards,
>
> --
> Yasuo Ohgaki
> yohgaki@ohgaki.net

---

## #84326 — Yasuo Ohgaki — 2015-03-05T08:50:12+00:00

URL: https://externals.io/message/84189#84326 · In reply to: #84323

Hi Niklas,



> If we introduce those new aliases, it should be clearly stated in the docs
> which function should be used, maybe we can remove the old one in the far
> future then. But the more important point is, that it's not that confusing
> to users. Which one should I use? Why's there another one? We already have
> that situation with `count` and `sizeof`.


Good point!
I'll update documents so that main function is prefered name/function to be
used.
Functions that have different parameter order may be marked as to be
deprecated.
Other aliases may be used. I'll add this in the RFC.

Thank you for the feedback.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84330 — Rowan Collins — 2015-03-05T09:40:07+00:00

URL: https://externals.io/message/84189#84330 · In reply to: #84326

>Hi Niklas,
>
>
>
> > […]
>docs
> > […]
>far
> > […]
>confusing
> > […]
>have
> > […]
>
>
>Good point!
>I'll update documents so that main function is prefered name/function
>to be
>used.

This would be fine if all the users read the manual, and only the manual. What about the thousands of books, tutorials, blog posts, Stack Overflow q&as, etc, all mentioning the names and behaviour that have been around for 15 to 20 years? Not to mention the thousands of lines of existing code which people will not only need to read and understand, but also contribute to without accidentally breaking compatibility with old versions of PHP.

Regards,
-- 
Rowan Collins
[IMSoP]

---

## #84332 — Jordi Boggiano — 2015-03-05T10:30:57+00:00

URL: https://externals.io/message/84189#84332 · In reply to: #84322

> So array functions are subject to be changed.
>
> bool in_array  ( mixed $needle  , array $haystack  [, bool $strict  ] )
> Renamed to array_in() and fix order.
>
> mixed array_search  ( mixed $needle  , array $haystack  [, bool $strict  ] )
> Renamed to `array_find()` and fix order.
>
> bool array_key_exists ( mixed $key , array $array )
> Renamed to array_key_find() and fix order.
>
> array array_keys ( array $array [, mixed $search_value [, bool $strict =
> false ]] )
> OK as it is now.
>
> `implode()` may be changed to have
> string implode ( string $glue , array $pieces )
> always.

If we do create new array functions I think it should be thought through 
a bit more than just cleaning up the arg order. For example we could 
support Traversable as well. Then at least it'd bring some value beyond 
consistency for the sake of it.

Cheers

---

## #84335 — Lester Caine — 2015-03-05T11:46:16+00:00

URL: https://externals.io/message/84189#84335 · In reply to: #84330

> > […]
> This would be fine if all the users read the manual, and only the manual. What about the thousands of books, tutorials, blog posts, Stack Overflow q&as, etc, all mentioning the names and behaviour that have been around for 15 to 20 years? Not to mention the thousands of lines of existing code which people will not only need to read and understand, but also contribute to without accidentally breaking compatibility with old versions of PHP.

This is perhaps the key ...

Yasuo has at least now come on board over the IEEE standards but has
also spotted that because of allowing a little to much freedom in the
past some of the current guide lines do not marry with the well
established standards :(

The bit I'm still unsure of here is not so much messing with some of the
fine detail of the procedural based functions, but the coding standard
that ACTUALLY applies at the object level. Using one naming standard for
ths area and a different one for an object version of the same set of
functions is equally confusing?

-- 
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

---

## #84389 — Yasuo Ohgaki — 2015-03-06T23:03:26+00:00

URL: https://externals.io/message/84189#84389 · In reply to: #84332

Hi Jordi,



> 
>
> > […]
>
> If we do create new array functions I think it should be thought through a
> bit more than just cleaning up the arg order. For example we could support
> Traversable as well. Then at least it'd bring some value beyond consistency
> for the sake of it.


I agree. Do you have more detailed suggestion for this?

http://ruby-doc.org/core-2.2.0/Array.html
https://docs.python.org/3/tutorial/datastructures.html
https://docs.python.org/2/library/array.html
https://scipy-lectures.github.io/intro/numpy/array_object.html

We have a lot of array_u*() functions such as

http://php.net/manual/en/function.array-uintersect-uassoc.php
array array_uintersect_uassoc ( array $array1 , array $array2 [, array $...
], callable $value_compare_func , callable $key_compare_func )
this can be consolidated to
http://php.net/manual/en/function.array-intersect-assoc.php
array array_intersect_assoc ( array $array1 , array $array2 [, array $... ]
)

All of these has callback the end of parameters. These may be consolidated.
I'll add this to the RFC if this is preferred.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84390 — Yasuo Ohgaki — 2015-03-06T23:18:42+00:00

URL: https://externals.io/message/84189#84390 · In reply to: #84335

Hi Lester,



> 
> > […]
> manual. What about the thousands of books, tutorials, blog posts, Stack
> Overflow q&as, etc, all mentioning the names and behaviour that have been
> around for 15 to 20 years? Not to mention the thousands of lines of
> existing code which people will not only need to read and understand, but
> also contribute to without accidentally breaking compatibility with old
> versions of PHP.
>
> This is perhaps the key ...
>
> Yasuo has at least now come on board over the IEEE standards but has
> also spotted that because of allowing a little to much freedom in the
> past some of the current guide lines do not marry with the well
> established standards :(
>

I've updated the RFC to have IEEE names as well as other established
library function
names as valid names. We wouldn't have much problem having aliases for it.
I think
it would be useful.

The bit I'm still unsure of here is not so much messing with some of the
> fine detail of the procedural based functions, but the coding standard
> that ACTUALLY applies at the object level. Using one naming standard for
> ths area and a different one for an object version of the same set of
> functions is equally confusing?


I agree. I wouldn't rush into.
If we change, we should change them right.

We have the implementation already.
http://php.net/arrayobject

I looked into the implementation. I'm surprised that it's overly
complicated.
It uses "array(hash)" and "object" for array storage for some reasons. This
makes it difficult to reuse procedural implementation. We may do something
for this issue.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84399 — Lester Caine — 2015-03-07T10:32:53+00:00

URL: https://externals.io/message/84189#84399 · In reply to: #84390

> Hi Lester,
> 
> 
> 
> > […]
> I've updated the RFC to have IEEE names as well as other established
> library function
> names as valid names. We wouldn't have much problem having aliases for it.
> I think it would be useful.

One of my own personal gripes has always been that while some names are
consistent with the standard, the rules for adding names adopted at the
time wasn't? It is this which has created the problem and if there is
any reason to change things now it should be to follow the IEEE coding
style which is also followed by secondary libraries like gettext.

is_int should simply be isint in line with the IEEE standard but that
divergence of standards was not a good enough reason to avoid the
current 'inconsistencies' at the time?

> The bit I'm still unsure of here is not so much messing with some of the
> > […]
> 
> I agree. I wouldn't rush into.
> If we change, we should change them right.
> 
> We have the implementation already.
> http://php.net/arrayobject
> 
> I looked into the implementation. I'm surprised that it's overly
> complicated.
> It uses "array(hash)" and "object" for array storage for some reasons. This
> makes it difficult to reuse procedural implementation. We may do something
> for this issue.

One of the reasons I don't think it as caught on?
But the starting point here is naming methods in these objects and the
'assumed standard' seems to be camelCaseStyle rather than under_style ?
Again the horse has bolted since objects like http are now well
established with camelCaseStyle rather than following the C coding style
anyway.

The only question that needs answering first is just what standard ARE
we working to and what should that be to be consistent between
procedural and object models?

-- 
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

---

## #84411 — Rowan Collins — 2015-03-07T18:35:26+00:00

URL: https://externals.io/message/84189#84411 · In reply to: #84389

> We have a lot of array_u*() functions such as
>
> http://php.net/manual/en/function.array-uintersect-uassoc.php
> array array_uintersect_uassoc ( array $array1 , array $array2 [, array $...
> ], callable $value_compare_func , callable $key_compare_func )
> this can be consolidated to
> http://php.net/manual/en/function.array-intersect-assoc.php
> array array_intersect_assoc ( array $array1 , array $array2 [, array $... ]
> )
>
> All of these has callback the end of parameters. These may be consolidated.
> I'll add this to the RFC if this is preferred.

Those functions both take any number of arguments, so given a function 
call with 4 arguments, you can't know if that's 4 arrays, or 2 arrays 
and 2 callbacks. Don't forget that array($class_name, $method_name) is a 
valid callback, so you can't judge it by the type of the arguments either.

Regards,

-- 
Rowan Collins
[IMSoP]

---

## #84417 — Yasuo Ohgaki — 2015-03-07T22:35:56+00:00

URL: https://externals.io/message/84189#84417 · In reply to: #84399

Hi all,



> 
> > […]
> been
> > […]
> but
> > […]
> it.
> > […]
>
> One of my own personal gripes has always been that while some names are
> consistent with the standard, the rules for adding names adopted at the
> time wasn't? It is this which has created the problem and if there is
> any reason to change things now it should be to follow the IEEE coding
> style which is also followed by secondary libraries like gettext.
>
> is_int should simply be isint in line with the IEEE standard but that
> divergence of standards was not a good enough reason to avoid the
> current 'inconsistencies' at the time?
>

I don't know how CONDING_STARNDARDS is made. Anyone remember
the discussion?

PHP has function names copied from C libraries at the beginning. Then
name with "_" became standard. Therefore, we have `phpversion()`, isset().
I remember empty() discussion whether it should be is_empty() or empty().
Shorter name is preferred and empty() is used. We chose
inconsistent names on occasions like StdClass::__set_state().

Having C library like name is not bad, but I think too many aliases are
better
to be avoided. Especially for basic functions. I'm not sure if it's good
for PHP
to have isstring(), isarray(), etc. It's one possibility though.


>
> > […]
> This
> > […]
> something
> > […]
>
> One of the reasons I don't think it as caught on?
> But the starting point here is naming methods in these objects and the
> 'assumed standard' seems to be camelCaseStyle rather than under_style ?
> Again the horse has bolted since objects like http are now well
> established with camelCaseStyle rather than following the C coding style
> anyway.
>
> The only question that needs answering first is just what standard ARE
> we working to and what should that be to be consistent between
> procedural and object models?


Function names without "_" is better for camelCase methods. I agree.
Personally, I don't have any bad impression for having "_" for procedural
functions while having camelCase for methods.

It's valid option to have camelCase for procedural functions' main name.
I don't mind removing "_" from procedural functions much, but C library
names are not standardized well enough. (I mean naming convention
differs library to library) My current impression is having "_" in names
and have PHP name would seem more consistent.

I guess this is the reason why CODING_STANDARDS is made like it
is now. We may introduce new procedural naming standard with
camelCase name that can keep consistency.

Thoughts?


Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84418 — Yasuo Ohgaki — 2015-03-07T22:47:48+00:00

URL: https://externals.io/message/84189#84418 · In reply to: #84411

Hi Rowan,

On Sun, Mar 8, 2015 at 3:35 AM, Rowan Collins <rowan.collins@gmail.com>
wrote:

> 
>
> > […]
>
> Those functions both take any number of arguments, so given a function
> call with 4 arguments, you can't know if that's 4 arrays, or 2 arrays and 2
> callbacks. Don't forget that array($class_name, $method_name) is a valid
> callback, so you can't judge it by the type of the arguments either.


Thank you for heads up. If I detect array($class_name, $method_name) as
callback, there could
be unintended callback calls.

Since we have been deprecated similar
call_user_method()/call_user_method_array(), we may
deprecate array callbacks for u* functions, then consolidate in the future,
perhaps PHP8.
I don't mind add this to the RFC.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84419 — Rowan Collins — 2015-03-07T23:31:43+00:00

URL: https://externals.io/message/84189#84419 · In reply to: #84418

>Hi Rowan,
>
>On Sun, Mar 8, 2015 at 3:35 AM, Rowan Collins <rowan.collins@gmail.com>
>wrote:
>
> > […]
>array
> > […]
>$...
> > […]
>function
> > […]
>and 2
> > […]
>valid
> > […]
>
>
>Thank you for heads up. If I detect array($class_name, $method_name) as
>callback, there could
>be unintended callback calls.
>
>Since we have been deprecated similar
>call_user_method()/call_user_method_array(), we may
>deprecate array callbacks for u* functions, then consolidate in the
>future,
>perhaps PHP8.
>I don't mind add this to the RFC.

What? That's not the same thing at all. I'm pretty sure those functions are deprecated *because* we have array callback forms, so you can use call_user_func to call a method.

PHP has a well-defined definition of "callable", as used by `is_callable()` and function parameter typehints, and literally everywhere that wants a callback. Since there's no such thing as a function or method pointer, that definition includes a string identifying a plain function, and two array forms, [string, string] and [object, string], representing static and instance methods, respectively. You can't not accept those forms as a callback parameter in one particular function just to make things tidier.

Regards,
-- 
Rowan Collins
[IMSoP]

---

## #84422 — Yasuo Ohgaki — 2015-03-08T01:25:16+00:00

URL: https://externals.io/message/84189#84422 · In reply to: #84419

Hi Rowan,

On Sun, Mar 8, 2015 at 8:31 AM, Rowan Collins <rowan.collins@gmail.com>
wrote:

> What? That's not the same thing at all. I'm pretty sure those functions
> are deprecated *because* we have array callback forms, so you can use
> call_user_func to call a method.
>
> PHP has a well-defined definition of "callable", as used by `is_callable()`
> and function parameter typehints, and literally everywhere that wants a
> callback. Since there's no such thing as a function or method pointer, that
> definition includes a string identifying a plain function, and two array
> forms, [string, string] and [object, string], representing static and
> instance methods, respectively. You can't not accept those forms as a
> callback parameter in one particular function just to make things tidier.
>

I should have written "Let deprecate _all_ array callbacks" by document and
raise deprecate error in PHP7.
Remove array callbacks in PHP 8.

Makes sense?

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

---

## #84435 — Rowan Collins — 2015-03-08T13:53:59+00:00

URL: https://externals.io/message/84189#84435 · In reply to: #84422

> Hi Rowan,
>
> On Sun, Mar 8, 2015 at 8:31 AM, Rowan Collins <rowan.collins@gmail.com 
> <mailto:rowan.collins@gmail.com>> wrote:
>
>     What? That's not the same thing at all. I'm pretty sure those
>     functions are deprecated *because* we have array callback forms,
>     so you can use call_user_func to call a method.
>
>     PHP has a well-defined definition of "callable", as used by
>     `is_callable()` and function parameter typehints, and literally
>     everywhere that wants a callback. Since there's no such thing as a
>     function or method pointer, that definition includes a string
>     identifying a plain function, and two array forms, [string,
>     string] and [object, string], representing static and instance
>     methods, respectively. You can't not accept those forms as a
>     callback parameter in one particular function just to make things
>     tidier.
>
>
> I should have written "Let deprecate _all_ array callbacks" by 
> document and raise deprecate error in PHP7.
> Remove array callbacks in PHP 8.


In favour of what? We have no other way of telling a function expecting 
a callback to use an existing method.

And why? Because one particular function signature you want to create 
would be possible if "array" and "callback" were non-overlapping type 
hints? Is there something wrong with having a function that explicitly 
tells people it takes callbacks, rather than guessing based on the 
arguments you pass in?

Regards,

-- 
Rowan Collins
[IMSoP]