Re: Preferred approach to inclusion of data in ELPA package

[Hugo Thunnissen <devel@hugot.nl>]

On 8/20/23 15:30, sbaugh@catern.com wrote:
> Hugo Thunnissen<devel@hugot.nl>  writes:
>> Hi all,
>>
>> For my package phpinspect.el I am now looking into the creation of an
>> index of PHP's built in functions and classes. I'm considering
>> different ways of distributing this dataset, but I'm not entirely sure
>> what would be the preferred way. Finding out the signatures/properties
>> of built in functions and classes is straightforward: I can generate
>> valid PHP stubs for them which can then be parsed an indexed by my
>> package just like any other PHP code.
> Isn't this data dependent on the version of PHP that the user is using
> phpinspect.el with?  So distributing a single canonical "set of stubs"
> would be inaccurate.

It is, but I think providing stubs for the latest stable version is 
acceptable. PHP is backwards compatible to a very high degree, so even 
stubs sourced from a different PHP version than their own will be useful 
for people.


> Is it possible to automatically generate even the set of stubs on the
> user's computer, by running PHP?  Doing that operation on the user's
> computer, and caching the output so that subsequent loads are fast,
> seems like the best option to me.  Then you completely avoid this
> problem of distributing data, and you also get behavior which reflects
> the version of PHP the user is working with.
>
I want to avoid directly executing PHP in an automated fashion, as 
phpinspect currently does not in any way depend on PHP. And with good 
reason. It is not uncommon for people to run PHP:

- In containers

- In virtual machines (there's a variety of ready-to-go "LAMP/XAMPP" 
virtual machine environments for example)

- on remote systems with network mounted filesystems (nothing like going 
live the minute you hit save amirite? ;))

- Maybe, in a future where I get it working: via TRAMP

That being said, there is room for improvement.

One option I'm considering is to make it straightforward for users to 
generate/add their own stubs. This is probably a good idea regardless, 
as even if the user's PHP version matches that of the PHP installation 
that the stubs were sourced from, some users may be using lesser 
known/non-standard php extensions and may want to add stubs for them.

Generating the stubs is quite straightforward, so most of the work would 
be to wrap this process in a nice UI within Emacs. Preferrably one that 
allows the management of multiple different sets of stubs. To give an 
idea of the process, this is a section of the current Makefile:

```
./stubs/builtins.php: ./scripts/generate-builtin-stubs.php
     mkdir -p ./stubs/
     php ./scripts/generate-builtin-stubs.php > ./stubs/builtins.php

./data/builtin-stubs-index.eld.gz: ./stubs/builtins.php | ./.deps
     mkdir -p ./data/
     $(RUN_EMACS) -l phpinspect-cache -f phpinspect-dump-stub-index
```

In an ideal world, this feature should probably be paired with the 
ability to configure/detect the PHP version and extensions that a 
project requires. Projects that use composer usually state this in their 
composer.json file, but I'd have to decide whether I want to make 
composer a hard requirement for this feature or not.

Another possibility is to add support for PHPStorm's stubs 
(https://github.com/JetBrains/phpstorm-stub). Their solution has been to 
generate stubs for every version of PHP + lots of extensions and 
distribute them with their IDE (see git branches for every version). I 
think this is a little overkill of a solution though. And I don't like 
the idea of users having to download all of these stubs from somewhere 
just to make this feature of the package functional. Also, would the 
apache2 license of these stubs cause any licensing problems? I imagine 
it would be fine if the stubs are not distributed with the package, but 
IANAL.

I'm open to discussing better solutions and/or implementing them in the 
future. I'm currently working towards a first public ELPA release, so I 
might save large/complex improvements for a version after the first release.