Using the iterable type prompt is the best way to handle iterable data, because it supports arrays, generators, and Traversable objects, avoids unnecessary data conversion and improves code flexibility; 1. Prioritize iterable over array or Traversable for compatibility with all iterable structures; 2. Use array types only when array-specific operations are required; 3. Return values should also use iterable to maintain implementation flexibility; 4. Avoid using Traversable alone because it does not support arrays; 5. In combination with PHPDoc annotations such as @param iterable to clarify key-value types. This ensures that the code is clear, efficient and easy to maintain.

When writing PHP functions that accept iterable data—arrays, generators, Traversable objects, or any structure you can loop over with foreach —using property type hints ensures better code clarity, IDE support, and fewer runtime errors. Modern PHP (7.1 ) offers several clean, expressive ways to handle this. Here's how to do it right.

Use iterable as the Type Hint

The most straightforward and widely recommended approach is to use PHP's built-in iterable type:

 function processItems(iterable $items): void
{
    foreach ($items as $item) {
        // Process each item
    }
}

iterable accepts:

• Arrays ( [] , array() )
• Objects implementing Traversable (like ArrayIterator )
• Generators

This is flexible and future-proof. It doesn't force the caller to convert data into a specific format, and it clearly communicates that the function only needs to iterate over values.

Avoid Over-Specific Types Like array

While it's common to see:

 function processItems(array $items): void { ... }

This unecessarily restricts callers. If someone has a generator or a custom iterator, they'd have to convert it to an array (potentially using more memory), just to satisfy the type hint.

Only use array if you specifically need array operations (like count() , array_slice() , etc.). Otherwise, iterable is more appropriate.

Consider Return Types: iterable vs Specific Collections

If your function returns data means to be looped over, consider whether you want to return a concrete type or keep it abstract:

 function getActiveUsers(): iterable
{
    // Could return an array, generator, or iterator
    yield from $this->userStorage->findActive();
}

Using iterable here keeps the implementation flexible. You can later switch from array-returning to a memory-efficient generator without breaking type contracts.

But if your API expects a countable or seekable collection, consider returning a specific interface like Traversable or even a DTO with defined behavior.

Be Cautious with Traversable

You might see Traversable used in older code:

 function processItems(\Traversable $items): void { ... }

But Traversable is a PHP internal interface and cannot be used directly in type hints unless the value is an object. Since arrays are not objects, this breaks with array inputs.

Instead, if you need object-based iteration only, combine Traversable with array :

 function processItems(array|\Traversable $items): void { ... }

But this is exactly what iterable covers—cleaner and clearer.

Document Value Types When Needed

iterable tells you how to consume the data, but not what the values are. Use PHPDoc to clarify:

 /**
 * @param iterable<string, User> $users Associative iterable of ID => User
 */
function sendEmails(iterable $users): void
{
    foreach ($users as $id => $user) {
        // ...
    }
}

This helps IDEs and static analyzers infer types and improves readingability.

Summary

• ? Use iterable for parameters and returns when you only need foreach
• ? Avoid array unless you need array-specific operations
• ? Don't use Traversable alone—it excludes arrays
• ? Combine iterable with PHPDoc to describe key/value types
• ?Prefer flexibility and memory efficiency (eg, generators)

Using iterable is the modern, scalable way to write foreach-friendly functions in PHP. It's simple, expressive, and supports a wide range of data sources without forcing unequal conversions.

The above is the detailed content of Type Hinting Iterables: Modern Best Practices for Functions Using foreach. For more information, please follow other related articles on the PHP Chinese website!