rfc:remove_utf8_decode_and_utf8_encode

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:remove_utf8_decode_and_utf8_encode [2022/03/04 23:24] – imsoprfc:remove_utf8_decode_and_utf8_encode [2022/06/21 09:42] (current) – The RFC has been implemented cmb
Line 1: Line 1:
 ====== PHP RFC: Deprecate and Remove utf8_encode and utf8_decode ====== ====== PHP RFC: Deprecate and Remove utf8_encode and utf8_decode ======
-  * Version: 1.1 +  * Version: 1.2 
-  * Date: 2022-03-04+  * Date: 2022-04-04
   * Author: Rowan Tommins <rowan.collins@gmail.com>   * Author: Rowan Tommins <rowan.collins@gmail.com>
-  * Status: Under Discussion+  * Status: [[https://github.com/php/php-src/pull/8726|Implemented]] (PHP 8.2.0) 
   * First Published at: https://wiki.php.net/rfc/remove_utf8_decode_and_utf8_encode   * First Published at: https://wiki.php.net/rfc/remove_utf8_decode_and_utf8_encode
  
Line 18: Line 18:
 ===== Proposal ===== ===== Proposal =====
  
-  * In PHP 8.2, all uses of utf8_encode and utf8_decode will raise an E_DEPRECATED diagnostic. Proposed wording: "Function utf8_encode is deprecated; check usage is correct and consider mb_convert_encoding or other replacement."+  * In PHP 8.2, all uses of utf8_encode and utf8_decode will raise a standard E_DEPRECATED diagnostic ("Function utf8_encode() is deprecated" / "Function utf8_decode() is deprecated").
   * In PHP 9.0, the utf8_encode and utf8_decode functions will be removed from PHP.   * In PHP 9.0, the utf8_encode and utf8_decode functions will be removed from PHP.
   * Documentation and deprecation messages will encourage users to check that their usage is correct, and recommend ''mb_convert_encoding'' as the primary replacement, with ''UConverter::transcode'' and ''iconv'' also listed as possibilities.   * Documentation and deprecation messages will encourage users to check that their usage is correct, and recommend ''mb_convert_encoding'' as the primary replacement, with ''UConverter::transcode'' and ''iconv'' also listed as possibilities.
Line 147: Line 147:
 These vary slightly in the options available, particularly around invalid and unmappable UTF-8 input. The 'to_subst' option to ''Uconverter::transcode'' allows the closest match to ''utf8_decode'', e.g. <php>$latin1 = UConverter::transcode($utf8, 'ISO-8859-1', 'UTF8', ['to_subst' => '?']);</php> These vary slightly in the options available, particularly around invalid and unmappable UTF-8 input. The 'to_subst' option to ''Uconverter::transcode'' allows the closest match to ''utf8_decode'', e.g. <php>$latin1 = UConverter::transcode($utf8, 'ISO-8859-1', 'UTF8', ['to_subst' => '?']);</php>
  
-Of these three extensions, ext/mbstring is probably the most commonly installed. It is already required by 65 of the 1000 most popular packages on Packagist, including ''phpunit/phpunit'' and ''laravel/framework''; another 35 require ''symfony/polyfill-mbstring''. By contrast, ext/iconv is required by only 6 (plus 4 via ''symfony/polyfill-iconv''), and ext/intl by only 2. It also has an implementation entirely contained in the ''php-src'' git repository, whereas ext/intl and ext/iconv rely on external libraries, with ext/iconv particularly prone to platform-specific differences. This raises the possibility of making it non-optional in future, although that is out of scope for the current discussion.+Of these three extensions, ext/mbstring is probably the most commonly installed. It is already required by 65 of the 1000 most popular packages on Packagist, including ''phpunit/phpunit'' and ''laravel/framework''; another 35 require ''symfony/polyfill-mbstring''. It is also listed as a requirement for [[https://www.drupal.org/docs/system-requirements/php-requirements#s-mbstring-|Drupal]] and [[https://www.phpbb.com/support/docs/en/3.3/ug/quickstart/|phpBB]], and recommended for [[https://woocommerce.com/document/server-requirements/#section-3|WooCommerce]].  
 + 
 +By contrast, ext/iconv is required by only 6 (plus 4 via ''symfony/polyfill-iconv''), and ext/intl by only 2. It also has an implementation entirely contained in the ''php-src'' git repository, whereas ext/intl and ext/iconv rely on external libraries, with ext/iconv particularly prone to platform-specific differences. 
 + 
 +The possibility has been raised of making ext/mbstring non-optional in future, although that is out of scope for the current discussion.
  
 An exact replacement is also straight-forward to implement in pure PHP, as long as performance is not critical. Examples are available in [[https://packagist.org/packages/patchwork/utf8|patchwork/utf8]] and [[https://packagist.org/packages/symfony/polyfill-php72|symfony/polyfill-php72]]. The same approach could be used for a standalone function for Windows-1252 or any other single-byte encoding. An exact replacement is also straight-forward to implement in pure PHP, as long as performance is not critical. Examples are available in [[https://packagist.org/packages/patchwork/utf8|patchwork/utf8]] and [[https://packagist.org/packages/symfony/polyfill-php72|symfony/polyfill-php72]]. The same approach could be used for a standalone function for Windows-1252 or any other single-byte encoding.
Line 189: Line 193:
  
 The use of these functions internally within the ext/xml extension has not been examined, and will not be changed. The use of these functions internally within the ext/xml extension has not been examined, and will not be changed.
- 
-===== Open Issues ===== 
- 
-  * Exact wording of deprecation notice. 
-  * What alternatives should the manual actively promote? 
- 
-===== Proposed Voting Choices ===== 
- 
-Should utf8_encode and utf8_decode be deprecated in 8.2 and removed in 9.0? (Yes / No) 
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
-  * [[https://github.com/php/doc-en/pull/1419|Proposed additional wording in the manual]]+  * [[https://github.com/IMSoP/doc-en/pull/1|Proposed additional wording in the manual]]
  
 ===== References ===== ===== References =====
Line 232: Line 227:
 However, this would require either implementing a significant amount of extra code, or wrapping one of the existing functions, all of which are in optional extensions. It would also require several versions before the benefit could be realised: first, add the parameter; in a later version, raise a deprecation if the new parameter is not passed; finally, make the parameter mandatory. Users would then still need to check and update every use of the functions, which would be a similar effort to switching to a new function. However, this would require either implementing a significant amount of extra code, or wrapping one of the existing functions, all of which are in optional extensions. It would also require several versions before the benefit could be realised: first, add the parameter; in a later version, raise a deprecation if the new parameter is not passed; finally, make the parameter mandatory. Users would then still need to check and update every use of the functions, which would be a similar effort to switching to a new function.
  
-==== Changelog ====+===== Vote ===== 
 + 
 +<doodle title="Should utf8_encode and utf8_decode be deprecated in 8.2 and removed in 9.0?" auth="imsop" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +Voting started 2022-04-05 18:40 UTC, and will run for two weeks, closing 2022-04-19 18:40 UTC 
 + 
 +===== Changelog =====
  
   * v1.0 (2022-02-20) Initial version sent for discussion   * v1.0 (2022-02-20) Initial version sent for discussion
   * v1.1 (2022-03-04) Made a stronger recommendation of mb_convert_encoding as a replacement (see "Alternatives to Removed Functionality")   * v1.1 (2022-03-04) Made a stronger recommendation of mb_convert_encoding as a replacement (see "Alternatives to Removed Functionality")
 +  * v1.2 (2022-04-04) Dropped proposed custom wording for deprecation message. The nuances can be better expressed in the manual.
rfc/remove_utf8_decode_and_utf8_encode.1646436289.txt.gz · Last modified: 2022/03/04 23:24 by imsop

Page Tools