View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Michael Schilli > PHP-HTTPBuildQuery > PHP::HTTPBuildQuery



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.09   Source  


PHP::HTTPBuildQuery - Data structures become form-encoded query strings


    use PHP::HTTPBuildQuery qw(http_build_query);

    my $query = http_build_query( 
        { foo => { 
              bar => "baz", 
                  quick => { "quack" => "schmack" },

    # Query: "foo%5Bbar%5D=baz&foo%5Bquick%5D%5Bquack%5D=schmack"

    # URL decoded: "foo[bar]=baz", "foo[quick][quack]=schmack"


PHP::HTTPBuildQuery implements PHP's http_build_query function in Perl. It is used to form-encode Perl data structures in URLs, so that PHP can read them on the receiving end.

New with version 0.04 comes http_build_query_utf8 which has an identical syntax but deals with utf8 data instead. See the GOTCHAS section below for details.

http_build_query accepts one mandatory and two optional parameters:

     http_build_query( $data, $prefix, $separator );




    $query = http_build_query( ['foo', 'bar'] );

    # Query: "name_0=foo&name_1=bar"

Hash with Array

    $query = http_build_query( { foo => [ 'bar', 'baz' ] } );

    # Query: "foo[0]=bar&foo[1]=baz" (not escaped for readability)


UTF8 Characters

The uri_escape() function used in http_build_query won't encode utf8 characters. If your data is utf8 encoded, use http_build_query_utf8 instead.

Hash Element Order

Perl hashes have no defined order, so if you encode something like { foo = "bar", baz => "quack" }>, don't be surprised if you get the entries in a different order:

    # Query: "baz=quack&foo=bar"
Frankenstein Arrays

PHP's Frankenstein arrays handle numeric indexing and hash-like lookups transparently. For example, you could have a data structure like

      # PHP
    $a = array(
       'foo'  => 'bar',
      # PHP

and you could access both its numeric and associative elements:

     # PHP
   print $a[0];
     # prints: 'baz'

     # PHP
   print $a[foo];
     # prints: 'bar'

PHP's http_build_query function would transform the Frankenstein array above to


or, better, with a prefix of 'name', to


In Perl, on the other hand, there's hashes for associative lookups and arrays for numerically indexed containers, so you can't mix and match, and there's no way to define a data structure to print out the query string above.

Special Characters

http_build_query creates a PHP-specific encoding format which can't handle ']' or '[' characters in its keys (they're ok in hash values, though). This module won't check against this case, it will just generate form strings that won't be decodable afterwards. Make sure to filter your data before passing it to http_build_query().


Thanks to the following Yahoos who provided advice, ideas and code: Sara Golemon, Rasmus Lerdorf, Evan Miller.



Copyright (c) 2008-2012 Yahoo! Inc. All rights reserved. The copyrights to the contents of this file are licensed under the Perl Artistic License (ver. 15 Aug 1997)


2008, Mike Schilli <>

syntax highlighting: