A Service contract is a design pattern of Magento 2 in which define set of classes and interfaces. This interfaces provides services which preserve data integrity and hide business logic from service requestors. Service Contract must define the service interfaces in the Api subdirectory for a Magento 2 module. You can add management, repository and metadata interfaces in service interfaces.
Why Magento 2 Use service contract ?
We all know that Magento follow the Modular system and we are using external modules in our stores, which allows thrid party developers for customization and override core parts of framework. Magento Gives this flexibilily, but it's may lead several issues during upgrade the Magento. The Magento 2 comes up with service contract pattern to overcome this problem.
The one more thing is we have already use Magento 1.x versions, we know that we are using helper classes and model classes directly for interecting with other modules. This is not proper way for communicating with other modules. You can now use service contract for solve these problems in Magento 2. You can easily set, get and manipulate data using service contract without worried about system. Using service contracts, You can easily convert this Service business logic to web APIs.
How service contract is works in module ?
There are two types of interface we need to define for create service contract in our module.
1) Data interfaces
2) Service Interfaces
Data Interfaces in Service Contract Magento 2
Data interfaces must define in the Api/Data subdirectory for a module. For example : The data interfaces for our custom module app/code/Testmodule/Test/Api/Data subdirectory.
Data interfaces are use for maintain data integrity. Data interfaces are defines all the setters and getters methods for entities.
You can define all the data interfaces in Api/Data subdirectory in which you can define all the setter and getters deffinition.
Let's see one example of data interface : Magento\Customer\Api\Data\CustomerInterface
<?php
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
namespace Magento\Customer\Api\Data;
/**
* Customer interface.
* @api
* @since 100.0.2
*/
interface CustomerInterface extends \Magento\Framework\Api\CustomAttributesDataInterface
{
/**#@+
* Constants defined for keys of the data array. Identical to the name of the getter in snake case
*/
const ID = 'id';
const CONFIRMATION = 'confirmation';
const CREATED_AT = 'created_at';
const UPDATED_AT = 'updated_at';
const CREATED_IN = 'created_in';
const DOB = 'dob';
const EMAIL = 'email';
const FIRSTNAME = 'firstname';
const GENDER = 'gender';
const GROUP_ID = 'group_id';
const LASTNAME = 'lastname';
const MIDDLENAME = 'middlename';
const PREFIX = 'prefix';
const STORE_ID = 'store_id';
const SUFFIX = 'suffix';
const TAXVAT = 'taxvat';
const WEBSITE_ID = 'website_id';
const DEFAULT_BILLING = 'default_billing';
const DEFAULT_SHIPPING = 'default_shipping';
const KEY_ADDRESSES = 'addresses';
const DISABLE_AUTO_GROUP_CHANGE = 'disable_auto_group_change';
/**#@-*/
/**
* Get customer id
*
* @return int|null
*/
public function getId();
/**
* Set customer id
*
* @param int $id
* @return $this
*/
public function setId($id);
/**
* Get group id
*
* @return int|null
*/
public function getGroupId();
/**
* Set group id
*
* @param int $groupId
* @return $this
*/
public function setGroupId($groupId);
/**
* Get default billing address id
*
* @return string|null
*/
public function getDefaultBilling();
/**
* Set default billing address id
*
* @param string $defaultBilling
* @return $this
*/
public function setDefaultBilling($defaultBilling);
/**
* Get default shipping address id
*
* @return string|null
*/
public function getDefaultShipping();
/**
* Set default shipping address id
*
* @param string $defaultShipping
* @return $this
*/
public function setDefaultShipping($defaultShipping);
/**
* Get confirmation
*
* @return string|null
*/
public function getConfirmation();
/**
* Set confirmation
*
* @param string $confirmation
* @return $this
*/
public function setConfirmation($confirmation);
/**
* Get created at time
*
* @return string|null
*/
public function getCreatedAt();
/**
* Set created at time
*
* @param string $createdAt
* @return $this
*/
public function setCreatedAt($createdAt);
/**
* Get updated at time
*
* @return string|null
*/
public function getUpdatedAt();
/**
* Set updated at time
*
* @param string $updatedAt
* @return $this
*/
public function setUpdatedAt($updatedAt);
/**
* Get created in area
*
* @return string|null
*/
public function getCreatedIn();
/**
* Set created in area
*
* @param string $createdIn
* @return $this
*/
public function setCreatedIn($createdIn);
/**
* Get date of birth
*
* @return string|null
*/
public function getDob();
/**
* Set date of birth
*
* @param string $dob
* @return $this
*/
public function setDob($dob);
/**
* Get email address
*
* @return string
*/
public function getEmail();
/**
* Set email address
*
* @param string $email
* @return $this
*/
public function setEmail($email);
/**
* Get first name
*
* @return string
*/
public function getFirstname();
/**
* Set first name
*
* @param string $firstname
* @return $this
*/
public function setFirstname($firstname);
/**
* Get last name
*
* @return string
*/
public function getLastname();
/**
* Set last name
*
* @param string $lastname
* @return $this
*/
public function setLastname($lastname);
/**
* Get middle name
*
* @return string|null
*/
public function getMiddlename();
/**
* Set middle name
*
* @param string $middlename
* @return $this
*/
public function setMiddlename($middlename);
/**
* Get prefix
*
* @return string|null
*/
public function getPrefix();
/**
* Set prefix
*
* @param string $prefix
* @return $this
*/
public function setPrefix($prefix);
/**
* Get suffix
*
* @return string|null
*/
public function getSuffix();
/**
* Set suffix
*
* @param string $suffix
* @return $this
*/
public function setSuffix($suffix);
/**
* Get gender
*
* @return int|null
*/
public function getGender();
/**
* Set gender
*
* @param int $gender
* @return $this
*/
public function setGender($gender);
/**
* Get store id
*
* @return int|null
*/
public function getStoreId();
/**
* Set store id
*
* @param int $storeId
* @return $this
*/
public function setStoreId($storeId);
/**
* Get tax Vat
*
* @return string|null
*/
public function getTaxvat();
/**
* Set tax Vat
*
* @param string $taxvat
* @return $this
*/
public function setTaxvat($taxvat);
/**
* Get website id
*
* @return int|null
*/
public function getWebsiteId();
/**
* Set website id
*
* @param int $websiteId
* @return $this
*/
public function setWebsiteId($websiteId);
/**
* Get customer addresses.
*
* @return \Magento\Customer\Api\Data\AddressInterface[]|null
*/
public function getAddresses();
/**
* Set customer addresses.
*
* @param \Magento\Customer\Api\Data\AddressInterface[] $addresses
* @return $this
*/
public function setAddresses(array $addresses = null);
/**
* Get disable auto group change flag.
*
* @return int|null
*/
public function getDisableAutoGroupChange();
/**
* Set disable auto group change flag.
*
* @param int $disableAutoGroupChange
* @return $this
*/
public function setDisableAutoGroupChange($disableAutoGroupChange);
/**
* Retrieve existing extension attributes object or create a new one.
*
* @return \Magento\Customer\Api\Data\CustomerExtensionInterface|null
*/
public function getExtensionAttributes();
/**
* Set an extension attributes object.
*
* @param \Magento\Customer\Api\Data\CustomerExtensionInterface $extensionAttributes
* @return $this
*/
public function setExtensionAttributes(\Magento\Customer\Api\Data\CustomerExtensionInterface $extensionAttributes);
}
You can see many setters and getters methods, data member variables in above customer data interface. You have questions about some methods like setExtensionAttributes and getExtensionAttributes in above data interface.
The setExtensionAttributes and getExtensionAttributes methods are use for set and get additional values in api.
Service Interface in Service Contract Magento 2
Service interfaces must define in the top-level Api directory for a module. Service interfaces hide business logic from service requestors.
Service interfaces have many types of interfaces. Please check below.
- Repository interfaces
- Management interfaces
- Metadata interfaces
Repository interfaces
Repository interfaces is use for access persistent data entities. Repository Interface provide many functions like save, get, getList, delete and deleteById. These function must have to implemented in repository interfaces.
For Example : Let's see one example of data interface : Magento\Customer\Api\CustomerRepositoryInterface
<?php
/**
*
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
namespace Magento\Customer\Api;
/**
* Customer CRUD interface.
* @api
* @since 100.0.2
*/
interface CustomerRepositoryInterface
{
/**
* Create or update a customer.
*
* @param \Magento\Customer\Api\Data\CustomerInterface $customer
* @param string $passwordHash
* @return \Magento\Customer\Api\Data\CustomerInterface
* @throws \Magento\Framework\Exception\InputException If bad input is provided
* @throws \Magento\Framework\Exception\State\InputMismatchException If the provided email is already used
* @throws \Magento\Framework\Exception\LocalizedException
*/
public function save(\Magento\Customer\Api\Data\CustomerInterface $customer, $passwordHash = null);
/**
* Retrieve customer.
*
* @param string $email
* @param int|null $websiteId
* @return \Magento\Customer\Api\Data\CustomerInterface
* @throws \Magento\Framework\Exception\NoSuchEntityException If customer with the specified email does not exist.
* @throws \Magento\Framework\Exception\LocalizedException
*/
public function get($email, $websiteId = null);
/**
* Get customer by Customer ID.
*
* @param int $customerId
* @return \Magento\Customer\Api\Data\CustomerInterface
* @throws \Magento\Framework\Exception\NoSuchEntityException If customer with the specified ID does not exist.
* @throws \Magento\Framework\Exception\LocalizedException
*/
public function getById($customerId);
/**
* Retrieve customers which match a specified criteria.
*
* This call returns an array of objects, but detailed information about each object’s attributes might not be
* included. See https://devdocs.magento.com/codelinks/attributes.html#CustomerRepositoryInterface to determine
* which call to use to get detailed information about all attributes for an object.
*
* @param \Magento\Framework\Api\SearchCriteriaInterface $searchCriteria
* @return \Magento\Customer\Api\Data\CustomerSearchResultsInterface
* @throws \Magento\Framework\Exception\LocalizedException
*/
public function getList(\Magento\Framework\Api\SearchCriteriaInterface $searchCriteria);
/**
* Delete customer.
*
* @param \Magento\Customer\Api\Data\CustomerInterface $customer
* @return bool true on success
* @throws \Magento\Framework\Exception\LocalizedException
*/
public function delete(\Magento\Customer\Api\Data\CustomerInterface $customer);
/**
* Delete customer by Customer ID.
*
* @param int $customerId
* @return bool true on success
* @throws \Magento\Framework\Exception\NoSuchEntityException
* @throws \Magento\Framework\Exception\LocalizedException
*/
public function deleteById($customerId);
}
Management interfaces
Management interface includes management related functions like createAccount(), changePassword(), activate(), and isEmailAvailable() functions..etc. These Management functions are not related to repositories.
AccountManagementInterface, AddressManagementInterface
Management interfaces are given below. Please check examples.
=> Magento\Customer\Api\AccountManagementInterface
=> Magento\Customer\Api\AddressManagementInterface
Metadata interfaces
Metadata interface is use for Retrieve metadata. For example : ProductMetadataInterface, AddressMetadataInterface..etc
That's all for this article. This will be too much for one article. If you have any questions in this article you can ask in the comments or email me by contact page. Thanks.