As an API developer you don't always have it easy. Of course you want to make it easy for other developers and as a icing on the cake the whole thing should be less error-prone.
Let's assume that you wrote your first module for QUIQQER. Your module now offers an interface where other developers can extend your module via different classes.
So that the whole hand and foot has you offer an interface. Your interface defines all interfaces and methods you start from.
So that you can access all extensions of other modules, you collect them in an array.
How can you make sure that only objects really end up in your array and that objects inherit from your interface?
For such cases, QUIQQER offers so-called collections. Some should know Collections, some perhaps not and cannot begin with Collections yet so much.
In programming, a collection is usually an object that mimics an array. You can imagine it as an array with super power.
The superpower comes from the fact that the object contains all the methods to manipulate the data it contains.
If we now want to do this with an array - for example, filter, dice, or split the array - we usually have another variable or destroy our source array. So far, it's not bad, but it's not very helpful for readability.
Additionally, there is a problem: anyone can insert what they want into an array. I have no way to prevent someone from stuffing int values, boolean values or objects into an array.
For API providers this is a bit stupid. Often you have the case that an array list exists that other developers can / should extend. For example, in QUIQQER we take so-called providers. These are classes that provide functionality for a specific purpose of a specific plugin.
A good example of a provider would be an ERP provider. The ERP module reads all plug-ins and checks whether these plug-ins provide ERP providers. If so, it records them.
As an API provider, you now want the ERP provider class to be dependent on a specific class. If the ERP provider is not dependent on the class, it should not be included at all.
The next example illustrates the problem.
Providers are generally registered via package.xml in QUIQQER.
The class QUI\ERP\Order\ErpProvider must inherit from the class QUI\ERP\Api\AbstractErpProvider. But what happens if the module developer forget it? So it is not guaranteed that the provided ERP provider behaves like an ERP provider.
This is exactly where the QUIQQER Collections come into play and this is exactly where the QUIQQER Collections differ from the standard Collection Concept. To solve the problem with the ERP provider, there are several possibilities.
- At every point where you need the ERP providers, you go through all the ERP providers and always check if the objects all inherit from the QUI\ERP\Api\AbstractErpProvider.
Well, that's a bit tedious and cumbersome and sometimes you forget the test - so also very error-prone.
- You use a QUI\Collection and offer it as a kind of collection object, which takes all ERP providers. The nice thing about a QUI\Collection is that you can determine what kind of child elements (objects) are allowed in the collection.
The basic procedure for collections is simple.
- You need some kind of collection object which inherits from the QUI\Collection
- You then work with this collection object.
That is all. Now, if you build an instance of the MyProvider class, it's a collection that only holds QUI\ERP\Api\AbstractErpProvider.
I will show you how to use the MyProvider Collection.
As you can see the whole thing has become quite simple through the collections.
I hope the QUI Collection will help one or the other API developer. This will definitely make your API simpler and safer (more stable) to use.