When Magento 2 was first released, many people wondered what service contracts are, and whether they’re important to the users. To this day, this is still unclear to some. As a modular system, Magento introduced service contracts in order to prevent business logic leakages across system layers, which is a result of granting 3^rd party developers the ability to modify its framework.

If you’re unfamiliar with what service contracts are in general, they’re actually agreements between two parties, a service provider and a service consumer. The contract defines the services that the consumer will get, along with some additional information.

So how does this work with Magento?

Magento service contracts

Essentially, service contracts are just a set of interfaces and classes that protect data integrity and hide the business logic. The reason why customers will want to use this is that the contract allows the service to evolve without affecting its users.

The reason this upgrade is important is because it changes the way that users interact with different modules. In Magento 1, there were no good ways of interacting with other modules. With service contracts in Magento 2, you can access and manipulate data easily, without having to worry about the system’s structure.

Service contract architecture

The service layer has two different interface types: Data interfaces and Service interfaces. Data interfaces are objects that preserve data integrity by using the following patterns:

• They’re read-only, since they only define constants and getters.
• Getter functions can contain no parameters.
• A getter function can only return a simple object type (string, integer, Boolean), a simple type array, and another data interface.
• Mixed types can’t be returned by getter functions.
• Data entity builders are the only way to populate and modify data interfaces.

Service interfaces provide a set of public methods that a client can use. There are three service interfaces subtypes:

• Repository Interfaces
• Management Interfaces
• Metadata Interfaces

Repository interfaces

Repository interfaces ensure that a user can access persistent data entities. For example, persistent data entities within the Customer Module are Consumer, Address, and Group. This gives us three different interfaces:

• CustomerRepositoryInterface
• AddressRepositoryInterface
• GroupRepositoryInterface

The methods that these interfaces have are:

• Save – If there’s no ID, creates a new record, and updates what’s existing if there is one.
• Get – Looks for the IDs in the database and returns a certain data entity interface.
• GetList – Finds all data entities that correspond with the search criteria, then gives access to the matches by returning the search result interface.
• Delete – Deletes the selected entity
• DeleteById – Deletes the entity when you only have its key.

Management interfaces

These interfaces contain different management functions that are unrelated to repositories. Here are some examples:

• AccountManagementInterface contains functions such as createAccount(), isEmailAvailable(), changePassword(), and activate().
• AddressManagementInterface checks whether an address is valid by using the validate() function.

The number of patterns is constantly growing, and as it does so, some of these functions are likely to be added to them.

Metadata interfaces

Metadata interfaces give information about all the attributes that are defined for a specific entity. This also includes custom attributes, which you can access with the getCustomAttribute($name) function. These custom attributes include:

• EAV attributes – Defined via the administration interface for a local site. They can differ according to the site, which means that they can’t be represented in the data entity interface written in PHP.
• Extension attributes, for which the extension modules are used.

Benefits of service contracts

The main benefit of service contracts is that they increase Magento’s modularity. They allow Magento and 3^rd party developers to use composer.json files to report system dependencies, which guarantees compatibility with all Magento versions. This kind of compatibility gives merchants a way of upgrading Magento easily.

Service contract also ensure a durable and well-defined API that can be implemented by third-party extensions and other modules.

Another major benefit is related to data entities. Database tables that are often used for these entities tend to be rather complex. For example, if some attributes are stored inside an EAV table, a single data entity might be defined by MySQL database tables.

Service contracts offer a much simpler solution. The data model that is simpler than a relational database schema. This gives users the ability to store different data collections using different storage technologies.

What are builders for?

If you take a closer look into data entities, you’ll notice that the only available methods are for reading from a data entity instance. So how do you use PHP code to create a data entity? Well, that’s what builders are for.

These are patterns that offer a class with the setter methods that allow you to set the properties, after which you use the final create() method to get a new instance. If you search the GitHub repo, you won’t be able to find the builder codes. The reason for this is that they’re already automatically generated for you.

Keep in mind that it’s impossible to modify the data entity that you got from somewhere. What you can do however, is use the populate($entity) method to copy the attributes from one entity into a new one. You can then change the attributes by calling the setter methods and create a new instance afterwards.

The final word

Now that you have a better understanding of what Magento 2 Service Contracts are, you can understand the reasons why they were implemented. They’re very important for increasing the modularity of Magento.

Once a module defines a service contract, it creates a well-defined API for other modules. They also allow clients to use the REST or SOAP interfaces to expose business logic.

What’s probably even more important to many users is that service contracts ensure that modules are stable after a Magento 2 upgrade. All of this makes Magento a lot more appealing to users, since this upgrade fixes quite a few well-documented shortcomings in the original. In the future, the number of service contract patterns will increase. This is all an integral part of Magento.