Language: enum_from() — BackedEnum::from / tryFrom (PHP 8.1)

[PurHur]

Category

language

Problem

Backed enums compile (#1356), but BackedEnum::from() / tryFrom() validation is missing or incomplete. Zend maps a scalar to the matching case or throws ValueError / returns null.

php-src reference

• php/php-src Zend/zend_enum.c — zend_enum_from_case(), zend_try_enum_from_case()
• php/php-src Zend/zend_interfaces.c — BackedEnum internal API
• php/php-src Zend/zend_enum.stub.php — from / tryFrom signatures

Repro (today)

Save as repro_enum_from.php (same shape as test/compliance/cases/language/enum_basic.phpt):

<?php
enum Color: string {
    case Red = 'red';
    case Blue = 'blue';
}
echo Color::from('red')->name;
echo Color::tryFrom('nope') === null ? 'null' : 'bad';

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro_enum_from.php'

Runtime	Expected output
Zend PHP	Rednull
This compiler (May 2026)	LogicException / wrong case / compile or php-cfg parse failure before dispatch

Observed (2026-05-29 harness)

On some harness images, enum TUs fail early in php-cfg with:

PHPCfg\Op\Stmt\Enum_::__construct(): Argument #3 ($implements) must be of type array, PHPCfg\Block given

Worker baseline before implementing from/tryFrom:

./script/ci-fast.sh --filter VmEnumBasicTest
./script/ci-fast.sh --filter enum_basic

If enum parse fails in Docker, run script/apply-patches.sh in the image and re-check; do not stub from() with internal_*.

Scope

Area	Path
VM	lib/VM.php — backed enum case table lookup
Compiler	lib/Compiler.php — Enum::from / tryFrom static call lowering
Tests	test/compliance/cases/language/enum_from.phpt, enum_try_from.phpt
JIT/AOT	after VM green; coordinate #3076 AOT enum metadata

Done when

• from('red') returns Color::Red; invalid scalar → ValueError with Zend-like message
• tryFrom('nope') returns null without throw
• ./script/ci-fast.sh --filter enum_from green
• No regression on enum_basic.phpt / VmEnumBasicTest

Links

• Language: Enum declarations (enum / backed enum) #1356, Language: UnitEnum::cases() / BackedEnum::cases() — list enum cases (PHP 8.1, Zend parity) #3308 (cases()), Language: Backed enum declarations AOT lowering (#1356 phase 2) #3076 (AOT) · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

Labels

implementation-ready

[PurHur]

claim: cursor-agent-lane-b — starting this run

[PurHur]

claim: cursor-agent-lane-a — continuing PR #3152 (rebase + conflict resolution this run)

[PurHur]

Rebased PR #3152 onto current master (May 2026):

• Resolved conflicts with enum case infrastructure (Language: enum case objects — ->name / ->value on backed enum cases (Zend zend_enum.c parity) #3420, Language: UnitEnum::cases() / BackedEnum::cases() — list enum cases (PHP 8.1, Zend parity) #3308, Language: clone() on enum unit cases — Error exception (Zend zend_clones.c parity) #3554): EnumCaseEntry::fetchProperty, enumCases[] backing lookup in BackedEnum::caseForValue, executeInternalHandler + stale callArgEntries clear after internal calls.
• Dropped redundant EnumCaseProperty.php (master uses fetchProperty on EnumCaseEntry).

Verification (Docker):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/unit/VmEnumFromTest.php test/compliance/EnumVMTest.php --filter "VmEnumFrom|enum_from|enum_try_from"'
# OK — enum_from/enum_try_from PHPTs green; enum_instanceof.phpt pre-existing master failure (#3550 gap)

php-src: Zend/zend_enum.c — zend_enum_from_case(), zend_try_enum_from_case()

[PurHur]

claim: cursor-agent-lane-a — continuing PR #3152 (int-backed enum_from compliance + verification this run)

[PurHur]

Run update (cursor-agent-lane-a)

Continued PR #3152 — all #3114 acceptance criteria green on current master.

Added

• test/compliance/cases/language/enum_from_int.phpt — int-backed ::from() / ::tryFrom() (Zend zend_enum.c parity for both backing types)

Verification (Docker)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/unit/VmEnumFromTest.php'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/compliance/EnumVMTest.php --filter enum_from_int'
# Issue repro
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php -r '"'"'enum Color: string { case Red = "red"; case Blue = "blue"; } echo Color::from("red")->name; echo Color::tryFrom("nope") === null ? "null" : "bad";'"'"''
# Rednull

Note: enum_instanceof.phpt failure is pre-existing (#3550), unrelated to this PR.

php-src: Zend/zend_enum.c — zend_enum_from_case(), zend_try_enum_from_case()

[PurHur]

claim: cursor-agent-lane-a — continuing PR #3152 this run (rebase + remaining acceptance criteria)

[PurHur]

Run update (cursor-agent-lane-a)

Continued PR #3152 — all #3114 acceptance criteria green.

Changes this run

• Fix ValueError message to match Zend (enum Color without quotes around enum name) — lib/VM/BackedEnum.php
• Add test/compliance/cases/language/enum_from_invalid.phpt — caught ValueError path
• Split unit tests: uncaught (PHPUnit Exception wrapper) vs caught ValueError in user code

Verification (Docker)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/unit/VmEnumFromTest.php'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit test/compliance/EnumVMTest.php --filter "enum_from|enum_try_from"'
# Issue repro
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php -r '"'"'enum Color: string { case Red = "red"; case Blue = "blue"; } echo Color::from("red")->name; echo Color::tryFrom("nope") === null ? "null" : "bad";'"'"''
# Rednull

Note: enum_instanceof.phpt failure is pre-existing (#3550), unrelated.

php-src: Zend/zend_enum.c — zend_enum_from_case(), zend_try_enum_from_case()