====== PHP RFC: Deprecate and Remove image2wbmp() ======
  * Version: 1.0
  * Date: 2018-05-26
  * Author: Christoph M. Becker, cmb@php.net
  * Status: Implemented (PHP 7.3)
  * First Published at: http://wiki.php.net/rfc/image2wbmp

===== Introduction =====

ext/gd has two functions to output WBMP ((Wireless Application Protocol Bitmap Format; not Windows Bitmap)) images: ''imagewbmp()'' and ''image2wbmp()''.
Both are supposed to handle the necessary monochrome conversion by different means.
While the former function allows the desired foreground color to be specified, the latter
function is supposed to take a brightness threshold parameter. However, as of PHP 5.0.0 the
threshold parameter of ''image2wbmp()'' is treated as foreground color, so both functions
are basically identical.

This pointless duplication of functionality could be resolved by fixing ''image2wbmp()''
according to the documentation (i.e. treat the third parameter actually as brightness treshold),
but

  * fixing **this** 10+y old bug is likely to cause more harm than good
  * a monochrome conversion should be a **general** feature of GD (or rather libgd), since it may be useful for other image formats as well (e.g. PNG)
  * the [[https://github.com/php/php-src/blob/PHP-7.2.4/ext/gd/gd.c#L4140|implemented monochrome conversion]] is very simplistic, and does not fit to [[http://libgd.github.io/manuals/2.2.5/files/gd_filter-c.html#gdImageGrayScale|gdImageGrayScale()]]'s [[https://github.com/php/php-src/blob/PHP-7.2.4/ext/gd/libgd/gd_filter.c#L74|algorithm]]
  * WBMP might be considered obsolete nowadays

===== Proposal =====

Therefore, this RFC proposes to:

  - fix the [[http://de2.php.net/manual/en/function.image2wbmp.php|documentation]] according to the current implementation
  - remove superfluous code (most notably [[https://github.com/php/php-src/blob/PHP-7.2.4/ext/gd/gd.c#L4103|_php_image_bw_convert()]])
  - deprecate ''image2wbmp()''
  - finally remove ''image2wbmp()'' altogether

===== Backward Incompatible Changes =====

After the deprecation, each call to ''image2wbmp()'' would issue a deprecated warning.
After the removal, each call to ''image2wbmp()'' would raise a fatal error.

===== Proposed PHP Version(s) =====

Item (1) to (3) of the proposal should target next PHP 7.y (i.e. PHP 7.3),
while item (4) (i.e. the actual removal) should target next PHP x (supposedly PHP 8).

===== Voting =====

A single vote will be held to decide whether to implement the [[#proposal|proposal]].
This vote will require a 2/3 supermajority.
Voting started on 2018-05-26, and ended on 2018-06-09 21:00 UTC.
<doodle title="Deprecate and Remove image2wbmp()" auth="cmb" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

A [[https://github.com/php/php-src/pull/3247|pull request regarding the deprecation]] is available.

===== Implementation =====

  - Implemented in PHP 7.3 via [[http://git.php.net/?p=php-src.git;a=commit;h=3cbf594dfd0708dc36f1655c50e16fa963e61501]]
  - [[http://php.net/manual/en/function.image2wbmp.php|doc]] [[http://svn.php.net/viewvc?view=revision&revision=345112|fix]]
  - [[http://git.php.net/?p=php-src.git;a=commit;h=dfa6c2046a8d7b66c4be52e46888f0fefccbcfd4|Removed for PHP 8]]

===== References =====

  * relevant [[https://bugs.php.net/73317|bug report]]
  * preliminary [[https://externals.io/message/102025|discussion on internals]]
  * [[https://externals.io/message/102106|RFC discussion]]