Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
151 lines (109 loc) · 5.79 KB

CONTRIBUTING.md

File metadata and controls

151 lines (109 loc) · 5.79 KB

Contributing

Safe-PHP code is generated automatically from the PHP doc.

Architecture

  • generator/ contains a bunch of code which will look at the PHP docs, figure out which functions are unsafe, and will generate safe wrappers for them, which are then written to generated/. As a Safe-PHP developer, you probably spend most time here.
    • generator/config/ has the rules for which functions are included or excluded
    • generated/ will be deleted and regenerated from scratch as part of CI runs - don't manually edit any of these files.
  • lib/ contains some special cases where automatic generation is tricky. Ideally this should be kept small - the goal is to have as much as possible generated automatically.

Generator

  • safe.php is the CLI entry point, with a few utility commands, but the most important one is \Safe\Commands\GenerateCommand, which does the generation:
    • Use \Safe\XmlDocParser to parse the PHP XML documentation and pull out information about Methods, Parameters, and Types - try to figure out which methods are unsafe.
    • Use \Safe\PhpStanFunctions to get a bit of extra data from PHPStan's typehint database, and merge that with the XML info.
    • Given this list of unsafe functions, use \Safe\Generator to write a bunch of safe wrappers.

End-Users

  • Users who depend on safe-php via composer will have the files in generated/ and the files in lib/ auto-loaded; they shouldn't need to worry about any files outside those two directories.

Compatibility with upstream PHP

Intentional changes:

  • Functions which return a special value to indicate an error should now throw an Exception.
    • eg file_get_contents() returns a string on success, or returns false on error. \Safe\file_get_contents() returns a string on success and throws an Exception on error.
  • If the return type included that type only for errors, that type is removed from the signature.
    • eg file_get_contents() returns string|false, \Safe\file_get_contents() returns string
    • proc_close() returns the process exit code on success and -1 on error. Both of these are int, so the signature remains int.
  • If the function returned true on success and false on error, and we have removed the false, then the signature gets changed from bool to void to stop people from accidentally writing if(function()) {...}
  • PHPDoc comments use the more specific type hints from PHPStan, eg array<string> rather than array, or 0|1 rather than int

Necessary changes / side effects:

  • Functions which have optional parameters without defaults (eg cubrid_bind() has $bind_value_type) are turned into functions with nullable parameters which default to null.
  • PHP's internal error marker (The thing retrieved by error_get_last()) will be cleared each time a Safe function is called.

Minimum Supported PHP Version

See https://www.php.net/supported-versions.php

  • The generator code should be compatible with "Active Support" versions
  • The generated code should be compatible with "Active Support" and "Security Fixes" versions

Installing dev dependencies

With a devcontainer

If you use VSCode or similar, opening the project folder should prompt you to re-open the folder inside a docker container with all the relevant tools pre-installed.

Manually

  • php CLI (with dom and curl modules)
  • composer

With docker

.devcontainer/Dockerfile contains the necessary dependencies to run the generator, as well as some handy shortcut shell scripts. You can use .devcontainer/build.sh to regenerate the files in generated/, and .devcontainer/run.sh to open a shell in the container.

Building Safe-PHP

The first step is to download the PHP documentation project locally, using git.

$ generator/safe.php download-docs

This will download the PHP documentation from the official repository.

https://github.com/php/doc-base

https://github.com/php/doc-en

To use the generator, you need to make sure you installed all the needed dependencies:

$ cd generator
$ composer install

Generating the functions

Generating the functions can be done with a simple command.

$ cd generator
$ php ./safe.php generate

Detecting new cases

generator/config/detectErrorType.php uses a list of regexes to scan the documentation looking for functions which return false (or null) on error. If you want to add support for more functions to Safe-PHP, the easiest way is to add more regexes here.

If you detect more cases where false is an exception, then you should probably also edit Method.php::stripReturnFalseText() to remove the "returns false on error" text from the documentation.

Deprecating old cases

If the unsafe-function-detector has made a false-positive (ie, it has detected a function returns false on error, when actually false is fine), then we don't want to completely remove the function because that would break backwards compatibility, but we can hide the function to avoid it being suggested to new users.

Special cases

In some cases, automatic generation is too difficult to execute and the function has to be written manually. This should however only be done exceptionally in order to keep the project easy to maintain. The most important examples are all the functions of the classes DateTime and DateTimeImmutable, since the entire classes have to be overloaded manually. All custom objects must be located in lib/ and custom functions must be in lib/special_cases.php.

Submitting a PR

The continuous integration hooks will regenerate all the functions and check that the result is exactly what has been committed. Therefore, before submitting a PR, please:

  • Perform step 1 to update doc
  • Regenerate the files using php ./safe.php generate