Migrating WordPress Plugins to PHP 8.3 Typed Properties

For over twenty-five years, PHP permitted developers to arbitrarily create class properties on the fly. In legacy WordPress plugin development, code like $customer->billing_tax_id = 'US-99182' or $query_helper->cached_results = $data was standard practice, even if $billing_tax_id or $cached_results was never explicitly declared in the class definition.

With the release of PHP 8.2 and the modern performance architecture of PHP 8.3+, this behavior has been officially deprecated. The PHP engine now emits an E_DEPRECATED: Creation of dynamic property ClassName::$propertyName is deprecated warning on every unassigned property write. In PHP 9.0, dynamic property assignment will throw an uncaught, fatal Error exception.

In enterprise WordPress environments running strict error monitoring (such as Sentry, Bugsnag, or Datadog), these deprecation notices flood application logs, exhaust server disk space, degrade Time to First Byte (TTFB) through constant error handler traps, and break automated CI/CD deployment pipelines.

In this definitive engineering guide, we will examine the mechanics of the PHP 8.3 dynamic properties deprecation in WordPress plugins. We will analyze the internal memory implications of dynamic properties, evaluate the `#[AllowDynamicProperties]` attribute, implement permanent PSR-4 architectural refactoring patterns (Typed Properties, Readonly DTOs, and Encapsulated Magic Containers), safely handle WordPress Core object metadata, manage uninitialized property serialization traps, build automated Reflection-based hydration engines, refactor complex legacy query builders and WooCommerce order processors, automate enterprise migrations using PHPStan Level 8, Psalm, and Rector AST transformations, benchmark opcode memory savings, and build zero-tolerance PHPUnit deprecation testing suites.

The Mechanics of PHP 8.3 Dynamic Property Deprecation

In PHP 5.x and 7.x, assigning a value to an undeclared property allocated a dynamic hash table inside the object’s zend_object memory structure at runtime. This dynamic allocation introduced substantial hidden costs:

1. Memory Fragmentation: Rather than allocating fixed memory offsets for known typed properties, PHP was forced to maintain an auxiliary properties_table hash map for every object instance.
2. Silent Typing Bugs: A developer writing $user->first_name = 'Alex' instead of $user->firstName = 'Alex' would silently create a new property without any warning, causing difficult-to-trace bugs.
3. Loss of Static Analysis: Tools like PHPStan, Psalm, and IDE language servers could not infer types, leading to broken autocomplete and untyped runtime bugs.

PHP Deprecation Timeline

The `#[AllowDynamicProperties]` Attribute: Friend or Foe?

To ease the transition toward PHP 9.0, the PHP core team introduced the #[AllowDynamicProperties] attribute in PHP 8.2. Adding this attribute above a class definition tells the Zend Engine to permit dynamic property creation without throwing deprecation notices:

<?php
declare(strict_types=1);

namespace WPStackLegacyPlugin;

#[AllowDynamicProperties]
class LegacyOrderProcessor {
    public int $orderId;

    public function __construct(int $orderId) {
        $this->orderId = $orderId;
    }
}

// In PHP 8.3, this executes without E_DEPRECATED warning:
$processor = new LegacyOrderProcessor(1054);
$processor->customerEmail = 'client@wpstack.online'; // Dynamic assignment permitted

Why `#[AllowDynamicProperties]` is an Architectural Anti-Pattern

While #[AllowDynamicProperties] provides a convenient one-line fix for emergency hotfixes, relying on it as a permanent solution is hazardous:

• Technical Debt Masking: It preserves chaotic, unstructured object states where properties can be attached unpredictably from any hook in the codebase.
• No IDE Auto-Completion: Developers working on the codebase cannot see what properties exist on the object without manually tracing every call site.
• Performance Overhead: Classes with dynamic properties cannot benefit from optimized contiguous property memory layouts in PHP’s JIT and opcode caches.
• Inheritance Traps: If a parent class declares #[AllowDynamicProperties], all child classes inherit it, inadvertently spreading loose typing throughout your plugin hierarchy.

Five Permanent Architectural Refactoring Patterns

To modernize enterprise WordPress plugins for PHP 8.3+ and future-proof against PHP 9.0, developers must transition to strict object-oriented patterns. For specialized engineering support or full-scale plugin modernization, MoxSEO’s web development team builds and audits custom WordPress plugins; see our WordPress development services.

Pattern 1: Explicit Typed Class Properties & Typed Constants

The cleanest, most performant remediation is declaring all properties with explicit PHP 8.3 type declarations, default values, and visibility modifiers. In PHP 8.3, class constants can also be explicitly typed:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginModels;

class PaymentTransaction {
    public const string DEFAULT_CURRENCY = 'USD';
    public const int MAX_RETRY_ATTEMPTS = 3;

    public int $transactionId;
    public string $currency;
    public int $amountMinorUnits;
    public string $status;
    public ?string $gatewayReference;
    public array $metadata;

    public function __construct(
        int $transactionId,
        string $currency = self::DEFAULT_CURRENCY,
        int $amountMinorUnits = 0,
        string $status = 'pending',
        ?string $gatewayReference = null,
        array $metadata = []
    ) {
        $this->transactionId     = $transactionId;
        $this->currency          = $currency;
        $this->amountMinorUnits  = $amountMinorUnits;
        $this->status            = $status;
        $this->gatewayReference = $gatewayReference;
        $this->metadata          = $metadata;
    }
}

Pattern 2: Readonly Data Transfer Objects (DTOs)

For data structures representing immutable entities (such as API payloads, webhook events, or query filters), modern PHP 8.2+ allows declaring classes as readonly. Every property in a readonly class is automatically typed and immutable:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginDTOs;

final readonly class WebhookEventPayload {
    public function __construct(
        public string $eventId,
        public string $eventType,
        public int $timestamp,
        public array $payloadData,
        public bool $isLiveMode = true
    ) {}

    public static function fromJson(string $rawJson): self {
        $data = json_decode($rawJson, true, 512, JSON_THROW_ON_ERROR);

        return new self(
            eventId: (string) ($data['id'] ?? ''),
            eventType: (string) ($data['type'] ?? 'unknown'),
            timestamp: (int) ($data['created'] ?? time()),
            payloadData: (array) ($data['data'] ?? []),
            isLiveMode: (bool) ($data['livemode'] ?? true)
        );
    }
}

Pattern 3: Encapsulated Magic Container Pattern

When building extensible plugins where third-party add-ons must attach arbitrary key-value attributes to an object, do not use dynamic properties. Instead, encapsulate dynamic storage inside explicit magic methods (__get, __set, __isset, __unset) backed by a private internal array:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginCore;

abstract class ExtensibleModel {
    /** @var array<string, mixed> Internal storage for dynamic attributes */
    private array $dynamicAttributes = [];

    public function __set(string $name, mixed $value): void {
        $this->dynamicAttributes[$name] = $value;
    }

    public function __get(string $name): mixed {
        return $this->dynamicAttributes[$name] ?? null;
    }

    public function __isset(string $name): bool {
        return isset($this->dynamicAttributes[$name]);
    }

    public function __unset(string $name): void {
        unset($this->dynamicAttributes[$name]);
    }

    /**
     * Export all attributes including dynamic extensions.
     *
     * @return array<string, mixed>
     */
    public function getDynamicAttributes(): array {
        return $this->dynamicAttributes;
    }
}

By routing property access through __set() and __get(), PHP 8.3’s deprecation engine is satisfied (because access is handled explicitly by userland code rather than unconstrained Zend Engine property injection), while preserving 100% backward compatibility for downstream consumers.

Pattern 4: ArrayAccess Hybrid Object/Array Emulation

Many legacy WordPress plugins accept configuration objects that can be accessed interchangeably as associative arrays ($config['timeout']) or class properties ($config->timeout). We can combine ArrayAccess with encapsulated magic methods:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginCore;

use ArrayAccess;

class HybridConfigObject implements ArrayAccess {
    /** @var array<string, mixed> */
    protected array $attributes = [];

    public function __construct(array $initialData = []) {
        $this->attributes = $initialData;
    }

    // Magic property access
    public function __get(string $name): mixed {
        return $this->attributes[$name] ?? null;
    }

    public function __set(string $name, mixed $value): void {
        $this->attributes[$name] = $value;
    }

    public function __isset(string $name): bool {
        return isset($this->attributes[$name]);
    }

    public function __unset(string $name): void {
        unset($this->attributes[$name]);
    }

    // ArrayAccess implementation
    public function offsetExists(mixed $offset): bool {
        return isset($this->attributes[(string) $offset]);
    }

    public function offsetGet(mixed $offset): mixed {
        return $this->attributes[(string) $offset] ?? null;
    }

    public function offsetSet(mixed $offset, mixed $value): void {
        if ($offset === null) {
            $this->attributes[] = $value;
        } else {
            $this->attributes[(string) $offset] = $value;
        }
    }

    public function offsetUnset(mixed $offset): void {
        unset($this->attributes[(string) $offset]);
    }
}

Pattern 5: stdClass to Strict Value Object Migration

Note that PHP’s built-in stdClass is explicitly exempt from the dynamic property deprecation—creating dynamic properties on an instance of stdClass is fully permitted in PHP 8.3 and PHP 9.0. However, passing untyped stdClass objects across plugin layers creates brittle code. Refactor stdClass instances into typed Value Objects:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginValueObjects;

final readonly class CurrencyAmount {
    public int $minorUnits;
    public string $currencyCode;

    public function __construct(int $minorUnits, string $currencyCode) {
        if ($minorUnits < 0) {
            throw new InvalidArgumentException('Monetary amounts cannot be negative.');
        }
        $this->minorUnits   = $minorUnits;
        $this->currencyCode = strtoupper(trim($currencyCode));
    }

    public function toDecimal(): float {
        return $this->minorUnits / 100.0;
    }

    public function format(): string {
        return sprintf('%s %0.2f', $this->currencyCode, $this->toDecimal());
    }
}

Refactoring Legacy Database Query Builders

A ubiquitous architectural flaw in legacy WordPress plugins is building custom database query helpers that dynamically bind where clauses, order parameters, and table joins directly onto the query object: $query->where_status = 'active'; $query->order_by = 'created_at';. Under PHP 8.3, each parameter assignment generates a deprecation notice.

We refactor legacy query helpers using an immutable QueryFilterDTO and a strictly typed Query Repository:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginDatabase;

use wpdb;

final readonly class LogQueryCriteria {
    public function __construct(
        public ?string $logLevel = null,
        public ?int $userId = null,
        public int $limit = 50,
        public int $offset = 0,
        public string $orderBy = 'id',
        public string $orderDirection = 'DESC'
    ) {}
}

class CustomAuditLogRepository {
    private wpdb $db;
    private string $tableName;

    public function __construct(wpdb $db) {
        $this->db        = $db;
        $this->tableName = $db->prefix . 'wpstack_audit_logs';
    }

    /**
     * Executes strict type-safe queries without dynamic property binding.
     *
     * @param LogQueryCriteria $criteria
     * @return array<int, array<string, mixed>>
     */
    public function findByCriteria(LogQueryCriteria $criteria): array {
        $where = ['1=1'];
        $params = [];

        if ($criteria->logLevel !== null) {
            $where[]  = 'log_level = %s';
            $params[] = $criteria->logLevel;
        }

        if ($criteria->userId !== null) {
            $where[]  = 'user_id = %d';
            $params[] = $criteria->userId;
        }

        $direction = strtoupper($criteria->orderDirection) === 'ASC' ? 'ASC' : 'DESC';
        $allowedColumns = ['id', 'created_at', 'log_level', 'user_id'];
        $orderColumn = in_array($criteria->orderBy, $allowedColumns, true) ? $criteria->orderBy : 'id';

        $whereSql = implode(' AND ', $where);
        $params[] = $criteria->limit;
        $params[] = $criteria->offset;

        $sql = "SELECT * FROM {$this->tableName} WHERE {$whereSql} ORDER BY {$orderColumn} {$direction} LIMIT %d OFFSET %d";
        $prepared = $this->db->prepare($sql, $params);

        return (array) $this->db->get_results($prepared, ARRAY_A);
    }
}

Reflection-Based Typed Property Hydrator

When hydrating model objects from raw MySQL database query results ($wpdb->get_results(..., ARRAY_A)), legacy code frequently iterated over key-value pairs and assigned them dynamically: foreach ($row as $k => $v) $model->$k = $v;. Under PHP 8.3, any unmapped column immediately throws a deprecation warning.

We solve this using a high-performance Reflection Hydrator that inspects declared properties, verifies types, and ensures uninitialized properties are safely initialized:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginHydration;

use ReflectionClass;
use ReflectionProperty;

class ReflectionModelHydrator {
    /** @var array<string, ReflectionProperty[]> Cached property reflection maps */
    private static array $reflectionCache = [];

    /**
     * Safely hydrates an object from database arrays without dynamic property creation.
     *
     * @template T of object
     * @param class-string<T> $className
     * @param array<string, mixed> $data
     * @return T
     */
    public static function hydrate(string $className, array $data): object {
        $reflection = new ReflectionClass($className);
        $object = $reflection->newInstanceWithoutConstructor();

        if (!isset(self::$reflectionCache[$className])) {
            self::$reflectionCache[$className] = $reflection->getProperties();
        }

        foreach (self::$reflectionCache[$className] as $property) {
            $propName = $property->getName();

            if (array_key_exists($propName, $data)) {
                $property->setValue($object, $data[$propName]);
            } elseif (!$property->hasDefaultValue() && $property->getType()?->allowsNull()) {
                $property->setValue($object, null);
            }
        }

        return $object;
    }
}

Uninitialized Typed Properties & Serialization Pitfalls

When refactoring dynamic properties to typed properties, developers frequently encounter a new fatal exception in PHP 8.3: Error: Typed property ClassName::$prop must not be accessed before initialization. This occurs when reading a property that has not been assigned a default value or passed to the constructor.

Furthermore, when objects with uninitialized typed properties are serialized via serialize() or json_encode() (common in WordPress transients and Redis object caching), the serializer crashes. We resolve this by implementing PHP 8.1+ __serialize() and __unserialize():

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginModels;

class CustomerSession {
    public int $customerId;
    public string $sessionToken;
    public ?string $ipAddress = null; // Default to null to avoid uninitialized state
    public array $cartSnapshot = [];

    public function __construct(int $customerId, string $sessionToken) {
        $this->customerId   = $customerId;
        $this->sessionToken = $sessionToken;
    }

    public function __serialize(): array {
        return [
            'customerId'   => $this->customerId,
            'sessionToken' => $this->sessionToken,
            'ipAddress'    => $this->ipAddress,
            'cartSnapshot' => $this->cartSnapshot,
        ];
    }

    public function __unserialize(array $data): void {
        $this->customerId   = (int) ($data['customerId'] ?? 0);
        $this->sessionToken = (string) ($data['sessionToken'] ?? '');
        $this->ipAddress    = $data['ipAddress'] ?? null;
        $this->cartSnapshot = (array) ($data['cartSnapshot'] ?? []);
    }
}

Case Study: Refactoring a Legacy WooCommerce Order Processor

To illustrate the complete refactoring lifecycle, consider a typical legacy WooCommerce order processing class with 8 undeclared dynamic properties, and its modern PSR-4 transformation:

1. The Legacy Anti-Pattern Code

<?php
// LEGACY: Emits 8 E_DEPRECATED notices in PHP 8.3 and crashes in PHP 9.0
class Legacy_Woo_Order_Hook {
    public function __construct() {
        add_action('woocommerce_thankyou', [$this, 'process_order']);
    }

    public function process_order($order_id) {
        $this->order_id = $order_id;
        $this->order = wc_get_order($order_id);
        $this->customer_email = $this->order->get_billing_email();
        $this->total = $this->order->get_total();
        $this->tax_exempt = $this->order->get_meta('is_vat_exempt');
        $this->processed_at = time();

        $this->dispatch_external_webhook();
    }

    private function dispatch_external_webhook() {
        wp_remote_post('https://erp.example.com/api', [
            'body' => json_encode([
                'order_id' => $this->order_id,
                'email'    => $this->customer_email,
                'total'    => $this->total,
            ])
        ]);
    }
}

2. The Modern PSR-4 Refactored Architecture

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginIntegrationsWooCommerce;

use WC_Order;
use WPStackEnterprisePluginDTOsOrderExportDTO;
use WPStackEnterprisePluginServicesErpSyncService;

class OrderFulfilledSubscriber {
    private ErpSyncService $erpService;

    public function __construct(ErpSyncService $erpService) {
        $this->erpService = $erpService;
    }

    public function register(): void {
        add_action('woocommerce_thankyou', [$this, 'handleOrderThankYou'], 10, 1);
    }

    public function handleOrderThankYou(int $orderId): void {
        $order = wc_get_order($orderId);
        if (!$order instanceof WC_Order) {
            return;
        }

        $dto = new OrderExportDTO(
            orderId: $orderId,
            customerEmail: $order->get_billing_email(),
            totalMinorUnits: (int) round(((float) $order->get_total()) * 100),
            currency: $order->get_currency(),
            isTaxExempt: (bool) $order->get_meta('is_vat_exempt'),
            processedTimestamp: time()
        );

        $this->erpService->dispatchOrderPayload($dto);
    }
}

Handling WordPress Core Entities Safely

WordPress core classes such as WP_Post, WP_User, and WP_Comment explicitly include the #[AllowDynamicProperties] attribute. This allows WordPress to support legacy dynamic properties like $post->filter = 'raw' or $post->custom_field = 'value'.

However, enterprise plugins should never attach custom business state directly onto global WP_Post instances. In WordPress, post objects are frequently cached in Redis or re-instantiated from the database across request filters, causing dynamically attached properties to disappear unpredictably.

<?php
// ANTI-PATTERN: Attaching dynamic properties to core WP_Post
add_action('the_post', function (WP_Post $post) {
    $post->wpstack_calculated_reading_time = 5; // DANGEROUS: Vanishes when post is reloaded from cache
});

// ENTERPRISE PATTERN: Use a WeakMap or Dedicated Cache Service
namespace WPStackEnterprisePluginServices;

class PostReadingTimeRegistry {
    /** @var WeakMap<WP_Post, int> Memory-safe association without polluting core objects */
    private WeakMap $readingTimes;

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

    public function setReadingTime(WP_Post $post, int $minutes): void {
        $this->readingTimes[$post] = $minutes;
    }

    public function getReadingTime(WP_Post $post): int {
        return $this->readingTimes[$post] ?? 0;
    }
}

Memory and JIT Performance Benchmarks

We benchmarked memory consumption and property access latency between unoptimized dynamic properties and compiled typed properties across 100,000 object instantiations under PHP 8.3 JIT:

Automated Codebase Auditing with PHPStan and Psalm

To detect dynamic property creations across large enterprise plugins before deployment, configure PHPStan Level 8 with the official WordPress extensions:

# phpstan.neon
includes:
    - vendor/szepeviktor/phpstan-wordpress/extension.neon

parameters:
    level: 8
    paths:
        - src/
    checkGenericClassInNonGenericObjectType: false
    reportUnmatchedIgnoredErrors: false
    ignoreErrors:
        # Whitelist intentional core WordPress dynamic properties
        - '#Access to an undefined property WP_Post::$#'

Complement PHPStan with Psalm configured at Level 1 for deep dataflow analysis:

<!-- psalm.xml -->
<psalm
    errorLevel="1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://getpsalm.org/schema/config"
>
    <projectFiles>
        <directory name="src" />
    </projectFiles>
    <issueHandlers>
        <UndefinedPropertyAssignment errorLevel="error" />
        <UndefinedPropertyFetch errorLevel="error" />
    </issueHandlers>
</psalm>

Run the static analysis audits via terminal:

vendor/bin/phpstan analyse --memory-limit=1G
vendor/bin/psalm

Automated AST Refactoring with Rector

When refactoring a legacy WordPress plugin containing hundreds of thousands of lines of code, manually finding and declaring missing properties is error-prone. Rector provides automated Abstract Syntax Tree (AST) transformations to automatically infer and declare properties:

<?php
// rector.php
declare(strict_types=1);

use RectorConfigRectorConfig;
use RectorCodeQualityRectorClass_CompleteDynamicPropertiesRector;
use RectorSetValueObjectSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/src',
    ]);

    // Automatically inspects assignments and injects explicit property declarations
    $rectorConfig->rule(CompleteDynamicPropertiesRector::class);

    $rectorConfig->sets([
        SetList::PHP_82,
        SetList::PHP_83,
    ]);
};

Execute the automated migration with a single command:

vendor/bin/rector process --dry-run
vendor/bin/rector process

GitHub Actions CI/CD Quality Gate

Integrate strict automated checks into your repository workflow to ensure no dynamic property regressions ever reach production:

# .github/workflows/quality-gates.yml
name: Code Quality & PHP 8.3 Compatibility

on: [push, pull_request]

jobs:
  php-compatibility:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: ['8.2', '8.3', '8.4']
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: mbstring, intl, redis, pdo_mysql
          coverage: none

      - name: Install Composer Dependencies
        run: composer install --prefer-dist --no-progress

      - name: Run PHPStan Level 8
        run: vendor/bin/phpstan analyse --no-progress

      - name: Run Rector Dry-Run
        run: vendor/bin/rector process --dry-run

      - name: Run PHPUnit Test Suite
        run: vendor/bin/phpunit --configuration phpunit.xml

Automated Testing with PHPUnit

Configure your PHPUnit test suite to convert E_DEPRECATED notices into immediate test failures to guarantee zero dynamic property regressions:

<?php
declare(strict_types=1);

namespace WPStackEnterprisePluginTestsUnit;

use PHPUnitFrameworkTestCase;
use WPStackEnterprisePluginModelsPaymentTransaction;
use WPStackEnterprisePluginDTOsWebhookEventPayload;

class Test_DynamicPropertyStrictness extends TestCase {
    protected function setUp(): void {
        parent::setUp();
        // Convert all deprecations into fatal exceptions during test run
        set_error_handler(static function (int $errno, string $errstr, string $errfile, int $errline) {
            if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
                throw new ErrorException("Deprecation Error: {$errstr} in {$errfile}:{$errline}", 0, $errno, $errfile, $errline);
            }
            return false;
        });
    }

    protected function tearDown(): void {
        restore_error_handler();
        parent::tearDown();
    }

    public function test_transaction_model_instantiates_without_deprecations(): void {
        $tx = new PaymentTransaction(
            transactionId: 1001,
            currency: 'USD',
            amountMinorUnits: 4999,
            status: 'completed',
            gatewayReference: 'ch_998811'
        );

        $this->assertSame(1001, $tx->transactionId);
        $this->assertSame('USD', $tx->currency);
        $this->assertSame(4999, $tx->amountMinorUnits);
    }

    public function test_webhook_dto_parses_json_immutably(): void {
        $json = json_encode([
            'id'       => 'evt_test_123',
            'type'     => 'payment_intent.succeeded',
            'created'  => 1700000000,
            'livemode' => false,
            'data'     => ['amount' => 5000],
        ]);

        $dto = WebhookEventPayload::fromJson($json);

        $this->assertSame('evt_test_123', $dto->eventId);
        $this->assertSame('payment_intent.succeeded', $dto->eventType);
        $this->assertFalse($dto->isLiveMode);
    }
}

Production Troubleshooting and Diagnostics

Frequently Asked Questions

Aditya Bhimrajka

Aditya Bhimrajka is the Chief Search Systems Architect at MoxSEO, leading research in enterprise technical SEO, knowledge graphs, large-scale indexing physics, and generative engine optimization.