"Fatal error: syntax error, unexpected token"
A plugin update goes out on Friday. It uses enum, which arrived in PHP 8.1. On most sites it works. On a client's host that is still on PHP 8.0 the plugin file does not even parse, and the site shows a fatal error. One line in the plugin header would have stopped the update from activating there.
Goal
Know which PHP 8 features your code needs, declare it with Requires PHP and read the limits that php.ini sets for WordPress.
Key concepts
The course baseline is PHP 8. PHP 7.x appears only as legacy, the "before" case.
| Version | What a WordPress developer meets first |
|---|---|
| 7.x (legacy) | no union types, no match, no enum: the code most tutorials still show |
| 8.0 | union types, match, nullsafe ?->, named arguments, constructor property promotion |
| 8.1 | enum, readonly properties, first-class callables foo(...), never |
| 8.2 | readonly classes, dynamic properties deprecated (a wall of notices in old plugins) |
| 8.3 | typed class constants, #[\Override], json_validate() |
| 8.4 | property hooks, asymmetric visibility, array_find() |
| 8.5 | pipe operator |>, #[\NoDiscard], array_first() / array_last() |
Requires PHPin the main plugin file header (andreadme.txt): since WordPress 5.2, WordPress refuses to activate or update a plugin on a lower PHP version.memory_limitinphp.iniis the hard ceiling.WP_MEMORY_LIMIT(default 40M, 64M on multisite) andWP_MAX_MEMORY_LIMIT(default 256M, for admin tasks) are what WordPress asks for inside it.max_execution_time,upload_max_filesize,post_max_size: the usual reasons an import or an upload stops halfway.php -lchecks syntax with the PHP version you run it with: run it with the oldest version you support.
Commands / artifacts
<?php
/**
* Plugin Name: My Plugin
* Requires at least: 6.5
* Requires PHP: 8.1
* Version: 1.4.0
*/
// wp-config.php: what WordPress asks for, within php.ini memory_limit.
define( 'WP_MEMORY_LIMIT', '128M' );
define( 'WP_MAX_MEMORY_LIMIT', '256M' );
php -r 'echo ini_get("memory_limit"), PHP_EOL;'
wp eval 'echo WP_MEMORY_LIMIT, " / ", ini_get("memory_limit");'
php -l my-plugin.php
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Fatal "syntax error, unexpected token" right after an update | The code uses a newer PHP feature than the host has | Set Requires PHP to the real minimum; lint with that version |
| Hundreds of "Creation of dynamic property is deprecated" notices | Old classes add properties on the fly; deprecated since PHP 8.2 | Declare the properties (or #[\AllowDynamicProperties] as a temporary fix) |
"Allowed memory size exhausted" although WP_MEMORY_LIMIT is 512M | php.ini memory_limit is lower; WordPress cannot go above it | Raise memory_limit on the server, keep WP_MEMORY_LIMIT within it |
| A large import stops at the same point every time | max_execution_time | Batch the work (Action Scheduler, WP-CLI) instead of one long request |
WPCS
Put Requires PHP and Requires at least in the plugin header and in readme.txt, and keep them equal. The WordPress PHP Compatibility ruleset (PHPCompatibilityWP) checks your code against that minimum: setup in the QA / Tests course.
Practice
Read the PHP version and memory limits, compare memory_limit with WP_MEMORY_LIMIT, then lint a plugin file.
Interview Questions
It is a plugin header (and readme.txt field) with the minimum PHP version. Since WordPress 5.2 the plugin cannot be activated, and its updates are not offered, on a site with a lower PHP version, so new syntax never reaches a host that cannot parse it.
memory_limit is the PHP setting and the hard limit. WP_MEMORY_LIMIT is how much WordPress tries to raise the limit to for front-end requests, and WP_MAX_MEMORY_LIMIT for admin tasks. WordPress can never go above what the server allows.
Dynamic properties became deprecated: assigning a property that the class does not declare now raises a deprecation notice. Old plugins that attach data to objects on the fly flood the log until the properties are declared.