php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #74364 imagepng misses default value for $quality param
Submitted: 2017-04-03 07:15 UTC Modified: 2017-04-05 10:11 UTC
From: maggus dot staab at googlemail dot com Assigned: peehaa (profile)
Status: Closed Package: GD related
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: maggus dot staab at googlemail dot com
New email:
PHP Version: OS:

 

 [2017-04-03 07:15 UTC] maggus dot staab at googlemail dot com
Description:
------------
the docs mention the valid for $quality spans from 0-9 but it doesnt mention what the default value is.

it defaults to 0 it seems (dont rely on my non-existent C-fu tho)
https://lxr.room11.org/xref/php-src%40master/ext/gd/gd.c#375

---
From manual page: http://www.php.net/function.imagepng
---



Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2017-04-03 07:52 UTC] requinix@php.net
-Status: Open +Status: Verified -Package: Documentation problem +Package: GD related
 [2017-04-03 07:52 UTC] requinix@php.net
tldr: The default depends on zlib but is probably 6.


:375 is not quite the right place. That does define the arguments but is not where the defaults are - see how everything uses 0? To see the default you have to check the code in the function itself (:2747). However that just passes execution to _php_image_output_ctx (gd_ctx.c:82), which does extract the arguments (:120) with quality=$quality. Then it sets q=quality if it had been passed to the function (:129) or else it will remain with its initial value of -1 (:91). GD gets involved later (:202) by calling *func_p, which was an argument passed to _php_image_output_ctx (from back in gd.c) and, in the case of imagepng, is gdImagePngCtxEx.

At this point you hit up Google and find
  https://libgd.github.io/manuals/2.2.2/files/gd_png-c.html
where gdImagePngCtxEx says the default compression is -1 too. Jump to "gdIamgePnEx" (lol) and you get
> A compression level of -1 will use the default compression level at the time
> zlib was compiled on your system.

Back to Google one more time and we find
  http://www.zlib.net/manual.html
> Compression levels.
> #define Z_DEFAULT_COMPRESSION  (-1)
...
> Z_DEFAULT_COMPRESSION requests a default compromise between speed and compression
> (currently equivalent to level 6).
 [2017-04-03 09:31 UTC] maggus dot staab at googlemail dot com
thx for your in-depth analysis. things seem to be more complicated then initially thought ;-).

would it make sense to mention in the docs that the param defaults to zlibs default compresssion Z_DEFAULT_COMPRESSION ?

maybe it would also be worthwhile when it will be mentioned that this parameter is not a linear 0 is worst and 9 is best compression thing but the "optimal" value lies somehow in the middle?
A lot of people are used to jpeg which works best when doing the most aggressive optimization ahead of time.

see also http://marcjschmidt.de/blog/2013/10/25/php-imagepng-performance-slow.html
 [2017-04-03 09:54 UTC] requinix@php.net
The average PHP developer doesn't know about the structure of PNG images or about zlib compression, so telling them the default is Z_DEFAULT_COMPRESSION will just confuse them. Similarly, drowning them in information about the relationship between compression level and file size/runtime will have their eyes glossing over.

I'd keep it simple: the default level is 6 [I doubt it will change anytime soon] and is a good compromise between the speed of level=0 and the compression of level=9.

If there's something more in-depth to be said then it would probably be best as a link to some external resource - minimizing the number of pages in the manual that can only be maintained by people with specialized knowledge.
 [2017-04-03 10:23 UTC] maggus dot staab at googlemail dot com
I guess you are right. when the default of "6" is mentioned this might already ring a bell that 9 is not the best for some reason in all cases ;-).

thanks!
 [2017-04-05 09:16 UTC] peehaa@php.net
Does this work for you?

Create a patch here http://edit.php.net/?patchID=2445&project=PHP
 [2017-04-05 10:10 UTC] maggus dot staab at googlemail dot com
looks great thx. wasnt aware of the tool, will play with it in the future. thx!
 [2017-04-05 10:11 UTC] peehaa@php.net
-Status: Verified +Status: Closed -Assigned To: +Assigned To: peehaa
 [2017-04-05 10:11 UTC] peehaa@php.net
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Fri Dec 06 23:01:26 2024 UTC