magento-service-contracts

Magento 2 Service Contracts & Repositories

Before writing code

Fetch live docs:

1. Fetch https://developer.adobe.com/commerce/php/development/components/web-api/services/ for service contract guide
2. Fetch https://developer.adobe.com/commerce/php/development/components/searching-with-repositories/ 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)
2. getById($id) — retrieve single entity
3. save(SomeInterface $entity) — create or update
4. delete(SomeInterface $entity) — remove
5. getList(SearchCriteriaInterface $criteria) — filtered/sorted/paginated results

1. Data Interfaces (Api/Data/SomeInterface.php)
2. Define getters and setters for entity fields
3. getId(), setId($id), getName(), setName($name), etc.
4. Constants for field names: const NAME = 'name';

1. SearchResults Interface (Api/Data/SomeSearchResultsInterface.php)
2. Extends Magento\Framework\Api\SearchResultsInterface
3. 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

Repository Implementation Pattern

The concrete repository class:

1. Injects: Model Factory, Resource Model, Collection Factory, SearchResultsFactory, CollectionProcessor
2. getById() — creates model via factory, loads via resource model
3. save() — calls resource model save(), handles exceptions
4. delete() — calls resource model delete()
5. getList() — creates collection, applies criteria via CollectionProcessor, wraps in SearchResults

Service Contracts as Web API

When you define a service contract interface and map it in webapi.xml, the same code serves:

• REST API endpoints
• SOAP API endpoints
• Internal PHP calls

Best Practices

• Always define data interfaces — don't expose models directly
• Use typed return types and parameter types on all interface methods
• Add @api annotation to indicate public API stability
• Use SearchCriteriaBuilder instead of raw collection filtering in service layer
• Throw specific exceptions: NoSuchEntityException, CouldNotSaveException, CouldNotDeleteException
• Map service contracts in webapi.xml for automatic REST/SOAP exposure

Fetch the service contracts and searching-with-repositories docs for exact interface signatures, exception classes, and CollectionProcessor usage before implementing.