Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:106533
Return-Path: <nikita.ppv@gmail.com>
Delivered-To: mailing list internals@lists.php.net
Received: (qmail 37149 invoked from network); 10 Aug 2019 22:28:19 -0000
Received: from unknown (HELO mail-lj1-f171.google.com) (209.85.208.171)
  by pb1.pair.com with SMTP; 10 Aug 2019 22:28:19 -0000
Received: by mail-lj1-f171.google.com with SMTP id u15so86016ljl.3
        for <internals@lists.php.net>; Sat, 10 Aug 2019 12:56:03 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=mime-version:references:in-reply-to:from:date:message-id:subject:to;
        bh=TT2mSkCOvrQz3IJxjX2GP/zkNRWMZ8Px/DGUXXhKdvc=;
        b=JVgEJmfzuAnyUjThUWiuqZsd0NtMxygmuJraI60ssBALltDni5MItt/R6Hp0UW5Tcp
         u7/0aFGW9U+9HBoSmlCEgC63xSPFwuRK+HuzHYa/Et2CyqFRjrVQyo8bJ4aXpC2jyt5i
         YZfHUfKaGjiamY0frckPK4kvweupefZUw3rMID86BLaYBvLI0DJsbkN2vAtI28V8fuMc
         mO595iq/H3FnOEE3QIqPs0rfIpjLQglhTRaeMKrDHoGsij8RsndYP9ZiHut9Qe4WPWI8
         fUBcaFOsZOd+x0Os6MZGOqEmcTS4ONilOEJ7df47NlP9u8v8R83FWm1TxKFNuH4vgGBw
         gWlA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:mime-version:references:in-reply-to:from:date
         :message-id:subject:to;
        bh=TT2mSkCOvrQz3IJxjX2GP/zkNRWMZ8Px/DGUXXhKdvc=;
        b=nGCWZ56zvx0wB+/XBhLf6JXXH0eeb4jxO2Pv4PmrhFBDVWYcuPQ2N8B7T5Ffo8M2de
         DwI05CFqsL6fp9/ct9mehm9aQ9H4IVL+y87ApN/PxL9thieCBgfmxCHJHDzgfy2r3BOK
         D3gHP940dYFdHG/q8HxVDLyzrXq7byo9uWFv7ymdn6rV5fKyQxLmE0TP6k7faCRJ7kAw
         I4kqF+geoWr5ncvflh5b7dVWgZlP7nNEuDjty2HkilyTu6yoq5qURstrq8l44mpQPSnv
         Vs00Nn9TXX51cuXkAxEri1HKvZRzaceDqPv3UBgKGPfGg0IXLvVgkZTMxctE6o0nwkzZ
         +BDg==
X-Gm-Message-State: APjAAAUltqyUys7Is9iBVvWQkHtHyiOyHLCdT6YZnzUxu4aaS7CJfvuy
	L74UnQI9eoH2O1+lhxdD7X4BZcjvYZ1SHM51sWFSirqKuJ4=
X-Google-Smtp-Source: APXvYqxwQRSxfRpsUvc5vsaeSLojb8r9LnxdMpYiOEq0uHnXolMk05J4y7sveALsYLkG+FR/bIZc1OcU/FaTAaj4H1w=
X-Received: by 2002:a05:651c:282:: with SMTP id b2mr3829567ljo.208.1565466962145;
 Sat, 10 Aug 2019 12:56:02 -0700 (PDT)
MIME-Version: 1.0
References: <CAF+90c95GBUbbWUDhP2jW1q9uK3cnEomcwN7xWAup=PhJ0+S1Q@mail.gmail.com>
In-Reply-To: <CAF+90c95GBUbbWUDhP2jW1q9uK3cnEomcwN7xWAup=PhJ0+S1Q@mail.gmail.com>
Date: Sat, 10 Aug 2019 21:55:45 +0200
Message-ID: <CAF+90c9pJdcz91cdT0J7vanBHJ7vtE+p1o6C6LLhnJPfSeACyg@mail.gmail.com>
To: PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="0000000000002fb553058fc8ae9d"
Subject: Re: Call for participation: Annotating internal function argument and
 return types
From: nikita.ppv@gmail.com (Nikita Popov)

--0000000000002fb553058fc8ae9d
Content-Type: text/plain; charset="UTF-8"

On Sat, Aug 10, 2019 at 12:56 PM Nikita Popov <nikita.ppv@gmail.com> wrote:

> Hi,
>
> Lack of type information for internal functions in Reflection is a
> long-standing issue. In PHP 8 we finally have all the necessary technical
> groundwork done to support argument and return type annotations on internal
> functions at scale.
>
> The only thing left is to actually add those type annotations ... to many
> hundreds of functions. This is something everyone can help with, as it does
> not need expertise in C.
>
> I've opened a sample PR to show the process:
> https://github.com/php/php-src/pull/4499
>
> Here, we take some existing arginfo structures in basic_functions.c and
> convert them into stubs in basic_functions.stub.php. We can take the
> argument names from the existing arginfo. To figure out the types, we need
> to look at the implementation (the php.net documentation tends to lie
> about details).
>
> For example, the first function, set_time_limit is defined in
> https://github.com/php/php-src/blob/172c71980df0fe4c9d62c3365f0a2cdb139e3e86/main/main.c#L1501.
> We see that it accepts an "l" parameter, which is an int. We see that it
> uses RETVAL_TRUE and RETVAL_FALSE, which means the return value is a bool.
>
> Once this is done, we need to auto-generate new arginfo data. If you have
> a development setup, this is done automatically when running "make".
> Otherwise, it's possible to manually run "php scripts/dev/gen_stub.php
> ext/standard/basic_functions.stub.php".
>
> Any help would be appreciated :)
>

A couple of things I didn't mention but noticed during reviews:

 * We can't add return types to methods (at least for non-final classes),
because these would force inheriting classes to specify the return type as
well. So return types on methods should be specified using @return for now
-- we should discuss if we want to add them as proper types (with the BC
break that implies).

 * For by-reference parameters, very likely no type should be specified.
This is because types are always input types. These are usually not
constrained for reference parameters. The output type may be constrained,
but there's no way to specify it in PHP right now.

 * Many internal functions have defaults that cannot be expressed as a
constant expression, e.g. because they depend on ini settings or other
parameters. In this cases by convention "$foo = UNKNOWN" is used, just to
mark that the argument is optional, but doesn't have a "proper" default
value.

Nikita

--0000000000002fb553058fc8ae9d--