BR-12610 - (CSI 96912) Unstable environment triggers a RecursiveDirec…

[klimslim]

…toryIterator PHP error

[klimslim]

⚠️ KT Handoff — Alexey Klimko (Distinguished Engineer, departing)

What this PR does

BR-12610 / CSI-96912 — Fixes a PHP error in the shadow C extension triggered when RecursiveDirectoryIterator encounters an unstable filesystem environment (e.g. files disappearing between directory scan and open, race conditions in build environments).

Changes:

• shadow.c / shadow_cache.c / shadow_cache.h / php_shadow.h — guards added in the C extension to handle the iterator entering an error state gracefully rather than surfacing a fatal PHP error
• tests/spl_recursive_iterator.phpt — new .phpt test reproducing the unstable-environment scenario to prevent regression

Shadow is the differential build/overlay tool used across SugarCRM development to layer changes without full rebuilds. Breakage here blocks developer workflows directly.

Current state

Open. The fix is targeted and self-contained. A companion test is included.

KT reference

Context on the shadow tool and its role in the dev tooling ecosystem:
👉 https://sugarcrm.atlassian.net/wiki/spaces/~55705856d228f75a114fd9847849503eb91898/pages/7286292484

KT index: https://sugarcrm.atlassian.net/wiki/x/moBVsQE

Recommendation

Review and merge promptly. This is a bug fix with a regression test — low risk, clear scope. The CSI ticket indicates this is causing real pain in unstable CI/dev environments. No successor ramp-up needed beyond a quick read of shadow_cache.c diff to confirm the guard logic is sound.