PHP: bool vs boolean type hinting
When modernizing legacy PHP codebases or writing new features, you will almost certainly encounter the need to enforce strict types. Type hints are a cornerstone of this practice, allowing you to catch logical errors at runtime rather than letting them propagate silently until a production failure occurs. However, not all syntax that looks valid is actually compatible with specific language rules regarding default values and class-based type hints.
A common stumbling block arises when attempting to define a function that accepts a boolean value with a default of false. If you use the full name boolean as the type hint, PHP throws a fatal error: "Default value for parameters with a class type hint can only be NULL." Conversely, using the short form bool works perfectly fine. This discrepancy often confuses developers because casting both (bool) and (boolean) on a variable yields identical results, suggesting they are functionally identical. They are not.
The root of this issue lies in how PHP distinguishes between scalar types and class names. In the context of type hints, bool is recognized as a primitive scalar type. It does not map to a specific object or class definition within the engine's internal structure; rather, it represents a fundamental data category. Because it lacks an associated class namespace, PHP treats it differently regarding default values, allowing constants like false, true, and 0 to serve as defaults.
On the other hand, boolean is technically a reserved word that maps to the name of a specific class. While you rarely encounter a class explicitly named "boolean" in standard PHP installations, the language parser treats the longer alias as a reference to a type that could be instantiated as an object. The rule enforcing that default values for class-type-hinted parameters must be NULL is a safeguard against initialization issues with objects. If you were to pass a non-null value to a function expecting an instance of a specific class without providing one, the behavior would differ significantly from passing a primitive scalar.
This distinction has practical implications when using external libraries or frameworks that might introduce custom boolean wrapper classes. Imagine a hypothetical scenario where a library defines class Boolean { }. If your code relies on the user passing an instance of this class, and you define the function signature as function handle(Boolean $flag = false), PHP will crash if no value is passed, because false is not an instance of the Boolean class. It would only accept null as a default.
In these specific cases involving custom wrappers or library-specific types, you might find yourself in a situation analogous to Java's wrapper classes (such as Boolean vs. boolean). In Java, using the primitive type allows for null defaults and unboxing behavior, whereas the object wrapper requires explicit instantiation or null assignment. PHP does not have built-in wrapper objects for booleans by default, but it does provide the parser distinction between the scalar keyword and the reserved word that mimics class naming conventions.
When writing robust code today, always prefer bool over boolean unless you are explicitly dealing with a custom class named Boolean. This habit eliminates the "Default value can only be NULL" error and ensures your function signatures align with standard type hinting expectations. If you are maintaining a large codebase where team members might mix these up, adding an ESLint rule or PHPStan configuration to enforce bool specifically can prevent these subtle but fatal runtime errors from slipping through automated checks.