Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:114763
MIME-Version: 1.0
References: <6D61A2FD-DC80-43A5-81C2-FB19F9CB5078@dafert.at>
In-Reply-To: <6D61A2FD-DC80-43A5-81C2-FB19F9CB5078@dafert.at>
Date: Mon, 7 Jun 2021 12:40:28 +0200
Message-ID: <CAF+90c_-qiTbzRigj+Tv=8CG-93DahbaxpcUSwtFSzjCOgJmcQ@mail.gmail.com>
To: Mel Dafert <mel@dafert.at>
Cc: PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="0000000000006ad65405c42aac95"
Subject: Re: [PHP-DEV] Policy for procedural style in new additions
From: nikita.ppv@gmail.com (Nikita Popov)

--0000000000006ad65405c42aac95
Content-Type: text/plain; charset="UTF-8"

On Thu, Jun 3, 2021 at 8:28 PM Mel Dafert <mel@dafert.at> wrote:

> Hi internals,
> After the RFC to add IntlDatePatternGenerator () was accepted, it was
> brought up that the duplication of
> procedural and OO style was not necessarily/useful anymore.
> This already has some (old) precedent - in 2012, UConverter was added to
> ext/intl
> (https://wiki.php.net/rfc/uconverter) and in 2014 IntlChar
> (https://wiki.php.net/rfc/intl.char) - both of which only provide a
> class, but not the
> procedural API.
> This was also shortly discussed on the mailing list for IntlChar:
> https://externals.io/message/79146#79167 after which the procedural API
> was dropped without much ado.
>
> When I wrote the IntlDatePatternGenerator RFC, I was not aware that the
> procedural API was viewed as deprecated, nor that there had been additions
> to
> ext/intl that were purely OO.
> In the thread after its vote, it was also suggested that we add a policy
> that
> forbids new additions from adding duplicated APIs, and that OO style should
> be preferred if possible. I am not sure if I am the best person to write
> such an RFC,
> but I wanted to bring this to its own thread and provide the context I
> have dug up so
> far.
>
> The duplication of the OO and procedural API dates back to the addition of
> the intl
> extension to core. There is some discussion about it in this thread from
> 2008:
> https://externals.io/message/36775
> (ignore the unrelated discussion about PHP6)
> The main argument at this point was that OO in PHP is a new thing, and
> that while
> the OO API is objectively better, the procedural API should also be there
> to
> lessen the learning curve for existing PHP users that are not yet familiar
> with OOP.
> I would argue that 13 years later, this argument no longer holds - anyone
> who
> has used PHP at some point since then most likely has encountered classes.
>
> One open question that still remains is what we do with the already
> existing
> procedural API.
> Should it be deprecated? Should it only be soft-deprecated, in that we
> mention in the
> documentation that the OO style is preferred, but that the procedural API
> is
> not planned to be removed?
> Should we just leave the procedural API as-is and live with the fact that
> some
> classes have procedural counterparts
> and some don't?
> I would personally lean towards (at least soft-) deprecation just for
> consistency,
> but I would like to hear what you would have to say.


I think that not adding new procedural mirror APIs is pretty
uncontroversial at this point. I think one open question is regarding API
additions to existing classes with a mirror API -- should we keep adding
procedural functions in that case?

The more interesting question here is whether we want to deprecate existing
APIs. From a quick look, these are the extensions that provide procedural
mirror APIs:

date
finfo
intl
mysqli
oci8 (only partially)
xmlwriter

I don't think I'd want to blanket deprecate all of these. I do see value in
some of the procedural APIs (okay, only date really) or at least historical
importance (mysqli is a migration target for mysql, which was only
procedural). I think if we want to deprecate these, it should be on a
case-by-case basis. For example, I see very little value in the procedural
intl APIs.

One annoying factor here is that these mirror APIs were often added
thoughtlessly and have design issues as a result. For example,
xmlwriter_open_uri() makes sense, but XMLWriter::openUri() should clearly
have been a static method, not an instance method. Similarly, mysqli_init()
makes some sense, but mysqli::init() is entirely useless.

Regards,
Nikita

--0000000000006ad65405c42aac95--