magento-service-contracts

Magento 2 Service Contracts & Repositories

Before writing code

Fetch live docs:

1. Fetch https://developer.adobe.com/commerce/webapi/rest/ for service contract guide
2. Fetch https://developer.adobe.com/commerce/php/development/components/ for SearchCriteria patterns
3. Web-search site:developer.adobe.com commerce php development components service-contracts for additional reference

Conceptual Architecture

What Service Contracts Are

Service contracts are PHP interfaces that define a module's public API. They guarantee backward compatibility — implementations can change across versions without breaking consumers.

Three Interface Categories

1. Repository Interfaces (Api/SomeRepositoryInterface.php)

   • getById($id) — retrieve single entity
   • save(SomeInterface $entity) — create or update
   • delete(SomeInterface $entity) — remove
   • getList(SearchCriteriaInterface $criteria) — filtered/sorted/paginated results

2. Data Interfaces (Api/Data/SomeInterface.php)

   • Define getters and setters for entity fields
   • getId(), setId($id), getName(), setName($name), etc.
   • Constants for field names: const NAME = 'name';

3. SearchResults Interface (Api/Data/SomeSearchResultsInterface.php)

   • Extends Magento\Framework\Api\SearchResultsInterface
   • Wraps getItems() / setItems() with typed returns

SearchCriteria Pattern

Used for querying repositories with filters, sorting, and pagination:

• SearchCriteriaBuilder — fluent builder for criteria
• FilterBuilder — builds individual filter conditions
• FilterGroupBuilder — groups filters with AND/OR logic
• SortOrderBuilder — defines sort order
• CollectionProcessorInterface — applies criteria to collections

Filter Logic

• Filters within a FilterGroup are OR'd together
• FilterGroups are AND'd together
• Condition types: eq, neq, gt, gteq, lt, lteq, like, in, nin, notnull, null, from, to