Magento 2 - what functions can I use?

Question

Recently I've went through the "Fundamentals of Magento 2 development" course and there was such statement that we SHOULD NOT use functions from other modules that are not defined in the API interfaces for example we should not rely on \Magento\Framework\Model\AbstractModel save() method, because it can be removed in feature releases.

Ok, fine by me, but going this way we should not use, for instance, the load() function from \Magento\Framework\Model\ResourceModel\Db\AbstractDb right? Yet, it's recommended to use it in the same course. Can anyone point me in right direction?

Answer 1

Not using any methods not in the API interfaces is an ideal that is just not possible yet, because the service contracts are far from complete, and also sometimes you need more flexibility. The core violates this principle all over the place.

It's good to try using the interfaces first, but if it's not possible in a sensible way, be pragmatic about it (Remember that SHOULD NOT does not mean MUST NOT).

Regarding load(), see also:

• Is there ever a reason to prefer $model->load() over service contracts?
• When Should We Use a Repository and Factory in Magento 2?

Answer 2

Regarding AbstractModel and save/load methods. Magento doesn't recommend to use them, because these methods violate Single Responsibility principle (S from SOLID). Entity/Domain Model which destiny is to be responsible for some business operation shouldn't be responsible for self-retrieval and saving from/into the data storage. These methods are marked @deprecated in the codebase https://github.com/magento/magento2/blob/develop/lib/internal/Magento/Framework/Model/AbstractModel.php#L633 https://github.com/magento/magento2/blob/develop/lib/internal/Magento/Framework/Model/AbstractModel.php#L526

We expect that Entity should be Extracted with the help of Repository API. Which implementation uses Entity Manager or successor of ResourceModel under the hood.

In general, Magento recommends to use interfaces/classes marked with PHP Doc @api, which means that we consider these entities as a part of module's API contract. For now the coverage of entities in a codebase with @api annotation is not full. So, we can't say that it's enough to use just @api to proceed with all possible business operations (usage/extension/customization) for successful integration with Magento modules. That's why Magento considers all the code as public APIs now, and apply Backward Compatibility policy for the whole codebase with each release, to protect 3rd party extensions from being broken after update to new Magento version.

That's why we are going to inspect how 3rd party extensions use Magento modules (what Magento entities being used which are not marked as @api) and add @api annotation to all those entities, if there is no existing valid API which should be used instead. As soon as we make this demarcation, we would start to consider code which not marked as @api as Private implementation. Thus we will modify it without applying Backward Compatibility policy. All the @api entities will follow SemVer.