Being a part of the Symfony ecosystem gives access to the vast number of open-source solutions built on top. A lot of people voluntarily committed the time to make impressive, multipurpose solutions. One of these solutions is the API Platform, the most mature framework for API development. In Sylius, it was always our goal to take advantage of the best of the breed and integrate with others. Keeping this in mind, we have decided to combine both projects and deliver a new quality in the headless e-commerce world. How did it go to integrate new infrastructure to the existing, pretty big codebase? What were the main challenges that we encountered, and how did we solve them? What are the key take-outs from our integrations? I will answer these and a few more questions during this presentation.

1. Sylius and API Platform
The story of integration

4. Foreword

5. Application & Infrastructure
Hexagonal

6. 3 topcis
Application, API Design, Testing

7. What did we want to
achieve?

8. Become modern,
API-
fi
rst e-commerce

9. Deliver a new quality in the
headless e-commerce

10. Be closer to Symfony

11. Always up-to-date
documentation

12. Application architecture
Photo by Marc-Olivier Jodoin on Unsplash

13. How to preserve Api Platform
usage easiness and Sylius
fl
exibility?

14. How to handle typical create,
update and read operations?

15. CRUD

16. Easy to setup

17. Easy to setup
Easy to use

18. Easy to setup
Easy to use
Easy to extend

19. Familiar for most developers

20. How?

21. #[ORMEntity
]
#[ApiResource
]
class Produc
t
{
/** */
}

23. Cons

24. Harder to bend to business
expectations

25. How to handle business
expectations?

26. Commands

27. Super
fl
exible
Gives possible to defer execution
Decouples layers

28. Infrastructure
Application

29. Infrastructure
Command
Application

30. Infrastructure
Handler
Command
Application

31. Infrastructure
Handler
Command
Messenger
Application

32. How?

33. class AddItemToCar
t
{
public ProductVariant $productVariant
;
public int $quantity;
}

34. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart;
}
}

35. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart
;
}
}

36. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart
;
}
}

37. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart
;
}
}

38. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart;
}
}

39. One command
One handler

40. Transaction & Validation
Middleware's

41. Super
fl
exible
Gives possible to defer execution
Decouples layers

42. Are they separated?

43. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart;
}
}

44. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $this->cartContext->getCart()
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart
;
}
}

45. class AddItemToCar
t
{
public Order $order;
public ProductVariant $productVariant
;
public int $quantity
;
}

46. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$cart = $command->order
;
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart
;
}
}

47. No session/request data
in handlers and below

48. Command should contain
all information required
to perform an action

49. Super
fl
exible
Gives possible to defer execution or
send it outside
Decouples layers

50. Can we defer it?

51. class AddItemToCar
t
{
public Order $order
;
public ProductVariant $productVariant
;
public int $quantity
;
}

52. class AddItemToCar
t
{
public string $orderToken;
public string $productVariantCode
;
public int $quantity;
}

53. final class AddItemToCartHandle
r
{
public function __invoke(AddItemToCart $command): Orde
r
{
$productVariant = $this->productVariantRepository->findOneBy
(
['code' => $addItemToCart->productVariantCode
]
)
;
$cart = $this->orderRepository->findCartByTokenValue
(
$addItemToCart->orderTokenValu
e
);
$cartItem = $this->cartItemFactory->createNew()
;
$cartItem->setVariant($command->productVariant)
;
$this->orderItemQuantityModifier->modify
(
$cartItem,
$command->quantit
y
)
;
$this->orderModifier->addToOrder($cart, $cartItem)
;
return $cart
;
}
}

54. Commands with raw data only

55. But where this data came from?

59. DataTransformer?

60. Every “new” keyword couples you to
given implementation

61. Not relevant for 87% of developers
Faked Data Institute ®

62. Command enrichment!

63. class AddItemToCart implements OrderTokenValueAwareInterfac
e
{
public ?string $orderTokenValue
;
public string $productVariantCode
;
public int $quantity
;
public function getOrderTokenValue(): ?strin
g
{
return $this->orderTokenValue
;
}
public function setOrderTokenValue(?string $orderTokenValue): voi
d
{
$this->orderTokenValue = $orderTokenValue
;
}
}

64. final class OrderTokenValueAwareInputCommandDataTransforme
r
implements CommandDataTransformerInterfac
e
{
public function transform($object, string $to, array $context = []
)
{
/** @var OrderInterface $cart *
/
$cart = $context['object_to_populate']
;
$object->setOrderTokenValue($cart->getTokenValue())
;
return $object
;
}
public function supportsTransformation($object): boo
l
{
return $object instanceof OrderTokenValueAwareInterface
;
}
}

65. DataTransformer
vs
DataEnrichment

66. Current user

67. Current user
Current locale

68. Current user
Current locale
Current channel(Sylius speci
fi
c)

69. Current user
Current locale
Current channel(Sylius speci
fi
c)
Current order

70. Current user
Current locale
Current channel(Sylius speci
fi
c)
Current order

71. No session/request data
in handlers and below

72. Enrichments provide better class
extendibility for framework

73. Interfaces as contracts

74. Cons

75. More complicated architecture
Steeper learning curve

76. API Design
Photo by Halacious on Unsplash

77. How to model our API?

78. IRI usage

79. {
"@context": "/api/v2/contexts/ProductVariant"
,
"@id": "/api/v2/shop/product-variants/MUG_BLUE"
,
"@type": "ProductVariant"
,
"id": @integer@
,
"onHand": 10
,
"code": "MUG_BLUE"
,
"currentStock": 5
,
"product": "/api/v2/shop/products/MUG"
,
"optionValues":
[
"/api/v2/shop/product-option-values/COLOR_BLUE
"
]
,
"translations": {...}
,
"price": 2000
,
"originalPrice": 2000
,
"inStock": tru
e
}

80. {
"@context": "/api/v2/contexts/ProductVariant"
,
"@id": "/api/v2/shop/product-variants/MUG_BLUE"
,
"@type": "ProductVariant"
,
"id": @integer@
,
"onHand": 10
,
"code": "MUG_BLUE"
,
"currentStock": 5
,
"product": "/api/v2/shop/products/MUG"
,
"optionValues":
[
"/api/v2/shop/product-option-values/COLOR_BLUE
"
]
,
"translations": {...}
,
"price": 2000
,
"originalPrice": 2000
,
"inStock": tru
e
}

81. {
"@context": "/api/v2/contexts/ProductVariant"
,
"@id": "/api/v2/shop/product-variants/MUG_BLUE"
,
"@type": "ProductVariant"
,
"id": @integer@
,
"onHand": 10
,
"code": "MUG_BLUE"
,
"currentStock": 5
,
"product": "/api/v2/shop/products/MUG"
,
"optionValues":
[
"/api/v2/shop/product-option-values/COLOR_BLUE
"
]
,
"translations": {...}
,
"price": 2000
,
"originalPrice": 2000
,
"inStock": tru
e
}

82. {
"@context": "/api/v2/contexts/ProductVariant"
,
"@id": "/api/v2/shop/product-variants/MUG_BLUE"
,
"@type": "ProductVariant"
,
"id": @integer@
,
"onHand": 10
,
"code": "MUG_BLUE"
,
"currentStock": 5
,
"product": "/api/v2/shop/products/MUG"
,
"optionValues":
[
"/api/v2/shop/product-option-values/COLOR_BLUE
"
]
,
"translations": {...}
,
"price": 2000
,
"originalPrice": 2000
,
"inStock": tru
e
}

83. class AddItemToCar
t
{
public string $orderToken;
public string $productVariantCode
;
public int $quantity;
}

86. How?

87. <class name="SyliusBundleApiBundleCommandCartAddItemToCart">
<attribute name="productVariantCode
"
serialized-name="productVariant
"
>
<group>shop:cart:add_item</group
>
</attribute
>
<attribute name="quantity"
>
<group>shop:cart:add_item</group
>
</attribute
>
</class>

88. class AddItemToCart implements IriToIdenti
fi
erConversionAwareInterfac
e
{
public string $orderToken
;
public string $productVariantCode
;
public int $quantity
;
}

89. Database =/= resource

90. Reset password

92. <resource
class=“SyliusBundleApiBundleCommandResetPassword
"
shortName="ResetPasswordRequest"
>
<collectionOperations
>
<collectionOperation name="shop_create_reset_password_request"
>
<attribute name="method">POST</attribute
>
<attribute name="path">/reset-password-requests</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandRequestResetPasswordToke
n
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</collectionOperation
>
</collectionOperations
>
<itemOperations
>
<itemOperation name="shop_update_reset_password_request"
>
<attribute name="method">PATCH</attribute
>
<attribute name="path">/reset-password-requests/{id}</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandResetPasswor
d
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</itemOperation
>
</itemOperations
>
</resource>

93. <resource
class=“SyliusBundleApiBundleCommandResetPassword
"
shortName="ResetPasswordRequest"
>
<collectionOperations
>
<collectionOperation name="shop_create_reset_password_request">
<attribute name="method">POST</attribute
>
<attribute name="path">/reset-password-requests</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandRequestResetPasswordToke
n
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</collectionOperation
>
</collectionOperations
>
<itemOperations
>
<itemOperation name="shop_update_reset_password_request"
>
<attribute name="method">PATCH</attribute
>
<attribute name="path">/reset-password-requests/{id}</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandResetPasswor
d
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</itemOperation
>
</itemOperations
>
</resource>

94. <resource
class=“SyliusBundleApiBundleCommandResetPassword
"
shortName="ResetPasswordRequest"
>
<collectionOperations
>
<collectionOperation name="shop_create_reset_password_request"
>
<attribute name="method">POST</attribute
>
<attribute name="path">/reset-password-requests</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandRequestResetPasswordToke
n
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</collectionOperation
>
</collectionOperations
>
<itemOperations
>
<itemOperation name="shop_update_reset_password_request">
<attribute name="method">PATCH</attribute
>
<attribute name="path">/reset-password-requests/{id}</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandResetPasswor
d
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</itemOperation
>
</itemOperations
>
</resource>

95. <resource
class=“SyliusBundleApiBundleCommandResetPassword
"
shortName="ResetPasswordRequest"
>
<collectionOperations
>
<collectionOperation name="shop_create_reset_password_request"
>
<attribute name="method">POST</attribute
>
<attribute name="path">/reset-password-requests</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandRequestResetPasswordToke
n
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</collectionOperation
>
</collectionOperations
>
<itemOperations
>
<itemOperation name="shop_update_reset_password_request"
>
<attribute name="method">PATCH</attribute
>
<attribute name="path">/reset-password-requests/{id}</attribute
>
<attribute name=“input"
>
SyliusBundleApiBundleCommandResetPasswor
d
</attribute
>
<attribute name="output">false</attribute
>
<attribute name="status">202</attribute
>
</itemOperation
>
</itemOperations
>
</resource>

97. Testing Architecture
Photo by Danist Soh on Unsplash

98. Sylius aka BDD Warriors

100. 1500+ scenario
s
17000+ steps

101. ~2000 scenario
s
~22000 steps

102. Behat

103. Business oriented scenarios

104. Gherkin notation

105. Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background:
Given there is a user "ted@example.com" identi
fi
ed by "bear
"
Scenario: Sign in with email and passwor
d
When I want to log in with the "ted@example.com" email and the "bear" passwor
d
Then I should be logged in

106. Great to keep conversation
about features

107. Abstraction over the
implementation

108. How to test our new
infrastructure?

109. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background
:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @ap
i
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

110. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background
:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @api
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

111. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background
:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @ap
i
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

112. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background
:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @ap
i
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

113. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background
:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @ap
i
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

114. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @ap
i
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

115. /*
*
* @When I log i
n
*
/
public function iLogIn(
)
{
$this->loginPage->logIn()
;
}

116. @customer_logi
n
Feature: Signing in to the stor
e
In order to view my order
s
As a Visito
r
I want to be able to log in to the stor
e
Background:
Given the store operates on a single channel in "United States
"
And there is a user "ted@example.com" identi
fi
ed by "bear
"
@ui @api
Scenario: Sign in with email and passwor
d
When I want to log i
n
And I specify the username as "ted@example.com
"
And I specify the password as "bear
"
And I log i
n
Then I should be logged in

117. /*
*
* @When I log i
n
*
/
public function iLogIn(): voi
d
{
$this->client->call()
;
}

118. Behat as migration tool

119. Cons

120. Implementation overhead
New syntax to be familiar with

121. We didn’t seen our APIs
that much

122. How to keep contracts and
design our APIs?

123. PHPUnit

124. Whole response easily visible

125. {
"@context": "/api/v2/contexts/Payment"
,
"@id": "/api/v2/shop/payments/@integer@"
,
"@type": "Payment"
,
"order": "/api/v2/shop/orders/nAWw2jewpA"
,
"id": @integer@
,
"method":
{
"@id": "/api/v2/shop/payment-methods/CASH_ON_DELIVERY"
,
"@type": "PaymentMethod"
,
"name": "Cash on delivery
"
}
,
"currencyCode": "USD"
,
"amount": 6500
,
"state": "new"
,
"details": []
,
"createdAt": "@string@"
,
"updatedAt": "@string@
"
}

126. It will fail if anything will be
removed or added

127. Easy to setup and maintain

128. lchrusciel/ApiTestCase
or
Internal Api Platform ApiTestCase

129. Simpli
fi
ed tests only

130. Mostly one API call only
Arrangement => DB
fi
xtures + commands
No business
fl
ow checks

131. /** @test *
/
public function it_gets_details_about_product_variant(): voi
d
{
$this->loadFixturesFromFile('test_data.yaml')
;
$this->client->request
(
'GET'
,
'/api/v2/shop/product-variants/MUG_BLUE',
[],
[],
self::CONTENT_TYPE_HEADE
R
)
;
$response = $this->client->getResponse()
;
$this->assertResponse($response, 'get_product_variant_response', Response::HTTP_OK)
;
}

132. /** @test *
/
public function it_gets_details_about_product_variant(): voi
d
{
$this->loadFixturesFromFile('test_data.yaml')
;
$this->client->request
(
'GET'
,
'/api/v2/shop/product-variants/MUG_BLUE',
[],
[],
self::CONTENT_TYPE_HEADE
R
)
;
$response = $this->client->getResponse()
;
$this->assertResponse($response, 'get_product_variant_response', Response::HTTP_OK)
;
}

133. /** @test *
/
public function it_gets_details_about_product_variant(): voi
d
{
$this->loadFixturesFromFile('test_data.yaml')
;
$this->client->request
(
'GET'
,
'/api/v2/shop/product-variants/MUG_BLUE',
[],
[],
self::CONTENT_TYPE_HEADE
R
)
;
$response = $this->client->getResponse()
;
$this->assertResponse($response, 'get_product_variant_response', Response::HTTP_OK)
;
}

134. /** @test *
/
public function it_gets_details_about_product_variant(): voi
d
{
$this->loadFixturesFromFile('test_data.yaml')
;
$this->client->request
(
'GET'
,
'/api/v2/shop/product-variants/MUG_BLUE',
[],
[],
self::CONTENT_TYPE_HEADE
R
)
;
$response = $this->client->getResponse()
;
$this->assertResponse($response, 'get_product_variant_response', Response::HTTP_OK)
;
}

135. /** @test */
public function it_gets_details_about_product_variant(): voi
d
{
$this->loadFixturesFromFile('test_data.yaml')
;
$this->client->request
(
'GET'
,
'/api/v2/shop/product-variants/MUG_BLUE',
[],
[],
self::CONTENT_TYPE_HEADE
R
)
;
$response = $this->client->getResponse()
;
$this->assertResponse($response, 'get_product_variant_response', Response::HTTP_OK)
;
}

136. {
"@context": "/api/v2/contexts/ProductVariant"
,
"@id": "/api/v2/shop/product-variants/MUG_BLUE"
,
"@type": "ProductVariant"
,
"id": @integer@
,
"onHand": 10
,
"code": "MUG_BLUE"
,
"currentStock": 5
,
"product": "/api/v2/shop/products/MUG"
,
"optionValues":
[
"/api/v2/shop/product-option-values/COLOR_BLUE
"
]
,
"translations":
{
"en_US":
{
"@id": "/api/v2/shop/product-variant-translation/@integer@"
,
"@type": "ProductVariantTranslation"
,
"id": @integer@
,
"name": "Blue Mug"
,
"locale": "en_US
"
}
}
,
"price": 2000
,
"originalPrice": 2000
,
"inStock": tru
e
}

137. Cons

138. Developer oriented usage

139. Summary

140. What are the pros & cons of
this integration?

142. https://master.demo.sylius.com/api/v2/docs

143. @Sylius
Thank you!
@lukaszchrusciel