define
Defines a named constant at runtime that cannot be changed or unset afterwards.
define(string $constant_name, mixed $value, bool $case_insensitive = false): bool- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$constant_name | string | The name of the constant. Valid names start with a letter or underscore; using a name with a hyphen or other punctuation creates a constant that can only be read via constant(). |
$value | mixed | The value to store. Scalars, null, arrays and, since PHP 8.1, objects are allowed; resources are permitted but not useful. |
$case_insensitiveoptional | bool= false | Legacy flag for defining a case-insensitive constant. Only false is meaningful today. |
Return value
booltrue on success, false if the constant could not be defined (for example because the name is already taken).
Errors
Does not throw. Redefining an existing constant fails, raises a diagnostic and returns false.
Changelog
- PHP 8.1.0value may now be an object.
- PHP 8.0.0Passing true for case_insensitive emits an E_WARNING and no longer creates a case-insensitive constant.
- PHP 7.3.0The case_insensitive parameter was deprecated.
define() creates a constant while the script is running. Unlike the const keyword, the name and the value can both be computed, so define() is what you use in bootstrap code, configuration loaders and conditional setup.
define() versus const
| define() | const | |
|---|---|---|
| Evaluated | At runtime | At compile time |
| Conditional / inside a function | Yes | No |
| Computed name | Yes | No |
| Namespace | Always global unless the name contains one | Current namespace |
What trips people up
The biggest surprise is namespacing. Inside namespace App;, define('MAX', 5) defines a global MAX, not App\MAX — you must spell the namespace out in the string. Second, constants are permanent: there is no undefine(), and a second define() with the same name fails quietly with a diagnostic and returns false. Third, define() is slower than const because it runs every request and cannot be cached by the opcode cache in the same way, so prefer const for values known when you write the file.
Example
When to use it
- Setting APP_ROOT or ENVIRONMENT once in a front controller before anything else loads.
- Turning a value read from an .ini or JSON config file into a process-wide constant.
- Defining a constant only if a host application has not already defined it, using defined() || define().
Frequently asked questions
What is the difference between define and const in PHP?
const is handled at compile time and needs a literal name, while define() runs at runtime and accepts a computed name and a conditional context. Use const for fixed values in a file, define() when the name or value is decided while the script runs.
Can you redefine a constant created with define?
No. A second define() with the same name returns false and raises a diagnostic; the original value stays. There is no way to unset or change a constant once it exists.
Can a constant hold an array or an object?
Yes, arrays have been allowed since PHP 7 and objects since PHP 8.1. The array itself is immutable, so you cannot append to it after defining.
More examples
Building a constant name at runtime
The output shows bool(true) and bool(false): the loop created FEATURE_CACHE and FEATURE_DEBUG from array keys, something const cannot do because it needs a literal name.
<?php
$features = ['cache' => true, 'debug' => false];
foreach ($features as $name => $enabled) {
define('FEATURE_' . strtoupper($name), $enabled);
}
var_dump(FEATURE_CACHE, FEATURE_DEBUG);
var_dump(constant('FEATURE_' . 'CACHE'));Objects as constant values (PHP 8.1+)
Since PHP 8.1 an object (here an enum case) can be stored in a constant, so MIN_LEVEL holds the case itself and compares identical to Level::Warning.
<?php
enum Level {
case Warning;
case Error;
}
define('MIN_LEVEL', Level::Warning);
var_dump(MIN_LEVEL === Level::Warning);
echo MIN_LEVEL->name, "\n";
Discussion