Skip to content

FormData and URLSearchParams

Jump to bottom
Greg Bowler edited this page Apr 24, 2026 · 2 revisions

FormData and URLSearchParams are based on the browser APIs of the same names.

They are both key/value stores, but they represent different kinds of data:

  • FormData is for form submission style body data, including files and repeated fields
  • URLSearchParams is for query-string style data

FormData

Build it manually

use GT\Http\FormData;

$formData = new FormData();
$formData->append("name", "Cody");
$formData->append("interest", "Mathematics");
$formData->append("interest", "Cryptography");

echo (string)$formData;
// name=Cody&interest[]=Mathematics&interest[]=Cryptography

Construct it from a DOM form

FormData can be created from a real DOM <form> element. When using PHP.GT/Dom this gives you a full modern HTMLDocument, just like in the browser:

use GT\Dom\HTMLDocument;
use GT\Http\FormData;

$html = <<<HTML
<form class="example-form">
	<input name="name" value="Cody" />
	<textarea name="message">Hello</textarea>
	<button name="do" value="send">Send message</button>
</form>
HTML;

$document = new HTMLDocument($html);

$form = $document->querySelector(".example-form");
$formData = new FormData($form);

The constructor reads named HTMLInputElements from the form.

Submit buttons

Just like when using FormData in JavaScript, buttons are not included automatically, because only the clicked submitter should contribute its value during a real form submission.

If you want that behaviour, pass the submitter element as the second argument:

$formData = new FormData($form, $button);

If the submitter is not part of the form, the constructor throws HttpException.

Files and blobs

FormData can hold:

  • strings
  • Blob
  • File
  • SplFileObject

If you pass an SplFileObject, the library wraps it in a File object for you.

Reading values

$formData->get("name");
$formData->getAll("interest");
$formData->getFile("avatar");
$formData->getBlob("attachment");

URLSearchParams

Construct from a query string

use GT\Http\URLSearchParams;

$params = new URLSearchParams("?page=2&sort=name");

echo $params->get("page"); // 2
echo $params->size;        // 2

The leading ? is optional and ignored.

Construct from an array

$params = new URLSearchParams([
	"page" => "2",
	"sort" => "name",
]);

Construct from FormData 

$params = new URLSearchParams($formData);

This is useful when you want query-string style output from data you already gathered as form fields.

Add and remove values

$params->append("filter", "new");
$params->append("filter", "popular");
$params->set("page", "3");
$params->delete("sort");

Repeated keys are preserved and serialised with [].

Iteration helpers

URLSearchParams and FormData both inherit helpers from KeyValuePairStore, including:

  • entries()
  • forEach()
  • get()
  • getAll()
  • has()
  • keys()
  • values()
  • delete()
  • sort()

That means once you learn one of these classes, the other feels familiar.

Type-safe getters

Both classes also support the nullable type-safe getter helpers used elsewhere in PHP.GT.

For example:

$age = $params->getInt("age");
$name = $formData->getString("name");

When to use which

Use FormData when:

  • you are representing a form submission
  • repeated fields matter
  • file values may be present

Use URLSearchParams when:

  • you are building or reading a query string
  • the data belongs in the URI
  • you want a compact URL-encoded string

The next page covers the body helpers these classes often work alongside: Streams, blobs, and binary data.

PHP.GT/Http is a separately maintained component of PHP.GT/WebEngine.

Requests and responses

Body data and helpers

Examples

Clone this wiki locally