But there is a solution to this problem: You can create a class which implements the \Traversable interface of PHP. The class needs to implement a getIterator(): Traversable method now, so you have full control over how it's elements are handled by external code. Encapsulating your iterables into their own classes might seem to bloat your code at first. But while this approach indeed comes with additional code, it has some major advantages.

Advantages

Internal type safety

When you encapsulate the concept of a list of User objects into it's own class, you can easily make sure to only allow User objects to be part of the list. Throw an exception if a different type is passed into it. Now you never have to do any type checks in the code that uses your iterable object.

Constrained access options

You have full control over which methods you add to your class. You don't have to worry that elements of your object are modified in a way you did not intend. Yes, you need to write those methods by yourself, but this gives you the power to decide for each individual case what is needed and what not.

External type safety

If your code gets an array passed in, you don't really know what you get. You need to look at the calling code and hope that it does not change. But if you get a custom UserList for example, you know exactly what it's possibilities and restrictions are.

Encapsulation of business logic

Often you need to perform the same operation on a list of objects multiple times, for example filter down a list of all users to only those with an active account. This code tends to go into service classes or - even worse - into controllers and other application layer code. Encapsulating these business rules into your iterable classes makes them easy to test and reuse. The calling code is also very straightforward to read: $users->filterOnlyActive().

Immutability

Writing your own methods enables you to always return a new object instead of modifying the existing one. This way you don't have to worry to break existing code when working with an iterable object.

Sorting

In an array you don't have information about it's sorting. While you can sort an array you need to do it directly in the code that uses it to make sure it wasn't modified elsewhere. By creating a dedicated class for a sorted list (e.g. SortedUserByAgeList) which makes sure the elements are always in the correct order you don't need to worry about it in the calling code any more.

Disadvantages

More Code

This one is pretty straightforward: You need to write those classes. If you don't have a complex domain model and you don't intend your application to be maintained for a long time, this might be overkill. But as soon as these classes exist, the improved readability and safety kicks in.

Performance

This one is more critical. The additional type checks and method calls make the execution of the code slower than using simple arrays. If this is a problem or not simply comes down to the use case and needs some profiling. Don't just dismiss the idea because of premature optimization.

Summary

I've been using this approach in multiple projects over the last few years and it made my code much more readable and safe. I use it mainly in my domain layer where safety is a must and I found that I could simplify the calling code in many places by moving business logic into my iterable classes.

In my first approaches I used a base class that provided a type check in the constructor and all the common methods for filtering, mapping, counting, etc. But this caused a huge inheritance tree which in turn caused many methods to exist only for a few subclasses and made adjustments very hard. Then I shifted the concept to a simple class that provides the common functionality but is instead used by the custom classes. This way I can decide for every custom class which methods to expose and just forward the method calls to the underlying generic one. Very specific methods are then handled by the custom classes on their own.

Now that I've come to a point where the structure of the generic classes do not change that much any more I extracted them into their own library: https://packagist.org/packages/cunningsoft/generic-list.

Your might have heard of phrases like Dependency Injection, Constructor Injection and Setter Injection. These sound a bit confusing at first, but at the end, the concepts are very simple, but also very powerful.

Dependency Injection

First, let me explain the phrase Dependency Injection, because it's maybe the simplest one and you most likely already use it every day. Let's say we have a Validator class which somehow validates things. Now we also have a Translator class, which translates things somehow. As we know that separation of concerns is a good thing, they are decoupled - the Validator does know nothing about translating things and the Translator does know nothing about validating things. But we might also want to translate the things that were validated. So the Validator needs some help from the Translator - it depends on it or it has a dependency. To give the Validator access to the Translator we pass it in - or inject it. We inject a dependency. That's all what dependency injection is, passing objects to other objects.

Setter Injection

Now we have several ways to achieve this. We could simply pass it every time something is validated, for example $validator->validate($someObject, $translator), but this clutters the validate-method and is not very intuitive. Instead, we could store the dependency as a property of the Validator. Now to pass it in we simply use a setter like $validator->setTranslator($translator). After we have done this we can call the validate-method as often as we like and it will always use the passed Translator. The Validator now looks something like this:

class Validator
{
    private $translator;

    public function setTranslator($translator)
    {
        $this->translator = $translator;
    }

    public function validate($someObject)
    {
        // do the magic here with the help of $this->translator
    }
}

That is all that setter injection is. Now this is great for optional dependencies. In our example the validate-method should also work fine with no Translator set because there is no guarantee it has been set before the validate-method has been called!
But what if we want to enforce that?

Constructor Injection

If you have a dependency that you cannot leave away because your class does not work without it, constructor injection is the way to go. Instead of calling a set method, the dependency is passed via the constructor. Now there is no way around, but passing it when an object is created. This means for our example that we have to pass a Translator to the Validator in its constructor. This will look something like this:

class Validator
{
    private $translator;

    public function __construct($translator)
    {
        $this->translator = $translator;
    }

    public function validate($someObject)
    {
        // do the magic here with the help of $this->translator
    }
}

Constructor Injection is great for obligatory dependencies. You clearly communicate to the user of that class: You have to pass me such an object, otherwise, I won't work.

So what should I use?

It absolutely depends on the use case. While in many situations a class simply does not work without its dependencies, it's perfectly fine to leave them away in other. For example, your Validator might not work without a Translator, because you always want to display the errors to your users. On the other hand it maybe also has a dependency on a Logger class which is able to write the errors to a log file or send it via email. But this might be completely optional.

Interfaces

At the beginning, I said that the Validator should know nothing about how to translate things. But now we have a hard dependency to the Translator. But what if we want to use a different implementation at some point? This might be more obvious with the example of a Logger, so let's talk about that one. So our Validator is also able to log its results to a log file. We used setter injection here to pass in a FileLogger:

class Validator
{
    private $logger;

    public function setLogger(FileLogger $logger)
    {
        $this->logger = $logger;
    }
}

That's fine - until we decide that we need to be informed about the results via email instead of having to look through the log files manually. Now we need to edit the Validator-class to pass in an EmailLogger instead. That's a bad thing because editing existing code always has the risk to break something. And after all, we just want to change the way we log things - why do we need to change a Validator for that?

Interfaces to the rescue: Instead of type hinting for the concrete implementation of the FileLogger in our Validator-class we type hint for the interface Logger. Now our FileLogger and EmailLogger simply implement that interface and we are free to change the logger we pass as often as we want - without changing a single line of the Validator code.

We write conditionals all the time. Often, we check for very simple things, not worth any extra effort of encapsulation. But in many cases, this makes perfect sense even for very basic things. Let me give you an example:

$date = new \DateTime('2016-05-15');
if ($date->format('N') == 6 || $date->format('N') == 7) {
    // do something
}

If you are like me, you always have to look up, that N is the character you need when you want to check for a specific day of the week. Or was it w? Well, yes, but then the Sunday is represented as 0 instead of 7. Whoo, lots of boring stuff to remember.

Now even if this is the only place in your entire code base that needs this check, this will always be a place where a fellow developer or your future self will stop and needs to think for some seconds what this means.

Now consider this:

$date = new DateTime('2016-05-15');
if ($date->isWeekend()) {
    // do something
}

Inheritance

This is way better to read, no need to think about that at all. If you own that class by yourself you can of course simply add that functionality. But in case you do not, all you need to do is to extend the class you want to do the check on.

namespace MyApp;

class DateTime extends \DateTime
{
    public function isWeekend()
    {
        return $this->format('N') == 6 || $this->format('N') == 7;
    }
}

Now you never have to worry about the characters to use in the format-method or what numbers to use.

Delegation

While inheritance seems the easiest way to achieve this, it comes with a drawback. Your class now completely depends on changes of the original underlying class. If for some reason the public API of it changes, your public API changes as well.

So instead you could use delegation:

namespace MyApp;

class DateTime
{
    private $dateTime;

    public function __construct(\DateTime $dateTime)
    {
        $this->dateTime = $dateTime;
    }

    public function isWeekend()
    {
        return $this->format('N') == 6 || $this->format('N') == 7;
    }

    public function format($format)
    {
        return $this->dateTime->format($format);
    }
}

Now you when the public API of the underlying class changes, only your wrapper breaks - but not your whole application. The drawback here is that you have to delegate all the methods you want to use. This might seem stupid at first glance, but it gives you the complete control over what can be done with your class and what not.