Forem: Anton Ukhanev

PHP Array: A Gross Mistake

Anton Ukhanev — Mon, 02 May 2022 11:51:23 +0000

Any developer who has spent a little time working with PHP knows one of the most used compound types - the array. Its uses reach from de-serialization results, to the backbone of sets, collections and containers, stacks and queues, indexes, and much more. It is so ubiquitous that it's possible to make an object appear to be an array with the ArrayAccess, Iterator, and Countable interfaces.

However, countless examples suggest that even experienced PHP developers frequently make the same kind of mistake, which often has a hidden cost months or even years later. I contend that

An array is not an array.
What you really want is either a map or a list.
You're doing it wrong.

// Detect dark theme var iframe = document.getElementById('tweet-1415951528658153477-691'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1415951528658153477&theme=dark" }

PHP Array

From Java to C++ to Pascal to Basic, an array is an implementation of a list. As follows from official documentation, however, a PHP array is really a linked hash map. This is very versatile and flexible; yet it goes against the very principles that keep our code sane. Specifically, it violates the Interface Segregation Principle, which leads to much lower separation of concerns, puts unnecessary burden on implementations, confuses and complicates consumers, and makes implementations less flexible. All this leads to a cascade of more negative side-effects which could easily be avoided by applying engineering to the problem at hand. What does this mean for us?

ISP

The Interface Segregation Principle states:

no client should be forced to depend on methods it does not use

Let's consider a typical scenario:

function sumNumbers(array $numbers, int $limit): float
{
    $sum = 0;
    $i = 0;
    foreach ($numbers as $number) {
        if ($i === $limit) {
            break;
        }

        $sum += $number;
        $i++;
    }

    return (float) $sum;
}

Most frequently, this is the sort of thing developers would write when it's necessary to perform some kind of operation on elements of a list. The way this list is consumed here is by iterating over its elements, starting from the first one and until either the end or the limit have been reached, using a simple foreach loop. Nothing else is done to this list of numbers, besides iterating over it in the given order. And yet, we are asking for an array, as if we would need to access or modify its elements directly, or in random order. What if the consumer of sumNumbers() has an infinite set of numbers and just wants to know the sum of the first 1000? The signature does not permit that, because nothing but an array must be passed. A type defines ways in which values of that type may be consumed, and looking at ArrayAccess, Iterator, and Countable, which together make up the true interface of an array, we see that this type is in reality far more complex than is let on by the ease of its use. But simplicity is not about ease, and a much simpler version of the function affords us incredible flexibility compared to its former state - without even changing anything about the algorithm:

function sumNumbers(iterable $numbers, int $limit): float
{
    // ...
}

echo sumNumbers((function () {
    $i = 0;
    $k = 1;
    yield $k;
    while(true)
    {
        $k = $i + $k;
        $i = $k - $i;
        yield $k;       
    }
})(), 1000)

The new consumer of sumNumbers() can now use any series of numbers, finite or infinite, generated, hard-coded, or loaded from an external source.

Another example of array usage.

function getGreeting(array $user): string
{
    $fullName = [];
    $fullNameSegments = ['first_name', 'last_name'];

    foreach ($fullNameSegments as $segment) {
        if (isset($user[$segment])) {
            $fullName[] = $user[$segment];
        }
    }

    return implode(' ', $fullName);
}

The only way that the $user argument is consumed is by accessing its specific, discreet indices. If the consumer wanted to use something that is only capable of exposing discreet members, which would actually be enough for the algorithm to work, they cannot! Let's consider a simplified version, where we depend only on what we actually use.

function getGreeting(MapInterface $user): string
{
    $fullName = [];
    $fullNameSegments = ['first_name', 'last_name'];

    foreach ($fullNameSegments as $segment) {
        if ($user->has($segment)) {
            $fullName[] = $user->get($segment);
        }
    }

    return implode(' ', $fullName);
}

interface MapInterface
{
    public function get(string $key);

    public function has(string $key): bool;
}

class Map implements MapInterface
{
    protected $data;

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

    public function get(string $key)
    {
        if (!array_key_exists($key, $this->data)) {
            throw new RangeException(sprintf('Key %1$s not found', $key));
        }

        return $this->data[$key];
    }

    public function has(string $key): bool
    {
        return array_key_exists($key, $this->data);
    }
}

$user = new Map([
    'first_name' => 'Xedin',
    'last_name' => 'Unknown',
    'id' => '12345',
]);
assert($user instanceof MapInterface);
echo getGreeting($user);

Because the new getGreeting() only consumes as well as requires the methods of a map, any compatible map can be used, whether hard-coded, loaded from a database, de-serialized, or from a remote API. Cases such as with a remote API or some key-value storages are especially curious here, because they may not allow the listing of all entries, while supporting retrieval/checking by key, and so cannot be represented by an array because its "members" are not enumerable.

Data Representation

Often, data needs to be encoded in text form in order to be saved or transferred. In these cases, some kinds of DTOs are used in order to represent that data in the program. Let's looks at a typical example of some remote API response:

{
    "users": [
        {
            "id": 1,
            "username": "xedin",
            "first_name": "Xedin",
            "last_name": "Unknown"
        },
        {
            "id": 2,
            "username": "jsmith",
            "first_name": "John",
            "last_name": "Smith"
        }
    ]
}

The response data contains a map with a single member users, which corresponds to a list, where every member is a map with members id, username, first_name, and last_name. This is because JSON is a very simple interchange format, and supports maps and lists. Note that there is no such thing as an "ordered map": looking at such a response, we understand quite intuitively and rather well that each "user" representation has a schema, which dictates certain mandatory (and perhaps some optional) fields, and in an application this data will be retrieved by key that is known in advance - because the application is written in accordance with the schema. There is never really a need to get all fields of a user. Let's look at a solution for a typical problem, where entries support arbitrary fields.

{
  "users": [
    {
      "id": 1,
      "username": "xedin",
      "first_name": "Xedin",
      "last_name": "Unknown",
      "meta": [
        {
          "name": "date_of_birth",
          "value": "1970-01-01"
        },
        {
          "name": "hair_colour",
          "value": null
        }  
      ]
    }
  ]
}

This adds support for an arbitrary number of arbitrary members through metadata in the meta member of each user, which is a list of maps, each map with key-value pairs, but can at any time receive additional members if necessary, such as a type which could determine the data or field type of the member. This is structurally very similar to how data is stored in various engines, be it EAV (Magento 1), WordPress (meta tables), some other relational or key-value storage, etc, and allows a simple and seamless flow between the HTTP, the application, and the data layers.

So then, why should the DTO type structure be any different from the schema? If we wanted to represent the entities from the above data in a PHP API, this is what it could look like.

interface UsersResponseInterface
{
    /**
     * @return iterable<UserInterface>
     */
    public function getUsers(): iterable;
}

interface UserInterface
{
    public function getId(): int;

    public function getUsername(): string;

    public function getFirstName(): string;

    public function getLastName(): string;

    /**
     * @return iterable<MetaInterface>
     */
    public function getMeta(): iterable;
}

interface MetaInterface
{
    public function getName(): string;

    public function getValue(): int|float|string|bool;
}

Here, each user is represented by a UserInterface instance, which is a data object that via its methods exposes the members of each "users" entry. Conceptually, it is consumed as a simple map, by knowing its exact getter method names (keys), and in no other way. The design of arbitrary metadata support follows a similar approach. For convenience, the metadata can also be represented as a map by simply augmenting the UserInterface:

interface MetaMapAwareInterface
{
    public function getMetaMap(): MapInterface;
}

interface UserInterface extends MetaMapAwareInterface
{
    public function getId(): int;

    public function getUsername(): string;

    public function getFirstName(): string;

    public function getLastName(): string;

    /**
     * @return iterable<MetaInterface>
     */
    public function getMeta(): iterable;

    // Inherits `getMetaMap()`
}

/** @var $user UserInterface */
$meta = $user->getMetaMap();
if ($meta->has('date_of_birth')) {
    echo $meta->get('date_of_birth');
}

Note: In the above example, generic syntax in e.g. iterable<MapInterface> may not be supported by PHPDoc natively, but is probably supported by your IDE, and is definitely supported by Psalm.

In fact, a more generic DTO type structure could be achieved by converting all maps to an e.g. MapInterface, and all lists to an iterable. Since these are the only two compound types necessary, any datastructure can be represented in lists of maps of lists etc. Following the ISP principle allows great flexibility, because any such structure can be parsed by a uniform algorithm, preserve more type information, and any part of it can be replaced by one that comes from another source, or retrieves data in a different way, or generates mock data on the fly - or anything else, really, and the meaning of the program or the logic of your DTO's consumers need not change.

Indexing

Another very common thing PHP developers do, and which can be found in the code of most frameworks, is something like this:

/**
 * @return array<UserInterface> A list of users, by ID.
 */
function get_users(): array
{
    // Retrieves users from DB...
}

Here, the value returned by get_users() betrays the principles described in this article. While it is perfectly reasonable and valuable to have an index, index does not imply any order, but simply the ability to reference a whole record directly, often by a combination of only some of its members. If consuming code needs an ordered set of users (for example, sorted by first_name), then it is consuming the interface of a list of users, and every user has the same significance to the consuming logic. If consuming code needs an index of users, where each user can be retrieved by their id, then it is consuming the interface of a map of users, every user has a potentially different significance, and the order is irrelevant. Naturally, it is possible to convert a list of users to an index of users at any time by simply iterating over it programmatically. Because with this separation the index is now a separate "collection" than the list, the index can even be cached separately - like databases do, but also in memory, in a file like JSON, etc. With some additional logic, such an index can easily be used as an entity repository, which is usually unable to reliably enumerate its members.

Summary

Here are some practical take-aways that I would like to suggest.

Achieve parity across your application layers by representing all data in a documented format with a single source of truth.
It's either a map or a list. It's not both. If you think you need both, it's a good sign that your design could be simplified.
Do not restrict the consumers of your APIs to using native types. Strings, lists, and maps can all be generated on the fly, in different ways, and there's no reason to limit how your consumers acquire the data they pass to your code.
Observe ISP on one hand, and on the other - always depend on the most narrow type that provides the necessary interface. The array type is far too wide for most cases.

Separation of Concerns and SOLID

Anton Ukhanev — Thu, 23 Jul 2020 10:57:32 +0000

I would like to start with a quote of E.W. Dijkstra, from his 1974 paper "On the role of scientific thought":

Let me try to explain to you, what to my taste is characteristic for all intelligent thinking. It is, that one is willing to study in depth an aspect of one's subject matter in isolation for the sake of its own consistency, all the time knowing that one is occupying oneself only with one of the aspects. We know that a program must be correct and we can study it from that viewpoint only; we also know that it should be efficient and we can study its efficiency on another day, so to speak. In another mood we may ask ourselves whether, and if so: why, the program is desirable. But nothing is gained —on the contrary!— by tackling these various aspects simultaneously. It is what I sometimes have called "the separation of concerns", which, even if not perfectly possible, is yet the only available technique for effective ordering of one's thoughts, that I know of. This is what I mean by "focusing one's attention upon some aspect": it does not mean ignoring the other aspects, it is just doing justice to the fact that from this aspect's point of view, the other is irrelevant. It is being one- and multiple-track minded simultaneously

If we want to make our code resilient to the negative effects of change i.e. make it more adaptable to change without breaking, as well as to make it simple to understand and modify, we need to separate concerns very well. But what does it mean - to have a concern? And how do we determine what the concern of a module is?

Note: if you understand why and how concerns are separated, but not sure what to do in practice, learn how to make cross-platform modules in PHP. You are also encouraged to read Alain Schlesser's excellent article Using A Config To Write Reusable Code.

Here is an example. Let's say, our project is a car, and we need an engine to run it. The engine needs something to ignite the fuel in a cylinder - a spark plug. Would you make a spark plug built in, baked into the engine? Of course not! When it comes to physical things, nobody in their right mind would do something like that. We would just "know" that spark plugs need to be separate. How do we know that?

We know that because the lifetime of an engine is much greater than the lifetime of a spark plug. We know that spark plugs have a tendency to get burned, or malfunction in other ways - due to their softer materials and complex construction (as opposed to a cylinder), and therefore they will have to be changed frequently; whereas an cylinder has a very long lifetime because it is made of metal, and therefore it will need to be changed less frequently.
We also know that because the problems that can cause an engine or cylinder to be changed are a different kind of problems rather than what could cause a spark plug to be changed: cylinder heads can get scratched or otherwise damaged from the friction with the cylinder, and this happens at a relatively slow rate (they're made of metal, and are lubricated with oil), whereas spark plugs are prone to all kinds of damage related to the wear of isolation components, due to electric currents passing through the conducting materials, or perhaps dampness, etc.

Thus, we can determine two basic rules that determine a concern of a component:

The frequency, with which the components need to be changed.
The reasons, for which the components need to be changed.

Effectively, an engine with separate spark plugs does not decide which spark plugs to use; instead, it is decided by the engineer who is assembling the car out of its components.

If some code needs to change at a different rate than other code, or for different reasons than other code, then we know that those two units of code have different concern.

As a direct result of the above, this gives us the corresponding benefits:

One unit can be changed more frequently than another, without causing the need for that other code to change.
One unit can be changed for different reasons than another, without causing the need for that other code to change.

Like this, we have made our code more adaptable to change. This gives us great flexibility, because we can choose any component of the system, and make it do stuff completely differently, according to our changing needs, without breaking or changing any other part of the software. With each iteration we write more and more code which does stuff; but this means that with each iteration we have more and more code that we need to keep in mind when doing these changes. And our mental capacity is limited, our minds can only hold so many things at once. When code is adaptable to change, the amount of things that we need to hold in our minds reduces by an order of magnitude, because things that are logically unrelated become actually unrelated, allowing us to focus on only one concern, without thinking of how it affects our ways of addressing other concern. This gives us tremendous agility, and development speeds do not fall but grow, because with every component we write there is one less component to write when we want to address the same concern again. This kind of agility - the ability to affect the greatest amount of change with the least amount of effort - is the ultimate type of agility that is more beneficial than any other kind of agility. This is very well explained by Rich Hickey in his talk "Simplicity Matters", which I take great inspiration from.

And so, for example, using a PSR-18 HTTP Client is good, better than directly using WP's HTTP client, because it allows us to de-couple ourselves from WP, and because it is re-usable, etc, making things easy. But we do not use a PSR-18 HTTP client because it's easy; we use it because it is the correct way to do it: a module, whose purpose is to access a REST API, does not decide which HTTP client to use; instead it is decided by the engineer who is assembling the application out of these components. And for the purposes of a WordPress plugin, they decide to use an HTTP client that makes requests through WordPress, because this is the appropriate transport that would ensure compatibility with WordPress and its extensions. All the benefits that this abstraction brings are therefore simply useful and desirable side effects of following the Separation of Concerns principle, which corresponds to Single Responsibility Principle - the S in SOLID.

An engineer should not be at the mercy of the components that they use; an engineer should be in control of components, assembling their system as it is necessary for the purpose of their task. It is an engineer's decision which components to use; it is not the decision of some other code that they are forced to use.

SOLID Principles

In practice, Separation of Concerns would mean making units of code smaller. If a class has too much responsibility, which we can understand by applying the rationale described above, we split it into multiple classes, and the same is applied to functions. We do that by establishing the concerns addressed by our unit, and creating multiple smaller units, each of which has a narrow and well-defined concern of its own. However, the original logic made all these concerns play together, and thus we need a way for one unit to invoke another, naturally causing our units to depend on other units. Our classes start depending on other classes, and these dependencies are most often fulfilled by using Dependency Injection: a class receives dependencies, including instances of other classes, via its constructor parameters. This is the process of configuration, as opposed to consumption, because it sets some values that are internal to the class, and that consumers of the class don't necessarily see.

Open-Closed Principle

With our units now addressing separate concerns, they move closer to being compliant with the Open-Closed Principle (OCP). If our unit is a class, for example, outside code cannot modify its logic, but it can change the logic of its dependencies, decreasing the need for modification, and thus making our system more adaptable to change.

There is an opinion that it is best to make classes final, i.e. non-extendable. This encourages Composition Over Inheritance, which is a good thing, but also brings about a slew of problems, such as the necessity to write forwarding method implementations. The most important drawback here is that a decorating class has no way of overwriting a method of the base class, even if the added or changed behaviour is simple. Ideally, all extension or modification of behaviour would be achieved by decoration; however, not giving developers the opportunity to change specific methods of the base class through inheritance assumes that the base is written perfectly, e.g. that it addresses only a single concern, injects all dependencies, etc. I conclude that composition should always be preferred over inheritance; but because it is not always possible or feasible, class authors should not put a hard boundary for inheritance, allowing it to be usable when necessary. For example, wen using a third-party library, it may be necessary to make changes to the behaviour of some service, and if (this happens often) the service has too much responsibility, developers are forced to either copy-paste code, or abandon the attempt to adapt the service altogether. Ultimately, these are two different concerns: service authors should not limit consumers of the service; at the same time, consumers should use services in a way that leads to better architecture.

Thus, separation of concerns leads to the Open-Closed principle, reducing (or localizing) the need for changes, and keeping code units open for extension.

Liskov Substitution Principle

A common way of adding responsibility is by sub-typing, which usually means either extension of a class, or by using composition in conjunction with extension of an interface. Either way, both methods lead to the creation of a sub-type - a descendant of a super-type, and this new type may add responsibilities by declaring additional methods. So if type A has method one(), its sub-type B may add responsibilities by declaring method two(), resulting this subtype having both methods. As a real-life example, a smartphone has all the characteristics of a phone in the sense that it allows one to make phone calls, but it also has additional features, such as the address book.

Following the smartphone example above, we can see that a smartphone is also a phone. This dictates that it must be usable as a phone, without the knowledge of any additional features if these features are not required. The Liskov Substitution Principle (LSP) codifies this, and is represented in the PHP engine itself in the form of certain inheritance rules, such as variance. Developers do not need to remember many of the aspects of the LSP, as they are forced to comply by PHP, which is moving closer to complete implementation of the principle every year through improvements in its syntax and the rules applied during compilation.

Thus, we can see that the Liskov Substitution Principle is derived from the Separation of Concerns principle, as it allows us to invoke the concerns of a sub-type inherited from its super-type without knowing of the specifics of the sub-type, allowing those specifics to change.

Interface Segregation Principle

When depending on an injected type, the consuming class promises that it will not use any API other than of that type. While providing a large degree of predictability, this is still not perfectly safe: the injected type may change in the future, possibly breaking some of the previously declared API. For this reason, consumers should use only the API they really need - see "Dependency Inversion Principle".

On the other hand, consumers can only depend on a type that is declared, and therefore, if a more narrow type is not available, they are forced to declare dependency on an API that they do not consume. The Interface Segregation Principle (ISP) codifies the rule that allows consumers to depend only on what they need, giving everything else the freedom to change.

Dependency Inversion Principle

Injection of services requires the declaration of dependencies, and the other SOLID principles tell us among other things how we should do that. But what of the type itself? If a class that contains the necessary functionality exists, is it fine to simply depend on it?

Not always. It makes no sense to declare dependency on an API that is not consumed, thus increasing useless coupling, and introducing discrepancy between actual and declared dependency. According to ISP, a type should declare an API that relates to only the specific concerns of that type. DIP is the opposite side of that: consumers should depend on only the API they need, in its most generic form. If type A declares method one(), and its sub-type B declares method two(), given that we are only going to use method one(), we must depend on type A, and not type B. Thus, DIP allows implementations to change freely as long as they do not break their dependents by making sure that declared dependencies correspond to actual ones.

Conclusion

Following SOLID principles results in software that is adaptable to change and resilient to negative effects of change, because it, among other things:

Makes sure that a unit of code changes only in response to changes of its concern.
Makes units of code de-coupled from logic that is not their concern.
Makes relationships between units of code very predictable, yet flexible.
Makes APIs more stable and reliable.
Lowers the complexity of individual components, making them easier to understand, use, and change.
Increases re-usability of individual components, making it possible to re-combine them for a different result.
Allows for better application of Package Management Principles.
Decreases maintenance costs as a result of the above.

However, the most important benefit, which could be made into a principle of its own is the following:

The responsibility of a software engineer is to understand the problem domain, and translate its processes and entities into a language that a computer can understand, thus creating a model of the problem domain.

The more accurate this model is, the more predictable, reliable, and flexible the behaviour of the software becomes. By following SOLID principles, software engineers can ensure that their models of problem domains are very accurate. These principles are natural, because they reflect the nature of logical concepts, and following them is a natural conseqence of normalization and optimization. This has many positive side effects, such as high maintainability, or a high level of re-use. These side effects appear automatically, as a consequence of the high level of model accuracy, and while desirable, they are not the main goal of SOLID principles; yet they will be naturally acquired simply by following these principles. Abstraction therefore is something that should be done immediately, as soon as the need for it arises; yet it is not for the sake of being there, but in order to correctly represent the problem domain by applying SoC.

[...] whatsoever is contrary to nature is also contrary to reason, and whatsoever is contrary to reason is absurd, and, ipso facto, to be rejected.
— Benedict de Spinoza, "A Theologico-Political Treatise", 1883

Cross-Platform Modularity in PHP

Anton Ukhanev — Tue, 02 Jun 2020 13:59:27 +0000

Notice: There's an on-going discussion in support of the underlying Service Provider standard. Join the effort!

Background

For over 12 years now, I have been working with various engines and frameworks, from CodeIgniter to Magento, but the greatest amount of time I have spent on projects related to WordPress. One of my biggest passions is re-usability, and so by far, I have spent most of my WordPress time on plugins, working with companies and teams to produce high-quality, customizable solutions.

Of course, there's no quality and re-usability without interoperability, and without design principles like SOLID or DDD. That's why they are my other great passion. I have been in trouble countless times for pushing for better standards and refusing to write low-quality code.

In PHP, when we think "interoperability", we think "FIG". And I have been a fan of FIG for a long time, even making it into a workgroup. Although I don't always like or agree with everything FIG does, it is an organization that takes interop standards very seriously. And we need interop standards.

In fact, we need them yesterday, and there simply aren't enough resources at FIG to provide for everyone. At the same time, FIG is quite a rigid organization (for good reason), which is why I created Dhii: to serve as a more flexible source of standards and compliant implementations, providing a testing ground for ideas and contributing to interoperability in more niche areas. For example, it is not uncommon to use a __toString() method for converting objects to their string representation, but for some reason, PHP is missing a native interface that would allow us to type-hint (or at least document) that a stringable object is an allowed type. The same goes for many other things, like ID-aware objects, objects with human-readable data like labels and captions, templates and other output-related objects, and many more. At Dhii, we address these concerns in hope that our solutions would help packages to be more interoperable.

Modularity

One of these concerns is modularity. Many systems lack the notion of modules. WordPress allows for plugins, themes, drop-ins, etc., but nothing unifies them. I describe the problem and solutions in detail in my article "Package Management in WordPress". Other systems, like Symfony, support modules, but they are coupled to those systems, and therefore cannot be used anywhere else. Moreover, if your WordPress plugin needs to be modular itself — perhaps because you want to support add-ons that would extend its core functionality — there is no available standard in WordPress or anywhere else to make that possible.

With all the interop standards that already exist and have yet to come, why not have modules that can work in any system, provided that it has a compatible loader? Wouldn't it be great if a piece of functionality that addresses a business problem in WordPress could also be used in Drupal? Why do we have to write the same thing so many times, over and over again? I cannot even imagine how much time and money gets spent on re-inventing the wheel every day.

Meet dhii/module-interface: a standard for cross-platform modules. Dependent on a FIG experimental service-provider standard, it allows you to quickly and easily define a cross-platform module for use in any system with a compatible loader. How you program the module internals, including the level of granularity for declared services, is entirely up to you; but when done correctly, it automatically allows every individual part of your module to be infinitely extendable from outside. One module can completely change the way another module works. And yet, the application comprised of these modules is ultimately in control. Here's how this is achieved.

Note: If you don't understand why you would want cross-platform modules with easily changeable components, you may want to learn about Separation of Concerns.

Inversion of Control

Traditional Approach

In most cases, a modular application includes some entry points which can be used by modules to interrupt or extend the flow of the application. In such systems, modules are made for the application, and can change only the aspects open for change by the application or other modules. Often, this is done via an event mechanism: the application would trigger an event which can be handled by module handlers; those would change some parameters of the event; these parameters would then be returned and used by the original code. For example, WordPress uses hooks to de-couple plugin code from its internal flow. These are some of the problems such a mechanism suffers from:

The event system is often proprietary, making any consumers (plugins) coupled to it.
The consumers can only modify the data that is exposed via the events, leaving all other aspects set in stone, which greatly limits what modules can do.

Even if a system does not use events, but relies on some other mechanism, such as service definitions, the module standard would be specific to that system, and you would not be able to re-use the same module somewhere else.

A Better Approach

Ideally, the application would have no more than the following responsibilities:

Combining individual parts. That is, implementing a mechanism for loading interoperable modules. This includes setting the load order.
Linking with a bigger system, if necessary. For example, a modular WordPress plugin is a part of WordPress, and so it would provide a bridge between the services of application modules, and WordPress.
Satisfying module dependencies. For example, modules may depend on an HTTP client, and the application can satisfy that dependency, thus deciding the HTTP client implementation used by the modules.

With such responsibility distribution, the application chooses which modules to load, how and when. For example, If an application needs logging capabilities, it may choose to use a module that addresses that concern. But that logging module may require a filesystem abstraction, and the application would be responsible for satisfying that requirement. The application may choose to load another module or library which provides that abstraction. Thus, the application is for modules, inverting control, taking it from modules into its own hands.

Module Loading

One of the main responsibilities of the application is loading the selected modules, and a crucial part of that is determining the module load order. This order has a direct effect on the services that will effectively be used in the application. The module standard relies on service-provider implementations exposed by the modules. These Service Providers expose service definitions in two ways:

Factories. The definitions returned by getFactories() completely override definitions of the same service factories that were declared in the modules loaded before. In other words, the last definition wins. All other service factories are not used in the application.
Extensions. The definitions returned by getExtensions() are applied on top of the same service extensions that were declared in the modules loaded before. In other words, later definitions extend earlier ones. All extensions are always applied.

And here is how the modules are loaded by a compliant system:

All module instances are retrieved.
The setup() method of all modules is invoked, and the exposed service providers are used to configure a single DI container.
The run() method of all modules is invoked, providing all configuration to each module via the DI container.

This creates an extremely simple yet powerful mechanism for modules to influence other modules in a way that is completely predictable, with one DI container being the single source of truth for all configuration.

A module's service provider exposed by setup() declares all services used by it.
These services are consumed by the run() method via a standard container.
Any module can access any service declared by any other module, because they are all available via the single source of truth.
Any module can extend or completely override any service declared by any other module, and the application decides the priority via the module load order.
A module may explicitly delegate a service to another module by not declaring it, and the application will then satisfy that dependency.

Here is an illustration of how service definitions would resolve according to the rules described above.

The following can be gathered from this illustration:

The modules are loaded in order: first Module1, then Module2.
When requesting services B, D, and E, they would be retrieved from definitions of modules 1, 2, and 2, respectively. This is because they are declared there, and not overridden or extended anywhere later.
The service C is first declared in Module, but then overridden by that in Module2.
The service A is declared in Module1, and then extended in Module2.

Out of the box, there is complete customizability and flexibility, without sacrificing centralization and control. Modules are self-contained, and depend on outside services through the DI container.

Getting started

So, how would one start working in a modular system like this, and what would it take to make a simple application?

Bootstrap

To fulfill its main responsibility, the application must load modules in an order pre-determined by it; the application must bootstrap the module system. If the module classes do not require any parameters in their constructors, the bootstrap could be as simple as this:

use Dhii\Modular\Module\ModuleInterface;
use Interop\Container\ServiceProviderInterface;
use Some\Container;
use MyPackage\Module as ModuleA;
use OtherPackage\Module as ModuleB;

// Module classes
$modulesToLoad = [
    ModuleA::class,
    ModuleB::class,
];

// A container implementation that supports service providers
$container = new Container();

/* @var ModuleInterface[] */
$modules = [];

// Get the modules' services
foreach ($modulesToLoad as $moduleClassName) {
    // Instantiate the module
    $module = new $moduleClassName();
    // Keep track of module instances
    $modules[$moduleClassName] = $module;

    // Retrieve the services
    $provider = $module->setup();
    // Add the services to the container
    $container->register($provider);
}

// Run the modules
foreach ($modules as $module) {
    $module->run($container);
}

That's all; barring comments, imports, and whitespace, all it takes to have a simple modular system is 20 lines of code. Module classes in this example get autoloaded like any other class.

A module

A module may provide services, consume services, or both. Let's create a simple module.

namespace MyPackage;

use Dhii\Modular\Module\ModuleInterface;
use Psr\Container\ContainerInterface;

class Module implements ModuleInterface
{
    public function setup(): ServiceProviderInterface
    {
        return new ServiceProvider([
            'my_service' => function (ContainerInterface $c): MyService {
                // A dependency
                $otherService = $c->get('other_service');
                // Perhaps a class declared in this package
                return new MyService($otherService);
            },
        ], []);
    }

    public function run(ContainerInterface $container)
    {
        // Retrieve a service - may have been overridden or extended elsewhere
        $myService = $container->get('my_service');
        $myService->doSomething();
    }
}

Here, we have a module that declares a service my_service of type MyPackage\MyService and consumes it. That service depends on a service other_service, and because it is not declared in this module, it is a dependency. The ServiceProvider class was omitted here for brevity, because implementations are extremely simple, and can even be easily created in the same package, including anonymously.

Additional Possibilities

The possibilities opened up by such an architecture are limitless, including:

Submodules. A module may contain a loading mechanism itself, which would load other modules that would therefore become its submodules. This fact allows for a module hierarchy of arbitrary depth, while each module remains agnostic of its environment.
Usage in non-modular applications. A modular WordPress plugin made in this way could be hooked up to the WordPress system through the DIC container, and thus may consume engine-specific things like settings, without breaking interop.
Dependency graphs. Service dependencies can be analyzed statically, producing a list of services that must be added to a system for the module to work. Combined with similar lists from other modules, it is possible to search for or suggest other modules that satisfy dependencies of any particular module.
Medium-agnostic configuration access. Dependency containers that draw configuration from different sources, like files, the database, or even network, can be combined into the single source of truth consumed by modules, allowing them to consume configuration values that are resolved based on the availability of the key in the above-mentioned sources. For example, service configuration is overridden by YAML configuration, which is overridden by settings stored in a database.