Tag Archives: php

Convert an image to indexed color mode with PHP

Indexed color is a technique to display an image with only a few specific colors. With indexed color mode, you can reduce the image file size or achieve amazing image effects.

In the GD library of php, there is a function called imagetruecolortopalette that could converts a truecolor image to a palette image. But using this function, you can’t decide which colors that the output image will contain, instead, you can only set the maximum number of colors that will be retained in the output image. In addition, there is no dither amount control in the this function.

I write the GDIndexedColorConverter library with PHP to achieve advanced indexed color conversion. To archieve image dithering effect, GDIndexedColorConverter uses Floyd–Steinberg dithering algorithm to apply error diffusion of each pixel onto its neighboring pixels.


GDIndexedColorConverter uses some functions of the GD extension, you need to enable GD extension in the PHP configuration file (php.ini).

GDIndexedColorConverter provide a function named convertToIndexedColor to convert an image into indexed color mode, it accepts three parameters(listed below), and return a new image resource of indexed color mode.

  • im (imageresource) The image resource created by the functions of GD library.
  • palette (array) The palette which contains all the specific colors that the indexed-color-mode image will use. This parameter is an array which stores all the colors, each color is an indexed array that consists of red, green and blue color channel values.
  • dither (float) How much the Floyd–Steinberg dithering algorithm will affect the image. This parameter is optional, its default value is 0.75, and the value must be between 0 and 1.

Code example:

// create an image
$image = imagecreatefromjpeg('example.jpg');

// create a gd indexed color converter
$converter = new GDIndexedColorConverter();

// the color palette
$palette = array(
    array(0, 0, 0),
    array(255, 255, 255),
    array(255, 0, 0),
    array(0, 255, 0),
    array(0, 0, 255)

// convert the image to indexed color mode
$new_image = $converter->convertToIndexedColor($image, $palette, 0.8);

// save the new image
imagepng($new_image, 'example_indexed_color.png', 0);


Applying different dither values on indexed-color images, you can get various image effects. For instance, the picture below shows three output images with different dither values(0.2, 0.4, 0.8) and five colors(white, black, red, green and blue). The original image that I use in this example is created by @sage_solar, the image is under Creative Commons License.


To check more information about GDIndexedColorConverter, visit https://github.com/ccpalettes/gd-indexed-color-converter


Remote Debugging PHP with VIM and XDebug

Many php developers enjoy outputting debugging information using functions such as var_dump during the development process, but sometimes it’s not effective if the program logic is complex or if you want to step through code line by line. To console debugging information, we have to manually add debug statements in our code, this is really a waste of time. Fortunately, there is a useful php extension called XDebug which provides debugging, profiling, tracing and code coverage support. With the debugging ability of XDebug, we could add breakpoints, watch variables and examine the call stack in our php code, just like IDEs for other languages such as java.

Now I have a local machine (debugger client) that runs Mac OS X 10.8 and a virtual machine (php + web server) that is running Ubuntu Server 12.04 operating system as a remote server in Oracle VM VirtualBox. In the virtual machine, there is a php web application. In this article, you’ll see how to install and configure XDebug, and how to debug the php application using VIM on a local machine.

The picture below describes the theory of remote debugging with xdebug.

theory about remote debuging with xdebug

In order that the local machine and remote server could access each other, I create a host-only network with virtualbox, the local machine could visit the site on the remote server through address, and the remote server could access the local machine through ip About setting host-only network in virtualbox, you can visit this article Host-Only Networking With VirtualBox.

Install XDebug in Remote Server

  • First download xdebug source files, then compile it to .so extension. Before compiling, make sure you have installed php5-dev package, if not, Debian users can install it by typing command:
    $ sudo install php5-dev
  • Compile xdebug.
    # run phpize, use phpize in your own environment instead.
    $ /usr/bin/phpize
    # remember use the path of php-config in your own environment.
    $ ./configure --enable-xdebug –with-php-config=/usr/bin/php-config
    # copy xdebug.so to php extensions directory
    $ sudo cp modules/xdebug.so /usr/lib/php5/20090626/
  • Edit the php configuration file php.ini, it’s located at /etc/php5/cli in my remote server. Then add these lines to php.ini.
  • [xdebug]
    ; The port to which xdebug tries to connect on the remote host.
    ; The host where the debugger client is running, is the ip address
    ; of the debugger client machine.
  • Restart the web server. To check whether xdebug extension takes effect, you could create a phpinfo page, and see whether the xdebug extension information appears on the page result.

    xdebug infomation in phpinfo page

Configure VDebug in VIM

In the local machine (debugger client), I will add a plugin called vdebug to the vim editor. Vdebug is a new, fast, powerful debugger client for Vim, it interfaces with any debugger that faithfully uses the DBGP protocol, including xdebug for PHP. One important issue to note is that the vim must have tabs, signs, python support and the version of python should be 2.6+.

  • Download vdebug and uncompress the pachage, then copy its content to your ~/.vim/ directory.

    For more installation methods about vdebug, please refer to README of vdebug.

  • Configure options for vdebug. You need set the port to which the xdebug connects, edit file ~/.vimrc, add these lines:
    let g:vdebug_options = {}
    let g:vdebug_options["port"] = 9000
  • Map code paths. To use xdebug remote debugging, a same copy of the php files in the remote server should already exist in the local machine. Although the php application runs in the remote server, but if you want to debug php files in local vim editor, the vim needs display the sames files for you. For example, the path of the php source files on my remote server is /var/www, and the I have the same code files in the directory /Users/ccpalettes/php/xdebug on my local machine. So I append the lines below to file ~/.vimrc.
  • let g:vdebug_options["path_maps"] = {
    \    "/var/www": "/Users/ccpalettes/php/xdebug"

How to Use

As I mentioned earlier, I could access the php web application through on my local machine. Follow these steps below, I could debug php files easily.

  • Open the php file that you want to debug in vim.
  • Put the cursor over the line to which you want to add a breakpoint, press F10, you can see the line will be highlighted which indicates a breakpoint has been set. To remove the breakpoint, just repeat the action on the same line.

    add a breakpoint

  • Then press F5 to start the debugger, a message will be shown at the bottom of the vim editor.debugger start message
  • Open your browser on the local machine, input the url of the web application ( into the address bar and append ?XDEBUG_SESSION_START=1 to the end of the url. Finally, the url will be concatenated into Parameter XDEBUG_SESSION_START will be saved in the cookie in your browser which tells the xdebug to make a connection with the debugging client.
  • After refreshing the page, the xdebug should work now, and you will able to see source, watch, stack and status window in the vim.

    debugger windows

Here are a few available commands in vdebug. You can see more details in vdebug document.

Run               <F5>
Step over         <F2>
Step in           <F3>
Step out          <F4>
Run to cursor     <F9>
Detach            <F7>
Stop/close        <F6>

Debugging in local environment

Although I am talking about remote debugging php, but these steps also could be applied to local debugging. The only difference is that the remote server and the debugger client are actually the same machine. The image below show how the xdebug works under local environment.

remote debugging php in local environment

One more note

XDebug is powerful, it provide you not only the debugging ability, but also a lot of features waiting to be discovered by yourself.