Deprecate Undefined Constant Usage in php.ini Files

[hakre]

Deprecate Undefined Constant Usage in php.ini Files

The php.ini file parser (as used by parse_ini_file()) supports constant resolution, including core predefined constants. However, the current behavior with undefined constants is inconsistent with PHP 8's strict handling of undefined constants in regular PHP code.

Problem Statement

Current Inconsistent Behavior

In PHP 8 scripts, undefined constants trigger immediate fatal errors:

<?php
$var = X_ERROR; // Fatal error: Undefined constant "X_ERROR"

However, in php.ini files, undefined constants are silently handled using PHP 4-era semantics:

[PHP]
error_reporting = X_ERROR|E_WARNING|E_PARSE|E_NOTICE

This silently:

1. Converts X_ERROR to string "X_ERROR"
2. Converts that string to integer 0 in bitwise context
3. Results in value 14 (0 | 4 | 2 | 8) without any indication of the error

This creates invisible configuration errors that are difficult to debug.

Proposed Change

Proposal: Add Diagnostics for Undefined Constants

We propose emitting diagnostics when undefined constants are encountered in configuration files:

During startup (php.ini parsing):

PHP: Use of undefined constant NAME_OF_CONSTANT - assumed 'NAME_OF_CONSTANT' (this will throw an Error in a future version of PHP)

During runtime (parse_ini_file/string):

PHP Warning: Use of undefined constant NAME_OF_CONSTANT - assumed 'NAME_OF_CONSTANT' (this will throw an Error in a future version of PHP) in filename on line X

This makes configuration errors visible and paves the way for future strict handling.

Message Severity Discussion

The proposed warning message and severity mirror the PHP 7.2 approach for undefined constants in scripts:

Warning: Use of undefined constant UNDEFINED_CONSTANT - assumed 'UNDEFINED_CONSTANT' (this will throw an Error in a future version of PHP)

Alternative severity levels could be considered:

Severity	Wording	Intent
E_DEPRECATED	"may throw"	Softer transition
E_WARNING	"will throw"	Clear future intent
E_NOTICE	"will throw"	Less intrusive

The PHP 7.2 precedent suggests E_WARNING is appropriate for this level of issue.

Benefits

• Early detection: Configuration errors become visible immediately
• Consistency: Aligns ini parsing behavior with PHP 8 language semantics
• Fail-fast: Helps users identify and fix configuration mistakes sooner
• Future-proof: Enables eventual strict mode matching PHP script behavior

Implementation Notes

The change would be implemented in zend_ini_get_constant() by adding diagnostics when constant resolution fails. The current ini_error() function uses ZEND_COLD (compiler hint for infrequently executed code), which remains appropriate since undefined constants should be rare in production configurations.

This infrastructure would also support a future transition to throwing Errors, though the error handling mechanism might need adjustment at that time.

Note: This section is preliminary and subject to implementation details.

References

Discussion

1. https://news-web.php.net/php.internals/128781

PHP Manual Pages

1. parse_ini_file()
2. The Configuration File
3. Core Predefined Constants

3v4l.org PHP Codes

1. https://3v4l.org/7PA3u Undefined constant
2. https://3v4l.org/vC6mg Unsupported operand types

[hakre]

How much this is a bug and where the root located, I have not looked so far. My guess would be that this was not streamlined when introducing the fatal in PHP 8.0 for script constants, perhaps overlooked as we didn't thought about the use of constants in ini files.

The other flaw for me is that the PATH_SEPARATOR constant is not available, haven't looked for it yet in the sources, my guess is that it is not in Core and therefore just is not available at ini-parse-time.

For that constants it would be great thought for portability in ini files as it would give the opportunity to have the ini file (more) architecture independent. Not yet sure if that is really complete as an idea, this is how I spotted it as trying that out.

[nielsdos]

INI's don't report errors on missing constants, so there is no bug in that regard.
The reason you get PATH_SEPARATOR is because of the fallback value.
I guess the INI is evaluated before the extensions are initialized, and therefore, before the extension constants are loaded. That would explain this behaviour.
I'm not sure this is supposed to work. It looks to me like a feature request.
If it must work, then there's also a dependency problem: if you want to use a constant defined in some shared extension, then the extensions need to be loaded first, but then we have to split INI parsing in two stages: one to load extensions and one to resolve the INI values.

[hakre]

INI's don't report errors on missing constants, so there is no bug in that regard.

Yes, I've also seen that now in the code (zend_ini_get_constant()) but shouldn't it? As not yet so far, probably stepping into it first with a notice, then stepping up as warning and finally error.

I've also seen that errors in a php.ini don't stop with failure, is that correct?

And wouldn't it be good (e.g. fail early) to have that?

For the other points: I'd like to stay away from a feature request at this beginning and more to align with principle of least astonishment. If only predefined constants (ref: man) are available that looks first of all fine to me, the problem is more that the visibility a certain constant is (yet still) undefined is not that good. Stopping with a clear diagnostic message (like since PHP 8 parsing/interpreting a script) looks more correct to me. Otherwise confiuration errors are only populated and postponed / distanced. @nielsdos

[hakre]

@nielsdos Thanks for your feedback, much appreceated. As you rightfully noted, this is not a bug and therefore demands a feature request, I changed the title and the description accordingly. My current understanding is that the main benefit lies in obtaining better visibility and alignment with PHP 8 expectations users may have.

Note

That the PATH_SEPARATOR is undefined I put out of the equation here as that is more a topic of it's own (but interesting: php_ini.c uses DEFAULT_DIR_SEPARATOR while dir.c uses ZEND_PATHS_SEPARATOR to register PATH_SEPARATOR after using DEFAULT_SLASH to register DIRECTORY_SEPARATOR)

/E: Request for comments in internals https://news-web.php.net/php.internals/128781

/E2: -> why not DEFAULT_DIR_SEPARATOR then instead of ZEND_PATHS_SEPARATOR?
-> and why not having PATH_SEPARATOR as core constants then instead of in ./ext/standard/dir.c; technical reason?

[nielsdos]

Yes, I've also seen that now in the code (zend_ini_get_constant()) but shouldn't it? As not yet so far, probably stepping into it first with a notice, then stepping up as warning and finally error.

I think that the silent failure is not great indeed. Even small typos can cause a lot of headache in that regard.

I've also seen that errors in a php.ini don't stop with failure, is that correct?

Right.

And wouldn't it be good (e.g. fail early) to have that?

Hard failing would probably be too harsh of a change all of the sudden, but at least logging that something isn't right seems desirable to me.

It's good that you opened the internals thread, it would be good to harden this part of PHP.

[hakre]

Hard failing would probably be too harsh of a change all of the sudden, but at least logging that something isn't right seems desirable to me.

This also matches my current understanding and is actually the reason why I suggested the deprecation instead of abrupt exit.

My hope is that it finds conseus at warning severity as this gives the visibility and is a wider (but still safe) step (than deprecation / "may" wording) towards alignment with PHP 8 semantics. @nielsdos

And thiking, there is already syntax error for ini parsing, it probably is a good(?) idea to also deprecate there and add to the message that it may/will throw an error in the future PHP version. Some food for thought.