HTTP Verbs Changes in PHP 8.4

PHP 8.4 released in November, and you and your team have no doubt been hard at work understanding the new features, deprecations, and changes that accompany this latest iteration of the language. This includes changes to non-POST HTTP verbs.

In this blog, I walk through the background of HTTP verbs in PHP, explaining why the HTTP verbs changes in PHP 8.4 matter. I then provide a guide for developers to reference when implementing these changes within their code.

HTTP Verbs in PHP: Background

PHP was developed with the web in mind and supported form handling from its earliest days. Originally in HTTP, there were essentially only two methods via which a browser could request a web page: via GET or POST.  While HTML forms still only really support these two methods, JavaScript has the ability to send HTTP requests using any HTTP method, and a number of toolkits (e.g. HTMX) can even handle this seamlessly for developers.

GET and POST HTTP Methods

A GET request passes form data via the URL's query string. This means that the form results can be bookmarked, repeated, and even cached. Because of this, GET requests are commonly only used for actions that are requesting state without altering state: searches, result sorting, result filtering, pagination, etc.

If you want to perform an action that might make changes within an application — e.g., processing a shopping cart, sending a support message, uploading an image, etc. — you will use the POST HTTP method. POST requests are considered non-idempotent, meaning they cannot be cached and should not be repeated, because they have side effects. Those effects might mean inserts, changes, or deletions in a database, filesystem operations, web requests, or something else.

In order to automate handling of form data, PHP provides several superglobal variables that it populates from the incoming request. $_GET is populated with URL query string arguments and can be populated from any request method. $_POST, however, is only populated from the body of POST requests made using the content type application/x-www-form-urlencoded, which might look something like this:

title=HTTP+Verbs+Changes+in+PHP+8.4&url=https%3A%2F%2Fexample.org%2Fblog%2Fphp-8.4-http-verbs&author=Just+Some+Guy&tags%5B0%5D=php&tags%5B1%5D=http

PHP will take that and populate the $_POST superglobal such that it becomes the following:

<?php
$_POST = [
    'title' => 'HTTP Verbs Changes in PHP 8.4',
    'url' => 'https://example.org/blog/php-8.4-http-verbs',
    'author' => 'Just Some Guy',
    'tags' => ['php', 'http'],
];

The fact that PHP does this behind the scenes for you is part of what makes PHP so easy to learn and get started with.

Further, it can also handle the content type multipart/form-data, which allows a browser to upload files in addition to provide form data. When it does so, it will populate an additional $_FILES superglobal, which provides information on the files uploaded; developers can then validate and pre-process those files before storing them in a permanent location.

Other HTTP Methods

There are a lot more HTTP methods than GET and POST, and developers for the web often will want to choose different methods to provide context to what they are attempting to do:

• PUT is often used to indicate that the data should replace existing data.
• PATCH is often used to indicate that a partial update to an existing record is being made.
• DELETE is used to indicate the record or content submitted should be deleted or marked as deleted.

While browsers do not support these natively (yet!), many JavaScript frameworks and libraries do.

But there's a catch: PHP does not automatically handle these requests. In fact, you have to handle parsing of these entirely on your own, which can be hugely problematic when you also start handling file uploads as well as form data. (Never roll your own parsers!)

Unless you're able to adopt the newly released PHP 8.4, that is!

Register Now: Features (and Deprecations) to Watch in PHP 8.4

Ready to learn more about PHP 8.4? Then register for my upcoming webinar! I'll be exploring new features, key deprecations, and upgrade paths for PHP teams.

Save Your Seat

Changes to Non-POST HTTP Verbs

PHP 8.4 introduces the method request_parse_body():

[$_POST, $_FILES] = request_parse_body(?array $options = null);

The function parses the incoming request in the same way that it always has for POST requests, but allows you to specify alternate variables to store the form data and file uploads in (or overwrite the superglobals, if you prefer). You can also alter the behavior of the parser via the $options argument, with more on that below.

A common pattern will likely be:

<?php
if (in_array($_SERVER['REQUEST_METHOD'], ['PUT', 'PATCH', 'DELETE'], true)) {
    [$_POST, $_FILES] = request_parse_body();
}

(Though if you're using a framework, expect the framework to take care of that detail for you.)

That's literally the entirety of the feature. A simple function to provide turnkey behavior you're already familiar with as a PHP developer. It doesn't get much better than this!

HTTP Verbs in PHP 8.4: A Developer's Guide

Now that we've talked through the changes to HTTP verbs in PHP 8.4, let's take a look at a few examples for how you can use and apply these updates in your code.

Supported Content Types

Just like POST requests, request_parse_body() will only parse requests with the following content types:

• application/x-www-form-urlencoded
• multipart/form-data

In the case of application/x-www-form-urlencoded, the $_FILES-equivalent array (index 1 in the returned array) will be empty. If the content type is not supported, the function will throw an InvalidArgumentException.

php://input

PHP allows you to inspect the raw request content via the php://input stream. This is a buffered stream that can be (as of PHP 7.4) read multiple times. However, when receiving multipart/form-data content, PHP gets a bit destructive, for a very good reason: buffering files could lead to the file content being written to disk twice, leading to more memory, storage, and I/O usage.

As such, request_parse_body() MUST NOT be called twice, as it will destructively consume php://input.

$options Parameter

The $options parameter to request_parse_body() allows you to alter its behavior at runtime, instead of relying on hard-coded php.ini configuration.

• Specify the post_max_size for the maximum content size it will attempt to parse.
• Specify the max_input_vars to limit how many form variables it will attempt to parse.
• Specify the upload_max_filesize to limit the size of individual files it will handle.
• Specify the max_file_uploads to limit how many file uploads it will handle.
• Specify the max_multipart_body_parts to limit the combination of file uploads and form data variables it will parse.

Final Thoughts

This is a relatively simple language feature syntactically, but it adds a lot of power to the language. Additionally, it provides an important security feature for people using non-POST verbs to send form requests and file uploads, as it prevents the need to manually parse the request to get these artifacts; parsing requests should be left to security experts.

With this support in the language, I'm hoping we'll start seeing native support in browsers for sending non-POST and non-GET requests in the future!

Get Started on Upgrading to PHP 8.4

Zend solves the hardest problems in PHP, including simplifying your next PHP upgrade. Explore Long Term Support options, migration services, security solutions, and more.

Discover Zend PHP LTS   See Professional Services

Additional Resources

• White Paper - The Hidden Costs of PHP Upgrades
• White Paper - Planning Your Next PHP Migration
• Blog - PHP 8.4: Features, Deprecations, and Changes to Watch
• Blog - A Guide to PHP 8.4 Property Hooks
• Blog - Asymmetric Visibility in PHP 8.4: What It Means for PHP Teams
• Blog - PHP Migrations: When Is Migrating the Right Choice?
• Blog - PHP Upgrades: How to Plan and Execute Your Next Upgrade