Service Implementation
This is the proposed model for implementing Magento services. Using a service layer with interfaces described by service IDLs provides the following advantages for developing and maintaining Magento extensions:
-
A service encapsulates domain/business logic in a single component.
-
Multiple implementations of a service can be supported in the same Magento instance.
-
A service’s owner controls the quality of the service component, because other components are restricted from directly modifying the implementation.
-
Data access becomes a private concern of the service implementation, which increases predictability and compatibility.
-
A service can be exposed as a Web API. To see how this is done, check out Creating Web APIs.
- The data are defined declaratively in schemas, rather than in PHP classes.
Implementing a Service
The first step in creating a service component is to define the service using the service IDL.
Once you have defined a service IDL, you implement the service using a PHP class. You make the public methods of this PHP class available to your extension’s presentation layer, which uses the methods to access data.
As an example, the documentation for the Product service IDL here describes how to define a service using the service IDL.
The source code for Product service is here
The service has a method, item (line 117). The method takes a single
parameter, which is the product ID, and retrieves product data in an array
defined by the response schema.
The @Consumes annotation names the schema for the request, and @Produces
annotation names the schema for the response defined in the IDL. (By the way,
@Version refers to the version of the service, not the individual call.)
The business logic for the service method is implemented using models and resource models.
Once you have implemented the service as a PHP class, you make the public methods of the service available to the presentation tier components by declaring the service-calls in service-calls.xml.
<service-calls>
<service-call name="selectedProductDetails" service="Mage_Catalog_Service_Product" method="item">
<arg name="productId">{{request.params.id}}</arg>
</service-call>
<service-call name="selectedProductOptions" service="Mage_Catalog_Service_Product" method="getOptions">
<arg name="productId">{{request.params.id}}</arg>
</service-call>
<service-call name="relatedProducts" service="Mage_Catalog_Service_Product" method="getRelatedProducts">
<arg name="productId">{{request.params.id}}</arg>
</service-call>
</service-calls>
Once the service is implemented and its service methods are declared as service-calls, you invoke the service-call by including the following declaration in layout.xml
<block type="Mage_Catalog_Block_Product_Twig" module="Mage_Catalog" name="product.info"
template="Mage_Catalog::product/view.twig">
<data service-call="selectedProductDetails" alias="product" />
...
...
</block>
The Product service-calls are invoked in the Catalog Product layout when rendering the templates for the Product View page. For details, you can refer to the layout.xml for Catalog Product.
Below are details of the input and output data schema for Product service item method.
Input Schema
This schema defines the service’s single request parameter.
| Name | Type | Description | Sample |
|---|---|---|---|
| id | xs:integer | The product ID number | 1234 |
Output Schema
This schema defines the array to be returned by the product service item method.
| Name | Type | Description | Sample |
|---|---|---|---|
| product | mage:product | ||
| product.data | |||
| product.relatedData | |||
| dictionary | Complex type | ||
| dictionary.urlInStore | xs:anyURI | ||
| dictionary.urlPath | xs:string | ||
| dictionaryurl | xs.anyURI | ||
| dictionary.submitUrl | xs.anyURI | ||
| dictionary.compareURL | xs:anyURI | ||
| dictionary.compareURL | xs:anyURI | ||
| dictionary.fileViewURL | xs:anyURI | ||
| dictionary.emailToFriendURL | xs:anyURI | ||
| dictionary.canEmailToFriend | xs:anyURI | ||
| dictionary.hasOptions | xs:boolean | ||
| dictionary.wishListDataAllowed | xs:boolean | ||
| dictionary.optionsContainer | xs:string | ||
| dictionary.jsonConfig | xs:string | ||
| dictionary.isSaleable | xs:boolean | ||
| dictionary.formattedPrice | xs:string |
The table below documents complex type Product from the above schema
| Name | Type | Description | Sample |
|---|---|---|---|
| name | string | Product name. Required. | New product |
| sku | string | Product SKU. Constrains: maxLength value = 64. Required. | new_product |
| description | string | Product description. Required. | This is a new product. |
| shortDescription | string | Product short description. Required. | A new product. |
| price | mage:price | Product price. Required. | 200 |
| specialPrice | complex type | ||
| specialPrice.specialPrice | mage:price | Product special price. Optional. | 150 |
| specialPrice.specialFromDate | dateTime | Date starting from which the special price will be applied to the product. Optional. | 2005-08-15T15:52:01+0000 |
| specialPrice.specialToDate | dateTime | Date till which the special price will be applied to the product. Optional. | 2005-08-15T15:52:01+0000 |
| cost | mage:price | Product cost. Optional. | 100 |
| weight | decimal | Product weight. Required. | 0.5 |
| manufacturer | integer | Product manufacturer. Optional. | Test manufacturer |
| metaTitle | string | Product meta title. Optional. | new product |
| metaKeyword | string | Product meta keywords. Optional. | new, product |
| metaDescription | string | Product meta description. Constrains: maxLength value = 255. Optional. | This is a new product |
| images | complex type | ||
| images.image | mage:image_type | Product image. Optional. | |
| images.smallImage | mage:image_type | Product small image. Optional. | |
| images.thumbnail | mage:image_type | Product thumbnail image. Optional. | |
| mediaGallery | mage:media_gallery | Product images. Optional. | |
| oldId | integer | Original system ID assigned to the product, if a catalog has been imported from legacy system. Optional. | 123 |
| groupPrice | mage:price | Product group price. Optional. | array of group price |
| tierPrice | mage:price | Product tier price. Optional. | array of tier price |
| color | integer | Product color. Optional. | |
| newsFromDate | dateTime | Date starting from which the product is promoted as a new product. Optional. | 2005-08-15T15:52:01+0000 |
| newsToDate | dateTime | Date till which the product is promoted as a new product. Optional. | 2005-08-15T15:52:01+0000 |
| gallery | string | Optional. | |
| status | mage:integer_label | Product status. Can have the following values: 1- Enabled, 2 - Disabled. Required. | 1 |
| urlKey | string | A friendly URL path for the product. Optional. | new-product |
| urlPath | string | Optional. | |
| minimalPrice | mage:price | Minimal price of the product. Optional. | |
| isRecurring | boolean | Defines whether the product is recurring. Optional. | 1 |
| recurringProfile | string | Information about the recurring payments. Optional. | |
| visibility | mage:integer_label | Product visibility. Can have the following values: 1 - Not Visible Individually, 2 - Catalog, 3 - Search, 4 - Catalog, Search. Required. | 1 |
| customDesign | string | Custom design applied for the product page. Optional. | enterprise/default |
| customDesignFrom | dateTime | Date starting from which the custom design will be applied to the product page. Optional. | 2005-08-15T15:52:01+0000 |
| customDesignTo | dateTime | Date till which the custom design will be applied to the product page. Optional. | 2005-08-15T15:52:01+0000 |
| customLayoutUpdate | string | An XML block to alter the page layout. Optional. | XML body |
| pageLayout | mage:string_label_array | Page template that can be applied to the product page. Optional. | one_column |
| categoryIds | mage:string_label_array | Contains the category(s) ID (s) to which a product belongs. Optional. | |
| optionsContainer | string | Defines how the custom options for the product will be displayed. Can have the following values: Block after Info Column or Product Info Column. Optional. | container2 |
| requiredOptions | boolean | Defines whether specifying the product option is mandatory or not. Optional. | 1 |
| hasOptions | boolean | Defines whether a product has the custom options or not. Optional. | 1 |
| createdAt | dateTime | Defines the date of a product creation. Optional. | 2005-08-15T15:52:01+0000 |
| updatedAt | dateTime | Defines the date of a product update. Optional. | 2005-08-15T15:52:01+0000 |
| countryOfManufacture | string | Product's country of manufacture. Optional. | AD |
| msrpEnabled | mage:integer_label | The Apply MAP option. Defines whether the price in the catalog in the frontend is substituted with a Click for price link. Optional. | 1 |
| msrpDisplayActualPriceType | mage:integer_label | Defines how the price will be displayed in the frontend. Can have the following values: In Cart, Before Order Confirmation, and On Gesture. Optional. | 2 |
| msrp | mage:price | The Manufacturer's Suggested Retail Price option. The price that a manufacturer suggests to sell the product at. Optional. | 140 |
| quantityAndStockStatus | complexType | ||
| quantityAndStockStatus.isInStock | boolean | Defines whether the product is available for selling. Optional. | 1 |
| quantityAndStockStatus.qty | decimal | Quantity of stock items for the current product. Optional. | 99 |
| bundle | complexType | ||
| bundle.priceType | integer | Defines whether the bundle product price is Dynamic or Fixed. Required. | 1 |
| bundle.skuType | integer | Defined whether the bundle product SKU is Dynamic or Fixed. Required. | 1 |
| bundle.weightType | integer | Defined whether the bundle product weight is Dynamic or Fixed. Required. | 1 |
| bundle.priceView | mage:integer_label | Defined whether the bundle product price should display as "Price Range" or "As Low as." Required. | 1 |
| bundle.shipmentType | integer | Defines whether the bundle items are to be shipped together or separately. Optional. | 1 |
| downloadable | complexType | ||
| downloadable.linksPurchasedSeparately | boolean | Defines whether the downloadable product links could be purchased separately. Optional. | 1 |
| downloadable.samplesTitle | string | Title of the downloadable product sample. Optional. | Sample |
| downloadable.linksTitle | string | Title of the downloadable product link. Optional. | Links |
| downloadable.linksExist | boolean | Optional. | 1 |
| giftMessageAvailable | boolean | Defines whether the gift message is available for the product. Optional. | 1 |
| taxClassId | mage:string_label | Product tax class. Can have the following values: 0 - None, 2 - taxable Goods, 4 - Shipping, etc., depending on created tax classes. Required. | 7 |
| enableGooglecheckout | boolean | Defines whether the product can be purchased with the help of the Google Checkout payment service. Can have the following values: Yes and No. Optional. | 1 |
| giftcard | complexType | ||
| giftcard.giftcardAmounts | complexType | Defines the available amounts for the gift card product. Required. | |
| giftcard.giftcardAmounts.amount | mage:price | Defines the amount for a gift card. Constrains: maxOccurs = unbounded. Required. | 20 |
| giftcard.allowOpenAmount | boolean | Defines whether the open amount is allowed for a gift card. Optional. | 1 |
| giftcard.openAmountMin | mage:price | Defines the minimal amount of a gift card if the open amount is allowed. Optional. | 5 |
| giftcard.openAmountMax | mage:price | Defines the maximal amount of a gift card if the open amount is allowed. Optional. | 100 |
| giftcard.giftcardType | mage:integer_label | Defines the type of a gift card: Virtual, Physical, or Combined. Required. | 2 |
| giftcard.isRedeemable | boolean | Defines whether the card is redeemable. Optional. | 1 |
| giftcard.useConfigIsRedeemable | boolean | Defines whether the settings specified in the store's Configuration section should apply for the Is Redeemable option. Optional. | 1 |
| giftcard.lifetime | integer | Defines for how many days a gift card is valid. Optional. | 3 |
| giftcard.useConfigLifetime | boolean | Defines whether the settings specified in the store's Configuration section should apply for the Lifetime option. Optional. | 1 |
| giftcard.emailTemplate | string | Defines which email template should be used for a gift card. Optional. | |
| giftcard.useConfigEmailTemplate | boolean | Defines whether the settings specified in the store's Configuration section should apply for the Email Template option. Optional. | 1 |
| giftcard.allowMessage | boolean | Defines whether the accompanying message is allowed for a gift card. Optional. | 1 |
| giftcard.useConfigAllowMessage | boolean | Defines whether the settings specified in the store's Configuration section should apply for the Allow Message option. Optional. | 1 |
| giftWrappingAvailable | boolean | Defines whether the gift wrapping is allowed. Optional. | 1 |
| giftWrappingPrice | mage:price | Defines the price for the gift wrapping of a product. Optional. | 5 |
| isReturnable | mage:integer_label | Defines whether a customer will be able to return a product. Optional. | 1 |
| targetRules | complexType | ||
| targetRules.related | mage:target_rule | Contains the IDs of the related products. Optional. | 1 |
| targetRules.upsell | mage:target_rule | Contains the IDs of the upsell products. Optional. | 1 |