The pipe operator

Functional pipelines in PHP have always been a mess. Chaining transformations meant either nesting function calls inside out, or breaking them into intermediate variables:

// before — read right to left
$result = array_sum(array_map('strlen', array_filter($strings, 'strlen')));

// or verbose but readable
$filtered   = array_filter($strings, 'strlen');
$lengths    = array_map('strlen', $filtered);
$result     = array_sum($lengths);

// after — read left to right
$result = $strings
    |> array_filter(?, 'strlen')
    |> array_map('strlen', ?)
    |> array_sum(?);

The |> operator passes the left-hand value into the right-hand expression. The ? placeholder marks where it goes. Pipelines now read in the order operations happen: left to right, top to bottom.

This pairs well with first-class callables from PHP 8.1. The two features compose nicely:

$result = $input |> trim(...) |> strtolower(...) |> $this->normalize(...);

The URI extension

Handling URIs in PHP has always meant either reaching for a third-party library or cobbling together parse_url() (returns an array, not an object), http_build_query(), and manual string concatenation.

The new Uri extension gives you a proper object-oriented API:

$uri = Uri\Uri::parse('https://example.com/path?query=value#fragment');
$modified = $uri->withPath('/new-path')->withQuery('key=val');
echo $modified; // https://example.com/new-path?key=val#fragment

Immutable value objects, RFC-compliant parsing, modify individual components without parsing and reconstructing the whole string. Long overdue.

#[\NoDiscard]

A new attribute that generates a warning when the return value is ignored:

#[\NoDiscard("Use the returned collection, the original is unchanged")]
public function filter(callable $fn): static { ... }

Useful for immutable methods where ignoring the return value is almost certainly a bug. Common in other languages for years, now in PHP where it belongs.

clone with

Cloning an object with modified properties without using property hooks or a custom with() method:

$updated = clone($point) with { x: 10, y: 20 };

Clean syntax for a pattern readonly objects needed: you clone to “modify” since direct mutation isn’t allowed.

PHP 8.5 has a functional streak. The pipe operator and URI extension together make data transformation code meaningfully easier to read. The language keeps moving in a consistent direction.

Closures in constant expressions

A constraint that’s been baked in since PHP 5: constant expressions (attribute arguments, property defaults, parameter defaults, const declarations) couldn’t contain closures or first-class callables. 8.5 removes that.

#[Validate(fn($v) => $v > 0)]
public int $count = 0;

const NORMALIZER = strtolower(...);

class Config {
    public function __construct(
        public readonly Closure $transform = trim(...),
    ) {}
}

This is the missing piece that makes attributes genuinely expressive for validation and transformation rules. Before 8.5, you had to pass class names or string references to attributes and let the framework look them up. Now the callable lives directly in the attribute.

Attributes on constants

The #[\Deprecated] attribute from 8.4 couldn’t be applied to const declarations. 8.5 adds attribute support for constants generally:

const OLD_LIMIT = 100;

#[\Deprecated('Use RATE_LIMIT instead', since: '3.0')]
const API_TIMEOUT = 30;

const RATE_LIMIT = 60;

ReflectionConstant, a new reflection class in 8.5, exposes getAttributes() so tools can read them. Combined with closures in constant expressions, attributes on constants become a real metadata layer for compile-time values.

#[\Override] extends to properties

PHP 8.3 brought #[\Override] for methods. 8.5 extends it to properties:

class Base {
    public string $name = 'default';
}

class Derived extends Base {
    #[\Override]
    public string $name = 'derived';
}

If the property doesn’t exist in the parent, PHP throws an error. Particularly useful with property hooks from 8.4: you can now signal that a hooked property is intentionally overriding a parent’s.

Static asymmetric visibility

8.4 introduced asymmetric visibility (public private(set)) for instance properties. 8.5 brings that to static properties too:

class Registry {
    public static private(set) array $items = [];

    public static function register(string $key, mixed $value): void {
        self::$items[$key] = $value;
    }
}

echo Registry::$items['foo']; // readable
Registry::$items['bar'] = 1; // Error: cannot write outside class

Straightforward pattern: expose a static collection for reading, block external mutation.

Constructor promotion for final properties

Property promotion in constructors has existed since PHP 8.0. The final modifier on promoted properties was the missing piece, 8.5 adds it:

class ValueObject {
    public function __construct(
        public final readonly string $id,
        public final readonly string $name,
    ) {}
}

A subclass can’t override $id or $name with a property of the same name. The final readonly combination on promoted properties makes value objects as locked down as possible without sealing the whole class.

Casts in constant expressions

Another gap in constant expressions: no type casts. 8.5 allows them:

const PRECISION = (int) 3.7;      // 3
const THRESHOLD = (float) '1.5';  // 1.5
const FLAG = (bool) 1;            // true

Sounds minor until you have configuration constants derived from environment variables that need type coercion right at the declaration.

Fatal errors include backtraces

Before 8.5, a fatal error (out-of-memory, stack overflow, type error in certain contexts) produced a message with no context about where in the code it happened. Finding the cause meant inserting debug logging and reproducing.

8.5 adds stack backtraces to fatal error messages, in the same format as exception backtraces. A new INI directive, fatal_error_backtraces, controls the behavior. It’s on by default.

array_first() and array_last()

PHP has had reset() and end() for accessing the first and last elements of an array since PHP 3. Both mutate the array’s internal pointer (not safe to call on a reference), and they return false for empty arrays in a way that’s indistinguishable from a stored false value.

$values = [10, 20, 30];

$first = array_first($values);  // 10
$last  = array_last($values);   // 30

$first = array_first([]);       // null

The new functions return null for empty arrays, don’t touch the internal pointer, and work on any array expression without needing a variable. reset($this->getItems()) was a deprecation warning waiting to happen.

get_error_handler() and get_exception_handler()

PHP has set_error_handler() and set_exception_handler(). Getting the current handler meant either storing it yourself before setting it, or calling set_error_handler(null) and capturing what came back, which also cleared the handler in the process.

8.5 adds:

$current = get_error_handler();
$current = get_exception_handler();

Handy in middleware chains where you want to wrap the existing handler without losing it, or in tests where you want to verify a handler was actually installed.

IntlListFormatter

Formatting a list with locale-appropriate conjunctions has always needed manual string assembly. 8.5 adds IntlListFormatter:

$formatter = new IntlListFormatter('en_US', IntlListFormatter::TYPE_AND);
echo $formatter->format(['apples', 'oranges', 'pears']);
// "apples, oranges, and pears"

$formatter = new IntlListFormatter('fr_FR', IntlListFormatter::TYPE_OR);
echo $formatter->format(['rouge', 'bleu', 'vert']);
// "rouge, bleu ou vert"

The class wraps ICU’s ListFormatter. Three types: TYPE_AND, TYPE_OR, TYPE_UNITS. Width constants control whether you get “and” or “&”. Oxford comma handling, locale-specific conjunction placement, all handled by ICU.

FILTER_THROW_ON_FAILURE for filter_var()

filter_var() returns false on validation failure, which produces the classic false vs null vs 0 ambiguity when you’re filtering untrusted input. A new flag changes that:

try {
    $email = filter_var($input, FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
} catch (Filter\FilterFailedException $e) {
    // explicitly invalid, not ambiguously false
}

The Filter\FilterFailedException and Filter\FilterException classes are new in 8.5. The flag can’t be combined with FILTER_NULL_ON_FAILURE: the behaviors are mutually exclusive.

Deprecations that clean up years of technical debt

The backtick operator (`command` as an alias for shell_exec()) is deprecated. It’s an obscure syntax that surprises anyone reading the code and is inconsistent with every other PHP function call.

Non-canonical cast names ((boolean), (integer), (double), (binary)) are deprecated in favor of their short forms: (bool), (int), (float), (string). The long forms have been undocumented for years; 8.5 starts the formal removal.

Semicolon-terminated case statements are deprecated:

// deprecated
switch ($x) {
    case 1;
        break;
}

// correct
switch ($x) {
    case 1:
        break;
}

The semicolon form has been syntactically valid since PHP 4 but nobody uses it on purpose. It’s a typo PHP happened to accept.

__sleep() and __wakeup() are deprecated in favor of __serialize() and __unserialize(), which return and receive arrays and compose correctly with inheritance. The old methods had messy semantics around property visibility.

max_memory_limit caps runaway allocations

A new startup-only INI directive: max_memory_limit. It sets a ceiling that memory_limit can’t exceed at runtime. If a script calls ini_set('memory_limit', '10G') and max_memory_limit is 512M, PHP warns and caps the value.

Useful in shared hosting environments, or anywhere you want to make sure a bug or a malicious payload can’t convince PHP to raise its own limit and eat the whole machine’s RAM.

Opcache is always present

In 8.5, Opcache is always compiled into the PHP binary and always loaded. The old situation (Opcache as a loadable extension that might or might not be present depending on build configuration) is gone.

You can still disable it: opcache.enable=0 works fine. What changes is the guarantee that the Opcache API (opcache_get_status(), opcache_invalidate(), etc.) is always available, regardless of how PHP was compiled. Any code that checks extension_loaded('opcache') before calling Opcache functions can drop the check.

JSON streamer for large collections

The default Symfony serializer builds the full response in memory before writing it to the output. For a collection of 10,000 items, this means allocating a PHP array, serializing it to a string, and keeping both in memory until the response is flushed. At scale, this is the source of the OOM errors that force people to add pagination everywhere.

4.2 adds a streaming JSON encoder that writes the response incrementally:

api_platform:
    serializer:
        enable_json_streamer: true

With streaming enabled, the response is written directly to the output buffer as each item is serialized. Memory usage stays roughly constant regardless of collection size. The trade-off: you cannot set response headers after streaming starts, and the HTTP status code must be committed before the first byte is written.

ObjectMapper replaces manual DTO wiring

3.1 introduced stateOptions with DoctrineOrmOptions for separating the API resource from the Doctrine entity. The provider received entity objects and the serializer mapped them to the DTO. This worked, but the mapping was implicit — the serializer used property names to match fields, and anything that did not match was either ignored or caused a normalization error.

4.2 introduces ObjectMapper, a declarative mapping layer between entities and DTOs:

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    public string $title;
    public string $authorName;
}

The #[Map] attribute tells ObjectMapper that BookDto can be populated from BookEntity. Field names are matched by convention; mismatches are declared explicitly at the property level:

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    #[Map(source: 'author.fullName')]
    public string $authorName;
}

The dot notation traverses nested objects. The mapping runs before serialization and replaces the implicit property-matching behavior of the serializer. Unmapped fields raise an error at configuration time, not at runtime.

ObjectMapper works with stateOptions:

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
#[Map(source: BookEntity::class)]
class BookDto {}

The provider fetches BookEntity objects from Doctrine. ObjectMapper converts them to BookDto instances. The serializer writes the DTO. Three distinct steps, each with a clear contract.

TypeInfo integration throughout the stack

Symfony 7.1 introduced the TypeInfo component , a unified type introspection layer that understands union types, intersection types, generic collections, and nullable types across reflection, PHPDoc, and PHP 8.x syntax.

4.2 replaces API Platform’s internal type resolution with TypeInfo. This affects filter schema generation, OpenAPI schema inference, and the serializer’s type coercion. The visible benefit is that types that previously generated incorrect or missing OpenAPI schemas — Collection<int, Book>, list<string>, intersection types — now produce accurate schemas without manual @ApiProperty annotations.

Autoconfigure #[ApiResource]

Before 4.2, adding #[ApiResource] to a class was sufficient for Hugo to discover it only if the class was in a path scanned by API Platform’s resource loader. Outside that path, you needed explicit service configuration.

4.2 hooks into Symfony’s autoconfigure system. Any class tagged with #[ApiResource] is automatically registered as a resource regardless of its location, as long as it is in a directory covered by Symfony’s component scan. No config/services.yaml entry needed.

For Laravel, the equivalent uses Laravel’s service provider autoloading — Eloquent models with #[ApiResource] are picked up automatically without manual registration.

Doctrine ExistsFilter

The ExistsFilter constrains a collection by whether a nullable relation or field is set:

#[ApiFilter(ExistsFilter::class, properties: ['publishedAt'])]
class Book {}

GET /books?exists[publishedAt]=true returns books where publishedAt is not null. exists[publishedAt]=false returns books where it is null.

Strict query parameter validation

3.3 introduced query parameter validation as opt-in. 3.4 deprecated the loose behavior. 4.1 formalizes it with a native strictQueryParameterValidation property on resources and operations: when set to true, unknown query parameters return 400.

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    strictQueryParameterValidation: true,
    parameters: [
        new QueryParameter(key: 'utm_source', required: false, schema: ['type' => 'string']),
        new QueryParameter(key: 'feature_flag', required: false, schema: ['type' => 'string']),
    ]
)]
class Book {}

Declared parameters pass through; undeclared parameters are rejected. To disable strict validation on a specific operation when it is enabled at the resource level, set strictQueryParameterValidation: false on that operation.

x-apiplatform-tag for multi-spec OpenAPI

Large APIs often need multiple OpenAPI specs: one per team, one per API version, one internal and one public. Before 4.1, the generated spec was one document, and splitting it required post-processing or separate API Platform instances.

4.1 adds an x-apiplatform-tag vendor extension (no trailing s). You tag operations with logical group names via the extensionProperties of an OpenAPI Operation object, then request the spec filtered to one or more groups:

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\OpenApi\Factory\OpenApiFactory;
use ApiPlatform\OpenApi\Model\Operation;

#[GetCollection(
    openapi: new Operation(
        extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['public', 'v2']]
    )
)]
class Book {}

Requesting /api/docs.json?filter_tags[]=public returns only the operations tagged public. The full spec is still available without a filter. Groups do not affect the actual API behavior — they are a documentation-layer concern only.

This makes it feasible to maintain one API Platform configuration while serving different spec views to different consumers: a public Swagger UI, a partner portal, and an internal tool that exposes admin endpoints.

HTTP authentication in Swagger UI

Before 4.1, the Swagger UI bundled with API Platform supported Bearer token authentication via its “Authorize” dialog. API Key and HTTP Basic authentication were not wired in.

4.1 adds support for multiple security schemes in the generated OpenAPI document. Security schemes are added by decorating the OpenApiFactory and modifying the components.securitySchemes object of the spec. Each declared scheme then appears in Swagger UI’s “Authorize” dialog and is applied to requests made from the UI. This is a documentation and developer experience improvement — the actual authentication logic in your application is not affected.

GraphQL query depth and complexity limits

GraphQL’s recursive query structure makes it trivial to craft a query that is small in bytes but enormous in execution cost. Without limits, a nested query four levels deep across a many-to-many relation can hit the database hundreds of times.

4.1 adds configurable depth and complexity limits:

api_platform:
    graphql:
        max_query_depth: 10
        max_query_complexity: 100

max_query_depth is the maximum nesting level. max_query_complexity assigns a cost to each field and rejects queries whose total cost exceeds the threshold. Queries that exceed either limit are rejected before execution with a 400 response.

There is no universally correct value for these limits — they depend on your schema shape and expected query patterns. The defaults are intentionally permissive to avoid breaking existing APIs on upgrade. Tightening them is a deliberate configuration choice.

Operation-level output formats

4.0 and earlier configured accepted and returned content types at the API level. 4.1 lets you narrow this per operation:

use ApiPlatform\Metadata\GetCollection;

#[GetCollection(
    outputFormats: ['jsonld' => ['application/ld+json']],
    inputFormats: ['json' => ['application/json']],
)]
class Book {}

Operations that do not specify formats inherit the API-level configuration. This is useful for endpoints that need to return a specific format (a CSV export, a binary stream) without changing the defaults for the rest of the API.

PostgreSQL has had built-in full-text search for over fifteen years. The platform was already on PostgreSQL. The catch: the project uses Doctrine ORM, and Doctrine doesn’t natively know what a tsvector is.

A community library, postgresql-for-doctrine, covers part of that gap. It registers basic DQL functions like TO_TSQUERY, TO_TSVECTOR, and the @@ match operator as separate atomic pieces. The foundation was there. Three things still had to be built on top.

The type Doctrine has never seen

PostgreSQL’s full-text search is built around two types: tsvector (a pre-processed list of normalized tokens) and tsquery (a search expression). You maintain a tsvector column, index it with GIN, and query with the @@ match operator.

Doctrine’s DBAL ships no tsvector type. Declaring #[ORM\Column(type: 'tsvector')] without registering it first throws a UnknownColumnTypeException. The fix is a custom DBAL type:

class TsVector extends Type
{
    final public const string DBAL_TYPE = 'tsvector';

    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return self::DBAL_TYPE;
    }

    public function getName(): string
    {
        return self::DBAL_TYPE;
    }

    public function convertToDatabaseValueSQL(string $sqlExpr, AbstractPlatform $platform): string
    {
        return sprintf("to_tsvector('simple', %s)", $sqlExpr);
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
    {
        if (is_array($value) && isset($value['data'])) {
            return $value['data'];
        }

        return is_string($value) ? $value : null;
    }

    public function getMappedDatabaseTypes(AbstractPlatform $platform): array
    {
        return [self::DBAL_TYPE];
    }
}

The interesting method is convertToDatabaseValueSQL(). Doctrine calls it to wrap the SQL placeholder before the value reaches the database. The written value automatically becomes to_tsvector('simple', ?) at the DBAL boundary with no extra step needed on the calling side.

Register the type in doctrine.yaml, then map the column on the entity:

doctrine:
    dbal:
        types:
            tsvector: App\Doctrine\DBAL\Types\TsVector

#[ORM\Column(type: 'tsvector', nullable: true)]
protected ?string $textSearch = null;

PHP-side, the value is a plain string. The conversion to a proper tsvector happens invisibly at the DBAL layer.

We used the 'simple' dictionary, which tokenizes on whitespace and punctuation without language-specific stemming. The platform handles multiple languages, and French stemming rules would break Spanish. Simple is good enough for phonetics.

Keeping the column current

A tsvector column is derived data: it has to stay in sync with the source fields whenever the entity changes. A Doctrine event listener handles that:

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class MediaTsVectorSubscriber
{
    public function prePersist(PrePersistEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    public function preUpdate(PreUpdateEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    private function updateTextSearch(Media $entity): void
    {
        $entity->setTextSearch(
            sprintf('%s %s', $entity->getTitle(), $entity->getCaption())
        );
    }
}

Before every persist and update, the subscriber concatenates the fields that should be searchable into textSearch. Doctrine flushes the combined string, the DBAL type wraps it in to_tsvector('simple', ...), and PostgreSQL stores the tokenized form.

One subtlety: the PHP-side value is "title caption", not the actual tsvector output. The database shows 'caption' 'title' (sorted tokens), but the entity holds a plain string. That’s expected: the conversion is a DBAL responsibility, not a PHP one. It can be confusing to debug until you remember where the boundary is.

Extending DQL with FTS operators

Doctrine’s DQL covers common SQL operations, but anything PostgreSQL-specific is out of scope. That’s where postgresql-for-doctrine starts: it registers TO_TSQUERY, TO_TSVECTOR, and TSMATCH as individual DQL functions. Writing a full-text query in DQL without it would mean dropping to native SQL entirely.

The library’s functions are atomic, though. Each maps to one SQL call. Expressing a full match check in DQL looks like TSMATCH(o.textSearch, TO_TSQUERY(:term)). Readable enough, but the team wanted something more compact: a single DQL function that encodes both the match operator and the query type, including websearch_to_tsquery, which postgresql-for-doctrine didn’t ship.

The solution is custom DQL functions via FunctionNode. You parse the DQL syntax, then emit SQL. All FTS functions share the same two-argument signature, so an abstract base class handles parsing:

abstract class TsFunction extends FunctionNode
{
    public PathExpression|Node|null $ftsField = null;
    public PathExpression|Node|null $queryString = null;

    public function parse(Parser $parser): void
    {
        $parser->match(TokenType::T_IDENTIFIER);
        $parser->match(TokenType::T_OPEN_PARENTHESIS);
        $this->ftsField = $parser->StringPrimary();
        $parser->match(TokenType::T_COMMA);
        $this->queryString = $parser->StringPrimary();
        $parser->match(TokenType::T_CLOSE_PARENTHESIS);
    }
}

Each concrete class implements getSql() to emit its PostgreSQL expression:

// e.textSearch @@ websearch_to_tsquery('simple', :term)
class TsWebsearchQueryFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return $this->ftsField->dispatch($sqlWalker)
            ." @@ websearch_to_tsquery('simple', "
            .$this->queryString->dispatch($sqlWalker).')';
    }
}

// ts_rank(e.textSearch, to_tsquery(:term)) for relevance ordering
class TsRankFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ts_rank('
            .$this->ftsField->dispatch($sqlWalker)
            .', to_tsquery('.$this->queryString->dispatch($sqlWalker).'))';
    }
}

doctrine:
    orm:
        entity_managers:
            default:
                dql:
                    string_functions:
                        tswebsearchquery: App\Doctrine\ORM\Query\AST\Functions\TsWebsearchQueryFunction
                        tsrank: App\Doctrine\ORM\Query\AST\Functions\TsRankFunction
                        tsquery: App\Doctrine\ORM\Query\AST\Functions\TsQueryFunction
                        tsplainquery: App\Doctrine\ORM\Query\AST\Functions\TsPlainQueryFunction

websearch_to_tsquery is the right choice for user-facing search: spaces become AND, quoted strings become phrases, -word excludes a term. No need to teach users to type interview & president. It was added in PostgreSQL 11. On older versions, plainto_tsquery is the closest equivalent.

The API Platform filter and the GIN index

With the DQL functions registered, the API Platform filter is straightforward. A custom AbstractFilter calls the DQL function directly in the QueryBuilder:

class TextSearchFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = []
    ): void {
        if ('textSearch' !== $property || empty($value)) {
            return;
        }

        $queryBuilder
            ->andWhere('tswebsearchquery(o.textSearch, :value) = true')
            ->setParameter(':value', $value);
    }

    public function getDescription(string $resourceClass): array
    {
        return [];
    }
}

Apply it on the entity alongside the index declaration:

#[ORM\Index(
    columns: ['text_search'],
    name: 'media_text_search_idx_gin',
    options: ['USING' => 'gin (text_search)']
)]
#[ApiFilter(TextSearchFilter::class, properties: ['textSearch' => 'partial'])]
class Media
{
    // ...
    #[ORM\Column(type: 'tsvector', nullable: true)]
    protected ?string $textSearch = null;
}

The USING gin option is non-negotiable. A standard B-tree index on a tsvector column is useless: PostgreSQL can’t use it for @@ queries. GIN (Generalized Inverted Index) works differently: it indexes each token individually, so lookups by any token are O(log n) rather than O(n). Without it, you’ve built a fast-looking system that still does a full table scan.

A GET /media?textSearch=interview+president now hits the GIN index and returns in single-digit milliseconds regardless of table size.

What the split actually looked like

The library covered the low-level atomic functions. The custom code covered the gaps: a tsvector DBAL type the library didn’t provide, convenience DQL wrappers that combined @@ and websearch_to_tsquery into a single call, and the application-specific glue connecting it all to Doctrine’s event system and API Platform. Nothing needed to drop to a native query.

The split is worth noting in general: postgresql-for-doctrine gives you the atomic PostgreSQL building blocks, but you still need to compose them into something the rest of the codebase can use without thinking about it. The FunctionNode pattern and the convertToDatabaseValueSQL() hook are the two extension points that make that composition clean. Both are worth knowing about, regardless of what library you start from.

Property hooks

For twenty years, if you wanted behavior on property access in PHP you had to write getters and setters:

class User {
    private string $_name;
    
    public function getName(): string { return $this->_name; }
    public function setName(string $name): void {
        $this->_name = strtoupper($name);
    }
}

PHP 8.4 adds hooks directly on the property:

class User {
    public string $name {
        set(string $name) {
            $this->name = strtoupper($name);
        }
    }
}

You can define get and set hooks independently. A property with only a get hook is computed on access:

class Circle {
    public float $area {
        get => M_PI * $this->radius ** 2;
    }
    
    public function __construct(public float $radius) {}
}

No backing storage, no explicit getter method, full IDE support. Interfaces can declare properties with hooks too, which means contracts can now specify behavior on property access, something that was flat-out impossible before.

Asymmetric visibility

A lighter option for when you just want public read, private write:

class Version {
    public private(set) string $value = '1.0.0';
}

$v = new Version();
echo $v->value;      // works
$v->value = '2.0';  // Error

Kills the private $x + public getX() pattern for read-only public properties without needing full readonly semantics.

array_find() and friends

$first = array_find($users, fn($u) => $u->isActive());
$any   = array_any($users, fn($u) => $u->isPremium());
$all   = array_all($users, fn($u) => $u->isVerified());

These have been in every other language’s standard library for decades. In PHP, you had to use array_filter() + index access or write a manual loop. They exist now: array_find(), array_find_key(), array_any(), array_all().

Instantiation without extra parentheses

// before
(new MyClass())->method();

// after
new MyClass()->method();

A syntax restriction that was always annoying and never justified is gone.

Lazy objects

Objects whose initialization is deferred until first property access:

$user = $reflector->newLazyProxy(fn() => $repository->find($id));
// No database call yet
$user->name; // Now the proxy initializes

The direct audience is framework ORM and DI container authors, not application developers. But the effect shows up in every app that uses Doctrine or Symfony: lazy loading implemented at the language level rather than through code generation.

PHP 8.4 is a language that barely resembles the PHP 5 most of us started with. Property hooks in particular: they’re not a workaround, they’re a design feature.

#[\Deprecated] for your own code

PHP has emitted deprecation notices for built-in functions for years. 8.4 lets you wire the same mechanism into your own code:

class ApiClient {
    #[\Deprecated(
        message: 'Use fetchJson() instead',
        since: '2.0',
    )]
    public function get(string $url): string { ... }
}

Calling a deprecated method now emits E_USER_DEPRECATED, just like calling mysql_connect(). IDEs pick it up, static analyzers flag it, the error log captures it. Before this, the only option was a @deprecated PHPDoc comment: fine for IDEs, completely invisible to the engine.

BcMath\Number makes arbitrary precision usable

The bcmath functions have been in PHP since forever, but their procedural API makes chaining anything painful. 8.4 adds BcMath\Number, an object wrapper with operator overloading:

$a = new BcMath\Number('10.5');
$b = new BcMath\Number('3.2');

$result = $a + $b;             // BcMath\Number('13.7')
$result = $a * $b - new BcMath\Number('1');
echo $result;                  // 32.6

The +, -, *, /, **, % operators all work. The object is immutable. Scale propagates automatically through operations. Financial calculations, which used to mean chains of bcadd(bcmul(...), ...), now just read like arithmetic.

New procedural functions complete the picture: bcceil(), bcfloor(), bcround(), bcdivmod().

RoundingMode enum replaces PHP_ROUND_* constants

round() has always taken a $mode int from a set of PHP_ROUND_* constants. 8.4 replaces that with a RoundingMode enum with cleaner names and four additional modes that weren’t available before:

round(2.5, mode: RoundingMode::HalfAwayFromZero);  // 3
round(2.5, mode: RoundingMode::HalfTowardsZero);   // 2
round(2.5, mode: RoundingMode::HalfEven);          // 2 (banker's rounding)
round(2.5, mode: RoundingMode::HalfOdd);           // 3

// The four new modes (only available via the enum)
round(2.3, mode: RoundingMode::TowardsZero);       // 2
round(2.7, mode: RoundingMode::AwayFromZero);      // 3
round(2.3, mode: RoundingMode::PositiveInfinity);  // 3
round(2.3, mode: RoundingMode::NegativeInfinity);  // 2

The old PHP_ROUND_* constants still work. The enum is the path forward.

Multibyte string functions that should have existed

mb_trim(), mb_ltrim(), mb_rtrim(): trim functions that respect multibyte character boundaries, not just ASCII whitespace. Also new: mb_ucfirst() and mb_lcfirst() for proper title-casing of multibyte strings.

$s = "\u{200B}hello\u{200B}"; // Zero-width spaces
echo mb_trim($s);              // "hello"
echo mb_ucfirst('über');       // "Über"

These fill gaps that have been sitting there since mbstring was introduced.

request_parse_body() for non-POST requests

PHP automatically parses application/x-www-form-urlencoded and multipart/form-data into $_POST and $_FILES, but only for POST requests. PATCH and PUT requests with the same content types needed manual parsing with file_get_contents('php://input') and custom code.

// Inside a PATCH handler
[$_POST, $_FILES] = request_parse_body();

The function returns a tuple. Same parsing logic PHP uses for POST, now available for any HTTP method.

A new DOM API that follows the spec

The existing DOMDocument API was built on an older DOM level 3 spec with PHP-specific quirks layered on top. 8.4 adds a parallel Dom\ namespace that implements the WHATWG Living Standard:

$doc = Dom\HTMLDocument::createFromString('<p class="lead">Hello</p>');
$p = $doc->querySelector('p');
echo $p->classList;  // "lead"
echo $p->id;         // ""

$doc2 = Dom\HTMLDocument::createFromFile('page.html');

Dom\HTMLDocument parses HTML5 correctly, tag soup included. Dom\XMLDocument handles strict XML. The new classes are strict about types, return proper node types, and expose modern properties like classList, id, className. The old DOMDocument stays, unchanged, for backward compatibility.

PDO gets driver-specific subclasses

PDO::connect() and direct instantiation now return driver-specific subclasses when available:

$pdo = PDO::connect('mysql:host=localhost;dbname=test', 'user', 'pass');
// $pdo is now a Pdo\Mysql instance

$pdo = new Pdo\Pgsql('pgsql:host=localhost;dbname=test', 'user', 'pass');

Each driver subclass (Pdo\Mysql, Pdo\Pgsql, Pdo\Sqlite, Pdo\Firebird, Pdo\Odbc, Pdo\DbLib) can expose driver-specific methods without polluting the base PDO interface. Doctrine, Laravel, and similar ORMs can now type-hint against the specific driver class when they need driver-specific behavior.

OpenSSL gets modern key support

openssl_pkey_new() and related functions now support Curve25519 and Curve448, the modern elliptic curves that have replaced older NIST curves in most security recommendations:

$key = openssl_pkey_new(['curve_name' => 'ed25519', 'private_key_type' => OPENSSL_KEYTYPE_EC]);
$details = openssl_pkey_get_details($key);

x25519 and x448 for key exchange, ed25519 and ed448 for signatures. All four now work with openssl_sign() and openssl_verify().

PCRE: variable-length lookbehind

The bundled PCRE2 library update (10.44) brings variable-length lookbehind assertions, something Perl and Python regex engines had and PHP couldn’t do:

// Match "bar" only when preceded by "foo" or "foooo"
preg_match('/(?<=foo+)bar/', 'foooobar', $matches);

Lookbehind assertions used to require a fixed-width pattern. Now they can match patterns of variable length. The r modifier (PCRE2_EXTRA_CASELESS_RESTRICT) is also new: it prevents mixing ASCII and non-ASCII characters in case-insensitive matches, closing a class of Unicode confusion attacks.

DateTime gets microseconds and timestamp factory

$dt = DateTimeImmutable::createFromTimestamp(1700000000.5);
echo $dt->getMicrosecond(); // 500000

$with_micros = $dt->setMicrosecond(123456);

createFromTimestamp() accepts a float for sub-second precision. getMicrosecond() and setMicrosecond() round out the API for the microsecond component that’s been inside DateTime internally but inaccessible directly.

fpow() for IEEE 754 compliance

pow(0, -2) in PHP has historically returned an implementation-defined value. 8.4 deprecates pow() with a zero base and negative exponent and introduces fpow(), which strictly follows IEEE 754: fpow(0, -2) returns INF, as the standard defines:

echo fpow(2.0, 3.0);   // 8.0
echo fpow(0.0, -1.0);  // INF
echo fpow(-1.0, INF);  // 1.0

Worth knowing in any code doing mathematical computations where IEEE compliance matters.

The cost of bcrypt goes up

The default cost for password_hash() with PASSWORD_BCRYPT went from 10 to 12. This hits any code calling password_hash($pass, PASSWORD_BCRYPT) without an explicit cost. The goal is to keep the default roughly “a few hundred milliseconds on modern hardware” as hardware gets faster.

If you store bcrypt hashes and upgrade to 8.4, existing hashes stay valid: password_verify() reads the cost from the hash itself. New hashes use cost 12. password_needs_rehash() returns true for old hashes if you pass ['cost' => 12], so you can upgrade them on next login.

Deprecations that matter

Implicitly nullable parameters are deprecated. If a parameter has a default of null, the type has to say so explicitly:

// Deprecated in 8.4
function foo(string $s = null) {}

// Correct
function foo(?string $s = null) {}
function foo(string|null $s = null) {}

trigger_error() with E_USER_ERROR is deprecated: replace it with an exception or exit(). The E_USER_ERROR level was always an awkward hybrid between a recoverable error and a fatal one, and nobody was sure which.

lcg_value() is deprecated too. Use Random\Randomizer::getFloat() instead. The LCG generator had poor randomness properties and no seeding control.

Laravel as a first-class target

Since its first release, API Platform was built on Symfony. The HTTP layer, metadata, serializer, and Doctrine bridge all assumed Symfony’s container, event dispatcher, and request lifecycle. Laravel users could run API Platform through a thin adapter, but filters, security, and Doctrine integration did not work on Eloquent.

4.0 ships a dedicated Laravel bridge. It maps API Platform’s state layer onto Laravel’s request lifecycle, integrates with Eloquent models directly, and wires into Laravel’s authorization system:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(
    operations: [new GetCollection(), new Get()]
)]
class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

Authorization uses Laravel policies and gates rather than Symfony’s security voters. Operations expose a dedicated policy parameter that maps to a policy method name:

#[Get(policy: 'view')]
class Book extends Model {}

API Platform maps the policy value to Laravel’s Gate::allows() with the model instance. Policies can also be auto-detected: if a model has a registered policy class, API Platform infers the correct method (view, viewAny, create, update, delete) based on the operation type. Filters for Eloquent collections cover the same ground as their Doctrine counterparts: PartialSearchFilter, EqualsFilter, RangeFilter, OrderFilter, DateFilter, and search variants (StartSearchFilter, EndSearchFilter). Pagination, sorting, and validation work through Laravel’s native mechanisms.

This is not a compatibility shim. The Laravel bridge is maintained alongside the Symfony bridge and is covered by the same test suite. Projects using either framework get the same resource definition API.

PUT removed from default operations

Since API Platform 1.0, #[ApiResource] without an explicit operations array generated CRUD operations including PUT. The PUT handler updated existing resources and, after 3.1, could also create them via allowCreate: true.

4.0 removes PUT from the default set. #[ApiResource] now generates GET, POST, PATCH, and DELETE. To use PUT, you must declare it explicitly:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Put;

#[ApiResource(
    operations: [
        // ... other operations
        new Put(),
    ]
)]
class Book {}

The motivation is semantic clarity. PATCH replaces PUT for most partial-update use cases. PUT’s semantics — replace the entire resource representation — are rarely what an API actually implements, but the default made it appear in every API unless actively removed. Making PUT opt-in aligns the defaults with how HTTP semantics are actually used in practice.

PHP 8.2 minimum

4.0 drops PHP 8.0 and 8.1. PHP 8.2 is the new minimum. The readonly class syntax, AllowDynamicProperties, and DNF¹ types introduced in 8.2 are available throughout the codebase. No specific 8.2 feature is load-bearing for 4.0 — the version bump is primarily about dropping the older maintenance burden.

Symfony 6.4+ and Doctrine ORM 2.17+ minimum

On the Symfony side, 4.0 requires Symfony 6.4 or 7.x and Doctrine ORM 2.17 or 3.x. Both were already supported in 3.4. The migration from 3.4 to 4.0 on the Symfony track is: resolve 3.4 deprecations, verify you are on Symfony 6.4+ and ORM 2.17+, then upgrade. No new migration work is required if those are already in place.

What 4.0 is not

4.0 is not a new architecture. The state providers, processors, and resource metadata model from 3.0 are unchanged. The Laravel bridge adds a new execution context but does not change how resources or operations are declared. The split is intentional: if 3.0 was the “what”, 4.0 is the “where”.

BackedEnum as API resources

Since PHP 8.1, BackedEnum classes have a fixed set of cases with string or integer backing values. API Platform 3.4 lets you put #[ApiResource] directly on a BackedEnum:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [new GetCollection()]
)]
enum BookStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

A GET /book_statuses endpoint returns the list of cases. Each case is serialized with its name and value. The endpoint is read-only — enums are immutable by nature.

This is mostly useful for frontend consumers that want a machine-readable list of valid values without hardcoding them. The alternative was a custom controller or a dedicated DTO resource listing the enum values manually.

BackedEnumFilter

The companion to enum resources is BackedEnumFilter, a new filter for Doctrine collections that constrains a query by a BackedEnum property:

use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
#[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
class Book
{
    public BookStatus $status;
}

GET /books?status=published filters the collection to books where status equals BookStatus::Published. Invalid enum values return a 400 response. Before this filter, you had to either write a custom filter or use SearchFilter and validate the value manually.

Security expressions on parameters

3.3 added security to links and properties. 3.4 extends this to query parameters. A parameter can declare a security expression that controls whether it is accepted at all:

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    parameters: [
        new QueryParameter(
            key: 'includeDeleted',
            security: "is_granted('ROLE_ADMIN')"
        ),
    ]
)]
class Book {}

When the security expression is false, the parameter is rejected with a 403, not silently ignored. This is more explicit than checking the user’s role inside the provider after receiving the parameter.

DBAL 4 support added

3.4 adds support for Doctrine DBAL 4, which ships with type system changes that affect how custom types and platform-specific SQL work. The Doctrine Orm filters and query extensions in API Platform were updated to work with the new DBAL 4 type API.

Both DBAL 3 (^3.4.0) and DBAL 4 are supported simultaneously in 3.4. This is the release to upgrade to if you want to adopt DBAL 4 while staying on a stable API Platform 3.x branch.

Query parameter validator deprecated

3.3 added the strict query parameter validator as an opt-in. 3.4 deprecates the old behavior (unknown parameters silently ignored) in preparation for making strict validation the default in 4.0. Projects that relied on pass-through query parameters have one more release to declare them explicitly.

Last stop before 4.0

3.4 is the last 3.x release with new features. Anything 3.x that was deprecated by 3.4 is gone in 4.0. The migration path from 3.4 to 4.0 is intentionally short: resolve the deprecations, then upgrade.

Declarative header configuration

Before 3.3, setting custom response headers required either a custom processor that modified the response object or a Symfony event listener on kernel.response. Both approaches worked but lived outside the resource definition.

3.3 adds a parameters parameter to operation metadata:

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\HeaderParameter;

#[Get(
    parameters: [
        'X-Custom-Header' => new HeaderParameter(description: 'A custom header'),
    ]
)]

For headers that vary per response (like Cache-Control with a computed max-age), the processor can still set them directly on the response. The headers parameter is primarily for documenting expected headers in the OpenAPI spec and for static header values.

Link security on sub-resources

When a resource exposes links to related resources, those links appear in the serialized output regardless of whether the current user can access the linked resource. This creates a disclosure problem: a user who can read a book but not its author profile still sees the author’s URI in the response.

3.3 adds security expressions to the Link descriptor:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Link;

#[ApiResource]
#[Get]
class Book
{
    #[Link(
        toClass: Author::class,
        security: "is_granted('ROLE_ADMIN')"
    )]
    public Author $author;
}

The link is omitted from the response when the security expression evaluates to false. The linked resource itself is not affected — only whether the current response includes the reference to it.

ApiProperty::security

The same security expression mechanism is available at the property level via ApiProperty::security. This lets you hide individual fields based on the current user without writing a custom normalizer:

use ApiPlatform\Metadata\ApiProperty;

class Book
{
    #[ApiProperty(security: "is_granted('ROLE_ADMIN')")]
    public string $internalNote;
}

The property is excluded from serialization when the expression is false. This is cleaner than a normalizer for the common case of role-gated fields.

OpenAPI webhooks

OpenAPI 3.1 supports webhooks — outbound HTTP calls that your API makes to registered listeners — in the spec document itself. Before 3.3, there was no way to document these in API Platform’s generated spec.

3.3 adds a Webhook class you pass to the openapi parameter of an operation. Declare a dedicated PHP class with #[ApiResource] and use Webhook on each operation to describe the outbound call shape:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Attributes\Webhook;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\PathItem;

#[ApiResource(
    operations: [
        new Post(
            openapi: new Webhook(
                name: 'bookCreated',
                pathItem: new PathItem(
                    post: new Operation(summary: 'A book was created'),
                ),
            )
        ),
    ]
)]
class BookWebhook {}

The webhook definitions appear in the generated spec under the webhooks key alongside regular paths. Swagger UI renders them in a separate section.

Swagger UI deep linking

Swagger UI supports deep linking — bookmarkable URLs that open directly to a specific operation in the interface. Before 3.3, the API Platform integration did not enable this. 3.3 turns on the Swagger UI deepLinking option, configurable via swagger_ui_extra_configuration:

api_platform:
    openapi:
        swagger_ui_extra_configuration:
            deepLinking: true

With this enabled, the URL fragment updates as you navigate the UI, and pasting or sharing the URL opens the same operation. Useful when writing docs that link directly to a specific endpoint.

Strict query parameter validation

3.3 tightens the query parameter validator: parameters not declared on the operation now return a 400 response instead of being silently ignored. This behavior is opt-in:

api_platform:
    validator:
        query_parameter_validation: true

The intent is to catch typos and API misuse early. If you rely on pass-through query parameters for custom logic (logging, feature flags), you need to declare them explicitly on the operation before enabling this.

Typed class constants

Class constants have been untyped since their introduction. PHP 8.3 fixes that:

interface HasVersion {
    const string VERSION;
}

class App implements HasVersion {
    const string VERSION = '1.0.0';
}

Without typed constants, an interface constant could be overridden with a completely different type in an implementing class and nothing would complain. Typed constants close that gap, and on interface-driven codebases the impact is immediate.

Dynamic class constant access

A gap that required a workaround since constants were introduced:

$name = 'STATUS';
echo MyClass::{$name}; // now works

Before, accessing a constant with a dynamic name meant calling constant('MyClass::STATUS'). The new syntax is consistent with how PHP already handles variable variables and dynamic method calls.

readonly can now be amended in clone

A specific but genuinely annoying limitation of 8.1 readonly: you couldn’t clone an object and change a readonly property. 8.3 adds the ability to reinitialize readonly properties during cloning, which makes immutable value objects usable in a lot more patterns.

json_validate()

if (json_validate($string)) {
    $data = json_decode($string);
}

Before 8.3, the only way to validate a JSON string was to decode it and check for errors. json_validate() checks without allocating the decoded structure, which matters when you only need to know if the string is valid JSON, not what’s in it.

Randomizer improvements

getBytesFromString() generates a random string composed only of characters from a given set:

$rng = new Random\Randomizer();
$token = $rng->getBytesFromString('abcdefghijklmnopqrstuvwxyz0123456789', 32);

The previous approach: str_split, array_map, random selection, implode. It worked, but it was longer than it had any right to be.

8.3 is for the teams that adopt PHP versions quickly and want the incremental improvements. The typed constants alone are worth it on any codebase with interface constants.

#[\Override] makes inheritance explicit

Before 8.3, nothing stopped you from writing a method you thought was overriding a parent’s, when you had a typo in the name or the parent had quietly removed it. Silent bugs, zero feedback from the engine.

class Cache {
    #[\Override]
    public function get(string $key): mixed {
        // Engine verifies this method exists in a parent or interface
    }
}

If the method doesn’t exist in any parent class or implemented interface, PHP throws an error. Same concept as Java’s @Override or C#’s override, finally in PHP.

final on trait methods

Traits have always had rough edges in PHP’s OOP model. One specific problem: a class using a trait could override any of its methods, undermining whatever guarantees the trait was trying to provide. 8.3 lets the trait itself mark a method as final:

trait Singleton {
    final public static function getInstance(): static {
        // ...
    }
}

Now a class using the trait cannot override getInstance(). The guarantee holds.

Anonymous classes can be readonly

PHP 8.1 brought readonly classes. Anonymous classes were left out for some reason. 8.3 fixes that:

$point = new readonly class(3, 4) {
    public function __construct(
        public float $x,
        public float $y,
    ) {}
};

Handy when you need a throwaway immutable value object without the ceremony of naming it.

Static variable initializers accept expressions

A small but long-standing restriction: static variable initializers only accepted constant expressions, no function calls. 8.3 drops that constraint:

function connection(): PDO {
    static $pdo = new PDO(getenv('DATABASE_URL'));
    return $pdo;
}

The initializer runs once on first call, the static variable persists. Achievable with a null-check before, this is just cleaner.

mb_str_pad() finally exists

str_pad() has always been byte-aware, not character-aware. For multibyte strings (Arabic, Japanese, accented characters) it produced wrong output. 8.3 finally adds the multibyte variant:

$padded = mb_str_pad('日本', 10, '*', STR_PAD_BOTH);

The function respects character boundaries, not byte counts.

str_increment() and str_decrement()

PHP’s ++ operator on strings has a history of quirks: it increments letter sequences ('a' → 'b', 'z' → 'aa'), but -- never worked symmetrically. The behavior was surprising enough that 8.3 deprecates ++/-- on non-alphanumeric strings and introduces explicit functions:

echo str_increment('a');  // b
echo str_increment('Az'); // Ba
echo str_decrement('b');  // a
echo str_decrement('Ba'); // Az

The functions make the intent obvious and the behavior predictable.

Random\Randomizer gets float support

8.3 fills in the float side of the Randomizer API:

$rng = new Random\Randomizer();

// A float in [0.0, 1.0)
$f = $rng->nextFloat();

// A float in a specific range with controlled boundary inclusion
$f = $rng->getFloat(1.5, 3.5, Random\IntervalBoundary::ClosedOpen);

IntervalBoundary is a new enum with four values: ClosedOpen, ClosedClosed, OpenClosed, OpenOpen. This matters for statistical correctness: the naive approach of rand() / getrandmax() doesn’t produce a uniform distribution over floats.

The Date exception hierarchy

Date/time errors in PHP used to throw generic exceptions with no way to tell “malformed string” from “invalid timezone” without parsing the message yourself. 8.3 adds a proper hierarchy:

try {
    new DateTimeImmutable('not a date');
} catch (DateMalformedStringException $e) {
    // specifically a parsing failure
} catch (DateException $e) {
    // other date-related errors
}

The full tree: DateError (engine-level), DateException (base), with specific subclasses for invalid timezone, malformed interval string, malformed period string, and malformed date string.

gc_status() tells you more

gc_status() now returns eight additional fields: running, protected, full, buffer_size, and timing breakdowns (application_time, collector_time, destructor_time, free_time). If you’re profiling memory pressure or GC pauses, this data was previously unavailable without pulling in an extension.

strrchr() grows a direction argument

strrchr() (find the last occurrence of a character, return from there to end) now accepts a $before_needle boolean, matching the API of strstr():

$path = '/var/www/html/index.php';
echo strrchr($path, '/', before_needle: true);  // /var/www/html
echo strrchr($path, '/');                        // /index.php

A function that’s been in PHP since 1994, finally consistent with its sibling.

Deprecations worth noting

get_class() and get_parent_class() without arguments now emit deprecation notices. The argumentless forms relied on implicit $this context, which was easy to misread. Pass the object explicitly.

assert_options() and the ASSERT_* constants are deprecated in favor of the zend.assertions INI directive, which is the right tool for controlling assertion behavior across environments.

The ++/-- operators on empty strings and non-numeric non-alphanumeric strings now emit deprecation warnings. The behavior was undefined territory. 8.3 starts the migration toward defined behavior in 9.0.

Stack overflow protection

Two new INI directives: zend.max_allowed_stack_size sets a hard limit on PHP’s stack depth, and zend.reserved_stack_size sets aside a buffer for cleanup after a limit is hit. Before 8.3, deeply recursive code could just crash at the OS level. Now PHP catches it and throws an Error with a useful message.

Errors as resources

Before 3.2, error handling was outside the resource model. Exceptions were caught by a Symfony event listener and converted to a response, with limited control over the shape of the output.

3.2 makes errors first-class ApiResource classes compliant with RFC 9457 (Problem Details for HTTP APIs). The built-in error class is ApiPlatform\ApiResource\Error, and you can create your own:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ApiResource]
#[ErrorResource]
class BookNotFoundError extends \RuntimeException implements ProblemExceptionInterface
{
    public function __construct(private readonly string $bookId)
    {
        parent::__construct("Book $bookId not found");
    }

    public function getType(): string
    {
        return '/errors/book-not-found';
    }
}

When this exception is thrown anywhere in the state layer, API Platform catches it, serializes it as a Problem Detail response, and generates a proper OpenAPI schema for it. The error type, title, detail, and status are all part of the resource contract — not hardcoded strings in a listener.

Sub-resources without the workarounds

Sub-resources existed in 2.x but were removed in 3.0 because they were tightly coupled to the old data provider model and couldn’t be cleanly mapped to the new operation-first architecture. 3.2 reintroduces them in a way that fits.

A sub-resource is a resource accessible through a parent resource’s URI. In 3.2, it is declared directly on the child resource using uriTemplate:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: [
                'bookId' => new Link(fromClass: Book::class),
            ],
        ),
    ]
)]
class Review
{
    // ...
}

The Link descriptor makes the relationship explicit. The provider receives bookId in $uriVariables and can use it to scope the query. No magic inference, no implicit joins — the URI structure and the data access are both declared.

canonical_uri_template for multiple access paths

When a resource is accessible through multiple URIs (a direct endpoint and a sub-resource endpoint), OpenAPI needs to know which URI is canonical for $ref links. 3.2 uses the top-level uriTemplate on ApiResource as the default canonical URI. For finer control, the canonical_uri_template option can be passed via extraProperties on any operation to override it explicitly.

#[ApiResource(
    uriTemplate: '/reviews/{id}',
    operations: [
        new Get(),
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: ['bookId' => new Link(fromClass: Book::class)],
        ),
    ]
)]
class Review {}

The generated OpenAPI spec uses the canonical URI for schema references, keeping the document consistent when a resource appears under several paths.

Union and intersection types

3.2 adds support for PHP union and intersection types in the metadata layer. A property declared as Book|Magazine generates a proper oneOf schema in OpenAPI. This was previously unsupported — you had to fall back to an untyped mixed or annotate the property manually.

Event listeners made optional

The last compatibility shim from 2.x was the ability to use Symfony event listeners on the kernel.request and kernel.view events to intercept API Platform’s data flow. 3.2 does not remove them, but introduces an opt-out: setting event_listeners_backward_compatibility_layer: false in the API Platform configuration disables the event-based hooks entirely. The replacement is a provider or processor decorated with another provider or processor. The event-based hook was stateful, order-dependent, and bypassed the operation context entirely. Decorated providers get the operation object and can call the inner provider when ready.

The state model is now complete

3.0 introduced the architecture. 3.1 added resource/entity separation. 3.2 closes the remaining gaps: errors have a resource contract, sub-resources have a clean declaration model, and the state layer now covers every extension point that event listeners once handled. The 2.x shims still exist, but opting out of them is now a single config flag.

The resource/entity split

In 2.x, API Platform worked best when your API resource and your persistence model were the same class. Using a DTO as the API surface was possible through the Input/Output DTO system, but that system was removed in 3.0 — it complicated the state model without enough benefit.

3.1 replaces it with something cleaner. The stateOptions parameter on an operation accepts a DoctrineOrmOptions object that points to a different entity:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\State\Options;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
class BookDto
{
    public string $title;
    public string $author;
}

The provider receives the BookEntity objects from Doctrine and the serialization layer maps them to BookDto. The Doctrine filters, pagination, and ordering all work on BookEntity. The API surface exposes BookDto. The two can evolve independently.

This matters more than it looks. Your persistence model accumulates internal fields, relations, and columns that have no business being in your API. Before 3.1, you either exposed them anyway or built an elaborate normalizer to hide them. Now you declare what the API looks like as a separate class and let the framework handle the mapping.

PUT that follows the spec

Since version 1.0, API Platform’s PUT handler updated existing resources. Creating a resource via PUT — which the HTTP spec explicitly allows — was not supported. 3.1 adds uriTemplate-based creation:

#[Put(
    uriTemplate: '/books/{id}',
    allowCreate: true,
)]

With allowCreate: true, a PUT to a URI that does not exist creates the resource instead of returning 404. The identifier comes from the URI, not from the request body. This is what RFC 9110 describes for PUT: “If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response.”

It is a small flag, but it opens API Platform to use cases — idempotent resource creation, client-assigned identifiers — that previously required a custom controller.

Denormalization errors collected, not thrown

Before 3.1, deserialization errors stopped at the first problem. Send a request body with five invalid fields and get an error about the first one. Fix it, send again, find the second. Repeat five times.

3.1 adds a collect_denormalization_errors option on the operation that changes this behavior:

#[Post(collectDenormalizationErrors: true)]

With this enabled, API Platform catches all type errors and constraint violations during deserialization and returns them as a structured list in the response, formatted the same way as validation errors. One round-trip, full picture.

ApiResource::openapi replaces openapiContext

The old openapiContext parameter accepted a raw array that was merged into the generated OpenAPI schema — convenient but untyped. 3.1 introduces a first-class openapi parameter that accepts an OpenApiOperation object:

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;

#[Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'Create a book',
            required: true,
        ),
        summary: 'Create a new book entry',
    )
)]

The old openapiContext array still works but is deprecated. The new approach is typed, IDE-friendly, and validates at construction time rather than at schema generation time. PHP 8.1 backed enums also get proper OpenAPI schema generation in 3.1 — a field typed as a backed enum produces a schema with enum values and the correct type, without any annotation.

The pattern is clear

3.0 established the architecture. 3.1 shows what that architecture enables: clean resource/entity separation without a parallel DTO system, RFC-correct HTTP semantics, better error reporting. None of these would have been as clean to implement on the 2.x data provider model. The features in 3.1 are the first proof that the rewrite was the right call.

Dynamic properties deprecated

PHP has always allowed adding properties to objects that weren’t declared in the class:

class User {}
$user = new User();
$user->name = 'Alice'; // no declaration, no error... until now

In 8.2, this triggers a deprecation notice. In PHP 9.0 it becomes a fatal error. The grace period exists, but the migration clock is running.

The reasoning is solid: dynamic properties are a classic source of typos that silently pass (write $user->nmae and PHP just creates a new property instead of complaining). Explicit declarations make the class contract clear and make tooling actually useful.

Migration is mostly mechanical: declare the properties, or slap #[AllowDynamicProperties] on legacy classes you can’t touch yet.

Readonly classes

8.1 added readonly for individual properties. 8.2 adds it to the class declaration itself:

readonly class Point {
    public function __construct(
        public float $x,
        public float $y,
        public float $z,
    ) {}
}

All promoted and explicitly declared properties become readonly automatically. Value objects (coordinates, money amounts, identifiers) are the obvious target. The syntax is clean and the intent reads clearly.

One constraint: readonly classes can’t have non-typed properties, which were already a bad idea with readonly anyway.

DNF types

Disjunctive Normal Form types let you combine union and intersection types:

function process(Countable&Iterator|null $collection): void { ... }

(Countable&Iterator)|null: an object that implements both interfaces, or null. This covers type expressions that 8.0 union types and 8.1 intersection types each got partway to but couldn’t represent together.

The Random extension

A dedicated Random extension replaces the scattered rand(), mt_rand(), random_int() functions with an object-oriented API:

$rng = new Random\Randomizer();
$rng->getInt(1, 100);
$rng->shuffleArray($items);

Engines are swappable: Mersenne Twister, PCG64, Xoshiro256StarStar, or CryptoSafeEngine for security-sensitive contexts. Same code, seeded deterministic engine in tests, cryptographic engine in production.

8.2 is a consolidation release. The dynamic properties deprecation is the one decision you need to make now.

null, false, and true as standalone types

PHP has had nullable types since 7.1 and union types since 8.0, but null as a standalone type declaration wasn’t valid. 8.2 fixes that:

function alwaysNull(): null {
    return null;
}

function disabled(): false {
    return false;
}

function enabled(): true {
    return true;
}

false and true as standalone types are useful when you need to be precise about what a function can actually return. It’s narrow but correct: a function that returns false on failure and a string on success should declare string|false, and now both sides of that union are real types.

Constants in traits

Traits could hold properties and methods. Constants were the odd gap. 8.2 closes it:

trait Timestamps {
    public const DATE_FORMAT = 'Y-m-d H:i:s';

    public function formatCreatedAt(): string {
        return $this->createdAt->format(self::DATE_FORMAT);
    }
}

class Article {
    use Timestamps;
}

echo Article::DATE_FORMAT; // 'Y-m-d H:i:s'

The constant belongs to the class that uses the trait, not the trait itself, so you can’t access Timestamps::DATE_FORMAT directly. Expected scoping behavior, consistent with how trait methods already work.

#[SensitiveParameter]

Stack traces have always been a liability: function arguments get logged verbatim, which means passwords and tokens end up in your error logs and monitoring dashboards. 8.2 adds an attribute to stop that:

function authenticate(
    string $user,
    #[\SensitiveParameter] string $password,
): bool {
    // if this throws, the stack trace shows:
    // authenticate('alice', Object(SensitiveParameterValue))
    return hash('sha256', $password) === getStoredHash($user);
}

The parameter value in the trace gets replaced with a SensitiveParameterValue object. One attribute, zero excuses not to add it to every function that touches credentials.

Deprecated string interpolation syntaxes

Two ways to interpolate expressions inside strings are deprecated in 8.2:

$name = 'world';

// These are deprecated:
echo "Hello ${name}";       // use "$name" or "{$name}"
echo "Hello ${getName()}";  // use "{$this->getName()}"

The ${...} forms created ambiguity between variable variables and expressions. The cleaner {$...} syntax has always been there and does the same thing. This is mostly a search-and-replace job in codebases that picked up the deprecated forms out of habit.

utf8_encode() and utf8_decode() deprecated

These two functions are deprecated in 8.2 and gone in 9.0. Their behavior was always narrower than the names suggested: utf8_encode() converts ISO-8859-1 to UTF-8, not “any encoding to UTF-8.”

// Deprecated in 8.2:
$utf8 = utf8_encode($latin1String);

// Use instead:
$utf8 = mb_convert_encoding($latin1String, 'UTF-8', 'ISO-8859-1');

mb_convert_encoding() or iconv() handle the general case. If you’re actually dealing with Latin-1 input, the replacement is a direct swap.

Locale-independent string functions

Several string functions silently varied behavior based on the system locale, producing different results in production versus a dev container. In 8.2, they’re locale-independent and ASCII-only:

// strtolower, strtoupper, stristr, stripos, strripos,
// lcfirst, ucfirst, ucwords, str_ireplace now do ASCII case conversion only.
// For locale-aware behavior, use mb_* equivalents:
$lowered = mb_strtolower($text, 'UTF-8');

This is a correctness fix. If your code was relying on locale-sensitive behavior from these functions, it was already broken on systems with different locale configurations. 8.2 makes the behavior deterministic everywhere, which is what you actually wanted.

str_split() on empty string

A quiet behavior change worth noting:

// PHP 8.1: str_split('') === ['']
// PHP 8.2: str_split('') === []

The new behavior makes more sense: splitting nothing produces nothing. If you’re checking count(str_split($input)), an empty input no longer produces a count of 1.

The old model had a conceptual leak. DataProviderInterface and DataPersisterInterface were called for every HTTP request, but the provider received the operation context as a hint — not as a contract. A collection provider and an item provider were separate interfaces, but both lived in the same mental bucket: “things that return data.” The HTTP layer knew what was being requested; the provider had to reconstruct that knowledge from context clues passed in the $context array.

3.0 inverts the model. Operations are declared first. Data access is wired to operations.

State providers replaced data providers

The old DataProviderInterface is gone. The replacement is ProviderInterface:

use ApiPlatform\State\ProviderInterface;
use ApiPlatform\Metadata\Operation;

class BookProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->repository->findAll();
        }

        return $this->repository->find($uriVariables['id']);
    }
}

The difference is not syntactic. In 2.x, you registered a provider and API Platform called it for any matching resource. In 3.0, you bind a provider to a specific operation. The provider no longer guesses what triggered it — the operation object it receives is the contract.

State processors replaced data persisters

DataPersisterInterface had the same problem on the write side: one class handling create, update, and delete, distinguishing them by inspecting the HTTP method or the object state. ProcessorInterface receives the operation as a typed argument:

use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\Metadata\Operation;

class BookProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        $this->entityManager->persist($data);
        $this->entityManager->flush();

        return $data;
    }
}

More usefully: you can bind a different processor per operation. The delete operation gets one that removes. The post operation gets one that validates and stores. No switch statement, no method inspection, no shared class trying to be three things at once.

Operations declared explicitly in PHP 8.1 attributes

The other half of 3.0 is the metadata layer. Doctrine annotations are replaced by PHP 8.1 native attributes, and each operation is declared explicitly on the resource class:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new GetCollection(provider: BookProvider::class),
        new Get(provider: BookProvider::class),
        new Post(processor: BookProcessor::class),
    ]
)]
class Book
{
    // ...
}

This is more verbose than @ApiResource with magic defaults. It is also explicit. You know exactly what HTTP operations exist for this resource, what retrieves data, what writes it, and where the logic lives. The defaults of 2.x were convenient until the day you needed to override one and couldn’t figure out which service to decorate without reading the source.

PHP 8.1 was not a coincidence

The hard requirement for PHP 8.1 is load-bearing. First-class callables make filter registration cleaner. The immutability of operation metadata is enforced through cloning patterns (withX() methods) that rely on named arguments and promoted constructor properties — PHP 8.0 foundations the architecture builds on heavily.

More practically: the full expression of 3.0’s architecture — typed operations, operation-scoped providers, explicit metadata — needed 8.1 to not feel like workarounds. Dropping PHP 7.x and 8.0 was not a housekeeping decision.

The migration is real work

The jump from 2.x to 3.0 is not a version bump. Every DataProvider becomes a ProviderInterface. Every DataPersister becomes a ProcessorInterface. Annotations become attributes. Custom normalizers and filters may need restructuring. The upgrade guide documents all of it, but “documented” does not mean “fast.”

What you get on the other side is an architecture that scales without the ambient complexity of 2.x: no more guessing which interface to implement, no more $this->supports() chains, no more invisible defaults quietly overriding explicit config.

3.0 is the API Platform you’d design from scratch knowing what you know after years of 2.x. The price is the migration. The version number is honest about that.

Enums

This is the one that changes codebases the moment you upgrade. Before 8.1, PHP enumerations were either class constants, strings, or integers with nothing enforcing them:

// before: nothing stops Status::INVALID from being passed
const ACTIVE = 'active';
const INACTIVE = 'inactive';

// after
enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

function activate(Status $status): void { ... }

PHP enums are objects, not scalars. They support methods, interfaces, and constants. Backed enums (with a string or int value) serialize cleanly and map to database columns naturally. Pure enums (no backing type) enforce domain concepts without worrying about serialization.

The immediate effect: every status field, every finite set of states in every codebase I maintain became an enum candidate. The type system finally has a native way to express the thing every PHP project has been faking for years.

Fibers

Fibers are a cooperative concurrency primitive: you can pause and resume execution of a function, yielding control without threads.

$fiber = new Fiber(function(): void {
    $value = Fiber::suspend('first');
    echo "Resumed with: {$value}\n";
});

$result = $fiber->start();    // 'first'
$fiber->resume('hello');      // "Resumed with: hello"

Fibers are the foundation async libraries like ReactPHP and Amp have needed from the runtime for a while. For most application developers the direct API matters less than the libraries built on top of it, but understanding fibers explains what those libraries are doing underneath.

:pencil2: Readonly properties

8.0 brought constructor promotion. 8.1 adds readonly:

class User {
    public function __construct(
        public readonly int $id,
        public readonly string $name,
    ) {}
}

A readonly property can be written exactly once, during initialization. After that, any write throws an Error. Combined with constructor promotion, value objects and DTOs become concise and actually mean what they say.

First-class callable syntax

$fn = strlen(...);
$fn = $this->process(...);
$fn = MyClass::create(...);

... after a callable creates a Closure without Closure::fromCallable() boilerplate. Useful when passing methods as callbacks.

8.1 is precise. Enums alone justify the upgrade.

Intersection types

Union types landed in 8.0. Intersection types follow in 8.1. Where a union says “one of these”, an intersection says “all of these”:

function process(Countable&Iterator $collection): void {
    foreach ($collection as $item) { /* ... */ }
    echo count($collection);
}

One constraint: intersection types can’t be mixed with union types in the same declaration (that arrives in 8.2 as DNF types). But this already unlocks precise type-checking for objects that must satisfy multiple interfaces at once, a pattern frameworks use constantly that had to stay untyped until now.

The never return type

A function that never returns (it always throws or exits) now has a type to say so:

function redirect(string $url): never {
    header("Location: {$url}");
    exit();
}

function fail(string $message): never {
    throw new \RuntimeException($message);
}

The practical benefit: static analyzers can prove that code after a never function is unreachable, and callers know there’s no return value to handle. Before this, it lived in docblocks with no enforcement.

Final class constants

Before 8.1, any subclass could quietly override a parent’s class constant. Now you can put a stop to that:

class Base {
    final public const VERSION = '1.0';
}

class Child extends Base {
    // Fatal error: Cannot override final constant Base::VERSION
    public const VERSION = '2.0';
}

Relatedly, interface constants are now overridable by implementing classes by default. A separate behavior fix that had been inconsistent since interfaces were introduced.

new in initializers

Default parameter values used to be restricted to scalars and arrays. 8.1 drops that restriction:

class Logger {
    public function __construct(
        private Handler $handler = new NullHandler(),
    ) {}
}

function createUser(
    Validator $validator = new DefaultValidator(),
): User { /* ... */ }

Same goes for attribute arguments and static variable initializers. Which means dependency injection with sensible defaults no longer needs a null check and lazy instantiation inside the method body.

Array unpacking with string keys

Array unpacking via the spread operator only worked with integer-keyed arrays before 8.1. String keys work now too:

$defaults = ['color' => 'red', 'size' => 'M'];
$custom = ['size' => 'L', 'weight' => '200g'];

$merged = [...$defaults, ...$custom];
// ['color' => 'red', 'size' => 'L', 'weight' => '200g']

Later keys override earlier ones. Same behavior as array_merge(), but expressed inline. Performance difference is marginal; readability difference is not.

fsync and fdatasync

Two functions that had no good reason to be missing from a filesystem-oriented language:

$fp = fopen('/tmp/important.dat', 'w');
fwrite($fp, $data);
fsync($fp);   // flush OS buffers to physical storage
fclose($fp);

fdatasync() does the same but skips metadata sync when you only care about the data being durable. Both return false on failure. If you’re writing anything that needs crash safety, you needed these.

Passing null to non-nullable built-in parameters

A quieter but consequential change: built-in functions that accept strings, integers, etc. have always silently swallowed null and coerced it. In 8.1, that starts emitting a deprecation notice.

str_contains("foobar", null);
// Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated

This aligns built-in functions with user-defined functions, which already refused nullable arguments for non-nullable parameters. PHP 9.0 turns this into a hard error. If you’re passing null into string functions, now is a better time to fix it than during a production incident.

MySQLi exceptions by default

Before 8.1, MySQLi failed silently unless you explicitly called mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT). That’s now the default:

// This throws \mysqli_sql_exception on connection failure in 8.1
// Previously returned false and set an error you had to check manually
$connection = new mysqli('localhost', 'user', 'wrong_password', 'db');

Every codebase that catches MySQLi errors by checking return values needs to be reviewed. The silent failures that caused hard-to-diagnose bugs now throw exceptions, which is the right behavior, just potentially surprising if you hit it mid-upgrade.

JIT

The Just-In-Time compiler was the headline announcement. The reality in production is more nuanced: for typical web apps (database queries, HTTP calls, template rendering) the gains are modest, because those workloads are I/O bound, not compute bound. Where JIT actually shines is CPU-intensive code: image manipulation, data transformation, mathematical computation.

For most web apps, the performance improvement comes from the overall engine work in 8.0, not JIT specifically. Still worth enabling though: it costs nothing on I/O-bound work.

Match expressions

switch has three problems: it uses loose comparison, it falls through by default, and it can’t be used as an expression. match fixes all three:

$result = match($status) {
    'active', 'pending' => 'processing',
    'done'             => 'finished',
    default            => throw new \UnexpectedValueException($status),
};

Strict comparison. No fall-through. Expression that returns a value. Non-exhaustive match throws. After one week with match I stopped writing switch.

Named arguments

array_slice(array: $users, offset: 0, length: 10, preserve_keys: true);

Named arguments let you pass arguments in any order and skip optional ones. The obvious win is readability on functions with multiple boolean flags. The less obvious win: named arguments survive PHP version upgrades even when parameter order changes, because you’re naming what you mean.

Attributes

Out with docblock annotations (the @Route, @ORM\Column style that frameworks have relied on for years), in with first-class PHP syntax:

#[Route('/users', methods: ['GET'])]
#[IsGranted('ROLE_ADMIN')]
public function list(): Response { ... }

Attributes are validated by the engine, not parsed from strings. IDE support just works, no plugin magic needed. For Symfony and Doctrine users, this is the real daily win of PHP 8.0.

Constructor promotion

class User {
    public function __construct(
        public readonly int $id,
        public string $name,
        private ?string $email = null,
    ) {}
}

Properties declared and assigned in one line in the constructor signature. The most immediate refactoring win in 8.0: every data class I’ve touched since upgrading is half the lines it used to be.

Nullsafe operator

$city = $user?->getAddress()?->getCity()?->getName();

null at any point in the chain short-circuits the rest and returns null. The alternative was nested null checks or a chain of early returns. This composes naturally.

Union types

Named arguments make function signatures more explicit at the call site. Union types make them more honest at the declaration site:

function processInput(int|float|string $value): string|int
{
    if (is_string($value)) {
        return strlen($value);
    }
    return (int) round($value);
}

The union int|float|string is a literal OR. The engine enforces it on entry and exit. Before 8.0, “this parameter accepts int or float” lived in a docblock that nothing enforced. There’s also null as a type component: ?string is just syntactic sugar for string|null, both are valid.

One special case: false. PHP has a bunch of built-in functions that return a typed value on success and false on failure. The 8.0 type system accommodates that: array|false, string|false. It’s an honest acknowledgment that the codebase can’t be rewritten overnight.

static return type

static as a return type was possible informally through docblocks, but 8.0 makes it official. The distinction between self and static matters in inheritance:

class Builder {
    protected array $config = [];

    public function set(string $key, mixed $value): static {
        $this->config[$key] = $value;
        return $this;
    }
}

class SpecialBuilder extends Builder {}

$result = (new SpecialBuilder())->set('foo', 'bar');
// $result is SpecialBuilder, not Builder

With self as the return type, that chain would return Builder, breaking fluent interfaces in subclasses. static makes fluent APIs work correctly across inheritance hierarchies without manual overrides.

mixed type

mixed was a docblock convention for years. 8.0 makes it a real type that shows up in signatures:

function debug(mixed $value): void {
    var_dump($value);
}

It accepts everything: null, objects, resources, scalars, arrays. Semantically it’s the same as having no type declaration, but it’s explicit rather than absent. The difference between “this parameter is untyped” and “this parameter intentionally accepts anything.” Worth using when you’re writing a general-purpose utility that would be dishonest with a narrower type.

throw as expression

Before 8.0, throw was a statement. Sounds like a pedantic distinction until you hit the places where you actually want an expression:

// In a ternary:
$value = $input ?? throw new \InvalidArgumentException('input required');

// In an arrow function:
$getId = fn(User $u) => $u->id ?? throw new \RuntimeException('no id');

// In a match arm (which is already an expression):
$status = match($code) {
    200     => 'ok',
    404     => 'not found',
    default => throw new \UnexpectedValueException("unknown code: $code"),
};

The last one is particularly useful: match without a default will throw UnhandledMatchError automatically, but sometimes you want to control the exception type and message.

catch without a variable

Small quality-of-life fix. When you catch an exception but don’t actually use the object, 8.0 lets you omit the variable:

try {
    $result = $cache->get($key);
} catch (CacheMissException) {
    $result = $this->compute($key);
}

Before 8.0, you had to write catch (CacheMissException $e) and then either use $e or live with the IDE warning about an unused variable. Neither was satisfying.

String functions that should have existed years ago

Three functions that every PHP developer has written manually at least once:

str_contains('hello world', 'world');  // true
str_starts_with('hello world', 'hell'); // true
str_ends_with('hello world', 'world'); // true

Before 8.0, the go-to approaches were strpos() !== false, strncmp(), or substr() ===, all of which require stopping to remember the semantics. These new functions are just direct and readable. No regex, no offset arithmetic.

Stable sort

PHP’s sorting functions weren’t stable before 8.0. “Not stable” means elements that compare as equal could end up in any order relative to each other. In practice this caused subtle bugs in UI code that needed consistent ordering, pagination that shifted between loads, and tests that only passed by luck.

8.0 guarantees stability across all sorting functions: sort(), usort(), array_multisort(), and the rest. Equal elements keep their original relative position. This is the behavior most people assumed was already there.

WeakMap

7.4 brought WeakReference for single objects. 8.0 brings WeakMap: a map where both the keys (objects) and their associated data can be garbage collected when no other reference to the key object exists:

class RequestCache {
    private WeakMap $cache;

    public function __construct() {
        $this->cache = new WeakMap();
    }

    public function get(Request $request): Response {
        return $this->cache[$request] ??= $this->compute($request);
    }
}

The moment $request is no longer referenced anywhere else, the entry disappears from the map. No manual cleanup needed. It’s the right pattern for memoization and computed property caches where you don’t want to be the sole reason an object stays alive.

New exception types

ValueError is thrown when a function gets the right type but an invalid value, as opposed to TypeError which fires on wrong types:

array_chunk([], -5); // ValueError: array_chunk(): Argument #2 ($length) must be greater than 0

Before 8.0, many of these were warnings that returned false or null. Now they throw. The engine is stricter, which means you catch problems earlier instead of getting weird results somewhere downstream.

get_debug_type() and fdiv()

Two utility functions worth knowing.

get_debug_type() returns a normalized string representation of any value, handy for error messages:

get_debug_type(1);          // "int"
get_debug_type(1.0);        // "float"
get_debug_type(null);       // "null"
get_debug_type(new Foo());  // "Foo" (not "object")
get_debug_type([]);         // "array"

The difference from gettype(): it returns class names for objects and uses normalized names ("int" not "integer"). Exactly what you want when building an exception message that says what you got versus what you expected.

fdiv() performs floating-point division following IEEE 754, meaning division by zero returns INF, -INF, or NAN instead of a warning:

fdiv(10, 0);   // INF
fdiv(-10, 0);  // -INF
fdiv(0, 0);    // NAN

The changes that break things

8.0 also ships a few changes that aren’t features, they’re corrections.

The big one: 0 == "foo" is now false. In PHP 7, comparing an integer to a non-numeric string would cast the string to 0, so 0 == "anything-non-numeric" evaluated to true. That was a persistent source of bugs and security headaches. PHP 8 flips it: the integer gets cast to a string instead:

var_dump(0 == "foo");  // bool(false) in 8.0, bool(true) in 7.x
var_dump(0 == "");     // bool(false) in 8.0, bool(true) in 7.x
var_dump(0 == "0");    // bool(true) in both ("0" is numeric)

If you relied on this intentionally, you already knew it was sketchy. If you didn’t know you relied on it, 8.0 will find those code paths for you.

Several functions that used to return resources now return proper objects: curl_init() returns a CurlHandle, imagecreate() returns a GdImage, xml_parser_create() returns an XMLParser. Code that checks is_resource($curl) will break, because is_resource() returns false for these objects. The fix is to check against false (the return value on failure) rather than checking the type of the success case.

PHP 8.0 is the kind of release where the features reinforce each other. Attributes play well with constructor promotion. Match pairs naturally with union types. The string functions cut noise that was hiding intent. The corrections are occasionally breaking, but they push the language toward consistency it should have had years ago.

Deleting them naively wasn’t an option. “Keep the last 50” loses all historical context for articles that haven’t been touched in a year. “Keep one per day” loses all the detail for content that’s actively being edited. What we needed was a distribution that matched how revisions are actually used: dense coverage for recent history, sparse coverage for old history.

That’s a logarithmic distribution. And building it required raw SQL.

Why simple strategies fail

The appeal of a fixed window is obvious: keep the N most recent revisions and delete the rest. It’s one line of SQL and zero math. The problem is that it treats a revision from yesterday and a revision from three years ago as equally valuable, which they aren’t. An editor who opens an article from 2017 doesn’t need its last 50 versions; they might need one per quarter. An article that shipped this morning might need every save from the past hour.

A time-based strategy (one revision per calendar day) has the opposite problem: it’s too aggressive for active content. If an article gets 30 saves between 09:00 and 10:00, all of them except one disappear. That’s not history, that’s erasure.

Neither strategy can express “keep more detail for recent content, less for old content.” That relationship is logarithmic.

The scoring idea

The algorithm assigns each revision a score based on its age, then keeps only one revision per score bucket. The score formula produces high, widely-spaced values for recent revisions and small, clustered values for old ones.

The core expression, simplified, looks like this:

(
  ln( EXTRACT(epoch FROM (now() - created_at)) )
  /
  ( EXTRACT(epoch FROM (now() - created_at)) / 6000 )
)
* ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
* 1000

Let s be the age in seconds. The formula is roughly ln(s) / s * C, where both the logarithm in the numerator and s in the denominator make the result decrease rapidly as s grows.

Cast to an integer, the effect is this: a revision saved 10 minutes ago might score 8432, one saved 11 minutes ago scores 8431. They’re in different buckets. A revision from six months ago scores 2, one from eight months ago also scores 2. Same bucket. The window function then picks the most recent revision from each bucket and discards the rest.

The result is automatic: recent saves are all kept because each has a distinct score; old saves are thinned because many share the same score.

The DQL attempt that didn’t ship

Window functions aren’t part of DQL. Doctrine’s query language has no syntax for OVER, PARTITION BY, or ROW_NUMBER(). Before going to raw SQL, the team tried to add them.

The FunctionNode approach works for single SQL functions, as we’d already seen with FTS. A RowNumber node emitting ROW_NUMBER() is trivial:

class RowNumber extends FunctionNode
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ROW_NUMBER()';
    }
}

The harder part is OVER(PARTITION BY ... ORDER BY ...). An Over function node was drafted, with a custom PartitionByClause AST node to handle the PARTITION BY clause:

class Over extends FunctionNode
{
    protected ?PartitionByClause $partitionByClause = null;
    protected ?OrderByClause $orderByClause = null;

    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'OVER('
            .($this->partitionByClause
                ? $this->partitionByClause->dispatch($sqlWalker)
                : ($this->orderByClause
                    ? $this->orderByClause->dispatch($sqlWalker)
                    : ''))
            .')';
    }
}

It was never finished. The classes shipped marked @deprecated and “NOT TESTED YET”. The issue is composability: DQL’s FunctionNode works cleanly for functions that appear in WHERE clauses or SELECT expressions. A window function like ROW_NUMBER() OVER (PARTITION BY ...) is a different structure: it appears in a SELECT position, modifies the surrounding query semantics, and requires the parser to handle PARTITION BY as an extension to DQL’s grammar. Making that robust enough to trust in production is a significant investment. Going to DBAL and writing the SQL directly took an afternoon.

The query, layer by layer

The final implementation is three nested queries:

DELETE FROM revision
WHERE iri = ?
AND id NOT IN (
    SELECT id FROM (
        SELECT
            row_number() OVER (
                PARTITION BY num, iri
                ORDER BY num DESC, created_at DESC
            ) AS lines,
            *
        FROM (
            SELECT
                (
                    ( ln( EXTRACT(epoch FROM (now() - created_at)) )
                      / ( EXTRACT(epoch FROM (now() - created_at)) / 6000 ) )
                    * ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
                    * 1000
                )::numeric::integer AS num,
                *
            FROM revision
            WHERE iri = ?
            ORDER BY created_at DESC
        ) AS lst
    ) AS rst
    WHERE lines = 1
);

Inner query: computes num, the integer score, for every revision of the given IRI. Rows are sorted by created_at DESC at this stage.

Middle query: runs ROW_NUMBER() OVER (PARTITION BY num, iri ORDER BY num DESC, created_at DESC). Within each score bucket (num), revisions are numbered starting from 1 in descending age order. The most recent revision in each bucket gets lines = 1.

Outer filter: keeps only the lines = 1 rows, one revision per score bucket.

DELETE: removes every revision for this IRI that isn’t in the kept set.

The PARTITION BY num, iri is redundant on the IRI (the whole query is already filtered to one IRI), but makes the intent explicit and keeps the logic correct if the query is ever reused in a broader context.

The method is called from a companion query that identifies which IRIs have accumulated more than a threshold of revisions:

public function getIrisWithMoreRevisionThan(int $maxRevisionsCount, int $limit = 0, ?int $retencyDay = null): array
{
    $queryBuilder = $this
        ->createQueryBuilder('revision')
        ->select('revision.iri')
        ->groupBy('revision.iri')
        ->having('COUNT(1) > :maxRevisions')
        ->orderBy('COUNT(1)', Order::Descending->value)
        ->setParameter('maxRevisions', $maxRevisionsCount);

    // ...

    return array_column($queryBuilder->getQuery()->getResult(), 'iri');
}

The two methods run together in a scheduled cleanup: find the IRIs over the threshold, prune each one.

Wiring it to a scheduled command

The pruning query doesn’t run in a request. It runs behind a Symfony command, called on a schedule.

The command takes a few options to control how aggressively it runs:

#[AsCommand('app:purge:revision', 'Remove useless revisions')]
final class PurgeRevisionCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addOption('max-revisions', 'm', InputOption::VALUE_REQUIRED,
                'Revision threshold above which an IRI gets pruned', 30)
            ->addOption('limit', 'l', InputOption::VALUE_REQUIRED,
                'Max number of IRIs to process per run')
            ->addOption('delay', 'w', InputOption::VALUE_REQUIRED,
                'Delay in seconds between each IRI')
            ->addOption('retencyDay', 'r', InputOption::VALUE_OPTIONAL,
                'Only process IRIs whose last revision is older than N days');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $iris = $this->revisionRepository->getIrisWithMoreRevisionThan(
            (int) $input->getOption('max-revisions'),
            (int) $input->getOption('limit'),
            (int) $input->getOption('retencyDay'),
        );

        foreach ($iris as $iri) {
            $totalDeleted += $this->revisionRepository->deleteOldRevisionForIri($iri);
            usleep((int) $input->getOption('delay') * 1_000_000);
        }

        return Command::SUCCESS;
    }
}

The --delay option is worth noting: on a busy database, hammering a hundred DELETE statements back-to-back can cause lock contention. A small sleep between iterations keeps the purge from competing with production traffic.

The command runs behind two crontab entries with different thresholds:

# Hourly: keep 30 revisions per IRI, process 100 IRIs per run
0 * * * * php bin/console app:purge:revision --max-revisions 30 --limit 100

# Nightly: for content untouched for a year, keep only 3
0 0 * * * php bin/console app:purge:revision --max-revisions 3 --limit 100 --retencyDay 365

The two-level strategy matters. The hourly job keeps 30 revisions per IRI, which is a reasonable ceiling for actively-edited content. The nightly job targets only IRIs not updated in over a year and keeps just 3. An article that hasn’t moved in twelve months doesn’t need thirty versions in its history.

What it looks like in practice

An article saved 200 times will typically keep 20 to 30 revisions after pruning: most of the recent saves, a handful from last month, one or two from each quarter of the previous year. The exact count depends on the age distribution of the saves, not on an arbitrary cap.

An article last edited two years ago might end up with 5 or 6 revisions. Recent edits are all there; the old history is compressed but not gone.

It’s not a perfect history. It’s a useful one.

The line between DQL and raw SQL

The window function attempt isn’t a failure worth hiding. It’s a useful data point: FunctionNode works well for scalar functions in WHERE and SELECT positions, but composing a full ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) expression in DQL is harder than it looks. The grammar extension, the AST nodes, the SQL walker integration: it’s a non-trivial amount of code for something that native SQL handles in three lines.

The practical boundary is roughly this: if a PostgreSQL feature maps to a function call with fixed arity, custom DQL works. If it requires new clause syntax (window frames, CTEs, lateral joins), native DBAL is usually the better trade-off.

Typed properties

This is the one. Since PHP 7.0, you could type function parameters and return values. But class properties? Still untyped:

class User {
    public int $id;
    public string $name;
    public ?DateTimeInterface $deletedAt;
}

7.4 changes that. Typed properties enforce types at assignment, not just at call sites. Classes become self-documenting in a way that docblocks never quite managed, and the engine catches type errors before they propagate through half your stack.

One subtlety: typed properties are uninitialized by default (not null). Accessing an uninitialized property throws an Error. This trips people up: ?string doesn’t imply a default of null. You still need an explicit = null for that.

Arrow functions

Closures in PHP have always required explicitly importing outer scope variables with use:

$multiplier = 3;
$fn = fn($x) => $x * $multiplier; // no use() needed

Arrow functions capture the enclosing scope automatically. Single expression, implicit return, no boilerplate. They don’t replace full closures for complex logic, but for short callbacks they eliminate a class of noise that had been accumulating for years.

Opcache preloading

For long-lived PHP-FPM setups, preloading allows a script to load and compile PHP files into opcache memory at server startup. Those files are available to all requests without compilation overhead.

The gain varies by application. On large frameworks where the same files are loaded on every request, it’s real. On smaller apps, negligible. Worth benchmarking before adding the configuration complexity.

The small ones that add up

The features mentioned in passing deserve more than a line. The null coalescing assignment operator ??= solves a pattern that was annoying enough to write every single time but never annoying enough to bother abstracting:

$config['timeout'] ??= 30;
// equivalent to: $config['timeout'] = $config['timeout'] ?? 30;

Spread operator in array literals does what you’d expect from the function call version — unpack an iterable into an array literal:

$defaults = ['color' => 'blue', 'size' => 'M'];
$options = ['size' => 'L', ...$defaults, 'weight' => 1.2];
// ['size' => 'M', 'color' => 'blue', 'weight' => 1.2]

Note: string keys weren’t supported in 7.4 for array unpacking. That came later.

Covariant return types and contravariant parameter types close a gap that made some inheritance patterns needlessly awkward. A child class can now narrow its return type to a subtype of the parent’s, without hitting a fatal error:

class Producer {
    public function get(): Iterator {}
}
class ChildProducer extends Producer {
    public function get(): ArrayIterator {} // ArrayIterator implements Iterator
}

Reading numbers at 3am

The numeric literal separator is one of those features you don’t know you wanted until the first time you write a large constant and immediately lose track of the magnitude:

$earthMass    = 5_972_168_000_000_000_000_000_000; // kg
$lightSpeed   = 299_792_458;                        // m/s
$planck       = 6.626_070_15e-34;                  // J·s
$hexMask      = 0xFF_EC_D5_08;
$binaryFlags  = 0b0001_1111_0010_0000;

The underscore is purely syntactic. The engine strips it before parsing the value. You can put it anywhere between digits, though convention follows the natural grouping of the number system you’re working in.

Holding without owning

WeakReference lets you hold a reference to an object without preventing the garbage collector from destroying it. The use case is caches and registries: you want to know an object is alive, but you don’t want to be the reason it stays alive:

$object = new HeavyObject();
$ref = WeakReference::create($object);

var_dump($ref->get()); // object(HeavyObject)

unset($object);

var_dump($ref->get()); // NULL — GC collected it

Before 7.4 you had WeakRef via an extension, and some frameworks were doing SplObjectStorage tricks that didn’t quite behave the same way. The native class is just straightforward.

Serialization without surprise

Custom object serialization before 7.4 went through the Serializable interface: implement serialize() and unserialize(), return a string, reconstruct from it. The problem is that serialize() triggered __sleep(), unserialize() triggered __wakeup(), and the interaction between these hooks was fragile, especially in inheritance hierarchies.

7.4 introduces __serialize() and __unserialize(), which work with arrays instead of strings and don’t interact with the old hooks:

class Session {
    private string $token;
    private \DateTime $createdAt;

    public function __serialize(): array {
        return ['token' => $this->token, 'created' => $this->createdAt->getTimestamp()];
    }

    public function __unserialize(array $data): void {
        $this->token = $data['token'];
        $this->createdAt = (new \DateTime())->setTimestamp($data['created']);
    }
}

When both the new and old methods exist on the same class, __serialize() wins. The old Serializable interface gets deprecated in 8.1.

What the standard library quietly got

mb_str_split() does what str_split() does but correctly for multibyte strings. The gap was genuinely embarrassing for a language used in as many locales as PHP:

mb_str_split('héllo', 1); // ['h', 'é', 'l', 'l', 'o']
str_split('héllo', 1);    // ['h', 'Ã', '©', 'l', 'l', 'o'] — broken

strip_tags() now accepts an array of allowed tags, which is cleaner than the string format it used to require:

strip_tags($html, ['p', 'br', 'strong']); // was: '<p><br><strong>'

proc_open() now accepts an array command, bypassing shell interpretation entirely. Same idea as Python’s subprocess with shell=False. Worth knowing whenever you’re passing user-supplied arguments to an external process.

The FFI chapter

The Foreign Function Interface extension landed in 7.4 after spending time in a feature branch. It lets PHP call native C functions by loading a shared library and declaring the signatures:

$ffi = FFI::cdef("int strlen(const char *s);", "libc.so.6");
var_dump($ffi->strlen("hello")); // int(5)

The practical applications are narrow but real: calling platform APIs with no PHP binding, wrapping performance-critical C code without writing a full extension, or just poking at native libraries directly. Not a replacement for proper extensions in production, but it removes the “write a C extension” barrier for exploration.

What got deprecated

A few things that should have been cleaned up a while ago finally got the deprecation treatment in 7.4.

Nested ternaries without parentheses have been ambiguous forever. PHP evaluated them left-to-right while pretty much every other language with a ternary evaluates right-to-left:

// Was ambiguous, now deprecated:
$a ? $b : $c ? $d : $e;

// Make it explicit:
($a ? $b : $c) ? $d : $e;

Curly brace offset access for strings and arrays — $str{0} instead of $str[0] — is deprecated and gone in 8.0. It was always an alias, never a separate feature.

implode() with reversed argument order (array first, glue second) is deprecated. The function has accepted both orders since the beginning, which was a mistake. The correct order is implode(string $separator, array $array).

What comes next

7.4 is the last 7.x release. The deprecations are mostly ground-clearing for removals in 8.0. The RFC backlog for 8.0 is substantial: JIT, attributes, named arguments, match expressions. 7.4 is a solid place to land while waiting for all that to arrive.

Flexible heredoc and nowdoc

Until 7.3, the closing marker of a heredoc had to be at column zero. That forced awkward de-indentation in otherwise well-formatted code:

// before
$html = <<<HTML
    <div>
        <p>Hello</p>
    </div>
HTML; // had to be at column 0, ugly

// after
$html = <<<HTML
    <div>
        <p>Hello</p>
    </div>
    HTML;

The closing marker can now be indented to match the surrounding code, and that indentation is stripped from the content. This looks cosmetic. It’s not. Heredocs in nested contexts (class methods, conditionals) were visually jarring before. Now they fit.

:1234: array_key_first() and array_key_last()

This existed forever as a workaround:

$first = array_keys($array)[0];

7.3 adds the obvious helpers:

$first = array_key_first($array);
$last  = array_key_last($array);

And is_countable() to safely check before calling count() on something that might not implement Countable. Functions that should have existed years ago.

PCRE2

The regular expression engine was migrated from PCRE to PCRE2. Mostly invisible for existing patterns, but PCRE2 is actively maintained and handles edge cases better. The main practical impact: some patterns that previously produced undefined behavior now throw errors. That’s the correct behavior, even if it surprises you on the first upgrade.

Trailing commas in function calls

7.2 allowed trailing commas in grouped namespace imports. 7.3 extends this to function and method calls:

$result = array_merge(
    $defaults,
    $overrides,
    $extras, // no more removing this comma before the closing paren
);

This matters most with multiline calls. Adding or removing an argument no longer means touching the adjacent line. Diffs stay honest, rebases get a little less painful.

Reference assignments in array destructuring

Array destructuring gained the ability to capture references instead of copies:

$data = ['Alice', 42];

[&$name, $age] = $data;

$name = 'Bob';
var_dump($data[0]); // string(3) "Bob"

Nested references work too:

[$a, [&$b]] = [1, [2]];

More niche than trailing commas, but the right tool when you need to alias deep into a structure without a pile of intermediate assignments.

instanceof with literals is now legal

Previously, using instanceof with a literal on the left side was a parse error. 7.3 makes it valid:

var_dump(null instanceof stdClass); // bool(false)

It always evaluates to false, which is exactly correct. The benefit is that code that conditionally constructs a value and then checks its type no longer needs to extract the value into a variable first. Useful in generated code and test helpers.

json_decode() and json_encode() can throw now

Before 7.3, JSON errors were silent unless you remembered to check json_last_error(). Easy to forget, easy to get wrong:

$data = json_decode($response);
if (json_last_error() !== JSON_ERROR_NONE) {
    // most people forgot this part
}

7.3 adds JSON_THROW_ON_ERROR:

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
// throws JsonException on malformed input

JsonException extends RuntimeException. Catch it specifically or let it propagate. Should have worked this way from day one.

setcookie() with an options array

The old setcookie() signature is a relic: seven positional arguments, most of which you leave as defaults just to reach the one you actually want. 7.3 adds an alternative form that takes an associative array:

setcookie('session', $token, [
    'expires'  => time() + 3600,
    'path'     => '/',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax',
]);

The samesite option is the real reason this was added — the old positional signature had no slot for it. session_set_cookie_params() received the same treatment, and a new session.cookie_samesite ini directive covers the default.

hrtime() for benchmarking that actually measures time

microtime() reads wall clock time. Fine for most cases. But it’s affected by NTP adjustments, and its resolution is implementation-dependent. hrtime() reads the monotonic high-resolution clock:

$start = hrtime(true);  // nanoseconds as integer
doWork();
$elapsed = hrtime(true) - $start;
echo $elapsed / 1e6 . " ms\n";

Without the true argument it returns [seconds, nanoseconds] as a two-element array. Use this for microbenchmarks, or anywhere clock drift would silently corrupt your measurement.

gc_status() — looking inside the garbage collector

PHP’s cyclic garbage collector runs when a buffer of potential cycles fills up. Until 7.3 you had no easy way to see what it was actually doing. gc_status() exposes the internal state:

$status = gc_status();
// [
//   'runs'       => 3,
//   'collected'  => 127,
//   'threshold'  => 10001,
//   'roots'      => 42,
// ]

Not something most app code needs. Useful when you’re trying to figure out why memory keeps climbing under specific workloads.

CompileError joins the exception hierarchy

Parse errors have been catchable as ParseError since PHP 7.0. 7.3 introduces CompileError as the parent class for compile-time failures, with ParseError becoming a subclass of it:

Error
└── CompileError
    └── ParseError

In practice, code that catches ParseError still works. The new class just gives future compile-time errors (that aren’t parse errors) a proper home in the hierarchy.

bcscale() as a getter

The BC Math scale was always settable via bcscale($n). Getting the current scale required tracking it yourself. 7.3 makes bcscale() work without arguments:

bcscale(4);
echo bcscale(); // 4

Minor. Worth knowing if you’re writing library code that needs to respect or restore whoever called it’s scale setting.

The continue inside switch warning

This one is a correctness fix that looks like a deprecation. In PHP, continue inside a switch has always behaved like break — it exits the switch, not the enclosing loop. Developers coming from other languages often write this expecting to skip to the next loop iteration:

foreach ($items as $item) {
    switch ($item->type) {
        case 'skip':
            continue; // WRONG: exits the switch, not the foreach
    }
}

7.3 adds a warning for this pattern. The fix is continue 2 to explicitly target the enclosing loop. The behavior hasn’t changed. The silence has.

Deprecations

Case-insensitive constants declared via define() are deprecated:

define('MY_CONST', 42, true); // third argument deprecated

Passing a non-string needle to strpos(), strstr(), and related functions is deprecated. In PHP 8 these will interpret the needle as a string, not an ASCII codepoint. If you’re passing integers to these functions intentionally, chr($n) is the explicit form.

fgetss() is deprecated — it was fgets() with HTML/PHP tags stripped. Use fgets() and strip tags explicitly if you need them stripped. The string.strip_tags stream filter goes with it.

7.3 is the kind of release you appreciate in hindsight. Nothing individually dramatic, but after six months with it the heredoc fix alone has paid back the upgrade cost in readability. Sometimes boring is exactly right.

This is good news, even if it doesn’t feel that way when you’re the one migrating.

The mcrypt problem

mcrypt has been unmaintained since 2007. More than a decade of stagnation in a cryptography library. It was deprecated in 7.1, and 7.2 removes it entirely. The replacement is sodium, now bundled as a core extension.

Sodium is the PHP binding for libsodium, a modern cryptographic library built around safe defaults. Where mcrypt required you to pick the right cipher, mode, and padding (and get it wrong silently), sodium’s API makes dangerous choices structurally hard. sodium_crypto_secretbox() for symmetric encryption, sodium_crypto_box() for asymmetric, sodium_crypto_sign() for signatures. The names tell you what you’re doing.

If you have mcrypt code in production, the migration is unavoidable. Worth doing carefully too: cryptography code that “still works” can be silently broken in ways you won’t notice until it’s too late.

The object type hint

7.2 adds object as a parameter and return type:

function serialize(object $data): string {
    // accepts any object
}

It’s broad — any object satisfies it — but it’s better than no type at all when you genuinely don’t care about the specific class. Complements the existing array, callable, and class-specific hints.

Argon2 in password_hash

$hash = password_hash($password, PASSWORD_ARGON2I);

PASSWORD_BCRYPT was the default and still reasonable, but Argon2 won the Password Hashing Competition for a reason: it’s memory-hard, which makes GPU-based cracking significantly more expensive. Worth switching for new apps.

7.2 is more of a security release than a language one. Remove mcrypt, add sodium, and you’ve moved the platform to a place where you can actually trust it with sensitive data. The language features are incremental. The infrastructure shift is not.

Parameter types you can now drop on purpose

7.2 formalizes something that was previously just a smell: when you implement an interface or override a method, you can now omit the parameter type entirely. This is valid contravariance under the Liskov substitution principle.

interface Serializable {
    public function serialize(array $data): string;
}

class JsonSerializer implements Serializable {
    public function serialize($data): string { // no type — accepts more, still valid
        return json_encode($data);
    }
}

It reads oddly at first. But it’s logically sound: a method that accepts anything is strictly more permissive than one that only accepts arrays. The type system agrees, even if your code reviewer raises an eyebrow.

Abstract methods that evolve

When an abstract class extends another abstract class, it can now override the abstract method with a different signature. The constraint is directional: parameters can be widened (contravariant), return types can be narrowed (covariant).

abstract class BaseProcessor {
    abstract function process(string $input);
}

abstract class TypedProcessor extends BaseProcessor {
    abstract function process($input): int; // parameter widened, return type added
}

This was rejected before 7.2. It unlocks intermediate abstractions without forcing every leaf class to repeat the same signature.

Trailing commas in grouped use statements

Small, but I notice its absence when it’s missing. Grouped namespace imports can now have a trailing comma on the last item:

use App\Services\{
    UserService,
    OrderService,
    NotificationService, // comma here — finally
};

This means you can reorder or add lines without touching the previous last entry. Git diffs get cleaner, merge conflicts get rarer.

count() grew a conscience

Before 7.2, count(null) returned 0. Silently. No warning. That’s exactly the kind of thing that buries a bug for months. Now it emits E_WARNING when you pass something that isn’t an array or a Countable object.

count(null);  // Warning: count(): Parameter must be an array or an object that implements Countable
count(42);    // same
count("hi");  // same

The behavior didn’t change for valid inputs. Only the silence was broken. That’s the correct direction.

spl_object_id() — the thing you were emulating with SplObjectStorage

If you’ve ever built a map keyed on object identity, you’ve written something like this:

$storage = new SplObjectStorage();
$storage[$obj] = true;

7.2 adds spl_object_id(), which returns a unique integer for the lifetime of an object. It’s the same internal handle SplObjectStorage uses, made directly accessible:

$id = spl_object_id($obj); // e.g. 42
$map[$id] = 'something';

The integer is reused after the object is destroyed, so don’t hold onto it past the object’s lifetime. Within a well-scoped context though, it’s a cheap identity key.

PDO: national character strings

When working with databases that distinguish between regular and national character string types (Oracle, SQL Server), 7.2 adds the flags you needed:

$stmt = $pdo->prepare("SELECT * FROM users WHERE name = ?");
$stmt->bindValue(1, 'Ångström', PDO::PARAM_STR | PDO::PARAM_STR_NATL);

Or set a connection-level default:

$pdo->setAttribute(PDO::ATTR_DEFAULT_STR_PARAM, PDO::PARAM_STR_NATL);

PDO::PARAM_STR_NATL signals that the string is a national character type (NCHAR/NVARCHAR). Obscure, yes. Essential if you’ve ever watched your Unicode data come out mangled because the driver had no idea about the difference.

GD got BMP support and clipping rectangles

Two things worth knowing. First, BMP files are now first-class citizens in the GD extension:

$image = imagecreatefrombmp('photo.bmp');
imagebmp($image, 'output.bmp');

Second, you can now define a clipping rectangle so that drawing operations only affect a portion of the image:

imagesetclip($image, 10, 10, 200, 150); // x1, y1, x2, y2
// everything drawn outside this rectangle is silently ignored

Neither feature reshapes how most apps work, but both replace “install an extra library” with “it’s just in core now.”

mb_chr() and mb_ord() — Unicode’s chr() and ord()

PHP has had chr() and ord() forever. They work on bytes. For Unicode code points, you were on your own. 7.2 adds the multibyte equivalents:

$char = mb_chr(0x1F600); // returns the 😀 emoji
$code = mb_ord('é');     // returns 233

And mb_scrub(), which strips invalid byte sequences from a string rather than failing silently or throwing:

$clean = mb_scrub($untrustedInput, 'UTF-8');

Handy at any external boundary: API responses, file uploads, database reads from legacy systems.

Deprecations worth knowing before 7.4 arrives

Several things were soft-deprecated in 7.2 that will become errors in later versions. The ones most likely to bite:

__autoload() is deprecated. If you’re still registering a global autoload function instead of using spl_autoload_register(), fix it before it becomes a fatal.

create_function() is deprecated. It’s a wrapper around eval() and was always dangerous. Use a closure:

// before
$fn = create_function('$x', 'return $x * 2;');

// after
$fn = fn($x) => $x * 2;

each() is deprecated. The loop pattern it enabled is better written as foreach. There’s no loss here.

parse_str() without a second argument dumps parsed values into the local symbol table — a security issue that should never have been allowed. Always pass the output variable:

parse_str($queryString, $params); // correct

The (unset) cast is deprecated because it always returns null, which you can just write as null. Completely pointless syntax that should never have existed.

The problem isn’t in the business logic. It’s in what Doctrine quietly does with dates.

What Doctrine does by default

When you declare a datetime field in a Doctrine entity, the conversion between PHP and the database goes through DateTimeType. That class calls format() on your DateTime object to write to the database, and DateTime::createFromFormat() to read it back. No mention of timezone anywhere.

If your PHP object is in Europe/Paris, Doctrine formats 2017-01-15 11:30:00 and writes it as-is. If the server reading that field is in UTC, it gets 2017-01-15 11:30:00 and interprets it as UTC. One hour has evaporated in the round trip, without a single error message.

The Doctrine docs cover this, suggesting custom types as the fix. What they mention in passing is that you can give those custom types the same name as the built-in ones. That detail changes everything.

Replace, don’t add

Most custom Doctrine type examples introduce a new name: utc_datetime, app_date, and so on. You then annotate every field with type: 'utc_datetime' in the entities. It works, but it’s tedious and doesn’t protect against a forgotten type: 'datetime'.

The other option: register the custom type under the name datetime. Doctrine replaces its own type with yours, everywhere, no exceptions. Every datetime field across all entities goes through your logic, without changing a single annotation.

That’s what we just shipped across our PHP microservices platform. Here’s what it looks like.

The shared trait

Both types (date and datetime) share the same conversion logic through a trait:

trait UTCDate
{
    private \DateTimeZone $utc;

    public function convertToPHPValue($value, AbstractPlatform $platform): ?\DateTime
    {
        if (null === $value || $value instanceof \DateTime) {
            return $value;
        }

        $format = $this->getFormat($platform);
        $converted = \DateTime::createFromFormat($format, $value, $this->getUtc());

        if (!$converted) {
            throw new \RuntimeException(
                sprintf('Could not convert database value "%s" to DateTime using format "%s".', $value, $format)
            );
        }

        $this->postConvert($converted);

        return $converted;
    }

    abstract protected function getFormat(AbstractPlatform $platform): string;

    private function getUtc(): \DateTimeZone
    {
        if (empty($this->utc)) {
            $this->utc = new \DateTimeZone('UTC');
        }

        return $this->utc;
    }
}

The key: \DateTime::createFromFormat() receives an explicit UTC timezone. The raw value from the database is interpreted as UTC, regardless of what the PHP server’s timezone is set to.

UTCDateTimeType

For datetime fields, the write path also needs to enforce UTC:

class UTCDateTimeType extends DateTimeType
{
    use UTCDate;

    #[\Override]
    public function convertToPHPValue($value, AbstractPlatform $platform): ?\DateTime
    {
        if (null === $value || $value instanceof \DateTimeInterface) {
            return parent::convertToPHPValue($value, $platform);
        }

        return parent::convertToPHPValue("$value+0000", $platform);
    }

    #[\Override]
    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
    {
        if ($value instanceof \DateTime) {
            $value->setTimezone($this->getUtc());
        }

        return parent::convertToDatabaseValue($value, $platform);
    }

    #[\Override]
    protected function getFormat(AbstractPlatform $platform): string
    {
        return $platform->getDateTimeFormatString();
    }

    protected function postConvert(\DateTime $converted): void {}
}

On read (convertToPHPValue), if the value is a raw string, we append +0000 before delegating to the parent. The parent then uses that timezone suffix to create the PHP object correctly.

On write (convertToDatabaseValue), we force the DateTime to UTC before formatting. What goes into the database is always UTC.

UTCDateType

For date columns (no time component), same approach with one extra step:

class UTCDateType extends DateType
{
    use UTCDate;

    #[\Override]
    protected function getFormat(AbstractPlatform $platform): string
    {
        return $platform->getDateFormatString();
    }

    protected function postConvert(\DateTime $converted): void
    {
        $converted->setTime(0, 0, 0);
    }
}

The postConvert() method resets the time to 00:00:00 after parsing. Without it, a date field might come back with 23:59:59 or 00:00:00+02:00 depending on the server’s timezone, which breaks comparisons and ordering.

Registering in Symfony

The decisive part: declaring the types under their built-in names in config/packages/doctrine.yaml.

doctrine:
    dbal:
        types:
            date:
                class: App\Doctrine\DBAL\Types\UTCDateType
            datetime:
                class: App\Doctrine\DBAL\Types\UTCDateTimeType

That’s it. Doctrine swaps out its own implementations for yours. Existing entities don’t change, migrations don’t move, annotations stay type: Types::DATETIME_MUTABLE. The behavior changes globally, without friction.

12 microservices, 89 columns, one config block

These two types are now running across 12 independent microservices, each with its own Doctrine config, covering 89 production columns. CI servers run in UTC, dev machines in Europe/Paris, data travels between them without shifting. It’s not spectacular. It’s just reliable.

The real lesson isn’t technical: an unresolved timezone issue is a data integrity issue. Offsets accumulate silently, comparisons go wrong, exports become inaccurate. Two lines of config and three classes can prevent that permanently.

Nullable types

7.0 let you declare string $name as a parameter type. What it didn’t let you do was say “this can also be null”. You had to drop the type hint entirely or hack around it. 7.1 adds ? prefix:

function findUser(?int $id): ?User {
    if ($id === null) return null;
    return $this->repository->find($id);
}

This sounds minor. It’s not. Nullable types make the difference between a signature that tells you what a function does and one that lies by omission. Every codebase I’ve worked on has functions that can return null. Now you can actually say so instead of hiding it in a docblock.

Void return type

The complement to nullable: a function that intentionally returns nothing:

public function process(Order $order): void {
    $this->dispatcher->dispatch(new OrderProcessed($order));
}

void makes the intent explicit and prevents accidentally returning a value from a function that shouldn’t. Combined with nullable types, PHP’s type system in 7.1 is quite a bit more expressive than 7.0.

Class constant visibility

A small but welcome fix. Constants in classes were always public before 7.1. Now:

class Config {
    private const DB_PASSWORD = 'secret';
    protected const VERSION = '2.0';
    public const MAX_RETRIES = 3;
}

Keeping implementation details private matters. This should have existed from the start.

Catching multiple exceptions

try {
    // ...
} catch (InvalidArgumentException | RuntimeException $e) {
    // handle both
}

Saves a duplicate catch block when two exceptions need identical handling. Simple, useful.

Destructuring arrays without list()

list() has been in PHP since 4.0 and always felt slightly out of place syntactically. 7.1 adds a shorthand using [] that reads much more naturally:

[$first, $second] = $coordinates;

foreach ($rows as [$id, $name, $email]) {
    // ...
}

It also gains key support, which makes destructuring associative arrays finally usable:

['id' => $id, 'name' => $name] = $user;

foreach ($records as ['id' => $id, 'status' => $status]) {
    // ...
}

Before this, extracting named keys from an array meant either extract() (which dumps everything into scope and invites collisions) or a bunch of individual assignments. This is just cleaner.

The iterable type

If you write a function that accepts either an array or a generator, there was no clean type hint for that in 7.0. You either typed it as array and silently excluded generators, or dropped the hint entirely:

function processItems(iterable $items): void {
    foreach ($items as $item) {
        $this->handle($item);
    }
}

iterable accepts anything you can foreach over: arrays and Traversable implementations. It also works as a return type. Not dramatic, but it closes a real gap.

Negative string offsets

String indexing with [] or {} now accepts negative values, counting from the end:

$str = 'hello';
echo $str[-1]; // "o"
echo $str[-2]; // "l"

Several string functions got the same treatment: strpos(), substr(), substr_count(), and others now accept a negative offset. Consistent with how Python has worked forever. Better late than never.

Closure::fromCallable()

Before this, converting a callable (like [$object, 'method'] or a function name string) to a proper Closure required Closure::bind() or bindTo() with awkward scope handling. 7.1 adds a static factory method:

class Processor {
    private function transform(string $value): string {
        return strtoupper($value);
    }

    public function getTransformer(): Closure {
        return Closure::fromCallable([$this, 'transform']);
    }
}

The resulting closure captures the correct $this and scope. It’s particularly useful when passing methods as callbacks to functions that expect callable, or when building pipelines.

ArgumentCountError

In PHP 7.0, calling a user-defined function with too few arguments generated a warning and execution continued with null-filled parameters. In 7.1, it throws an ArgumentCountError:

function connect(string $host, int $port): void { /* ... */ }

try {
    connect('localhost'); // Throws ArgumentCountError
} catch (\ArgumentCountError $e) {
    // ...
}

ArgumentCountError extends TypeError, which extends Error. Call sites that previously silently degraded now fail loudly. That’s a migration risk if you have code that relied on the permissive behavior, but honestly, it’s the right call.

7.1 is the kind of release that makes you trust a platform more. The core team was clearly paying attention to the friction, not just shipping headlines.

The headline number is 2x faster than PHP 5.6. That’s not a benchmark cherry-pick — it’s the median across real applications. The Zend Engine was rewritten to use a new internal value representation that cuts memory usage significantly and reduces allocations. On one project, average response time dropped by 40% with zero code changes. You just upgrade and it goes faster.

But performance isn’t the most interesting part.

Types, finally

PHP has had type hints for objects since 5.0, for arrays since 5.1. In 7.0, you can finally declare scalar types for function parameters and return values:

function add(int $a, int $b): int {
    return $a + $b;
}

In strict mode (declare(strict_types=1)), passing a float to that function throws a TypeError. In the default coercive mode, PHP converts the value. That distinction matters: strict mode is per-file, so you can adopt it gradually without nuking your whole codebase at once.

Return type declarations are the other half. Putting intent in the signature rather than a docblock means the engine enforces it, not a code reviewer who might be half-asleep.

The null coalescing operator

?? is small but used constantly:

$username = $_GET['user'] ?? 'guest';

That replaces isset($_GET['user']) ? $_GET['user'] : 'guest'. It chains too: $a ?? $b ?? $c. After years of isset() noise, this alone was worth upgrading.

The breaking part

The error handling overhaul is the real upgrade risk. Many fatal errors are now Error exceptions, catchable but different from Exception. Code that relied on fatal errors to halt execution silently now needs explicit handling. Legacy error suppression with @ also works differently in places.

Read the migration guide before touching a production app. The payoff is real, but the gap between 5.6 and 7.0 is the widest PHP has ever had.

The spaceship operator

<=> is a combined comparison operator that returns -1, 0, or 1. It’s mostly there for sorting:

usort($users, function ($a, $b) {
    return $a->age <=> $b->age;
});

Before this, a custom sort comparator was a small exercise in remembered arithmetic. $a - $b works for integers but silently breaks for floats. <=> does the right thing for every comparable type.

Anonymous classes

You can now instantiate a class defined inline, on the spot, without giving it a name:

$logger = new class($config) implements LoggerInterface {
    public function __construct(private array $config) {}

    public function log(string $message): void {
        file_put_contents($this->config['path'], $message . PHP_EOL, FILE_APPEND);
    }
};