Everything
php
Learn Community Releases The PHP Project
Home » Project » Newsgroups » php.internals » Proposal: Rename image functions »

Proposal: Rename image functions

php.internals

Andreas Treichel

8 years ago
For a better readability of the gd functions I would like to rename them so that they contain underscores to separate the words. The only exception is image2wbmp which is renamed to image_to_wbmp. The order of the parameters of all functions whould be unchanged. Due to the unchanged parameters it should be easyly possible to create wrappers for forward / backward compatiblity to use the new function names in old versions of PHP and via versa. This was already part of the (inactive?) RFC Consistent Function Names https://wiki.php.net/rfc/consistent_function_names. But this seems to be too big change for a single RFC. Step 1: I create a patch with the new aliases. Step 2: Merge the changes with next minor release of PHP 7.x. Soft deprecation of old function names in the manual. Step 3: Deprecated old function names with PHP 8.0. What is your opinion for this change? Did you prefer "image_" or "gd_" as a common prefix? New name Old name image_affine imageaffine image_affine_matrix_concat imageaffinematrixconcat image_affine_matrix_get imageaffinematrixget image_alpha_blending imagealphablending image_antialias imageantialias image_arc imagearc image_bmp imagebmp image_char imagechar image_char_up imagecharup image_color_allocate imagecolorallocate image_color_allocate_alpha imagecolorallocatealpha image_color_at imagecolorat image_color_closest imagecolorclosest image_color_closest_alpha imagecolorclosestalpha image_color_closest_hwb imagecolorclosesthwb image_color_deallocate imagecolordeallocate image_color_exact imagecolorexact image_color_exact_alpha imagecolorexactalpha image_color_match imagecolormatch image_color_resolve imagecolorresolve image_color_resolve_alpha imagecolorresolvealpha image_color_set imagecolorset image_color_transparent imagecolortransparent image_colors_for_index imagecolorsforindex image_colors_total imagecolorstotal image_convolution imageconvolution image_copy imagecopy image_copy_merge imagecopymerge image_copy_merge_gray imagecopymergegray image_copy_resampled imagecopyresampled image_copy_resized imagecopyresized image_create imagecreate image_create_from_bmp imagecreatefrombmp image_create_from_gd imagecreatefromgd image_create_from_gd2 imagecreatefromgd2 image_create_from_gd2_part imagecreatefromgd2part image_create_from_gif imagecreatefromgif image_create_from_jpeg imagecreatefromjpeg image_create_from_png imagecreatefrompng image_create_from_string imagecreatefromstring image_create_from_wbmp imagecreatefromwbmp image_create_from_webp imagecreatefromwebp image_create_from_xbm imagecreatefromxbm image_create_from_xpm imagecreatefromxpm image_create_truecolor imagecreatetruecolor image_crop imagecrop image_crop_auto imagecropauto image_dashed_line imagedashedline image_destroy imagedestroy image_ellipse imageellipse image_fill imagefill image_fill_to_border imagefilltoborder image_filled_arc imagefilledarc image_filled_ellipse imagefilledellipse image_filled_polygon imagefilledpolygon image_filled_rectangle imagefilledrectangle image_filter imagefilter image_flip imageflip image_font_height imagefontheight image_font_width imagefontwidth image_ft_bbox imageftbbox image_ft_text imagefttext image_gamma_correct imagegammacorrect image_gd imagegd image_gd2 imagegd2 image_get_clip imagegetclip image_gif imagegif image_grab_screen imagegrabscreen image_grab_window imagegrabwindow image_interlace imageinterlace image_is_truecolor imageistruecolor image_jpeg imagejpeg image_layer_effect imagelayereffect image_line imageline image_load_font imageloadfont image_open_polygon imageopenpolygon image_palette_copy imagepalettecopy image_palette_to_truecolor imagepalettetotruecolor image_png imagepng image_polygon imagepolygon image_rectangle imagerectangle image_resolution imageresolution image_rotate imagerotate image_save_alpha imagesavealpha image_scale imagescale image_set_brush imagesetbrush image_set_clip imagesetclip image_set_interpolation imagesetinterpolation image_set_pixel imagesetpixel image_set_style imagesetstyle image_set_thickness imagesetthickness image_set_tile imagesettile image_string imagestring image_string_up imagestringup image_sx imagesx image_sy imagesy image_to_wbmp image2wbmp image_truecolor_to_palette imagetruecolortopalette image_ttf_bbox imagettfbbox image_ttf_text imagettftext image_types imagetypes image_wbmp imagewbmp image_webp imagewebp Further improvement: Rename the output functions to image_write_* New name Old name image_write_bmp imagebmp image_write_gd imagegd image_write_gd2 imagegd2 image_write_gif imagegif image_write_jpeg imagejpeg image_write_png imagepng image_write_wbmp imagewbmp image_write_webp imagewebp

Rowan Collins

8 years ago
On 4 November 2017 16:40:56 GMT+00:00, Andreas Treichel <gmblar@gmail.com> wrote:
> The only >exception is image2wbmp which is renamed to image_to_wbmp.
What is the difference between imagewbmp and image2wbmp? If we're going to rename things, shouldn't that difference be made clearer? Or should we be looking to deprecate one of them anyway? In my opinion, IF we rename, which I'm not 100% sold on, then all the output functions should have "_to_" in the name: image_to_gif, image_to_png, etc. Or perhaps some other infix, like "_save_", or "_generate_", particularly if using "gd_" as the prefix. Regards,
-- Rowan Collins [IMSoP]

Christoph Becker

8 years ago
On 04.11.2017 at 18:39, Rowan Collins wrote:
> On 4 November 2017 16:40:56 GMT+00:00, Andreas Treichel <gmblar@gmail.com> wrote: > >> The only >> exception is image2wbmp which is renamed to image_to_wbmp. > > What is the difference between imagewbmp and image2wbmp? If we're going to rename things, shouldn't that difference be made clearer? Or should we be looking to deprecate one of them anyway?
WBMP images are monochrome (at least in practice). Theoretically, image2wbmp() allows to set a threshold (light pixels will become foreground, dark pixels will become background), but imagewbmp() allows only to chose a foreground color (all other pixels will become background). However, this somewhat useful distinction has been removed as of PHP 5.0.0, see <https://bugs.php.net/73317>. Re-introducing the supposed functionality of image2wbmp() doesn't appear to be sensible after that long time, so I'm +1 on deprecating the function. Instead we might consider to add a general function to convert an image to monochrome according to a given brightness threshold. And frankly, I have doubts that WBMP is of any real value nowadays, so we might consider to deprecate both functions (imagecreatefromwbmp() might still be useful to convert old WBMP images to a more contemporary format).
-- Christoph M. Becker

Christoph Becker

8 years ago
On 04.11.2017 at 17:40, Andreas Treichel wrote:
> For a better readability of the gd functions I would like to rename them > so that they contain underscores to separate the words. The only > exception is image2wbmp which is renamed to image_to_wbmp. The order of > the parameters of all functions whould be unchanged. > > Due to the unchanged parameters it should be easyly possible to create > wrappers for forward / backward compatiblity to use the new function > names in old versions of PHP and via versa.
In my opinion, just renaming the functions doesn't make much sense. Instead we might consider to introduce OO wrappers, which wouldn't unnecessarily polute the global namespace, and also could lead to more concise userland code. Kalle's gdobjects[1] might serve as a base. On the other hand, such OO wrappers could also be implemented in userland, what might already have been done. [1] <https://github.com/KalleZ/gdobjects>
-- Christoph M. Becker

Sara Golemon

8 years ago
On Sat, Nov 4, 2017 at 5:25 PM, Christoph M. Becker <cmbecker69@gmx.de> wrote:
> In my opinion, just renaming the functions doesn't make much sense. > Instead we might consider to introduce OO wrappers, which wouldn't > unnecessarily polute the global namespace, and also could lead to more > concise userland code. Kalle's gdobjects[1] might serve as a base. >
100,000% this. Step 1: Transition the GD resource type to an object handle. Step 2: Add methods to that object as aliases to the original functions. Step 3: Profit. -Sara

Andrew Faulds

8 years ago
Hi, Sara Golemon wrote:
> On Sat, Nov 4, 2017 at 5:25 PM, Christoph M. Becker <cmbecker69@gmx.de> wrote: >> In my opinion, just renaming the functions doesn't make much sense. >> Instead we might consider to introduce OO wrappers, which wouldn't >> unnecessarily polute the global namespace, and also could lead to more >> concise userland code. Kalle's gdobjects[1] might serve as a base. >> > 100,000% this. > > Step 1: Transition the GD resource type to an object handle. > Step 2: Add methods to that object as aliases to the original functions. > Step 3: Profit. > > -Sara >
OOP would be nice for avoiding having to type image* constantly. But as for the hard-to-read naming, OOP isn't necessaary, IMO. The current GD API's naming without underscores cries out for camelCase. And that's possible for methods… but it's also possible for functions! Both are case-insensitive, so in fact, you can already type GD function names in camelCase and the code will work. The problem here is we have a convention of writing global function names in the manual in lowercase, something we don't do for methods. The simple and pragmatic solution is to make an exception and document GD in camelCase, as God intended. (Probably.)
-- Andrea Faulds https://ajf.me/

Christoph Becker

8 years ago
On 07.11.2017 at 02:53, Andrea Faulds wrote:
> OOP would be nice for avoiding having to type image* constantly. > > But as for the hard-to-read naming, OOP isn't necessaary, IMO. The > current GD API's naming without underscores cries out for camelCase. And > that's possible for methods… but it's also possible for functions! Both > are case-insensitive, so in fact, you can already type GD function names > in camelCase and the code will work. The problem here is we have a > convention of writing global function names in the manual in lowercase, > something we don't do for methods.
The convention is rather to document function names in their canonical form, i.e. what's returned via reflection.
> The simple and pragmatic solution is > to make an exception and document GD in camelCase, as God intended. > (Probably.)
I don't know what God intended, but it seems that Rasmus intended PascalCase, see <http://php.net/manual/phpfi2.php#imagearc>.
-- Christoph M. Becker

Andrew Faulds

8 years ago
Hi Andreas, Andreas Treichel wrote:
> For a better readability of the gd functions I would like to rename them > so that they contain underscores to separate the words.
From my perspective, GD's function names are a documentation problem. They're perfectly readable if typed in camelCase, as I do in my code, but the manual insists on lowercase here. I would argue we should simply make the manual deliberately break with convention for this extention, and document in camelCase. Thanks.
-- Andrea Faulds https://ajf.me/

Stas Malyshev

8 years ago
Hi!
> Step 1: > I create a patch with the new aliases.
I don't see much wrong with old names - nobody remembers those names anyway, and once you use IDE or - for people that still type PHP code by banging two rocks together, like I sometimes do, the manual - it doesn't matter whether there is underscore there or not. Nobody expects those functions to read like a fine prose anyway :)
> Step 2: > Merge the changes with next minor release of PHP 7.x. > Soft deprecation of old function names in the manual.
There's no reason to either soft or hard deprecate old names. There's nothing wrong with these names or the code that uses them. Forcing people to change their code just because somebody likes names with underscores better is plain wrong. Believe me, there's plenty to do with any large PHP codebase project besides doing pointless changes like this. Especially if you want codebase that works from 5.5 to 7.x and beyond (and yes, that happens). Of course, if you like new names better, and they are introduced, you are welcome to use them, but that's as far as it should go. I am still kinda skeptical on the cost/benefit ratio, given how many new names are added, but maybe it's ok if people like it. But names already used in code should stay.
-- Stas Malyshev smalyshev@gmail.com

Peter Kokot

8 years ago
Hello all, correct me if I'm wrong, but wouldn't be a good practice to follow the currently set coding standards? https://github.com/php/php-src/blob/master/CODING_STANDARDS Good: 'foo_select_bar' Bad: 'fooinsertbaz' And therefore making aliases for all inconsistently named functions in the core for the next PHP version (and furthermore removing other conventions in future versions)? My preference is definitely camelCase but that would break all other prevailing naming of functions with underscores...

Johannes Schlueter

8 years ago
On So, 2017-11-05 at 14:51 +0100, Peter Kokot wrote:
> Hello all, > > correct me if I'm wrong, but wouldn't be a good practice to follow > the > currently set coding standards? > https://github.com/php/php-src/blob/master/CODING_STANDARDS
That is good for new code. But breaking 20 years of history for only that reason is questionable. johannes

Michael Morris

8 years ago
No. Hell no. The last thing PHP needs is an ill thought out string of function name changes to further pollute the global name space. Further, merely changing the names isn't going to do anything. What would help is a massive clean and redo for PHP 8 in the same vein as Actionscript 2 to 3 had a massive cleanup. Namespaces give us the means to do it along with the import keyword - but it would be painful to write the code and I don't think anyone is willing to do it. The strategy would be to put all existing global namespace functions into a new namespace: PHP\Legacy Then add an import keyword. Similar to use, import pulls the designated namespace into the current namespace. Then, for backward compatibility, add a php.ini setting that runs "import PHP\Legacy" at the start of each script. Then create the new functions, separated and organized by namespace. For example. PHP\String\split. And while doing this, decide once and for all whether it's haystack, needle or needle, haystack damn it. On Sun, Nov 5, 2017 at 4:36 PM, Johannes Schlüter <johannes@schlueters.de> wrote:

Johannes Schlueter

8 years ago
On So, 2017-11-05 at 20:18 -0500, Michael Morris wrote:
> Then, for backward compatibility, add a php.ini setting that runs > "import PHP\Legacy" at the start of each script.
We did that mistake with magic_quotes and the ze1 compatibility mode in PHP 5.0. We should learn from that and reduce number of ini settings which have impact on the script behavior, not increase this. This makes, among other things, writing portable code hard (While the environment changed, back in the days shared hosting was a bigger thing, while nowadays with containers users often have more control over their environment) *If* we do something in those areas this should always be that we provide superb options to do stuff in a "clean" (as defined in contemporary understanding) way, which makes the old way obsolete. Introducing a new set of APIs without substantial gain won't get traction (as developers have to relearn, books, tutorials, ... are suddenly outdated, libraries have to make compatibility choices, copy&paste-programming keeps legacy alive, ....) As an example: If we provide a new full set of unicode aware string manipulation, routines these might render byte-based string functions obsolete for many use-cases and offer a gain. (how else could an application handle emojis ... so this is nowadays is even relevant for English-only use cases ... 🤓) Or if we provide an image manipulation framework which supports higher level constructs than pixels and lines ... johannes