Cannot pass null argument when using type hinting
In PHP, declaring a parameter as Type $t establishes a strict contract: the function expects an instance of Type. When you invoke foo(null), PHP immediately raises a fatal error stating that the argument must not be null. This behavior often confuses developers coming from statically typed languages like Java or C#, where null might be implicitly cast to any reference type, or from dynamic languages like Python, where None is frequently accepted unless explicitly guarded against. The confusion stems from a misunderstanding of what PHP's type system actually enforces and how it differs from "loose" typing patterns common in older versions of the language.
Historically, PHP was famous for its dynamic nature. If you passed a string to a function expecting an integer, PHP would often attempt to cast the value automatically. However, nullability has always been a specific opt-in feature rather than the default state. When you write Type $t, you are telling the engine that this variable holds a reference to a class object. In PHP's type system, null is not a subtype of any class unless explicitly declared as such. Therefore, passing null violates the contract defined by the function signature. The error message "Argument 1 passed to foo() must not be null" is not a suggestion; it is a hard failure because the engine cannot safely assume that a raw object reference can represent an absence of value without explicit permission.
If you need a function to accept either an instance of Type or nothing (null), you must explicitly declare union types. This syntax was introduced in PHP 8.0 and refined further with nullable types in PHP 7.4 and later. To allow null, the signature should look like this:
function foo(?Type $t): void {
// ...
}
The leading question mark ? is the critical modifier here. It tells the type checker that the parameter accepts a union of Type and null. Without it, the default assumption is that the parameter represents a non-nullable object. This distinction is crucial for preventing runtime crashes in applications where missing data should be handled gracefully rather than causing a fatal error immediately upon function entry.
Consider a scenario involving database records. A method getAuthor() might return an Author object or nothing if the book is anonymous. If you define this as function getAuthor(): Author, calling it and assigning the result to a nullable variable works fine: $author = getAuthor();. However, if that returned value were immediately passed to another function defined without a nullable hint, the chain breaks. The error occurs at the point of invocation, not assignment.
There is also a distinction between passing null and passing an uninitialized variable. In older PHP versions (prior to 7.0), uninitialized variables were treated as empty strings or null depending on context, but modern PHP enforces type safety strictly. Passing null explicitly is the same as omitting the value in a nullable context, but forbidden in a non-nullable one.
The trade-off here is verbosity versus safety. Explicitly adding ? makes your intent clear to both the IDE and future maintainers. It forces you to think about whether a missing value is a valid state for that specific operation. If your function requires an object to perform its logic, keeping it non-nullable acts as a guard rail. If the absence of an object is a valid operational state, the nullable modifier is mandatory.
For developers working within the Laravel ecosystem, this concept extends naturally into Eloquent relationships and service contracts. When defining interfaces or trait methods that interact with optional resources, ensuring the return type or argument types use ? prevents the "Argument must not be null" fatal errors that can break request pipelines unexpectedly. If you are maintaining legacy code that relies on loose typing, refactoring to explicit nullable unions is a significant step toward stability, though it requires careful auditing of existing function signatures to ensure no valid use cases rely on implicit casting that might now be considered unsafe.
Ultimately, the error exists because PHP prioritizes explicit contracts over implicit assumptions. By declaring ?Type, you align your code with the engine's expectations, allowing null to pass through safely while maintaining strong typing for actual instances of Type.
