Magic Constants (__FILE__, __DIR__, __LINE__…)
debt(d3/e1/b1/t5)
Closest to 'default linter catches the common case' (d3). The detection_hints list phpcs and rector as tools, both of which are standard PHP linting/refactoring tools that catch the canonical misuse pattern (dirname(__FILE__) instead of __DIR__, 'ClassName' string instead of ClassName::class) without specialist configuration.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix confirms replacing dirname(__FILE__) with __DIR__ or string class literals with ::class — these are mechanical single-token or single-expression substitutions, each correctable in one line with no broader refactor needed.
Closest to 'minimal commitment' (b1). Magic constants are syntax-level constructs localised to the exact line they appear on. They carry no architectural weight, impose no cross-cutting tax, and switching from a misuse pattern to the correct form has zero downstream impact on other parts of the codebase.
Closest to 'notable trap' (t5). The misconception field documents that __DIR__ and dirname(__FILE__) appear equivalent but have subtle differences in compile-time resolution and trailing-slash behaviour. Additionally, __CLASS__ vs get_class($this) in inheritance is a documented gotcha that competent developers commonly encounter — these are known, learnable traps rather than catastrophic or fully contradictory ones.
Also Known As
TL;DR
Explanation
PHP provides eight magic constants: __LINE__ (current line number), __FILE__ (full file path), __DIR__ (directory of the file), __FUNCTION__ (function name), __CLASS__ (class name), __TRAIT__ (trait name), __METHOD__ (class::method), and __NAMESPACE__. They are resolved at compile time (not runtime) so they reflect the file where they are written, not where the code is called from — important when using them in traits or included files. Common uses: building file paths relative to the current file (__DIR__ . '/config.php'), logging, and error messages.
Common Misconception
Why It Matters
Common Mistakes
- Using __DIR__ . '/file.php' when __DIR__ is already the directory — no need to dirname() it.
- Hardcoding file paths as strings that break when the file is moved — use __DIR__ instead.
- Confusing __CLASS__ (compile-time class name) with get_class($this) (runtime actual class) in inheritance.
- Not knowing __NAMESPACE__ — useful for dynamic class loading within a namespace.
Code Examples
// Hardcoded paths — breaks when deployed to different directory:
require '/var/www/app/config.php';
require 'src/helpers.php'; // Relative to CWD, not file location
// Reliable with magic constants:
require __DIR__ . '/config.php';
require __DIR__ . '/src/helpers.php';// Resolved at compile time — not runtime variables
echo __FILE__; // /var/www/app/src/Service.php (absolute)
echo __DIR__; // /var/www/app/src
echo __LINE__; // current line number
echo __CLASS__; // 'App\Domain\OrderService'
echo __METHOD__; // 'App\Domain\OrderService::place'
echo __FUNCTION__; // 'place'
echo __NAMESPACE__; // 'App\Domain'
echo __TRAIT__; // trait name (inside trait)
// Common uses:
require_once __DIR__ . '/../bootstrap.php'; // robust — not affected by cwd
$logger->debug('Hit', ['method' => __METHOD__, 'line' => __LINE__]);
define('BASE_PATH', dirname(__DIR__));