PHP RFC: Platform Requirement Declares

• Version: 0.1
• Date: 2020-02-16
• Target: PHP 8.0
• Author: Mark Randall, marandall@php.net
• Status: Draft
• First Published at: https://wiki.php.net/rfc/platform_requirement_declares

PHP scripts currently have no way of easily expressing which versions of PHP they support without the need to run boilerplate code at the start of each script to check against PHP_VERSION.

With increasing numbers of features under development that subtlety change language behaviour, it may be preferable to add a mechanism for a script to indicate that it depends on the behaviour of a certain version, or certain range of versions, so that it can protect itself from trigger unexpected behaviour if run on an earlier version that does not support them.

To that end, I propose adding the following declare statement:

declare(platform_target=xx.yy)

As part of the compilation stage, the target version would be checked against the PHP_VERSION and a compile error would be emitted if the current version was below the target.

It is envisaged that this declare would be used primarily with namespaced / imported declares when they eventually arrive, but could just as easily work with single scripts.

The availability of a platform_target would also allow an easy bail-out for compilation that is known to fail before a certain version, although this would not necessarily prevent parser errors for major new syntax such as generics / annotations.

I suggest that the sooner we add support for this declare (even if only suppressing the compile warning that would come with it on earlier versions) the sooner we have options available to provide both safety from unintended consequences due to running on prior versions, and the option to implement new features while preserving backwards compatibility for those files which have not stated their intent to use newer behaviour.

Composer ​repositories have the ability to check packages against certain requirements,​ including the PHP version. However, this is only performed when the vendor directory is installed or updated, meanwhile the PHP version ​is free to change independently,​ either through being installed on the server, or the source code itself being moved.

Crucially, if Composer handles this of its own accord, that information is not exposed to PHP, and therefore the engine will be unable to make decisions based upon it (see future scope).

As a new declare, encountering this statement would trigger a compile warning on all versions prior to its implementation.

This would target PHP 8.0, although as a small preemptive change, discussions could be had about back-porting a limited version to 7.4 that would suppress the error.

This RFC is laying the groundwork for the language to take decisions based on the file authors stated version. To that end it may be beneficial to expose the platform_target to the execution context by storing it against functions / opcodes so it can be read as part of the execute data.

This opens the door for limiting backwards compatibility issues by only making certain changes when targeting versions xx.yy or above.

This would mean that new breaking changes could be made by allowing programmers to opt-in, meanwhile those without platform targets, or those with a platform target less than the version the breaking change was introduced, could continue to receive historic behaviour, with a deprecation notice giving an approximate date at which point the new behaviour will be considered default.