Return types in PHP improve code reliability and clarity by specifying what a function must return. 2. Use basic types like string, array, or DateTime to enforce correct return values and catch errors early. 3. Apply nullable types with ? (e.g., ?string) when null is a valid return value. 4. Use void for functions that perform actions without returning data, allowing only return; or no return statement. 5. Leverage union types (e.g., string|int|bool) in PHP 8.0 for functions returning multiple distinct types. 6. Prefer explicit return type declarations over implicit mixed to enhance IDE support and maintainability. 7. Avoid overusing union types and mixed, reserving mixed for cases where any type is genuinely expected. 8. Handle internal PHP functions carefully by aligning return types with their behavior, such as converting false to null for ?int. 9. Do not return null in void functions to prevent confusion, even though it is technically allowed. 10. Adopt return types progressively, starting with core logic and APIs, to make code more predictable and less error-prone while maintaining readability and intent.

PHP’s type system has evolved significantly since its early days, and return type declarations are a cornerstone of writing more predictable and maintainable code. If you've ever worked with loosely typed PHP functions—returning strings, arrays, or null without any clear contract—you’ve likely run into bugs that were hard to trace. That’s where return types come in.

Starting with PHP 7.0, you can now specify what a function should return, helping both the engine and your teammates understand your code’s intent. This guide walks you from using no types (mixed, though not always explicit) to embracing void, with practical examples and best practices.

Why Return Types Matter

Before diving into syntax, it’s worth understanding why return types help:

• Catch bugs early: Returning an array when you expect a string? PHP will throw a TypeError.
• Improve code readability: Anyone reading your function knows what to expect.
• Enable better IDE support: Autocompletion, refactoring, and inline docs become more accurate.
• Encourage intentional design: You think harder about what your function should return.

Without return types, everything is effectively mixed—a value of any type. While flexible, this leads to uncertainty. Return types let you narrow that down.

Basic Return Types: From Strings to Objects

You can declare return types for all common types:

function getUserName(): string {
    return "Alice";
}

function getUserData(): array {
    return ['name' => 'Alice', 'age' => 30];
}

function createDateTime(): DateTime {
    return new DateTime();
}

If you break the contract:

function getUserName(): string {
    return null; // Fatal error: Return value must be of type string, null returned
}

Unless you allow null explicitly using a nullable type:

function getUserName(): ?string {
    return null; // This is now valid
}

The ? prefix means “this type or null”.

When to Use void: Functions That Don’t Return Anything

Use void when a function performs an action but doesn’t return meaningful data—like logging, printing, or modifying state.

function logMessage(string $message): void {
    file_put_contents('log.txt', $message . PHP_EOL, FILE_APPEND);
    // No return statement needed
}

Or with an explicit return;:

function abortIfNotAdmin(User $user): void {
    if (!$user->isAdmin()) {
        die('Access denied');
    }
    return; // Optional, but allowed
}

Key rules for void:

• You cannot return a value: return 5; → Fatal error.
• return; with no value is allowed (same as not returning).
• null is not a valid return value either.

This enforces the idea: “this function does something, but gives you nothing back.”

Handling Optional or Multiple Types with Union Types (PHP 8.0 )

Before PHP 8.0, you couldn’t express “this returns string or bool”. Now you can:

function findUser(int $id): ?User {
    // returns User or null
}

Even better with union types:

function processInput($input): string|int|bool {
    if ($input === '') {
        return false;
    }
    if (is_numeric($input)) {
        return (int)$input;
    }
    return trim($input);
}

This makes the return contract explicit instead of leaving it as an undocumented mixed.

? Tip: Avoid overusing union types. If a function returns too many types, consider whether it’s doing too much.

Common Pitfalls and Best Practices

Here are a few things to watch out for:

• Don’t add types just for the sake of it
  Start with critical functions (APIs, core logic), not every helper.

• Be careful with internal PHP functions
  Some return false on failure (e.g., strpos()). Match expectations:

  function findPosition(string $haystack, string $needle): ?int {
      $pos = strpos($haystack, $needle);
      return $pos === false ? null : $pos;
  }

  Now the return type is ?int, which is clearer than int|false.

• Use mixed intentionally (PHP 8.0 )
  If a function truly accepts or returns any type, use mixed:

  function debugPrint(mixed $value): void {
      var_dump($value);
  }

  This is better than no type hint at all.

• Avoid return null; in void functions
  While allowed, it can confuse readers. Omit the return unless you’re exiting early.

---

Summary

Moving from untyped (mixed by convention) to well-typed functions makes your PHP code more robust:

• Use specific types (string, array, User) when you know the return value.
• Use ?Type when null is a valid response.
• Use void for side-effect-only functions.
• Use union types (string|int) when multiple types are expected.
• Use mixed sparingly and deliberately.

The goal isn’t to type everything to the maximum extent, but to make your code’s behavior clearer and less error-prone.

Basically: if your function promises a return type, make sure it keeps that promise. PHP will help you enforce it.

The above is the detailed content of From `mixed` to `void`: A Practical Guide to PHP Return Type Declarations. For more information, please follow other related articles on the PHP Chinese website!