Welcome! Log In Create A New Profile

Advanced

[PHP-DEV] Proposal: Rename image functions

Posted by Andreas Treichel 
Andreas Treichel
[PHP-DEV] Proposal: Rename image functions
November 04, 2017 05:50PM
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

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Rowan Collins
Re: [PHP-DEV] Proposal: Rename image functions
November 04, 2017 06:50PM
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]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Christoph M. Becker
[PHP-DEV] Re: Proposal: Rename image functions
November 04, 2017 10:30PM
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

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Christoph M. Becker
Re: [PHP-DEV] Proposal: Rename image functions
November 04, 2017 10:50PM
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

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Andrea Faulds
[PHP-DEV] Re: Proposal: Rename image functions
November 04, 2017 11:50PM
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/

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Stanislav Malyshev
Re: [PHP-DEV] Proposal: Rename image functions
November 05, 2017 01:40AM
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

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Peter Kokot
Re: [PHP-DEV] Proposal: Rename image functions
November 05, 2017 03:00PM
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...

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Johannes Schlüter
Re: [PHP-DEV] Proposal: Rename image functions
November 05, 2017 10:40PM
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


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Michael Morris
Re: [PHP-DEV] Proposal: Rename image functions
November 06, 2017 02:20AM
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:

> 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
>
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>
Johannes Schlüter
Re: [PHP-DEV] Proposal: Rename image functions
November 06, 2017 01:40PM
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 ... 
Sara Golemon
Re: [PHP-DEV] Re: Proposal: Rename image functions
November 07, 2017 02:50AM
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

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Andrea Faulds
Re: [PHP-DEV] Re: Proposal: Rename image functions
November 07, 2017 03:00AM
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/

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Christoph M. Becker
Re: [PHP-DEV] Re: Proposal: Rename image functions
November 07, 2017 01:00PM
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

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
Sorry, only registered users may post in this forum.

Click here to login