Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:84328
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.216.172 as permitted sender)
MIME-Version: 1.0
Sender: yohgaki@gmail.com
In-Reply-To: <CEF2AD42-3CE1-489F-8192-D1DC3D8D8698@gmail.com>
References: <CAGa2bXYa5Lz0JqySVSQ+hGfCW-WxxKWvqFtWaZo=OVf+LLsV8A@mail.gmail.com>
 <54F4E29D.7080501@garfieldtech.com> <CAGa2bXbph51CUHr_G87FL65hSDfLSDHo14Bnke-vaLu7SmH=ZQ@mail.gmail.com>
 <54F4E93C.80206@gmail.com> <54F4EBEC.2090702@garfieldtech.com>
 <CAGa2bXaQ0SgLWdv7WCoo_qyOQH=t2Vi_bwpk7qXZDEUk+7S7ew@mail.gmail.com>
 <54F4F3FC.6060501@fischer.name> <CAGa2bXb-d7A3So8e76=p5qqxrZgLK2B_4RKA1OKg0nHZiw9z6A@mail.gmail.com>
 <54F4FDFB.8010701@lsces.co.uk> <CAGa2bXZUvJJVDVj-48qpPuMas12fnDigKGcE-r=TK20Sahyi7w@mail.gmail.com>
 <54F5895D.3090002@gmail.com> <CAGa2bXbuNEcvoeeBhkUUEkiHZJFvJTVX=h_JPTLHpMTtgbCokw@mail.gmail.com>
 <554F0C3F-770F-4694-A5AB-FDC54FCCBF00@gmail.com> <CAGa2bXbDdS=N=JmPwBa1iorx1aJPuo00EfU7bw31cknAxAfDyQ@mail.gmail.com>
 <1FCB68B8-3E55-4B5D-B805-9D92D848A3A1@gmail.com> <CAGa2bXYrsa7t80qo_9YEiU=ZD4k+KESU3Hn+DiJeVvwgFyyjRQ@mail.gmail.com>
 <5D8591E2-5AE6-4B4C-AAE0-3D15523410AC@gmail.com> <CAGa2bXa+RyQLuYe72f2m+j5c+YObfPtaOTeknMRU7p3s+96Seg@mail.gmail.com>
 <CEF2AD42-3CE1-489F-8192-D1DC3D8D8698@gmail.com>
Date: Thu, 5 Mar 2015 18:24:28 +0900
Message-ID: <CAGa2bXZDnuE3mKQYD+Sq2=kH=YDXuRQA3o+9wg4v81ZS+h3rLw@mail.gmail.com>
To: Rowan Collins <rowan.collins@gmail.com>
Cc: "internals@lists.php.net" <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=001a1134101ee29fc5051087242c
Subject: Re: [PHP-DEV] Consistent function names
From: yohgaki@ohgaki.net (Yasuo Ohgaki)

--001a1134101ee29fc5051087242c
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hi Rowan,

On Thu, Mar 5, 2015 at 5:51 PM, Rowan Collins <rowan.collins@gmail.com>
wrote:

> On 5 March 2015 03:59:00 GMT, Yasuo Ohgaki <yohgaki@ohgaki.net> wrote:
> >Hi Rowan,
> >
> >On Thu, Mar 5, 2015 at 10:16 AM, Rowan Collins
> ><rowan.collins@gmail.com>
> >wrote:
> >
> >> On 4 March 2015 21:27:53 GMT, Yasuo Ohgaki <yohgaki@ohgaki.net>
> >wrote:
> >> >We cannot remove all issue at once. We are better to adopt
> >incremental
> >> >improvement, aren't we?
> >>
> >> I think this, more than anything else, is where I disagree (having
> >been
> >> persuaded by arguments in previous discussions). Incremental
> >improvements
> >> mean having the cost of change multiple times, and the benefit just a
> >> promise for the future. It's like living in a building site while
> >> rebuilding your house - sometimes necessary, but not what you'd
> >choose.
> >>
> >> If we have two names with no other fixes now, then later a third
> >name, or
> >> some magic flag, which fixes the argument order and error behaviour,
> >then
> >> go through and tidy up, we'll end up with a whole flow chart of "if
> >you
> >> need to support version X, use Y; if you find a tutorial using A,
> >replace
> >> with B..."
> >>
> >> Some such change is inevitable - a huge number of tutorials became
> >out of
> >> date when ext/mysql was deprecated, for instance - but it's not
> >something
> >> to do "little and often" just to make things "a little bit better".
> >
> >
> >Sounds reasonable. I've updated RFC to note not addressed
> >inconsistencies
> >explicitly.
> >There may be others.
> >
> >Some of these may be addressed by this RFC.
> >
> >
> https://wiki.php.net/rfc/consistent_function_names#unaffected_php_functio=
nality
> >-----------------
> >Unaffected PHP Functionality
> >
> >This RFC only addresses inconsistent names. These are the list of
> >related
> >inconsistencies.
> >
> >  - Parameter order inconsistency. This may be addressed by =E2=80=9Cdef=
ault
> >namespace=E2=80=9D in other RFC.
> >- Return type inconsistency. Most severe inconsistency is =E2=80=9Cwrong=
 number
> >of parameters returns NULL=E2=80=9D. This may be addressed by =E2=80=9CI=
NI switch=E2=80=9D in
> >other
> >RFC.
> >  - Constant name inconsistency.
> >- Class and method names. Only =E2=80=9C__set_state()=E2=80=9D and =E2=
=80=9Ccreate_sid()=E2=80=9D
> >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.
> >----------------
> >
> >Functions return NULL for wrong number of parameters is easy one to fix
> >without BC.
> >We may have INI switch return FALSE for invalid number of parameters.
> >
> >return_value_consistency=3DOn/Off  ; Returns FALSE when number of
> >parameter
> >is wrong for module functions.
> >
> >Parameter ordering issue may be addressed also. Instead of having
> >alias, we
> >may introduce new functions
> >for them. The new function name could be issue, though. If you know
> >good
> >list of functions have strange
> >parameter ordering, I appreciate it.
> >
> >Parameter ordering issue could be addressed by "default namespace" that
> >can
> >import functions/classes
> >to root namespace. This approach requires more work, but it would be
> >cleaner than simply having new
> >API. I think this issue would be large enough to be a RFC, though...
> >
> >Do you have particular suggestions?
>
> You missed my point: doing this but by bit is the worst solution, not the
> best. One of your suggestions implies that we'll have 3 names for the sam=
e
> function: the one that's existed for 20 years but is a bit awkward; a new
> alias that fits our/your ideal naming scheme; and another with a namespac=
e
> prefix which is identical except for argument order. Do you not see that
> that is going to be really confusing for users, no matter how clever we
> make the manual?
>
> If we add such functions at all, the answer to "which one should I use an=
d
> why?" should be more than "whichever one was added most recently (unless
> you need compatibility)". That's why a radical API like scalar methods, o=
r
> just a designed from scratch set of functions, is the only sensible way t=
o
> move forward.


I've decided to address parameter ordering issue by this RFC. So one issue
will
be resolved. I'll explicitly state functions that have misordered
parameters are
subject to be deprecated. Removal should be more than a decade later
if we ever remove them. I pasted mail content from other thread at the end
of
this mail. If you notice anything, please let me know.

I'll document main function as preferred function.
New manual pages will not have dedicated pages for aliases, but aliases are
documented as main function's alias. It will help to avoid confusions
hopefully.

I don't think it's much problem to comply both PHP and IEEE standards. I
even
think it better to comply both PHP and IEEE standards as we can have both
of
goodies. (C/C++ programmers can easily find proper PHP functions and use it
if they would like to, for example)

I would love to have new OO APIs for variables. I also like to write
procedural
code for simple scripts. Therefore, even if we have new OO APIs, I would
like to
improve/maintain procedural functions and make them not legacy functions.

Regards,

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
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 logica=
l
> language.
>
> ATM, it's a real headache, we constantly have to read the documentation t=
o
> 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=3D 0  ] )
string stristr ( string $haystack , mixed $needle [, bool $before_needle =
=3D
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 =3D
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.
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

--
Yasuo Ohgaki
yohgaki@ohgaki.net

--001a1134101ee29fc5051087242c--