Skip to content

compatibility.md

Latest commit

 

History

History
87 lines (54 loc) · 2.37 KB

compatibility.md

File metadata and controls

87 lines (54 loc) · 2.37 KB

Compatibility Notes

Project Scope

This repository is a PHP 8 migration layer for old PHP applications.

It supports realistic compatibility for code originally written for:

  • PHP 5.x
  • PHP 7.x
  • early PHP 8 versions with newly deprecated behavior

Polyfills vs Approximations

This project intentionally distinguishes between different compatibility types.

True Polyfill

A true polyfill restores removed behavior closely enough that old code can keep working with the same basic expectations.

Examples:

  • each()
  • create_function()
  • is_real()
  • image2wbmp() when GD is available

Partial Polyfill

A partial polyfill restores the useful core behavior, but some edge cases cannot be reproduced exactly because the old runtime or engine features are gone.

Examples:

  • session_register()
  • session_unregister()
  • session_is_registered()

Safe Fallback

A safe fallback reports the modern truth honestly instead of pretending an old engine feature still exists.

Examples:

  • get_magic_quotes_gpc()
  • get_magic_quotes_runtime()
  • set_magic_quotes_runtime()

Compatibility Approximation

A compatibility approximation recreates the most useful practical behavior, while clearly documenting limits where exact restoration is impossible.

Examples:

  • ereg() and related POSIX regex wrappers
  • legacy_compat_strftime()
  • legacy_compat_gmstrftime()
  • money_format() in universal mode only

Universal vs Strict

Universal

The universal file is intended for real-world migration rescue work. It keeps a broader compatibility surface and includes carefully documented approximations when those approximations are still honest and operationally useful.

Strict

The strict file is intended for teams that want a safer default. It excludes looser behavior where the risk of silent semantic drift is higher.

Examples of stricter choices:

  • money_format() is omitted
  • helper behavior is tighter for counting, array merging, and implode handling
  • session compatibility behavior is more conservative

Framework and Ecosystem Relevance

The compatibility files are especially relevant to:

  • WordPress
  • Laravel
  • Symfony
  • CodeIgniter
  • Magento
  • custom PHP frameworks
  • internal enterprise platforms

They are not framework-specific files, but they are designed around the kinds of legacy breakage commonly seen in those ecosystems during PHP 8 upgrades.