Repository files navigation

This project backports features found in the latest PHP versions and providescompatibility layers for some extensions and functions. It is intended to beused when portability across PHP versions and extensions is desired.

Polyfills are provided for:

• theapcu extension when the legacyapc extension is installed;
• thectype extension when PHP is compiled without ctype;
• thembstring andiconv extensions;
• theuuid extension;
• theMessageFormatter class and themsgfmt_format_message functions;
• theNormalizer class and thegrapheme_* functions;
• theutf8_encode andutf8_decode functions from thexml extension or PHP-7.2 core;
• theCollator,NumberFormatter,Locale andIntlDateFormatter classes,limited to the "en" locale;
• theintl_error_name,intl_get_error_code,intl_get_error_message andintl_is_failure functions;
• theidn_to_ascii andidn_to_utf8 functions;
• aBinary utility class to be used when compatibility withmbstring.func_overload is required;
• thespl_object_id andstream_isatty functions introduced in PHP 7.2;
• themb_ord,mb_chr andmb_scrub functions introduced in PHP 7.2 from thembstring extension
• thesapi_windows_vt100_support function (Windows only) introduced in PHP 7.2;
• thePHP_FLOAT_* constant introduced in PHP 7.2;
• thePHP_OS_FAMILY constant introduced in PHP 7.2;
• theis_countable function introduced in PHP 7.3;
• thearray_key_first andarray_key_last functions introduced in PHP 7.3;
• thehrtime function introduced in PHP 7.3;
• theJsonException class introduced in PHP 7.3;
• theget_mangled_object_vars,mb_str_split andpassword_algos functionsintroduced in PHP 7.4;
• thefdiv function introduced in PHP 8.0;
• theget_debug_type function introduced in PHP 8.0;
• thepreg_last_error_msg function introduced in PHP 8.0;
• thestr_contains function introduced in PHP 8.0;
• thestr_starts_with andstr_ends_with functions introduced in PHP 8.0;
• theValueError class introduced in PHP 8.0;
• theUnhandledMatchError class introduced in PHP 8.0;
• theFILTER_VALIDATE_BOOL constant introduced in PHP 8.0;
• theget_resource_id function introduced in PHP 8.0;
• theAttribute class introduced in PHP 8.0;
• theStringable interface introduced in PHP 8.0;
• thePhpToken class introduced in PHP 8.0 when the tokenizer extension is enabled;
• thearray_is_list function introduced in PHP 8.1;
• theenum_exists function introduced in PHP 8.1;
• theMYSQLI_REFRESH_REPLICA constant introduced in PHP 8.1;
• theReturnTypeWillChange attribute introduced in PHP 8.1;
• theCURLStringFile class introduced in PHP 8.1 (but only if PHP >= 7.4 is used);
• theAllowDynamicProperties attribute introduced in PHP 8.2;
• theSensitiveParameter attribute introduced in PHP 8.2;
• theSensitiveParameterValue class introduced in PHP 8.2;
• theRandom\Engine interface introduced in PHP 8.2;
• theRandom\CryptoSafeEngine interface introduced in PHP 8.2;
• theRandom\Engine\Secure class introduced in PHP 8.2 (checkarokettu/random-polyfill for more engines);
• theodbc_connection_string_is_quoted function introduced in PHP 8.2;
• theodbc_connection_string_should_quote function introduced in PHP 8.2;
• theodbc_connection_string_quote function introduced in PHP 8.2;
• theini_parse_quantity function introduced in PHP 8.2;
• thejson_validate function introduced in PHP 8.3;
• theOverride attribute introduced in PHP 8.3;
• themb_str_pad function introduced in PHP 8.3;
• theldap_exop_sync function introduced in PHP 8.3;
• theldap_connect_wallet function introduced in PHP 8.3;
• thestream_context_set_options function introduced in PHP 8.3;
• thestr_increment andstr_decrement functions introduced in PHP 8.3;
• theDate*Exception/Error classes introduced in PHP 8.3;
• theSQLite3Exception class introduced in PHP 8.3;
• themb_ucfirst andmb_lcfirst functions introduced in PHP 8.4;
• thearray_find,array_find_key,array_any andarray_all functions introduced in PHP 8.4;
• theDeprecated attribute introduced in PHP 8.4;
• themb_trim,mb_ltrim andmb_rtrim functions introduced in PHP 8.4;
• theCURL_HTTP_VERSION_3 andCURL_HTTP_VERSION_3ONLY constants introduced in PHP 8.4;

It is strongly recommended to upgrade your PHP version and/or install the missingextensions whenever possible. This polyfill should be used only when there is nobetter choice or when portability is a requirement.

To write portable code between PHP5 and PHP7, some care must be taken:

• \*Error exceptions must be caught before\Exception;
• after callingerror_clear_last(), the result of$e = error_get_last() must beverified usingisset($e['message'][0]) instead ofnull !== $e.

When usingComposer to manage your dependencies, youshouldnotrequire thesymfony/polyfill package, but the standalone ones:

• symfony/polyfill-apcu for using theapcu_* functions,
• symfony/polyfill-ctype for using the ctype functions,
• symfony/polyfill-php54 for using the PHP 5.4 functions,
• symfony/polyfill-php55 for using the PHP 5.5 functions,
• symfony/polyfill-php56 for using the PHP 5.6 functions,
• symfony/polyfill-php70 for using the PHP 7.0 functions,
• symfony/polyfill-php71 for using the PHP 7.1 functions,
• symfony/polyfill-php72 for using the PHP 7.2 functions,
• symfony/polyfill-php73 for using the PHP 7.3 functions,
• symfony/polyfill-php74 for using the PHP 7.4 functions,
• symfony/polyfill-php80 for using the PHP 8.0 functions,
• symfony/polyfill-php81 for using the PHP 8.1 functions,
• symfony/polyfill-php82 for using the PHP 8.2 functions,
• symfony/polyfill-php83 for using the PHP 8.3 functions,
• symfony/polyfill-php84 for using the PHP 8.4 functions,
• symfony/polyfill-iconv for using the iconv functions,
• symfony/polyfill-intl-grapheme for using thegrapheme_* functions,
• symfony/polyfill-intl-idn for using theidn_to_ascii andidn_to_utf8 functions,
• symfony/polyfill-intl-icu for using the intl functions and classes,
• symfony/polyfill-intl-messageformatter for using the intl messageformatter,
• symfony/polyfill-intl-normalizer for using the intl normalizer,
• symfony/polyfill-mbstring for using the mbstring functions,
• symfony/polyfill-util for using the polyfill utility helpers.
• symfony/polyfill-uuid for using theuuid_* functions,

Requiringsymfony/polyfill directly would prevent Composer from sharingcorrectly polyfills in dependency graphs. As such, it would likely installmore code than required.

This package is designed for low overhead and high quality polyfilling.

It adds only a few lightweightrequire statements to the bootstrap processto support all polyfills. Implementations are then loaded on-demand whenneeded during code execution.

If your project requires a minimum PHP version it is advisable to add polyfillsfor lower PHP versions to thereplace section of yourcomposer.json.This removes any overhead from these polyfills as they are no longer part of your project.The same can be done for polyfills for extensions that you require.

If your project requires php 7.0, and needs the mb extension, the replace section would looksomething like this:

{"replace": {"symfony/polyfill-php54":"*","symfony/polyfill-php55":"*","symfony/polyfill-php56":"*","symfony/polyfill-php70":"*","symfony/polyfill-mbstring":"*"    }}

Polyfills are unit-tested alongside their native implementation so thatfeature and behavior parity can be proven and enforced in the long run.

This library is released under theMIT license.