1
0
mirror of https://github.com/danog/psalm.git synced 2024-12-11 16:59:45 +01:00
psalm/docs/contributing/editing_callmaps.md

82 lines
3.5 KiB
Markdown
Raw Permalink Normal View History

2021-09-04 16:39:29 +02:00
# Altering callmaps
## Intro
One of the first things most contributors start with is proposing changes to
callmaps.
Callmap is a data file (formatted as a PHP file returning an array) that tells
Psalm what arguments function/method takes and what it returns.
There are two full callmaps (`CallMap.php` and `CallMap_historical.php`) in
`dictionaries` folder, and a number of delta files that provide information on
how signatures changed in various PHP versions. `CallMap_historical` has
signatures as they were in PHP 7.0, `CallMap.php` contains current signatures
(for PHP 8.1 at the time of writing).
## Full callmap format
Full callmaps (`CallMap.php` and `CallMap_historical.php`) have function/method
names as keys and an array representing the corresponding signature as a value.
First element of that value is a return type (it also doesn't have a key), and
subsequent elements represent function/method parameters. Parameter name for an
optional parameter is postfixed with `=`.
## Delta file format
Delta files (named `CallMap_<PHP major version><PHP minor version>_delta.php`)
2021-09-07 23:02:02 +02:00
list changes that happened in the corresponding PHP version. There are
2021-09-04 18:27:09 +02:00
three section with self-explanatory names: `added` (for functions/methods that
2021-09-04 16:39:29 +02:00
were added in that PHP version), `removed` (for those that were removed) and
`changed`.
Entry format for `removed` and `added` section matches that of a full callmap,
while `changed` entries list `old` and `new` signatures.
## How Psalm uses delta files
When the current PHP version is set to something other than the latest PHP
version supported by Psalm, it needs to process delta files to arrive at a
version of callmap matching the one that is used during analysis. Psalm uses
the following process to do that:
2022-08-20 23:29:03 +02:00
1. Read `CallMap.php` (Note: it's the one having the latest signatures).
2021-09-04 16:39:29 +02:00
2. If it matches configured PHP version, use it.
2021-09-07 23:02:02 +02:00
3. If the callmap delta for previous PHP version exists, read that.
2021-09-04 16:39:29 +02:00
4. Take previous callmap delta and apply it in reverse order. That is, entries
in `removed` section are added, those in `added` section are removed and
`changed.new` signatures in the current callamp are replaced with
`changed.old`.
5. Goto 2
## Consistent histories
To make sure there are no mismatches in deltas and the callmap, CI validates
that all function/method entries have consistent histories. E.g. that the
signature in `changed.new` matches the one in `CallMap.php`, the `removed`
entries are actually absent from `CallMap.php` and so on.
## Typical changes
To put that into practical perspective, let's see how a couple of typical
callmap changes may look like.
### Adding a new function
Say, there's a function added in PHP 8.1, e.g. `array_is_list()`. Add it to the
`CallMap_81_delta.php` (as it was introduced in PHP 8.1), and `CallMap.php` (as
it exists in the latest PHP version). Here's [the PR that does it](https://github.com/vimeo/psalm/pull/6398/files).
### Correcting the function signature
2022-08-20 23:29:03 +02:00
Assume you found an incorrect signature, the one that was always different to what
2021-09-04 16:39:29 +02:00
we currently have in Psalm. This will need a change to `CallMap_historical.php`
(as the signature was always that way) and `CallMap.php` (as the signature is
still valid). Here's [the PR that does it](https://github.com/vimeo/psalm/pull/6359/files).
If function signature is correct for an older version but has changed since you
will need to edit the delta for PHP version where signature changed and
`CallMap.php` (as this new signature is still valid). Here's
[the PR that does it (makes `timestamp` nullable)](https://github.com/vimeo/psalm/pull/6244/files).