Sylius Release

Nov 30, 2016

Contents

1 The Book 3 1.1 The Book...... 3

2 The Customization Guide 33 2.1 The Customization Guide...... 33

3 The API Guide 47 3.1 The API Guide...... 47

4 Cookbook 113 4.1 Cookbook...... 113

5 The Behat Guide 117 5.1 Behat guide...... 117

6 Bundles 133 6.1 Symfony2 Bundles...... 133

7 Components 313 7.1 PHP Components...... 313

8 Contributing 463 8.1 Contributing...... 463

i ii Sylius, Release

Sylius is a modern e-commerce solution for PHP, based on Symfony2 Framework.

Note: This documentation assumes you have a working knowledge of the Symfony2 Framework. If you haven’t, please start by reading the Quick Tour from the Symfony documentation.

Contents 1 Sylius, Release

2 Contents CHAPTER 1

The Book

The Developer’s guide to leveraging the ﬂexibility of Sylius.

1.1 The Book

1.1.1 Introduction to Sylius

Sylius is a game-changing e-commerce solution for PHP, based on the Symfony2 framework.

Philosophy

Sylius is completely open source (MIT license) and free, maintained by diverse and creative community of developers and companies. What are our core values and what makes us different from other solutions? • Components based approach • Unlimited ﬂexibility and simple customization • Developer-friendly, using latest technologies • Developed using best practices and BDD approach • Highest quality of code And much more, but we will let you discover it yourself.

The Three Natures of Sylius

Sylius is constructed from fully decoupled and ﬂexible e-commerce components for PHP. It is also a set of Symfony2 bundles, which integrate the components into the full-stack framework. On top of that, Sylius is also a complete e-commerce platform crafted from all these building blocks. It is your choice how to use Sylius, you can beneﬁt from the components with any framework, integrate selected bundles into existing or new Symfony2 app or built your application on top of Sylius platform.

3 Sylius, Release

Sylius Platform

This book is about our full-stack e-commerce platform, which is a standard Symfony application providing the most common webshop and a foundation for custom systems.

Leveraging Symfony2 Bundles

If you prefer to build your very custom system step by step and from scratch, you can integrate the standalone Sym- fony2 bundles. For the installation instructions, please refer to the appropriate bundle documentation.

E-Commerce Components for PHP

If you use a different framework than Symfony, you are welcome to use Sylius components, which will make it much easier to implement a webshop with any PHP application and project. They provide you with default models, services and logic for all aspects of e-commerce, completely separated and ready to use.

Final Thoughts

Depending on how you want to use Sylius, continue reading The Book, which covers the usage of the full stack solution, browse the Bundles Reference or learn about The Components.

1.1.2 Understanding Environments

Every Sylius application is the combination of code and a set of configuration that dictates how that code should function. The configuration may define the database being used, whether or not something should be cached, or how verbose logging should be. In Symfony, the idea of “environments” is the idea that the same codebase can be run using multiple different configurations. For example, the dev environment should use configuration that makes development easy and friendly, while the prod environment should use a set of configuration optimized for speed.

Development

Development environment or dev, as the name suggests, should be used for development purposes. It is much slower than production, because it uses much less aggressive caching and does a lot of processing on every request. However, it allows you to add new features or ﬁx bugs quickly, without worrying about clearing the cache after every change. Sylius console runs in dev environment by default. You can access the website in dev mode via the /app_dev.php ﬁle in the web/ directory. (under your website root)

Production

Production environment or prod is your live website environment. It uses proper caching and is much faster than other environments. It uses live APIs and sends out all e-mails. To run Sylius console in prod environment, add the following parameters to every command call:

$ app/console --env=prod --no-debug cache:clear

You can access the website in production mode via the /app.php ﬁle in your website root (web/) or just / path. (on Apache)

4 Chapter 1. The Book Sylius, Release

Test

Test environment or test is used for automated testing. Most of the time you will not access it directly. To run Sylius console in test environment, add the following parameters to every command call:

$ app/console --env=test cache:clear

Final Thoughts

You can read more about Symfony environments in this cookbook article.

1.1.3 Installation

The Sylius main application can serve as an end-user app, as well as a foundation for your custom e-commerce application.

Warning: This article assumes you’re familiar with Composer, a dependency manager for PHP. It also assumes you have Composer installed globally.

Note: If you downloaded the Composer phar archive, you should use php composer.phar where this guide uses composer.

Sylius can be installed using two different approaches, depending on your use case.

Install to Contribute

To install Sylius main application from our main repository and contribute, run the following command:

$ composer create-project -s dev sylius/sylius

This will create a new sylius project in the sylius directory. When all the dependencies are installed, you’ll be asked to ﬁll the parameters.yml ﬁle via an interactive script. Please follow the steps. If you hit enter, the default values will be loaded.

Creating the "app/config/parameters.yml" file Some parameters are missing. Please provide them. database_driver(pdo_mysql): # - provide a database driver that you are willing to use database_host(127.0.0.1): database_port(null): database_name(sylius): # - you should rename the database to for instance `my_custom_

˓→application_name` database_user(root): # - provide the database user and password database_password(null): 1234 mailer_transport(smtp): # - if you will be testing e-mails please provide here your

˓→test account data, use `gmail` as transport for example. mailer_host(127.0.0.1): mailer_user(null): # - your test email mailer_password(null): # - and password secret(EDITME): locale(en_US):

1.1. The Book 5 Sylius, Release

currency(USD): wkhtmltopdf.bin_path(/usr/bin/wkhtmltopdf): wkhtmltoimage.bin_path(/usr/bin/wkhtmltoimage):

After everything is in place, run the following commands:

$ cd sylius # Move to the newly created directory $ php app/console sylius:install

The sylius:install command actually runs several other commands, which will ask you some questions and check if everything is setup to run Sylius properly. This package contains our main Sylius development repository, with all the components and bundles in the src/ folder. For the contributing process questions, please refer to the Contributing Guide.

Bootstrap A New Sylius Project

To create a new project using Sylius Standard Edition, run this command:

$ composer create-project -s dev sylius/sylius-standard acme

This will create a new Symfony project in acme directory. When all the dependencies are installed, you’ll be asked to ﬁll the parameters.yml ﬁle via interactive script. Please follow the steps. After everything is in place, run the following commands:

$ cd acme # Move to the newly created directory $ php app/console sylius:install

This package has the whole sylius/sylius package in vendors, so you can easily update it and focus on your custom development.

Accessing the Shop

In order to see the shop, access the web/app_dev.php ﬁle via your web browser.

Tip: We strongly recommend using the Symfony built-in web server by running the php app/console server:start 127.0.0.1:8000 command and then accessing http://127.0.0.1:8000 in your web browser.

Note: The localhost’s 8000 port may be already occupied by some other process. If so you should try other ports, like for instance: php app/console server:start 127.0.0.1:8081 Want to know more about using a built-in server, see here.

You can log in as an administrator, with the credentials you have provided during the installation process. Since now you can play with your clean Sylius installation.

Accessing the Administration Panel

In order to see a fully functional Administration you will need to install Gulp.

6 Chapter 1. The Book Sylius, Release

Sylius already has a gulpfile.js, therefore you just need to get Gulp using Node.js. Having Node.js installed git to your project directory and run:

$ npm install

And now you can use gulp for installing views, by just running a simple command:

$ npm run gulp

After you’ve run the gulp command please have a look at the /admin url, where you will ﬁnd the administration panel.

1.1.4 Architecture Overview

Before we dive separately into every Sylius concept, you need to have an overview of how our main application is structured. You already know that Sylius is built from components and Symfony2 bundles, which are integration layers with the framework. All bundles share the same conventions for naming things and the way of data persistence. Sylius, by default, uses the Doctrine ORM for managing all entities. For deeper understanding of how Doctrine works, please refer to the excellent documentation on their ofﬁcial website.

Resource Layer

We created an abstraction on top of Doctrine, in order to have a consistent and ﬂexible way to manage all the resources. By “resource” we understand every model in the application. Simplest examples of Sylius resources are “product”, “order”, “tax_category”, “promotion”, “user”, “shipping_method” and so on... Sylius resource management system lives in the SyliusResourceBundle and can be used in any Symfony2 project.

Services

For every resource you have four essential services available: • Factory • Manager • Repository • Controller Let us take the “product” resource as an example. By default, it is represented by an object of a class that implements the Sylius\Component\Core\Model\ProductInterface.

Factory

The factory service gives you an ability to create new default objects. It can be accessed via the sylius.factory.product id (for the Product resource of course).

1.1. The Book 7 Sylius, Release

$factory= $this->container->get('sylius.factory.product');

/** @var ProductInterface $product **/ $product= $factory->createNew(); }

Note: Creating resources via this factory method makes the code more testable, and allows you to change the model class easily.

Manager

The manager service is just an alias to appropriate Doctrine’s ObjectManager and can be accessed via the sylius.manager.product id. API is exactly the same and you are probably already familiar with it:

container->get('sylius.manager.product');

// Assuming that the $product1 exists in the database we can perform such

˓→operations: $manager->remove($product1);

// If we have created the $product2 using a factory, we can persist it in the

˓→database. $manager->persist($product2);

// Before performing a flush, the changes we have made, are not saved. There is

˓→only the $product1 in the database. $manager->flush(); // Saves changes in the database.

//After these operations we have only $product2 in the database. The $product1

˓→has been removed. }

Repository

Repository is deﬁned as a service for every resource and shares the API with standard Doctrine ObjectRepository. It contains two additional methods for creating a new object instance and a paginator provider. The repository service is available via the sylius.repository.product id and can be used like all the repositories you have seen before.

container->get('sylius.repository.product');

$product= $repository->find(4); // Get product with id 4, returns null if not

˓→found. $product= $repository->findOneBy(['slug' => 'my-super-product']); // Get one

˓→product by defined criteria.

8 Chapter 1. The Book Sylius, Release

$products= $repository->findAll(); // Load all the products! $products= $repository->findBy(['special' => true]); // Find products matching

˓→some custom criteria. }

Every Sylius repository supports paginating resources. To create a Pagerfanta instance use the createPaginator method.

container->get('sylius.repository.product');

$products= $repository->createPaginator(); $products->setMaxPerPage(3); $products->setCurrentPage($request->query->get('page',1));

// Now you can return products to template and iterate over it to get products

˓→from current page. }

Paginator can be created for a speciﬁc criteria and with desired sorting.

container->get('sylius.repository.product');

$products= $repository->createPaginator(['foo' => true], ['createdAt' => 'desc

˓→']); $products->setMaxPerPage(3); $products->setCurrentPage($request->query->get('page',1)); }

Controller

This service is the most important for every resource and provides a format agnostic CRUD controller with the following actions: • [GET] showAction() for getting a single resource • [GET] indexAction() for retrieving a collection of resources • [GET/POST] createAction() for creating new resource • [GET/PUT] updateAction() for updating an existing resource • [DELETE] deleteAction() for removing an existing resource As you see, these actions match the common operations in any REST API and yes, they are format agnostic. This means, all Sylius controllers can serve HTML, JSON or XML, depending on what you request. Additionally, all these actions are very ﬂexible and allow you to use different templates, forms, repository methods per route. The bundle is very powerful and allows you to register your own resources as well. To give you some idea of what is possible, here are some examples!

1.1. The Book 9 Sylius, Release

Displaying a resource with a custom template and repository methods:

# routing.yml app_product_show: path: /products/{slug} methods: [GET] defaults: _controller: sylius.controller.product:showAction _sylius: template: AppStoreBundle:Product:show.html.twig # Use a custom template. repository: method: findForStore # Use a custom repository method. arguments: [$slug] # Pass the slug from the url to the repository.

Creating a product using custom form and a redirection method:

# routing.yml app_product_create: path: /my-stores/{store}/products/new methods: [GET, POST] defaults: _controller: sylius.controller.product:createAction _sylius: form: app_user_product # Use this form type! template: AppStoreBundle:Product:create.html.twig # Use a custom template. factory: method: createForStore # Use a custom factory method to create a

˓→product. arguments: [$store] # Pass the store name from the url. redirect: route: app_product_index # Redirect the user to his products. parameters: [$store]

All other methods have the same level of ﬂexibility and are documented in the Resource Bundle Guide.

Core, Admin and Ui

Main application is constructed from four main bundles: SyliusCoreBundle, which is the glue for all other bundles. It is the integration layer of Core component - the heart of Sylius, providing the whole e-commerce framework. SyliusUiBundle, which contains the default web interface, assets, templates and menu builders. SyliusAdminBundle, which contains the default administration of the whole system, that is easily extensible. SyliusShopBundle, that takes care of the things visible for the customer like the customer account or the cart.

Third Party Libraries

Sylius uses a lot of libraries for various tasks: • [SymfonyCMF] for content management • [Gaufrette] for ﬁlesystem abstraction (store images locally, Amazon S3 or external server) • [Imagine] for images processing, generating thumbnails and cropping • [Snappy] for generating PDF ﬁles

10 Chapter 1. The Book Sylius, Release

• [HWIOAuthBundle] for facebook/amazon/google logins • [Pagerfanta] for pagination

1.1.5 State Machine

...

States

...

Transitions

...

Callbacks

...

Conﬁguration

...

Final Thoughts

...

Learn more

• ...

1.1.6 Channels

In the modern world of e-commerce your website is no longer the only point of sale for your goods. Sylius supports multiple-channels and in this guide you will understand them from a technical point of view. Channel model represents a single sales channel, which can be one of the following things: • Webstore • Mobile application • Cashier in your physical store Or pretty much any other channel type you can imagine. The default model has the following basic properties: code An unique code identifying this channel name The human readable name of the channel

1.1. The Book 11 Sylius, Release description Short description color: Color representation url: The url pattern used to identify the channel enabled: Is the channel currently enabled? createdAt Date of creation updateAt Timestamp of the most recent update Channel configuration also allows you to configure several important aspects: locales You can select one or more locales available in this particular store currencies Every channel operates only on selected currencies paymentMethods You can define which payment methods are available in this channel shippingMethods Channel must have shipping methods configured

Final Thoughts

...

Learn more

• ...

1.1.7 Products

Product model represents unique products in your Sylius store. Every product can have different variations or attributes and has following values: • name - The full name of the product • slug - Urlized version of the name • description - Description of the product • shortDescription - Simple description of the product for lists and banners • metaDescription - Description for search engines • metaKeywords - SEO keywords • createdAt - Date of creation • updateAt - Timestamp of the most recent update

Options

In many cases, you will have product with different variations. The simplest example would be a T-Shirt available in different sizes and colors. In order to automatically generate appropriate variants, you need to deﬁne options. Every option type is represented by ProductOption and references multiple ProductOptionValue entities. • Size – S

12 Chapter 1. The Book Sylius, Release

– M – L – XL – XXL • Color – Red – Green – Blue

Variants

ProductVariant represents a unique combination of product options and can have its own pricing conﬁguration, inventory tracking etc. You are also able to use product variations system without the options at all.

Master Variant

Each product has a master variant, which tracks the same information as any other variant. It exists to simplify the internal Sylius logic. Whenever a product is created, a master variant for that product will be created too.

Attributes

Attributes allow you to deﬁne product speciﬁc values.

Prototypes

...

Images

...

Final Thoughts

...

Learn more

• ...

1.1. The Book 13 Sylius, Release

1.1.8 Addresses

Every address in Sylius is represented by Address model. Default structure has the following ﬁelds: • ﬁrstname • lastname • street • city • postcode • reference to Country • reference to Province (optional) • createdAt • updatedAt

Countries

Every country to which you will be shipping your goods lives as Country entity. Country consists of name and isoName.

Provinces

Province is a smaller area inside of a Country. You can use it to manage provinces or states and assign it to an address as well. Attribute Description id Unique id of the province name country Reference to a country createdAt Date when province was created updatedAt Date of last update

Zones

This library allows you to deﬁne Zones, which represent a speciﬁc geographical area.

Zone Model

Every Zone is represented by the following model: Attribute Description id Unique id of the zone name type String type of zone members Zone members createdAt Date when zone was created updatedAt Date of last update Three different types of zones are supported out-of-the-box.

14 Chapter 1. The Book Sylius, Release

• country zone, which consists of many countries. • province zone, which is constructed from multiple provinces. • zone, which is a group of other zones. Each zone type has different ZoneMember model, but they all expose the same API: There are following models and each of them represents a different zone member: • ZoneMemberCountry • ZoneMemberProvince • ZoneMemberZone

Matching a Zone

Zones are not very useful by themselves, but they can be part of a complex taxation/shipping or any other system. A service implementing the ZoneMatcherInterface is responsible for matching the Address to a speciﬁc Zone.

$zoneMatcher= $this->get('sylius.zone_matcher'); $zone= $zoneMatcher->match($user->getAddress());

Zone matcher can also return all matching zones. (not only the best one)

$zoneMatcher= $this->get('sylius.zone_matcher'); $zones= $zoneMatcher->matchAll($user->getAddress());

Internally, Sylius uses this service to deﬁne the shipping and billing zones of an Order, but you can use it for many different things and it is totally up to you.

Final Thoughts

...

Learn more

• ...

1.1.9 Inventory

Sylius leverages a very simple approach to inventory management. The current stock of an item is stored on the ProductVariant entity. It is always accessible via simple API:

echo $productVariant->getOnHand(); // Prints current inventory.

1.1. The Book 15 Sylius, Release

Every variant also has an unique code and can be available on demand, if you do not want to have strict inventory tracking.

$variant= $product->getFirstVariant(); $variant->setAvailableOnDemand(false); if ($variant->isAvailableOnDemand()) { // Order any amount you want! }

InventoryUnit

Every item sold in the store is represented by InventoryUnit, which has many different states: • checkout - When item is in the cart. • onhold - When checkout is completed, but we are waiting for the payment. • sold - When item has been sold and is no longer in the warehouse. • backordered - Item has been sold, but is not in stock and waiting for supply. • returned - Item has been sold, but returned and is in stock. For example, if someone puts a product “Book” with quantity “4” in the cart, 4 inventory units are created. This allows us for very precise tracking of all sold/backordered/returned items.

InventoryUnitFactory

Normally, inventory units are created automatically by Sylius and you do not need to bother. If you want to create some inventory units yourself, you should use the sylius.inventory_unit_factory service.

$variant= // Get variant from product. $inventoryUnits= $this->get('sylius.inventory_unit_factory')->create($variant,6,

˓→InventoryUnitInterface::STATE_BACKORDER);

$inventoryUnits is now ArrayCollection with 6 instances of InventoryUnit, referencing the ProductVariant and with state backordered.

InventoryOperator

Inventory operator is the service responsible for managing the stock amounts of every ProductVariant with following methods: • increase(variant, quantity) • hold(variant, quantity) • release(variant, quantity) • decrease(InventoryUnit[])

16 Chapter 1. The Book Sylius, Release

Backorders

...

Inventory On Hold

Final Thoughts

...

Learn more

• ...

1.1.10 Orders

Order model is one of the most important in Sylius, it represents the order placed via your store! It has a very consistent and clear API, which allows you to easily manipulate and process orders.

Customer Reference

Order holds a reference to speciﬁc User, which is available through getUser() method: echo $order->getUser()->getEmail(); // [email protected]

When creating order programatically, you can deﬁne the user yourself:

$order= $this->get('sylius.repository.order')->createNew(); $john= $this->get('sylius.repository.user')->find(3);

$order->setUser($john);

Order may not have reference to User in case when Order was created by guest.

Billing and Shipping Address

By default, every order has its own billing and shipping address, which are heavily used through whole process. Both of them are represented by Address model.

$shippingAddress= $order->getShippingAddress(); echo 'Shipped to: '.$shippingAddress->getCountry();

Order Contents

Order holds a collection of OrderItem instances. OrderItem model has the attributes listed below:

1.1. The Book 17 Sylius, Release

Attribute Description id Unique id of the item order Reference to an Order variant Reference to Variant product Product loaded via Variant unitPrice The price of a single unit quantity Quantity of sold item adjustments Collection of Adjustments adjustmentsTotal Total value of adjustments total Order grand total createdAt Date when order was created updatedAt Date of last change

Taxes and Shipping Fees as Adjustments

...

Shipments

...

Shipping State

...

Payments

...

Payment State

...

The Order State Machine

Order has also its general state, which can have the following values: • cart • pending • released • conﬁrmed • shipped • abandoned • cancelled • returned

18 Chapter 1. The Book Sylius, Release

Final Thoughts

...

Learn more

• ...

1.1.11 Shipments

...

The Shipment State Machine

...

Shipping Methods

...

Shipping Cost Calculators

...

Default Calculators

...

Shipping Zones

...

Examples

...

Product and ProductVariant Conﬁguration

...

Final Thoughts

...

1.1. The Book 19 Sylius, Release

Learn more

• ...

1.1.12 Payments

Sylius contains a very ﬂexible payments management system with support for many gateways. (payment providers) We are using very powerful payment abstraction library, called [Payum], which handles all sorts of capturing, refunding and recurring payments logic. On Sylius side, we integrate it into our checkout and manage all the payment data.

Payment

Every payment in Sylius, successful or failed, is represented by Payment model, which contains basic information and reference to appropriate order. Payment has following attributes: • id • currency (code) • amount • reference to PaymentMethod • reference to Order • state • reference to [PaymentSource] (optional) • createdAt • updatedAt All these properties are easily accessible through simple API:

echo $payment->getAmount(). $payment->getCurrencyCode();

$order= $payment->getOrder(); // Get the order.

echo $payment->getMethod()->getName(); // Get the name of payment method used.

1.1.13 Payment State and Workﬂow

We are using [StateMachine] library to manage all payment states, here is the full list of defaults: • new (initial) • unknown • pending • processing • completed

20 Chapter 1. The Book Sylius, Release

• failed • cancelled • void • refunded Of course, you can define your own states and transitions to create a workflow, that perfectly matches your business. Full configuration can be seen here. Changes to payment happen mostly through applying appropriate transitions.

Payment Methods

A [PaymentMethod] represents a way that your customer pays during the checkout process. It holds a reference to specific gateway with custom configuration. You can have different payment methods using the same gateway, like PayPal or Stripe. Default model of payment method contains the following fields: • name • description • enabled • gateway • configuration • environment • feeCalculator • feeCalculatorConfiguration • createdAt • updatedAt

Gateway and Conﬁgurations

...

Payment Processing

...

Supported Gateways

...

Final Thoughts

...

1.1. The Book 21 Sylius, Release

Learn more

• ...

1.1.14 Troubleshoooting

Sylius stores payment output inside the details column of the sylius_payment table. It can provide valuable info when debugging the payment process.

PayPal Error Code 10409

Also known as “Checkout token was issued for a merchant account other than yours”. You most likely changed the PayPal credentials from conﬁg.yml during the checkout process. Clear the cache and try again: app/console cache:clear

1.1.15 Taxation

Sylius has a very ﬂexible taxation system, which allows you to apply appropriate taxes for different items, billing zones and use custom calculators.

Tax Categories

In order to process taxes in your store, you need to conﬁgure at least one TaxCategory, which represents a speciﬁc type of merchandise. If all your items are taxed with the same rate, you can have a simple “Taxable Goods” category assigned to all items. If you sell various products and some of them have different taxes applicable, you could create multiple categories. For example, “Clothing”, “Books” and “Food”.

Tax Zones

Additionally to tax categories, you can have different tax zones, in order to apply correct taxes for customers coming from any country in the world. To understand how zones work, please refer to the Zones chapter of this book.

Tax Rates

A tax rate is essentially a percentage amount charged based on the sales price. Tax rates also contain other important information: • Whether product prices are inclusive of this tax • The zone in which the order address must fall within • The tax category that a product must belong to in order to be considered taxable • Calculator to use for computing the tax

Default Tax Zone

...

22 Chapter 1. The Book Sylius, Release

Examples

...

Calculators

...

Final Thoughts

...

Learn more

• ...

1.1.16 Pricing

Pricing is the part of Sylius responsible for calculating the product prices for the cart. This functionality comes from the SyliusPricingBundle. ProductVariant implements the PriceableInterface and has following attributes available: • pricingCalculator • pricingConﬁguration

Note: All prices in Sylius are represented by integers, so 14.99$ is stored as 1499 in the database.

First parameter holds the name of calculator type and second contains the conﬁguration array for this particular calculator. For example, if you have a product without any variations, its master variant can have a simple setup with: • price = 2099 • pricingCalculator = group_based • pricingConﬁguration = [23 => 2499, 85 => 2999]

Calculators

A calculator is a very simple service implement PriceCalculatorInterface and has a very important calculate(priceable, configuration, context) method. Every time product is added, removed to cart and generally on every cart modification event, this method is used to calculate the unit price. It takes the appropriate calculator configured on the product, together with the configuration and context. Context is taken from the product as well, but context is coming from the cart. Currently the context is really simple and contains the following details: • quantity of the cart item • user

1.1. The Book 23 Sylius, Release

• groups You can easily [implement your own pricing calculator] and allow store managers to deﬁne complex pricing rules for any merchandise.

Final Thoughts

...

Learn more

• ...

1.1.17 Promotions

...

Promotion Rules

...

Promotion Actions

...

Coupons

...

Examples

...

Exclusive Promotions

Final Thoughts

...

Learn more

• ...

24 Chapter 1. The Book Sylius, Release

1.1.18 Users and Groups

Retrieving users and groups from the database should always happen via repository, which implements Sylius\Bundle\ResourceBundle\Model\RepositoryInterface. If you are using Doctrine, you’re already familiar with this concept, as it extends the native Doctrine ObjectRepository interface. Your user repository is always accessible via sylius.repository.user service. Of course, sylius.repository.group is also available for use. Sometimes you will not need it because you can obtain a group directly from the User.

User Management

Creating users is quite straight forward. You simply call the createNew() method on the repository. Next you are able to set all the information.

container->get('sylius.repository.user'); $user= $repository->createNew(); $user->setEmail('[email protected]'); $user->setFirstName('John'); $user->setLastName('Doe');

$manager= $this->container->get('sylius.manager.user'); $manager->persist($user); $manager->flush(); // Save changes in database. }

Setting billing and shipping addresses is easy. First you need an Address object. This is created by calling the createNew() method on the repository. Afterwards you can set all the data and assign the Address object to the user by using either setShippingAddress() or setBillingAddress().

container->get('sylius.repository.user'); $user= $userRepository->find(1);

$addressRepository= $this->container->get('sylius.repository.address'); $address= $addressRepository->createNew();

$address->setFirstName('John'); $address->setLastName('Doe'); $address->setCity('New York'); $address->setPostcode(2000); $address->setStreet('Times Sq. 137');

$user->setBillingAddress($address);

$manager= $this->container->get('sylius.manager.user'); $manager->persist($user);

1.1. The Book 25 Sylius, Release

$manager->flush(); // Save changes in database. }

Groups

To create a new group instance, you can simply call the createNew() method on the repository. Do not forget setting a name for the group, it is a required ﬁeld as it is not nullable. The name for the group must also be unique.

container->get('sylius.repository.group'); $group= $repository->createNew(); $group->setName('Premium customers'); }

You can now start adding users to your newly made group.

container->get('sylius.repository.group'); $group= $groupRepository->findOneBy( array('name' => 'Premium customers');

$userRepository= $this->container->get('sylius.repository.user'); $user= $userRepository->find(1); $user->addGroup($group);

$manager= $this->container->get('sylius.manager.group'); $manager->persist($user); $manager->flush(); // Save changes in database. }

Final Thoughts

...

Learn more

• ...

1.1.19 Currencies

Sylius supports multiple currencies per store and makes it very easy to manage them. There are several approaches to processing several currencies, but we decided to use the simplest solution we store all money values in the default currency and convert them to different currency with current rates or speciﬁc rates. Every currency is represented by Currency entity and holds basic information:

26 Chapter 1. The Book Sylius, Release

• id • code • exchangeRate • enabled • createdAt • updatedAt The default currency has exchange rate of “1.000”.

Currency Context

By default, user can switch his current currency in the frontend of the store. To manage the currently used currency, we use CurrencyContext. You can always access it through sylius.context.currency id.

get('sylius.context.currency')->getCurrencyCode(); }

To change the currently used currency, you can simply use the setCurrencyCode() method of context service.

get('sylius.context.currency')->setCurrencyCode('PLN'); }

The currency context can be injected into your custom service and give you access to currently used currency.

Product Prices

...

Available Currencies Provider

The default menu for selecting currency is using a special service called sylius.currency_provider, which returns all enabled currencies. This is your entry point if you would like override this logic and return different currencies for various scenarios.

get('sylius.currency_provider')->getAvailableCurrencies();

foreach ($currencies as $currency){ echo $currency->getCode();

1.1. The Book 27 Sylius, Release

} }

Final Thoughts

...

Learn more

• ...

1.1.20 Locales

To support multiple site languages, we use Locale model with the following set of ﬁelds: • id • code • enabled • createdAt • updatedAt

Locale Context

With the default conﬁguration, customers are able to change the store language in the frontend. To manage the currently used language, we use LocaleContext. You can always access it through sylius.context.locale id.

public function fooAction() { $locale= $this->get('sylius.context.locale')->getLocale();

echo $locale; // pl_PL }

To change the locale, you can simply use the setLocale() method of the context service.

public function fooAction() { $this->get('sylius.context.locale')->setLocale('de_DE'); // Store will be

˓→displayed in German. }

The locale context can be injected into your custom service and give you access to currently used locale.

28 Chapter 1. The Book Sylius, Release

Available Locales Provider

Service sylius.locale_provider is responsible for returning all languages available to the current user. By default, it ﬁlters out all disabled locales. You can easily modify this logic by overriding this component.

get('sylius.locale_provider')->getAvailableLocales();

foreach ($locales as $locale){ echo $locale->getCode(); } }

To get all languages conﬁgured in the store, including the disabled ones, you can simply use the repository.

$locales= $this->get('sylius.repository.locale')->findAll();

Final Thoughts

...

Learn more

• ...

1.1.21 Content

...

SymfonyCMF and PHPCR

...

Static Content

...

Pages

...

Blocks

...

1.1. The Book 29 Sylius, Release

Final Thoughts

...

Learn more

• ...

1.1.22 E-Mails

Sylius is sending various e-mails and this chapter is a reference about all of them. Continue reading to learn what e- mails are sent, when and how to customize the templates. To understand how e-mail sending works internally, please refer to SyliusMailerBundle documentation.

User Conﬁrmation E-Mail

Every time new customer registers via registration form or checkout, user_confirmation e-mail is sent to him. The default template is

SyliusWebBundle:Email:userConfirmation.html.twig

You also have the following parameters available: user Instance of the user model

Order Conﬁrmation

This e-mail is sent when order is paid. Unique code is order_confirmation. Template name is:

SyliusWebBundle:Email:orderConfirmation.html.twig

You also have the following parameters available: order Instance of the user order order.user Customer order.shippingAddress Shipping address order.billingAddress Billing address order.items Collection of order items

Order Comment

In the backend, you can comment orders and optionally notify the customer via e-mail with code order_comment, this template is used:

SyliusWebBundle:Email:orderComment.html.twig

You also have the following parameters available: comment: Comment instance order Instance of the user order

30 Chapter 1. The Book Sylius, Release order.user Customer order.shippingAddress Shipping address order.billingAddress Billing address order.items Collection of order items

Final Thoughts

...

Learn more

• ...

1.1.23 Settings

...

General Settings

...

Taxation Settings

...

Final Thoughts

...

Learn more

• ... • Introduction to Sylius • Installation • Architecture Overview • State Machine • Channels • Products • Addresses • Inventory • Orders • Shipments

1.1. The Book 31 Sylius, Release

• Payments • Taxation • Pricing • Promotions • Users and Groups • Currencies • Locales • Content • E-Mails • Settings • Introduction to Sylius • Installation • Architecture Overview • State Machine • Channels • Products • Addresses • Inventory • Orders • Shipments • Payments • Taxation • Pricing • Promotions • Users and Groups • Currencies • Locales • Content • E-Mails • Settings

32 Chapter 1. The Book CHAPTER 2

The Customization Guide

2.1 The Customization Guide

2.1.1 Customizing Models

All models in Sylius are placed in the Sylius\Component\*ComponentName*\Model namespaces alongside with their interfaces.

Warning: Many models in Sylius are extended in the Core component. If the model you are willing to override exists in the Core your should be extending the Core one, not the base model from the component.

Why would you customize a Model?

To give you an idea of some purposes of models customizing have a look at a few examples: • Add flag ﬁeld to the Country • Add secondNumber to the Customer • Change the reviewSubject of a Review (in Sylius we have ProductReviews but you can imagine for instance a CustomerReview) • Add icon to the PaymentMethod And of course many similar operations limited only by your imagination. Let’s now see how you should perform such customizations.

How to customize a Model?

Let’s take the Sylius\Component\Addressing\Country as an example. This one is not extended in Core. How can you check that? For the Country run:

$ php app/console debug:container --parameter=sylius.model.country.class

As a result you will get the Sylius\Component\Addressing\Model\Country - this is the class that you need to be extending. Assuming that you would want to add another ﬁeld on the model - for instance a flag.

33 Sylius, Release

1. The ﬁrst thing to do is to write your own class which will extend the base Country‘ class.

namespace AppBundle\Entity;

use Sylius\Component\Addressing\Model\Country as BaseCountry;

class Country extends BaseCountry { /** * @var bool */ private $flag;

/** * @return bool */ public function getFlag() { return $this->flag; }

/** * @param bool $flag */ public function setFlag($flag) { $this->flag= $flag; } }

2. Next deﬁne your entity’s mapping: The ﬁle should be placed in AppBundle/Resources/config/doctrine/Country.orm.yml

AppBundle\Entity\Country: type: entity table: sylius_country fields: flag: type: boolean nullable: true

3. Finally you’ll need to override the model’s class in the app/config/config.yml.

sylius_addressing: resources: country: classes: model: AppBundle\Entity\Country

4. Additionally if you want to give the administrator an ability to add a flag to any of Countries, you’ll need to update its form type. Check how to do it here.

What happens while overriding Models?

• Parameter sylius.model.country.class contains AppBundle\\Entity\\Country.

34 Chapter 2. The Customization Guide Sylius, Release

• sylius.repository.country represents Doctrine repository for your new class. • sylius.manager.country represents Doctrine object manager for your new class. • sylius.controller.country represents the controller for your new class. • All Doctrine relations to Sylius\\Component\\Adressing\\Model\\Country are using your new class as target-entity, you do not need to update any mappings. • CountryType form type is using your model as data_class. • Sylius\\Component\\Addressing\\Model\\Country is automatically turned into Doctrine Mapped Superclass.

2.1.2 Customizing Forms

The forms in Sylius are placed in the Sylius\Bundle\*BundleName*\Form\Type namespaces.

Warning: Many forms in Sylius are extended in the CoreBundle. If the form you are willing to override exists in the CoreBundle your should be extending the one from Core, not the base form from the bundle.

Why would you customize a Form?

There are plenty of reasons to modify forms that have already been defined in Sylius. Your business needs may sometimes slightly differ from our internal assumptions. You can: • add completely new fields, if you need another phone number for your customers, • modify existing fields, make them required, change their HTML class, change labels etc., • remove fields that are not used.

How to customize a Form?

If you want to modify the form for the Address in your system there are a few steps that you should take. Assuming that you would like to (for example): • Add a contactHours field, • Remove the company field, • Change the label for the lastName from sylius.form.address.last_name to app.form.address.surname These will be the steps that you will have to take to achieve that: 1. If your are planning to add new fields remember that beforehand they need to be added on the model that the form type is based on. In case of our example if you need to have the contactHours on the model and the entity mapping for the Address resource. To get to know how to prepare that go there. 2. Write your own form type class that will be extending the default one. Place it in your AppBundle\Form\Type directory.

2.1. The Customization Guide 35 Sylius, Release

Your new class has to extend a proper base class. How can you check that? For the AddressType run:

$ php app/console debug:container sylius.form.type.address

As a result you will get the Sylius\Bundle\AddressingBundle\Form\Type\AddressType - this is the class that you need to be extending.

// Adding new fields works just like in the parent form. $builder->add('contactHours', 'text',[ 'required' => false, 'label' => 'app.form.address.contact_hours', ]);

// To remove a field from a form simply call ->remove(`fieldName`). $builder->remove('company');

// You can change the label by adding again the same field with a changed

˓→`label` parameter. $builder->add('lastName', 'text',[ 'label' => 'app.form.address.surname', ]); } }

3. Deﬁne your newly created class in the app/config/config.yml. sylius_addressing: resources: address: classes: form: default: AppBundle\Form\Type\AddressType

Note: Of course remember that you need to render the new ﬁelds you have created, and remove the rendering of the ﬁelds that you have removed in your views.

In Twig for example you can render your modiﬁed form in such a way:

36 Chapter 2. The Customization Guide Sylius, Release

{{ form_row(form.firstName) }} {{ form_row(form.lastName) }} {{ form_row(form.city) }} {{ form_row(form.street) }} {{ form_row(form.postcode) }} {{ form_row(form.countryCode) }} {{ form_row(form.provinceCode) }} {{ form_row(form.phoneNumber) }} {{ form_row(form.contactHours) }}

What happens while overriding Forms?

• Parameter sylius.form.type.address.class contains the AppBundle\Form\Type\AddressType. • sylius.form.type.address form type service uses your custom class. • sylius_address form type uses your new form everywhere.

2.1.3 Customizing Repositories

Warning: In Sylius we are using both default Doctrine repositories and the custom ones. Often you will be needing to add your very own methods to them. You need to check before which repository is your resource using.

Why would you customize a Repository?

Different sets of different resources can be obtained in various scenarios in your application. You may need for instance: • finding Orders by a Customer and a chosen Product • finding Products by a Taxon • finding Comments by a Customer

How to customize a Repository?

Let’s assume that you would want to ﬁnd products that are the bestsellers in your shop. 1. Create your own repository class under the AppBundle\Repository namespace. Remember that it has to extend a proper base class. How can you check that? For the ProductRepository run:

$ php app/console debug:container sylius.repository.product

As a result you will get the Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository - this is the class that you need to be extending.

2.1. The Customization Guide 37 Sylius, Release

use Sylius\Bundle\CoreBundle\Doctrine\ORM\ProductRepository as BaseProductRepository; class ProductRepository extends BaseProductRepository { /** * @param int $limit * * @return array */ public function findBySold($limit=4) { $queryBuilder= $this->createQueryBuilder('o'); $queryBuilder ->addSelect('variant') ->addSelect('translation') ->leftJoin('o.variants', 'variant') ->leftJoin('o.translations', 'translation') ->addOrderBy('variant.sold', 'DESC') ->setMaxResults($limit) ;

return $queryBuilder->getQuery()->getResult(); } }

We are using the Query Builder in the Repositories. As we are selecting Products we need to have a join to translations, because they are a translatable resource. Without it in the query results we wouldn’t have a name to be displayed. We are sorting the results by the count of how many times the product has been sold, which is being hold on the sold field on the specific variant of each product. Then we are limiting the query to 4 by default, to get only 4 bestsellers. 2. In order to use your repository you need to configure it in the app/config/config.yml. sylius_product: resources: product: classes: repository: AppBundle\Repository\ProductRepository

3. After conﬁguring the sylius.product.repository service has your findBySold() method available. You can form now on use your method in any Controller.

container->get('sylius.repository.product');

$bestsellers= $productRepository->findBySold(); }

What happens while overriding Repositories?

• The parameter sylius.repository.product.class contains AppBundle\Repository\ProductRepository. • The repository service sylius.repository.product is using your new class.

38 Chapter 2. The Customization Guide Sylius, Release

• Under the sylius.repository.product service you have got all methods from the base repository available plus the one you have added.

2.1.4 Customizing Controllers

All Sylius resources are using the ‘‘ SyliusBundleResourceBundleControllerResourceController‘‘ as default, but some of them have been already extended in Bundles. If you want to override some controller action, check which controller you should be extending.

Note: There are two types of controllers we can deﬁne in Sylius. Resource Controllers - are basing only on one Entity, so they return only the resources they have in their name. For instance a ProductController should return only products. Standard Controllers - non-resource; these may use many entities at once, they are useful on more general pages. We are extending these controllers only if the actions we want cannot be done through yaml conﬁguration - like sending emails.

Why would you customize a Controller?

To add your custom actions you need to override controllers. You may bee needing to: • add a generic action that will render a list of recommended products with a product on its show page, • render a partial template that cannot be done via yaml resource action.

How to customize a Resource Controller?

Imagine that you would want to render a list of best selling products in a partial template that will be reusable anywhere. Assuming that you already have a method on the ProductRepository - you can see such an example here. Having this method you may be rendering its result in a new action of the ProductController using a partial template. See example below: 1. Create a new Controller class under the AppBundle/Controller namespace. Remember that it has to extend a proper base class. How can you check that? For the ProductController run:

$ php app/console debug:container sylius.controller.product

As a result you will get the Sylius\Bundle\CoreBundle\Controller\ProductController - this is the class that you need to be extending. Now you have to create the controller that will have a generic action that is basically the showAction from the ResourceController extended by getting a list of recommended product from your external api.

namespace AppBundle\Controller;

use FOS\RestBundle\View\View; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Sylius\Bundle\CoreBundle\Controller\ProductController as BaseProductController; use Sylius\Component\Resource\ResourceActions;

2.1. The Customization Guide 39 Sylius, Release

class ProductController extends BaseProductController { /** * @param Request $request * * @return Response */ public function showAction(Request $request) { $configuration= $this->requestConfigurationFactory->create($this->metadata,

˓→$request);

$this->isGrantedOr403($configuration, ResourceActions::SHOW); $product= $this->findOr404($configuration);

$recommendationServiceApi= $this->get('app.recommendation_service_api');

$recommendedProducts= $recommendationServiceApi->getRecommendedProducts(

˓→$product);

$this->eventDispatcher->dispatch(ResourceActions::SHOW, $configuration,

˓→$product);

$view= View::create($product);

if ($configuration->isHtmlRequest()) { $view ->setTemplate($configuration->getTemplate(ResourceActions::SHOW.'.

˓→html')) ->setTemplateVar($this->metadata->getName()) ->setData([ 'configuration' => $configuration, 'metadata' => $this->metadata, 'resource' => $product, 'recommendedProducts' => $recommendedProducts, $this->metadata->getName() => $product, ]) ; }

return $this->viewHandler->handle($configuration, $view); } }

2. In order to use your controller and its actions you need to conﬁgure it in the app/config/config.yml. sylius_product: resources: product: classes: controller: AppBundle\Controller\ProductController

How to customize a Standard Controller?

Let’s assume that you would like to send some kind of emails (which are not resources) after something has been purchased in your shop - to do this you should modify an afterPurchaseAction on the OrderController.

40 Chapter 2. The Customization Guide Sylius, Release

1. Create a new Controller class under the AppBundle/Controller/Frontend namespace. Run $ php app/console debug:container sylius.controller.frontend.order. Your class needs to be extending this base class.

˓→BaseOrderController; use Sylius\Bundle\PayumBundle\Request\GetStatus; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; class OrderController extends BaseOrderController { /** * @param Request $request * * @return Response */ public function afterPurchaseAction(Request $request) { $token= $this->getHttpRequestVerifier()->verify($request); $this->getHttpRequestVerifier()->invalidate($token);

$status= new GetStatus($token); $this->getPayum()->getGateway($token->getGatewayName())->execute($status); $payment= $status->getFirstModel(); $order= $payment->getOrder(); $this->checkAccessToOrder($order);

$orderStateResolver= $this->get('sylius.order_processing.state_resolver'); $orderStateResolver->resolvePaymentState($order); $orderStateResolver->resolveShippingState($order);

$this->getOrderManager()->flush();

$emailManager= $this->get('sylius.email_manager.order'); $emailManager->sendConfirmationEmail($order);

return $this->redirectToRoute('sylius_checkout_thank_you'); } }

2. The next thing you have to do is to override the sylius.controller.frontend.order.class parameter in AppBundle/Resources/config/services.yml. parameters: sylius.controller.frontend.order.class:

˓→AppBundle\Controller\Frontend\OrderController

From now on your afterPurchaseAction of the OrderController will also send emails in addition to its default behaviour.

2.1. The Customization Guide 41 Sylius, Release

2.1.5 Customizing Validation

The default validation group for all resources is sylius, but you can conﬁgure your own validation.

How to customize validation?

Let’s take the example of changing the length of name for the Product entity - watch out the field name is hold on the ProductTranslation model. In the sylius validation group the minimum length is equal to 2. What if you’d want to have at least 10 characters? 1. Create the AppBundle\Resources\config\validation.yml. In this file you need to overwrite the whole validation of your field that you are willing to modify. Take this configuration from the Sylius\Bundle\ProductBundle\Resources\config\validation.xml - you can choose format xml or yaml. Give it a new, custom validation group - [app_product].

Sylius\Component\Product\Model\ProductTranslation: properties: name: - NotBlank: message: sylius.product.name.not_blank groups: [app_product] - Length: min: 10 minMessage: sylius.product.name.min_length max: 255 maxMessage: sylius.product.name.max_length groups: [app_product]

2. Conﬁgure the new validation group in the app/config/config.yml.

sylius_product: resources: product: validation_groups: default: [app_product]

Done. Now in all forms where the Product name is being used your new validation group will be applied, not letting users add products with name shorter than 10 characters.

2.1.6 Customizing Menus

Adding new positions in your menu is done via events. You have got the Sylius\Bundle\WebBundle\Event\MenuBuilderEvent with FactoryInterface and ItemInterface of KnpMenu. So you can manipulate the whole menu. You’ve got such events that you should be subscribing to:

sylius.menu.admin.main # Admin Panel menu sylius.menu_builder.frontend.main # Main Shop menu (top bar) sylius.menu_builder.frontend.currency # sylius.menu_builder.frontend.taxons # sylius.menu_builder.frontend.social # sylius.menu_builder.frontend.account #

42 Chapter 2. The Customization Guide Sylius, Release

How to customize a Menu?

1. In order to add items to any of the Menus in Sylius you have to create a AppBundle\EventListener\MenuBuilderListener class. In the example below we are adding a one new item to the Admin panel menu and a one new item to main menu of the shop.

getMenu();

$menu->addChild('backend_main') ->setLabel('Test Backend Main'); }

/** * @param FrontendMenuBuilderEvent $event */ public function addFrontendMenuItems(FrontendMenuBuilderEvent $event) { $menu= $event->getMenu();

$menu->addChild('frontend') ->setLabel('Frontend Menu Item'); } }

2. After creating your class with proper methods for all the menu customizations you need, subscribe your listener to proper events in the AppBundle\Resources\config.services.yml. services: app.admin.menu_builder_listener: class: AppBundle\EventListener\MenuBuilderListener tags: -{ name: kernel.event_listener, event: sylius.menu.admin.main, method:

˓→addBackendMenuItems} -{ name: kernel.event_listener, event: sylius.menu_builder.frontend.

˓→currency, method: addFrontendMenuItems}

2.1.7 Customizing Templates

2.1. The Customization Guide 43 Sylius, Release

Note: There are two kinds of templates in Sylius. Shop and Admin ones, plus you can create your own to satisfy your needs.

Why would you customize a template?

The most important case for modifying the existing templates is of course integrating your own layout of the system. Sometimes even if you have decided to stay with the default layout provided by Sylius, you need to slightly modify it to meet your business requirements. You may just need to add your logo anywhere.

How to customize templates?

Note: How do you know which template you should be overriding? Go to the page that you are going to modify, at the bottom in the Symfony toolbar click on the route , which will redirect you to the proﬁler. In the Request Attributes section under _sylius [ template => ...] you can check the path to the current template.

• Shop templates: customizing Login Page template: The default login template is: SyliusShopBundle:Account:login.html.twig. In order to override it you need to create your own: app/Resources/SyliusShopBundle/views/Account/login.html.twig. Copy the contents of the original template to make your work easier. And then modify it to your needs.

{% extends 'SyliusShopBundle:Layout:main.html.twig'%}

{% import 'SyliusUiBundle:Macro:messages.html.twig' as messages%}

{% block content%}

{% if last_error%} {{ messages.error(last_error.messageKey|trans(last_error.messageData,

˓→'security')) }} {% endif %}

// You can add a headline for instance to see if you are changing things in the

˓→correct place.

This Is My Headline

44 Chapter 2. The Customization Guide Sylius, Release

{% endblock%}

Done! If you do not see any changes on the /shop/login url, clear your cache. $ php app/console cache:clear. • Admin templates: Customization of the Country form view. The default template for the Country form is: SyliusAdminBundle:Country:_form.html.twig. In order to override it you need to create your own: app/Resources/SyliusAdminBundle/views/Country/_form.html.twig. Copy the contents of the original template to make your work easier. And then modify it to your needs.

// You can add a headline for instance to see if you are changing things in the

˓→correct place.

My Custom Headline

{{ form_row(form.provinces, {'label': false}) }}

Done! If you do not see any changes on the /admin/countries/new url, clear your cache. $ php app/console cache:clear. • Customizing Models • Customizing Forms • Customizing Repositories • Customizing Controllers • Customizing Validation • Customizing Menus • Customizing Templates • Customizing Models • Customizing Forms • Customizing Repositories • Customizing Controllers • Customizing Validation • Customizing Menus • Customizing Templates

2.1. The Customization Guide 45 Sylius, Release

46 Chapter 2. The Customization Guide CHAPTER 3

The API Guide

This chapter covers the REST API of Sylius platform.

3.1 The API Guide

3.1.1 Introduction to Sylius REST API

This part of documentation is about RESTful JSON/XML API for Sylius platform.

Note: This documentation assumes you have at least basic experience with REST APIs.

3.1.2 Authorization

This part of documentation is about authorization to Sylius platform through API. In order to check this conﬁguration, please set up your local copy of Sylius platform and change sylius.dev to your address.

OAuth2

Sylius has conﬁgured OAuth2 authorization. The authorization process is standard procedure. Authorize as admin and enjoy the API!

Note: User has to have ROLE_API role in order to access /api resources

Create OAuth client

Use sylius command: php app/console sylius:oauth-server:create-client --grant-type="password" --grant-type="refresh_token" --grant-type="token"

You will receive client public id and client secret

47 Sylius, Release

Example Result

A new client with public id 3e2iqilq2ygwk0ccgogkcwco8oosckkkk4gkoc0k4s8s044wss,

˓→secret 44ectenmudus8g88w4wkws84044ckw0k4w4kg0sokoss84oko8 has been added

Tip: If you use Guzzle check out OAuth2 plugin and use Password Credentials.

Obtain access token

Send the request with the following parameters:

Deﬁnition

GET /oauth/v2/token

Parame- Parameter Description ter type client_id query Client public id generated in the previous step client_secret query Client secret generated in the previous step grant_type query We will use ‘password’ to authorize as user. Other available options are token and refresh-token username query User name password query User password

Note: This action can be done by POST method as well.

Example curl http://sylius.dev/oauth/v2/token -d "client_id"=demo_client -d "client_secret"=secret_demo_client -d "grant_type"=password -d "username"[email protected] -d "password"=api

Tip: In a developer environment there is a default API user and client data. To use this credentials you have to load API data ﬁxtures. Otherwise you have to use your user data and replace client id and client secret with data generated in a previous step.

Example Response

{ "access_token":

˓→"NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ

˓→",

48 Chapter 3. The API Guide Sylius, Release

"expires_in": 3600, "token_type": "bearer", "scope": null, "refresh_token":

˓→"MDk2ZmIwODBkYmE3YjNjZWQ4ZTk2NTk2N2JmNjkyZDQ4NzA3YzhiZDQzMjJjODI5MmQ4ZmYxZjlkZmU1ZDNkMQ

˓→" }

Request for resource

Put access token in the request header:

Authorization: Bearer

˓→NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ

You can now access any resource you want under /api preﬁx.

Example curl http://sylius.dev/api/users/ -H "Authorization: Bearer

˓→NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ

˓→"

Note: You have to refresh your token after it expires.

Refresh Token

Send request with the following parameters

Deﬁnition

GET /oauth/v2/token

Parameter Parameter type Description client_id query Public client id client_secret query Client secret grant_type query We will use ‘refresh_token’ to authorize as user refresh_token query Refresh token generated during authorization

Example curl http://sylius.dev/oauth/v2/token -d "client_id"=demo_client -d "client_secret"=secret_demo_client -d "grant_type"=refresh_token -d "refresh_token

˓→"=MDk2ZmIwODBkYmE3YjNjZWQ4ZTk2NTk2N2JmNjkyZDQ4NzA3YzhiZDQzMjJjODI5MmQ4ZmYxZjlkZmU1ZDNkMQ

3.1. The API Guide 49 Sylius, Release

Example Response

You can now use new token to send requests

{ "access_token":

˓→"MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→", "expires_in": 3600, "token_type": "bearer", "scope": null, "refresh_token":

˓→"MWI4NzVkNThjZDc2Y2M1N2JiNzBmOTQ0MDFmY2U0YzVjYzllMDE1OTU5OWFiMzJiZTY5NGU4NzYyODU1N2ZjYQ

˓→" }

3.1.3 Channels API

Sylius channels API endpoint is /api/channels.

Index of all channels

To browse all channels available in the Sylius e-commerce platform you can call the following GET request:

GET /api/channels/

Parameters page Number of the page, by default = 1 limit Number of items to display per page

Response

Response will contain a paginated list of channels.

STATUS: 200 OK

{ "page":1, "limit":10, "pages":1, "total":3, "_links":{ "self":{ "href":"\/api\/channels\/?page=1" }, "first":{ "href":"\/api\/channels\/?page=1"

50 Chapter 3. The API Guide Sylius, Release

}, "last":{ "href":"\/api\/channels\/?page=12" }, "next":{ "href":"\/api\/channels\/?page=2" } }, "_embedded":{ "items":[ { "code": "WEB-UK", "color": "Red", "created_at": "2014-11-26T23:00:15+0000", "currencies":[ ], "enabled": true, "id": 91, "locales":[ ], "name": "UK Webstore", "payment_methods":[ ], "shipping_methods":[ ], "type": "web", "updated_at": "2014-11-26T23:00:15+0000" } ] } }

Getting a single channel

You can view a single channel by executing the following request:

GET /api/channels/91

Response

STATUS: 200 OK

{ "code": "WEB-UK", "color": "Red", "created_at": "2014-11-26T23:00:15+0000", "currencies":[ ], "enabled": true, "id": 91, "locales":[ ], "name": "UK Webstore", "payment_methods":[

3.1. The API Guide 51 Sylius, Release

], "shipping_methods":[ ], "type": "web", "updated_at": "2014-11-26T23:00:15+0000" }

Creating a channel

To create a new channel, you can execute the following request:

POST /api/channels/

Parameters code Unique code color Color used in the backend enabled (optional) Is enabled? (boolean) locales (optional) Array of Locale id currencies (optional) Array of Currency id paymentMethods (optional) Array of PaymentMethod id shippingMethods (optional) Array of ShippingMethod id

Response

STATUS: 201 CREATED

{ "code": "WEB-US", "color": "Blue", "created_at": "2014-11-26T23:00:15+0000", "currencies":[ ], "enabled": true, "id": 92, "locales":[ ], "name": "US Webstore", "payment_methods":[ ], "shipping_methods":[ ], "type": "web", "updated_at": "2014-11-26T23:00:15+0000" }

52 Chapter 3. The API Guide Sylius, Release

Updating a channel

You can update an existing channel using PUT or PATCH method:

PUT /api/channels/92

PATCH /api/channels/92

Response

STATUS: 204 NO CONTENT

Deleting a channel

You can delete (soft) a channel from the system by making the following DELETE call:

DELETE /api/channels/92

Response

STATUS: 204 NO CONTENT

3.1.4 Orders API

Sylius orders API endpoint is /api/orders.

Index of all orders

You can retrieve the full list order by making the following request:

GET /api/orders/

3.1. The API Guide 53 Sylius, Release

Parameters page Number of the page, by default = 1 limit Number of items to display per page

Response

The response will contain the newly created order information.

STATUS: 200 OK

{ "page":1, "limit":10, "pages":12, "total":120, "_links":{ "self":{ "href":"\/api\/orders\/?page=1" }, "first":{ "href":"\/api\/orders\/?page=1" }, "last":{ "href":"\/api\/orders\/?page=12" }, "next":{ "href":"\/api\/orders\/?page=2" } }, "_embedded":{ "items":[ { "id":301, "completed_at":"2014-11-26T23:00:33+0000", "number":"000000048", "items":[ { "id":1353, "quantity":3, "unit_price":9054, "adjustments":[

], "adjustments_total":0, "total":27162, "immutable":false, "variant":{ "id":13099, "object":{ "id":2107, "name":"T-Shirt \"voluptas\"", "code": "T-SHIRT-VOLUPTAS", "description":"Non molestias voluptas quae nemo omnis

˓→totam. Impedit ad perferendis quaerat sint numquam voluptate eum. Facilis sed

˓→accusamus enim repellendus officiis rerum at.",

54 Chapter 3. The API Guide Sylius, Release

"created_at":"2014-11-26T23:00:17+0000", "updated_at":"2014-11-26T23:00:17+0000", "short_description":"Quos in dignissimos in fugit

˓→culpa vitae." }, "created_at":"2014-11-26T23:00:17+0000", "updated_at":"2014-11-26T23:00:34+0000", "available_on":"2013-12-10T09:16:56+0000", "sku":"8808" }, "inventory_units":[ ], "_links":{ "product":{ "href":"\/api\/products\/2107" }, "variant":{ "href":"\/api\/products\/2107\/variants\/13099" } } } ], "items_total":97783, "adjustments":[ ], "comments":[

], "adjustments_total":24240, "total":122023, "confirmed":true, "created_at":"2014-04-30T10:41:14+0000", "updated_at":"2014-11-26T23:00:34+0000", "state":"pending", "email":"[email protected]", "expires_at":"2014-11-27T02:00:33+0000", "user":{ "id":476, "username":"[email protected]", "username_canonical":"[email protected]", "email":"[email protected]", "email_canonical":"[email protected]", "enabled":false, "groups":[

], "locked":false, "expired":false, "roles":[

], "credentials_expired":false }, "channel":{ "id":91, "code":"WEB-UK", "name":"UK Webstore", "type":"web",

3.1. The API Guide 55 Sylius, Release

"color":"Red", "enabled":true, "created_at":"2014-11-26T23:00:15+0000", "updated_at":"2014-11-26T23:00:15+0000", }, "shipping_address":{ }, "billing_address":{ }, "payments":[ ], "shipments":[ ], "currency":"GBP", "checkout_state":"cart" } ] } }

Getting a single order

You can view a single order by executing the following request:

GET /api/orders/24/

Response

STATUS: 200 OK

{ "id":301, "completed_at":"2014-11-26T23:00:33+0000", "number":"000000048", "items":[ { "id":1353, "quantity":3, "unit_price":9054, "adjustments":[

], "adjustments_total":0, "total":27162, "immutable":false, "variant":{ "id":13099, "object":{ "id":2107, "name":"T-Shirt \"voluptas\"", "code": "T-SHIRT-VOLUPTAS" "description":"Non molestias voluptas quae nemo omnis totam.

˓→Impedit ad perferendis quaerat sint numquam voluptate eum. Facilis sed accusamus

˓→enim repellendus officiis rerum at.",

56 Chapter 3. The API Guide Sylius, Release

"created_at":"2014-11-26T23:00:17+0000", "updated_at":"2014-11-26T23:00:17+0000", "short_description":"Quos in dignissimos in fugit culpa vitae." }, "created_at":"2014-11-26T23:00:17+0000", "updated_at":"2014-11-26T23:00:34+0000", "available_on":"2013-12-10T09:16:56+0000", "sku":"8808" }, "inventory_units":[ { "id":4061, "inventory_state":"onhold", "created_at":"2014-11-26T23:00:34+0000", "updated_at":"2014-11-26T23:00:34+0000", "_links":{ "order":{ "href":"\/app_dev.php\/api\/orders\/301" } } }, { "id":4062, "inventory_state":"onhold", "created_at":"2014-11-26T23:00:34+0000", "updated_at":"2014-11-26T23:00:34+0000", "_links":{ "order":{ "href":"\/app_dev.php\/api\/orders\/301" } } }, { "id":4063, "inventory_state":"onhold", "created_at":"2014-11-26T23:00:34+0000", "updated_at":"2014-11-26T23:00:34+0000", "_links":{ "order":{ "href":"\/app_dev.php\/api\/orders\/301" } } } ], "_links":{ "product":{ "href":"\/app_dev.php\/api\/products\/2107" }, "variant":{ "href":"\/app_dev.php\/api\/products\/2107\/variants\/13099" } } } ], "items_total":97783, "adjustments":[ { "id":1011,

3.1. The API Guide 57 Sylius, Release

"type":"tax", "description":"EU VAT (23%)", "amount":22490, "neutral":false, "locked":false, "created_at":"2014-11-26T23:00:33+0000", "updated_at":"2014-11-26T23:00:34+0000" }, { "id":1012, "type":"shipping", "description":"UPS Ground", "amount":2500, "neutral":false, "locked":false, "created_at":"2014-11-26T23:00:33+0000", "updated_at":"2014-11-26T23:00:34+0000" }, { "id":1013, "type":"promotion", "description":"New Year Sale for 3 and more items.", "amount":-500, "neutral":false, "locked":false, "created_at":"2014-11-26T23:00:33+0000", "updated_at":"2014-11-26T23:00:34+0000" }, { "id":1014, "type":"promotion", "description":"Christmas Sale for orders over 100 EUR.", "amount":-250, "neutral":false, "locked":false, "created_at":"2014-11-26T23:00:33+0000", "updated_at":"2014-11-26T23:00:34+0000" } ], "comments":[

58 Chapter 3. The API Guide Sylius, Release

], "locked":false, "expired":false, "roles":[

], "credentials_expired":false }, "channel":{ "id":91, "code":"WEB-UK", "name":"UK Webstore", "type":"web", "color":"Red", "enabled":true, "created_at":"2014-11-26T23:00:15+0000", "updated_at":"2014-11-26T23:00:15+0000", }, "shipping_address":{ }, "billing_address":{ }, "payments":[ ], "shipments":[ ], "currency":"GBP", "checkout_state":"cart" }

Create an order

To create a new order (cart), you need to execute the following request:

POST /api/orders/

Parameters channel The id of channel user The id of customer currency Currency code

Response

STATUS: 201 CREATED

{ "id":304, "items":[ ],

3.1. The API Guide 59 Sylius, Release

"items_total":0, "adjustments":[ ], "comments":[

], "adjustments_total":0, "total":0, "confirmed":true, "created_at":"2014-11-29T12:29:07+0000", "updated_at":"2014-11-29T12:29:08+0000", "state":"cart", "email":"[email protected]", "expires_at":"2014-11-29T15:29:07+0000", "user":{ "id":481, "username":"[email protected]", "username_canonical":"[email protected]", "email":"[email protected]", "email_canonical":"[email protected]", "enabled":true, "groups":[

], "locked":false, "expired":false, "roles":[

], "credentials_expired":false }, "channel":{ "id":91, "code":"WEB-UK", "name":"UK Webstore", "type":"web", "color":"Red", "enabled":true, "created_at":"2014-11-26T23:00:15+0000", "updated_at":"2014-11-26T23:00:15+0000", }, "payments":[ ], "shipments":[ ], "currency":"USD", "checkout_state":"cart" }

Deleting a single order

You can delete (soft) an order from the system by making the following DELETE call:

DELETE /api/orders/24

60 Chapter 3. The API Guide Sylius, Release

Response

STATUS: 204 NO CONTENT

Add an item to order

To add an item to order, you simply need to do a POST request:

POST /api/orders/305/items/

Parameters variant The id of product variant unitPrice Unit price of the item quantity Desired quantity

Response

Response will contain a representation of the newly created item.

STATUS: 201 CREATED

{ "_links":{ "product":{ "href": "/app_dev.php/api/products/101" }, "variant":{ "href": "/app_dev.php/api/products/101/variants/779" } }, "adjustments": [], "adjustments_total":0, "id": 277, "immutable": false, "inventory_units":[ { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 828, "inventory_state": "checkout", "updated_at": "2014-12-15T13:18:48+0000" }, { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52"

3.1. The API Guide 61 Sylius, Release

} }, "created_at": "2014-12-15T13:18:48+0000", "id": 829, "inventory_state": "checkout", "updated_at": "2014-12-15T13:18:48+0000" }, { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 830, "inventory_state": "checkout", "updated_at": "2014-12-15T13:18:48+0000" } ], "quantity":3, "total":0, "unit_price": 500000, "variant":{ "available_on": "2014-04-01T06:43:02+0000", "created_at": "2014-12-03T09:54:35+0000", "id": 779, "object":{ "attributes":[ { "id": 238, "name": "Book author", "presentation": "Author", "value": "Marlen Yost" }, { "id": 239, "name": "Book ISBN", "presentation": "ISBN", "value": "326ccbc7-92d1-3aec-b3af-df8afdc5651d" }, { "id": 240, "name": "Book pages", "presentation": "Number of pages", "value": "149" } ], "created_at": "2014-12-03T09:54:35+0000", "description": "Et eveniet voluptas ut magni vero temporibus nihil. Omnis

˓→possimus accusantium quia corporis culpa. Et recusandae asperiores qui architecto

˓→culpa autem sint accusantium. Officiis iusto accusantium perferendis aliquid

˓→ducimus.", "id": 101, "name": "Book \"Quidem\" by \"Marlen Yost\"", "options": [], "short_description": "Distinctio quos est eaque fugit totam repellendus.", "updated_at": "2014-12-03T09:54:35+0000" },

62 Chapter 3. The API Guide Sylius, Release

"options": [], "sku": "326ccbc7-92d1-3aec-b3af-df8afdc5651d", "updated_at": "2014-12-03T09:54:35+0000" } }

Removing an item from order

To remove an item from order, you can simply call a DELETE on its url.

DELETE /api/orders/49/items/245

Response

STATUS: 204 NO CONTENT

3.1.5 Checkouts API

After you create a cart (an empty order) and add some items to it, you can start the checkout via API. This basically means updating the order with concrete information, step by step, in a correct order. Default Sylius checkout via API is constructed from the following steps: addressing You enter customer shipping and billing address shipping Shipments are proposed and you can select methods payment Payments are calculated and methods proposed ﬁnalize Final order is built and you can conﬁrm it, cart will become an order purchase You provide Sylius with payment information and order is paid Sylius API endpoint is /api/checkouts.

Addressing step

After you added some items to the cart, to start the checkout you simply need to provide a shipping address. You can also specify a different billing address if needed. You need to pass order id in the following url and make a PUT call:

PUT /api/checkouts/44

Parameters

shippingAddress[ﬁrstName] Firstname for shipping address shippingAddress[lastName] Lastname for shipping address shippingAddress[city] City name shippingAddress[postcode] Postcode

3.1. The API Guide 63 Sylius, Release shippingAddress[street] Address line 1 shippingAddress[country] Id of the country shippingAddress[province] (optional) Id of the province If you do not specify the billing address block, shipping address will be used for that purpose. billingAddress[ﬁrstName] Firstname for billing address billingAddress[lastName] Lastname for billing address billingAddress[city] City name billingAddress[postcode] Postcode billingAddress[street] Address line 1 billingAddress[country] Id of the country billingAddress[province] (optional) Id of the province

Response

The response will contain the updated order information.

STATUS: 200 OK

{ "adjustments":, "adjustments_total": -250, "shipping_address":{ "_links":{ "country":{ "href": "/app_dev.php/api/countries/9" } }, "city": "New York", "created_at": "2014-12-15T13:37:28+0000", "first_name": "John", "id": 105, "last_name": "Doe", "postcode": "12435", "street": "Test", "updated_at": "2014-12-15T13:37:29+0000" }, "billing_address":{ "_links":{ "country":{ "href": "/app_dev.php/api/countries/9" } }, "city": "New York", "created_at": "2014-12-15T13:37:28+0000", "first_name": "John", "id": 106, "last_name": "Doe", "postcode": "12435", "street": "Test", "updated_at": "2014-12-15T13:37:29+0000"

64 Chapter 3. The API Guide Sylius, Release

}, "channel":{ "_links":{ "self":{ "href": "/app_dev.php/api/channels/3" } }, "code": "WEB-US", "color": "Pink", "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":3, "name": "United States Webstore", "type": "web", "updated_at": "2014-12-03T09:58:29+0000" }, "checkout_state": "addressing", "comments": [], "confirmed": true, "created_at": "2014-12-15T13:15:22+0000", "email": "[email protected]", "expires_at": "2014-12-15T16:15:22+0000", "id": 52, "items": [], "items_total": 1500000, "payments": [], "shipments": [], "state": "cart", "total": 1499750, "updated_at": "2014-12-15T13:37:29+0000", "user":{ "credentials_expired": false, "email": "[email protected]", "email_canonical": "[email protected]", "enabled": true, "expired": false, "groups": [], "id":5, "locked": false, "roles": [], "username": "[email protected]", "username_canonical": "[email protected]" } }

Shipping step

When order contains the address information, we are able to determine the stock locations and available shipping methods. You can get these informations by ﬁrst calling a GET request on the checkout unique URL.

GET /api/checkouts/44

STATUS: 200 OK

[ {

3.1. The API Guide 65 Sylius, Release

"methods":[ { "_links":{ "self":{ "href": "/app_dev.php/api/shipping-methods/4" }, "zone":{ "href": "/app_dev.php/api/zones/4" } }, "calculator": "flexible_rate", "category_requirement":1, "configuration":{ "additional_item_cost": 500, "additional_item_limit": 10, "first_item_cost": 4000 }, "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":4, "name": "FedEx World Shipping", "updated_at": "2014-12-03T09:54:28+0000" } ], "shipment":{ "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T14:11:32+0000", "state": "checkout" } } ]

Response contains the proposed shipments and for each, it also has a list of shipping methods available. Next step is updating the order with the types of shipping method that we have selected. To do so, you need to call another PUT request, but this time with different set of parameters. You need to pass an id of shipping method for every id, you should obtain them in the previous request.

PUT /api/checkouts/44

Parameters shipments[X][method] The id of the shipping method, where X is the shipment number. Leave empty to add new

Response

Response will contain an updated order information.

STATUS: 200 OK

66 Chapter 3. The API Guide Sylius, Release

{ "adjustments":{ }, "adjustments_total": 4750, "billing_address":{ }, "channel":{ }, "checkout_state": "shipping", "comments": [], "confirmed": true, "created_at": "2014-12-15T13:15:22+0000", "email": "[email protected]", "expires_at": "2014-12-15T16:15:22+0000", "id": 52, "items":[ ], "items_total": 1500000, "payments": [], "shipments":[ { "_links":{ "method":{ "href": "/app_dev.php/api/shipping-methods/4" }, "order":{ "href": "/app_dev.php/api/orders/52" }, "self":{ "href": "/app_dev.php/api/shipments/51" } }, "created_at": "2014-12-15T14:30:40+0000", "id": 51, "method":{ "_links":{ "self":{ "href": "/app_dev.php/api/shipping-methods/4" }, "zone":{ "href": "/app_dev.php/api/zones/4" } }, "calculator": "flexible_rate", "category_requirement":1, "configuration":{ "additional_item_cost": 500, "additional_item_limit": 10, "first_item_cost": 4000 }, "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":4, "name": "FedEx World Shipping", "updated_at": "2014-12-03T09:54:28+0000" }, "state": "checkout", "updated_at": "2014-12-15T14:30:41+0000"

3.1. The API Guide 67 Sylius, Release

} ], "shipping_address":{ }, "state": "cart", "total": 1504750, "updated_at": "2014-12-15T14:30:41+0000", "user":{ } }

Payment step

When we are done with shipping choices and we know the ﬁnal price of an order, we can select a payment method. To obtain a list of available payment methods for this order, simply call a GET request again:

GET /api/checkouts/44

STATUS: 200 OK

{ "methods":{ "1":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/1" } }, "id":1, "code": "dummy", "created_at": "2014-12-03T09:54:28+0000", "updated_at": "2014-12-03T09:54:28+0000" }, "2":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/2" } }, "id":2, "code": "paypal_express_checkout", "created_at": "2014-12-03T09:54:28+0000", "updated_at": "2014-12-03T09:54:28+0000" }, "3":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/3" } }, "id":3, "code": "stripe", "created_at": "2014-12-03T09:54:28+0000", "updated_at": "2014-12-03T09:54:28+0000" },

68 Chapter 3. The API Guide Sylius, Release

"4":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/4" } }, "id":4, "code": "be_2_bill", "created_at": "2014-12-03T09:54:28+0000", "updated_at": "2014-12-03T09:54:28+0000" }, "5":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/5" } }, "id":5, "code": "stripe_checkout", "created_at": "2014-12-03T09:54:28+0000", "updated_at": "2014-12-03T09:54:28+0000" } }, "payment":{ "_links":{ "self":{ "href": "/app_dev.php/api/payments/2" }, "order":{ "href": "/app_dev.php/api/orders/52" } }, "id":2, "amount": 1504750, "created_at": "2014-12-15T14:57:28+0000", "updated_at": "2014-12-15T14:57:28+0000", "state": "new" } }

With that information, another PUT request with the id of payment method is enough to proceed:

PUT /api/checkouts/44

Parameters payments[X][method] The id of the payment method, where X is the payment number. Leave empty to add new

Response

Response will contain the updated order information.

STATUS: 200 OK

3.1. The API Guide 69 Sylius, Release

{ "adjustments":[ ], "adjustments_total": 4750, "billing_address":{ }, "channel":{ }, "checkout_state": "payment", "comments": [], "confirmed": true, "created_at": "2014-12-15T13:15:22+0000", "email": "[email protected]", "expires_at": "2014-12-15T16:15:22+0000", "id": 52, "items":[ ], "items_total": 1500000, "payments":[ { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" }, "payment-method":{ "href": "/app_dev.php/api/payment-methods/1" }, "self":{ "href": "/app_dev.php/api/payments/51" } }, "amount": 1504750, "created_at": "2014-12-15T15:02:54+0000", "id": 51, "method":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/1" } }, "created_at": "2014-12-03T09:54:28+0000", "id":1, "name": "Dummy", "updated_at": "2014-12-03T09:54:28+0000" }, "state": "new", "updated_at": "2014-12-15T15:02:55+0000" } ], "shipments":[ ], "shipping_address":{ }, "state": "cart", "total": 1504750, "updated_at": "2014-12-15T15:02:55+0000", "user":{ }

70 Chapter 3. The API Guide Sylius, Release

}

Finalize step

Now your order is fully constructed, you can get its latest snapshot by calling your last GET request:

GET /api/checkouts/44

STATUS: 200 OK

{ "adjustments":[ { "amount":0, "created_at": "2014-12-15T13:37:29+0000", "description": "No tax (0%)", "id": 205, "type": "tax", "locked": false, "neutral": false, "updated_at": "2014-12-15T13:37:29+0000" }, { "amount": 5000, "created_at": "2014-12-15T14:30:41+0000", "description": "FedEx World Shipping", "id": 207, "type": "shipping", "locked": false, "neutral": false, "updated_at": "2014-12-15T14:30:41+0000" }, { "amount": -250, "created_at": "2014-12-15T14:30:41+0000", "description": "Christmas Sale for orders over 100 EUR.", "id": 208, "type": "promotion", "locked": false, "neutral": false, "updated_at": "2014-12-15T14:30:41+0000" } ], "adjustments_total": 4750, "billing_address":{ "_links":{ "country":{ "href": "/app_dev.php/api/countries/9" } }, "city": "New York", "created_at": "2014-12-15T13:37:28+0000", "first_name": "John", "id": 106, "last_name": "Doe", "postcode": "12435",

3.1. The API Guide 71 Sylius, Release

"street": "Test", "updated_at": "2014-12-15T13:37:29+0000" }, "channel":{ "_links":{ "self":{ "href": "/app_dev.php/api/channels/3" } }, "code": "WEB-US", "color": "Pink", "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":3, "name": "United States Webstore", "type": "web", "updated_at": "2014-12-03T09:58:29+0000" }, "checkout_state": "payment_selected", "comments": [], "created_at": "2014-12-15T13:15:22+0000", "updated_at": "2014-12-15T15:02:55+0000", "expires_at": "2014-12-15T16:15:22+0000", "id": 52, "items":[ { "_links":{ "product":{ "href": "/app_dev.php/api/products/101" }, "variant":{ "href": "/app_dev.php/api/products/101/variants/779" } }, "adjustments": [], "adjustments_total":0, "id": 277, "immutable": false, "inventory_units":[ { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 828, "inventory_state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" }, { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 829,

72 Chapter 3. The API Guide Sylius, Release

"inventory_state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" }, { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 830, "inventory_state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" } ], "quantity":3, "total": 1500000, "unit_price": 500000, "variant":{ "available_on": "2014-04-01T06:43:02+0000", "created_at": "2014-12-03T09:54:35+0000", "id": 779, "master": true, "object":{ "attributes":[ { "id": 238, "name": "Book author", "presentation": "Author", "value": "Marlen Yost" }, { "id": 239, "name": "Book ISBN", "presentation": "ISBN", "value": "326ccbc7-92d1-3aec-b3af-df8afdc5651d" }, { "id": 240, "name": "Book pages", "presentation": "Number of pages", "value": "149" } ], "created_at": "2014-12-03T09:54:35+0000", "description": "Et eveniet voluptas ut magni vero temporibus

˓→nihil. Omnis possimus accusantium quia corporis culpa. Et recusandae asperiores qui

˓→architecto culpa autem sint accusantium. Officiis iusto accusantium perferendis

˓→aliquid ducimus.", "id": 101, "name": "Book \"Quidem\" by \"Marlen Yost\"", "options": [], "short_description": "Distinctio quos est eaque fugit totam

˓→repellendus.", "updated_at": "2014-12-03T09:54:35+0000" }, "options": [], "sku": "326ccbc7-92d1-3aec-b3af-df8afdc5651d",

3.1. The API Guide 73 Sylius, Release

"updated_at": "2014-12-03T09:54:35+0000" } } ], "items_total": 1500000, "payments":[ { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" }, "payment-method":{ "href": "/app_dev.php/api/payment-methods/1" }, "self":{ "href": "/app_dev.php/api/payments/51" } }, "amount": 1504750, "created_at": "2014-12-15T15:02:54+0000", "id": 51, "method":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/1" } }, "created_at": "2014-12-03T09:54:28+0000", "id":1, "name": "Dummy", "updated_at": "2014-12-03T09:54:28+0000" }, "state": "new", "updated_at": "2014-12-15T15:02:55+0000" } ], "shipments":[ { "_links":{ "method":{ "href": "/app_dev.php/api/shipping-methods/4" }, "order":{ "href": "/app_dev.php/api/orders/52" }, "self":{ "href": "/app_dev.php/api/shipments/51" } }, "created_at": "2014-12-15T14:30:40+0000", "id": 51, "method":{ "_links":{ "self":{ "href": "/app_dev.php/api/shipping-methods/4" }, "zone":{ "href": "/app_dev.php/api/zones/4"

74 Chapter 3. The API Guide Sylius, Release

} }, "calculator": "flexible_rate", "category_requirement":1, "configuration":{ "additional_item_cost": 500, "additional_item_limit": 10, "first_item_cost": 4000 }, "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":4, "name": "FedEx World Shipping", "updated_at": "2014-12-03T09:54:28+0000" }, "state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" } ], "shipping_address":{ "_links":{ "country":{ "href": "/app_dev.php/api/countries/9" } }, "city": "New York", "created_at": "2014-12-15T13:37:28+0000", "first_name": "John", "id": 105, "last_name": "Doe", "postcode": "12435", "street": "Test", "updated_at": "2014-12-15T13:37:29+0000" }, "state": "cart", "total": 1504750 }

This is how your ﬁnal order looks, if you are happy with that response, simply call another PUT to conﬁrm the checkout, which will became a real order and appear in the backend.

PUT /api/checkouts/44

Response

Final response contains the full order information, now you can call the purchase action to actually pay for the order.

STATUS: 200 OK

{ "adjustments":[ { "amount":0, "created_at": "2014-12-15T13:37:29+0000", "label": "No tax (0%)", "id": 205,

3.1. The API Guide 75 Sylius, Release

"type": "tax", "locked": false, "neutral": false, "updated_at": "2014-12-15T13:37:29+0000" }, { "amount": 5000, "created_at": "2014-12-15T14:30:41+0000", "label": "FedEx World Shipping", "id": 207, "type": "shipping", "locked": false, "neutral": false, "updated_at": "2014-12-15T14:30:41+0000" }, { "amount": -250, "created_at": "2014-12-15T14:30:41+0000", "description": "Christmas Sale for orders over 100 EUR.", "id": 208, "type": "order_promotion", "locked": false, "neutral": false, "updated_at": "2014-12-15T14:30:41+0000" } ], "adjustments_total": 4750, "billing_address":{ "_links":{ "country":{ "href": "/app_dev.php/api/countries/9" } }, "city": "New York", "created_at": "2014-12-15T13:37:28+0000", "first_name": "John", "id": 106, "last_name": "Doe", "postcode": "12435", "street": "Test", "updated_at": "2014-12-15T13:37:29+0000" }, "channel":{ "_links":{ "self":{ "href": "/app_dev.php/api/channels/3" } }, "code": "WEB-US", "color": "Pink", "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":3, "name": "United States Webstore", "type": "web", "updated_at": "2014-12-03T09:58:29+0000" }, "comments": [],

76 Chapter 3. The API Guide Sylius, Release

"created_at": "2014-12-15T13:15:22+0000", "updated_at": "2014-12-15T15:02:55+0000", "expires_at": "2014-12-15T16:15:22+0000", "id": 52, "items":[ { "_links":{ "product":{ "href": "/app_dev.php/api/products/101" }, "variant":{ "href": "/app_dev.php/api/products/101/variants/779" } }, "adjustments": [], "adjustments_total":0, "id": 277, "immutable": false, "inventory_units":[ { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 828, "inventory_state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" }, { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 829, "inventory_state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" }, { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" } }, "created_at": "2014-12-15T13:18:48+0000", "id": 830, "inventory_state": "checkout", "updated_at": "2014-12-15T14:30:41+0000" } ], "quantity":3, "total": 1500000, "unit_price": 500000, "variant":{ "available_on": "2014-04-01T06:43:02+0000",

3.1. The API Guide 77 Sylius, Release

"created_at": "2014-12-03T09:54:35+0000", "id": 779, "master": true, "object":{ "attributes":[ { "id": 238, "name": "Book author", "presentation": "Author", "value": "Marlen Yost" }, { "id": 239, "name": "Book ISBN", "presentation": "ISBN", "value": "326ccbc7-92d1-3aec-b3af-df8afdc5651d" }, { "id": 240, "name": "Book pages", "presentation": "Number of pages", "value": "149" } ], "created_at": "2014-12-03T09:54:35+0000", "description": "Et eveniet voluptas ut magni vero temporibus

˓→nihil. Omnis possimus accusantium quia corporis culpa. Et recusandae asperiores qui

˓→architecto culpa autem sint accusantium. Officiis iusto accusantium perferendis

˓→aliquid ducimus.", "id": 101, "name": "Book \"Quidem\" by \"Marlen Yost\"", "options": [], "short_description": "Distinctio quos est eaque fugit totam

˓→repellendus.", "updated_at": "2014-12-03T09:54:35+0000" }, "options": [], "sku": "326ccbc7-92d1-3aec-b3af-df8afdc5651d", "updated_at": "2014-12-03T09:54:35+0000" } } ], "items_total": 1500000, "payments":[ { "_links":{ "order":{ "href": "/app_dev.php/api/orders/52" }, "payment-method":{ "href": "/app_dev.php/api/payment-methods/1" }, "self":{ "href": "/app_dev.php/api/payments/51" } }, "amount": 1504750, "created_at": "2014-12-15T15:02:54+0000",

78 Chapter 3. The API Guide Sylius, Release

"id": 51, "method":{ "_links":{ "self":{ "href": "/app_dev.php/api/payment-methods/1" } }, "created_at": "2014-12-03T09:54:28+0000", "id":1, "name": "Dummy", "updated_at": "2014-12-03T09:54:28+0000" }, "state": "new", "updated_at": "2014-12-15T15:02:55+0000" } ], "shipments":[ { "_links":{ "method":{ "href": "/app_dev.php/api/shipping-methods/4" }, "order":{ "href": "/app_dev.php/api/orders/52" }, "self":{ "href": "/app_dev.php/api/shipments/51" } }, "created_at": "2014-12-15T14:30:40+0000", "id": 51, "method":{ "_links":{ "self":{ "href": "/app_dev.php/api/shipping-methods/4" }, "zone":{ "href": "/app_dev.php/api/zones/4" } }, "calculator": "flexible_rate", "category_requirement":1, "configuration":{ "additional_item_cost": 500, "additional_item_limit": 10, "first_item_cost": 4000 }, "created_at": "2014-12-03T09:54:28+0000", "enabled": true, "id":4, "name": "FedEx World Shipping", "updated_at": "2014-12-03T09:54:28+0000" }, "state": "onhold", "updated_at": "2014-12-15T14:30:41+0000" } ], "shipping_address":{

3.1. The API Guide 79 Sylius, Release

"_links":{ "country":{ "href": "/app_dev.php/api/countries/9" } }, "city": "New York", "created_at": "2014-12-15T13:37:28+0000", "first_name": "John", "id": 105, "last_name": "Doe", "postcode": "12435", "street": "Test", "updated_at": "2014-12-15T13:37:29+0000" }, "total": 1504750, "state": "new", "number": "000000001", "completed_at": "2016-06-24T10:55:28+0200", "checkout_state": "completed", }

Purchase step

TODO.

PUT /api/checkouts/44

Parameters type Card type cardholderName Card holder name number Card number securityCode Card security code expiryMonth Month expire number expiryYear Year of card expiration

Response

You can check the payment status in the payment lists on order response.

STATUS: 200 OK

{"to": "do"}

3.1.6 Products API

Sylius products catalogue API endpoint is /api/products and it allows for browsing, creating & editing product information.

80 Chapter 3. The API Guide Sylius, Release

Index of all products

To browse all products available in the store you should call the following GET request:

GET /api/products/

Parameters page Number of the page, by default = 1 limit Number of items to display per page criteria[channel] Id of the channel (optional) criteria[name] Name of the product (optional)

Response

Response will contain a paginated list of products.

STATUS: 200 OK

{ "page":1, "limit":10, "pages":12, "total":120, "_links":{ "self":{ "href":"\/api\/products\/?page=1" }, "first":{ "href":"\/api\/products\/?page=1" }, "last":{ "href":"\/api\/products\/?page=12" }, "next":{ "href":"\/api\/products\/?page=2" } }, "_embedded":{ "items":[ { "created_at": "2014-11-26T23:00:20+0000", "description": "Facere ipsum id eveniet rem omnis et. Totam vero eos

˓→eveniet nihil sint. Labore occaecati qui placeat fugit.", "id": 2173, "name": "T-Shirt \"ipsam\"", "code": "T-SHIRT-IPSAM", "short_description": "Aut rerum quasi neque.", "updated_at": "2014-11-26T23:00:20+0000" } ] } }

3.1. The API Guide 81 Sylius, Release

Getting a single product

You can view a single product by executing the following request:

GET /api/products/2173

Response

STATUS: 200 OK

{ "created_at": "2014-11-26T23:00:20+0000", "description": "Facere ipsum id eveniet rem omnis et. Totam vero eos eveniet

˓→nihil sint. Labore occaecati qui placeat fugit.", "id": 2173, "name": "T-Shirt \"ipsam\"", "code": "T-SHIRT-IPSAM", "short_description": "Aut rerum quasi neque.", "updated_at": "2014-11-26T23:00:20+0000" }

Creating an product

To create a new product, you can execute the following request:

POST /api/products/

Parameters name Name of the product description Description of the product price Price of the product shortDescription (optional) Short description of the product (for lists)

Response

STATUS: 201 CREATED

{ "created_at": "2014-11-29T14:23:57+0000", "description": "Bar", "id": 2181, "name": "Foo", "code": "FOO", "updated_at": "2014-11-29T14:23:58+0000" }

82 Chapter 3. The API Guide Sylius, Release

Updating a product

You can update an existing product using PUT or PATCH method:

PUT /api/products/2181

PATCH /api/products/2181

Parameters name Name of the product description Description of the product price Price of the product shortDescription (optional) Short description of the product (for lists)

Response

STATUS: 204 NO CONTENT

Deleting a product

You can delete (soft) a product from the catalog by making the following DELETE call:

DELETE /api/products/24

Response

STATUS: 204 NO CONTENT

3.1.7 Users API

Sylius users API endpoint is /api/users and it allows for browsing, creating & editing user data.

Index of all users

To browse all users available in the store you should call the following GET request:

GET /api/users/

Parameters page Number of the page, by default = 1 limit Number of items to display per page

3.1. The API Guide 83 Sylius, Release criteria[query] Username, email or ﬁrst & last names

Response

Response will contain a paginated list of users.

STATUS: 200 OK

{ "page":1, "limit":10, "pages":10, "total":100, "_links":{ "self":{ "href":"\/api\/users\/?page=1" }, "first":{ "href":"\/api\/users\/?page=1" }, "last":{ "href":"\/api\/users\/?page=12" }, "next":{ "href":"\/api\/users\/?page=2" } }, "_embedded":{ "items":[ { "credentials_expired": false, "email": "[email protected]", "email_canonical": "[email protected]", "enabled": true, "expired": false, "groups": [], "id": 481, "locked": false, "password":

˓→"EbOLtGHYxJKotA+bdb9BElhXPd8qZsnlo8CjDdCk+qFR22EEZJoOTntBX/

˓→M5GUXw2vnEqOKIEVPaJr66yxXqqQ==", "roles": [], "salt": "h9ltmmawvdsk08oocogkws4sg040k04", "username": "[email protected]", "username_canonical": "[email protected]" } ] } }

Getting a single user

You can view a single user by executing the following request:

84 Chapter 3. The API Guide Sylius, Release

GET /api/users/481

Response

STATUS: 200 OK

{ "credentials_expired": false, "email": "[email protected]", "email_canonical": "[email protected]", "enabled": true, "expired": false, "groups": [], "id": 481, "locked": false, "password": "EbOLtGHYxJKotA+bdb9BElhXPd8qZsnlo8CjDdCk+qFR22EEZJoOTntBX/

˓→M5GUXw2vnEqOKIEVPaJr66yxXqqQ==", "roles": [], "salt": "h9ltmmawvdsk08oocogkws4sg040k04", "username": "[email protected]", "username_canonical": "[email protected]" }

Create an user

To create a new user, you can execute the following request:

POST /api/users/

Parameters

ﬁrstName Firstname of the customer lastName Lastname of the customer email User e-mail plainPassword Password string enabled (optional) User account status (boolean)

Response

STATUS: 201 CREATED

{ "credentials_expired": false, "email": "[email protected]", "email_canonical": "[email protected]", "enabled": true, "expired": false,

3.1. The API Guide 85 Sylius, Release

"groups": [], "id": 481, "locked": false, "password": "EbOLtGHYxJKotA+bdb9BElhXPd8qZsnlo8CjDdCk+qFR22EEZJoOTntBX/

˓→M5GUXw2vnEqOKIEVPaJr66yxXqqQ==", "roles": [], "salt": "h9ltmmawvdsk08oocogkws4sg040k04", "username": "[email protected]", "username_canonical": "[email protected]" }

Updating a user

You can update an existing user using PUT or PATCH method:

PUT /api/users/481

PATCH /api/users/481

Parameters

ﬁrstName Firstname of the customer lastName Lastname of the customer email User e-mail plainPassword Password string enabled (optional) User account status (boolean)

Response

STATUS: 204 NO CONTENT

Deleting a user

You can delete (soft) a user from the system by making the following DELETE call:

DELETE /api/users/24

Response

STATUS: 204 NO CONTENT

86 Chapter 3. The API Guide Sylius, Release

Request password resetting

You can create a new password resetting request by calling the following API endpoint:

POST /api/password-resetting-requests/

Parameters

username Username or e-mail

Response

The successful response will contain the user object with a conﬁrmation token and date of password request.

STATUS: 200 OK

{ "confirmation_token": "dzOeNrmdnn20IVHBW2Uaq-yAYsO2sY2hCXhfKdYl_xM", "credentials_expired": false, "email": "[email protected]", "email_canonical": "[email protected]", "enabled": true, "expired": false, "groups": [], "id":1, "last_login": "2014-12-08T13:08:02+0000", "locked": false, "password_requested_at": "2014-12-08T14:19:26+0000", "roles":[ "ROLE_ADMINISTRATION_ACCESS" ], "username": "[email protected]", "username_canonical": "[email protected]" }

Index of all user orders

To browse all orders for speciﬁc user, you can do the following call:

GET /api/users/14/orders/

Parameters

page Number of the page, by default = 1 limit Number of items to display per page

3.1.8 Customers API

These endpoints will allow you to easily manage customers. Base URI is /api/customers. Customer class is strongly coupled with a user class. Because of that we recommend these endpoints to manage all related to user actions

3.1. The API Guide 87 Sylius, Release

When you get a collection of resources, “Default” serialization group will be used and following fields will be exposed: Field Description id Id of customer user[id] (optional) Id of related user user[username] (optional) Users username user[enabled] (optional) Flag set if user is enabled email Customers email first_name Customers first name last_name Customers last name If you request for a more detailed data, you will receive an object with following fields: Field Description id Id of customer user[id] (optional) Id of related user user[username] (optional) Users username user[username_canonical] (optional) Canonicalized users username user[roles] (optional) Array of users roles user[enabled] (optional) Flag set if user is enabled email Customers email email_canonical Canonicalized customers email first_name Customers first name last_name Customers last name gender Customers gender birthday Customers birthday groups Array of groups customer belongs to

Note: Read more about Customer and User

Collection of Customers

You can retrieve the full customers list by making the following request:

Deﬁnition

GET /api/customers/

Parameter Parameter type Description Authorization header Token received during authentication page query (optional) Number of the page, by default = 1 limit query (optional) Number of items to display per page, by default = 10

Example curl http://sylius.dev/api/customers/ -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json”

88 Chapter 3. The API Guide Sylius, Release

Example Response

STATUS: 200 OK

{ "page":1, "limit":10, "pages":21, "total":205, "_links":{ "self":{ "href":"\/api\/customers\/?page=1&limit=10" }, "first":{ "href":"\/api\/customers\/?page=1&limit=10" }, "last":{ "href":"\/api\/customers\/?page=21&limit=10" }, "next":{ "href":"\/api\/customers\/?page=2&limit=10" } }, "_embedded":{ "items":[ { "id":407, "email":"[email protected]", "first_name":"Random", "last_name":"Doe" }, { "id":406, "email":"[email protected]", "first_name":"Alexanne", "last_name":"Blick" }, { "id":405, "user":{ "id":404, "username":"[email protected]", "enabled":true }, "email":"[email protected]", "first_name":"Dereck", "last_name":"McDermott" }, { "id":404, "user":{ "id":403, "username":"[email protected]", "enabled":false }, "email":"[email protected]", "first_name":"Benton",

3.1. The API Guide 89 Sylius, Release

"last_name":"Satterfield" }, { "id":403, "user":{ "id":402, "username":"[email protected]", "enabled":false }, "email":"[email protected]", "first_name":"Rusty", "last_name":"Jerde" }, { "id":402, "user":{ "id":401, "username":"[email protected]", "enabled":false }, "email":"[email protected]", "first_name":"Omer", "last_name":"Schaden" }, { "id":401, "user":{ "id":400, "username":"[email protected]", "enabled":true }, "email":"[email protected]", "first_name":"Willard", "last_name":"Hand" }, { "id":400, "user":{ "id":399, "username":"[email protected]", "enabled":false }, "email":"[email protected]", "first_name":"Caterina", "last_name":"Koelpin" }, { "id":399, "user":{ "id":398, "username":"[email protected]", "enabled":false }, "email":"[email protected]", "first_name":"Levi", "last_name":"Friesen" } ]

90 Chapter 3. The API Guide Sylius, Release

} }

Getting a Single Customer

You can request detailed customer information by executing the following request:

Deﬁnition

GET /api/customers/{id}

Parameter Parameter type Description Authorization header Token received during authentication id url attribute Id of requested resource page query (optional) Number of the page, by default = 1 limit query (optional) Number of items to display per page, by default = 10

Example curl http://sylius.dev/api/customers/399 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json”

Example Response

STATUS: 200 OK

{ "id":399, "user":{ "id":398, "username":"[email protected]", "username_canonical":"[email protected]", "roles":[ "ROLE_USER" ], "enabled":false }, "email":"[email protected]", "email_canonical":"[email protected]", "first_name":"Levi", "last_name":"Friesen", "gender":"u", "groups":[

] }

3.1. The API Guide 91 Sylius, Release

Creating Customer

Deﬁnition

POST /api/customers/

Parameter Parameter Description type Authorization header Token received during authentication email request (unique) Customers email ﬁrst_name request Customers ﬁrst name last_name request Customers last name groups request (optional) Array of groups customer belongs to gender request Customers gender birthday request (optional) Customers birthday user[plainPassword] request (optional) Users plain password. Required if user account should be created together with customer user[authorizationRoles]request (optional) Array of users roles user[enabled] request (optional) Flag set if user is enabled

Example curl http://sylius.dev/api/customers/ -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Content-Type: application/json" -X POST --data' { "firstName": "John", "lastName": "Diggle", "email": "[email protected]", "gender": "m", "user": { "plainPassword" : "testPassword" } } '

Example Response

STATUS: 201 Created

{ "id":409, "user":{ "id":405, "username":"[email protected]", "roles":[ "ROLE_USER" ],

92 Chapter 3. The API Guide Sylius, Release

"enabled":false }, "email":"[email protected]", "email_canonical":"[email protected]", "first_name":"John", "last_name":"Diggle", "gender":"m", "groups":[

] }

If you try to create a customer without email, ﬁrst name, last name or gender, you will receive a 400 error.

Example curl http://sylius.dev/api/customers/ -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Accept: application/json" -X POST

Example Response

STATUS: 400 Bad Request

{ "code":400, "message":"Validation Failed", "errors":{ "children":{ "firstName":{ "errors":[ "Please enter your first name." ] }, "lastName":{ "errors":[ "Please enter your last name." ] }, "email":{ "errors":[ "Please enter your email." ] }, "birthday":{

}, "gender":{ "errors":[ "Please choose your gender." ]

3.1. The API Guide 93 Sylius, Release

}, "groups":{

} } } }

Updating Customer

You can request full or partial update of resource. For full customer update, you should use PUT method.

Deﬁnition

PUT /api/customers/{id}

Parameter Parameter Description type Authorization header Token received during authentication id url attribute Id of requested resource email request (unique) Customers email first_name request Customers first name last_name request Customers last name groups request (optional) Array of groups customer belongs to gender request Customers gender birthday request (optional) Customers birthday user[plainPassword] request (optional) Users plain password. Required if any of user fields is defined user[authorizationRoles] request (optional) Array of users roles. user[enabled] request (optional) Flag set if user is enabled.

Example curl http://sylius.dev/api/customers/399 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Content-Type: application/json" -X PUT --data' { "firstName": "John", "lastName": "Diggle", "email": "[email protected]", "gender": "m" } '

94 Chapter 3. The API Guide Sylius, Release

Example Response

STATUS: 204 No Content

If you try to perform full customer update without all required ﬁelds speciﬁed, you will receive a 400 error.

Example curl http://sylius.dev/api/customers/399 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json” -X PUT

Example Response

STATUS: 400 Bad Request

}, "gender":{ "errors":[ "Please choose your gender." ] }, "groups":{

} } } }

3.1. The API Guide 95 Sylius, Release

In order to perform a partial update, you should use a PATCH method.

Deﬁnition

PATCH /api/customers/{id}

Parameter Parameter type Description Authorization header Token received during authentication id url attribute Id of requested resource email request (optional) (unique) Customers email ﬁrst_name request (optional) Customers ﬁrst name last_name request (optional) Customers last name groups request (optional) Array of groups customer belongs to gender request (optional) Customers gender birthday request (optional) Customers birthday user[plainPassword] request (optional) Users plain password. user[authorizationRoles] request (optional) Array of users roles. user[enabled] request (optional) Flag set if user is enabled.

Example curl http://sylius.dev/api/customers/399 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Content-Type: application/json" -X PATCH --data '{"first_name": "Joe"}'

Example Response

STATUS: 204 No Content

Deleting Customer

Deﬁnition

DELETE /api/customers/{id}

Parameter Parameter type Description Authorization header Token received during authentication id url attribute Id of requested resource

Example

96 Chapter 3. The API Guide Sylius, Release

curl http://sylius.dev/api/customers/399 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json” -X DELETE

Example Response

STATUS: 204 No Content

3.1.9 Shipments API

Sylius shipments API endpoint is /api/shipments.

Index of all shipments

You can retrieve the full list shipment by making the following request:

GET /api/shipments/

Parameters page Number of the page, by default = 1 limit Number of items to display per page criteria[channel] (optional) The channel id criteria[stockLocation] (optional) The id of stock location criteria[number] (optional) The order number criteria[shippingAddress] (optional) First or last name of the customer ship to address criteria[createdAtFrom] (optional) Starting date criteria[createdAtTo] (optional) End date

Response

STATUS: 200 OK

{ "page":1, "limit":10, "pages":8, "total":80, "_links":{ "self":{ "href":"\/api\/shipments\/?page=1"

3.1. The API Guide 97 Sylius, Release

}, "first":{ "href":"\/api\/shipments\/?page=1" }, "last":{ "href":"\/api\/shipments\/?page=12" }, "next":{ "href":"\/api\/shipments\/?page=2" } }, "_embedded":{ "items":[ { "_links":{ "method":{ "href": "/api/shipping-methods/120" }, "order":{ "href": "/api/orders/302" }, "self":{ "href": "/api/shipments/251" } }, "created_at": "2014-11-26T23:00:34+0000", "id": 251, "method":{ "_links":{ "self":{ "href": "/api/shipping-methods/120" }, "zone":{ "href": "/api/zones/120" } }, "calculator": "flexible_rate", "category_requirement":1, "configuration":{ "additional_item_cost": 500, "additional_item_limit": 10, "first_item_cost": 4000 }, "created_at": "2014-11-26T23:00:15+0000", "enabled": true, "id": 120, "name": "FedEx World Shipping", "updated_at": "2014-11-26T23:00:15+0000" }, "state": "backordered", "updated_at": "2014-11-26T23:00:34+0000" } ] } }

98 Chapter 3. The API Guide Sylius, Release

Getting a single shipment

You can view a single shipment by executing the following request:

GET /api/shipments/251

Response

STATUS: 200 OK

{ "_links":{ "method":{ "href": "/api/shipping-methods/120" }, "order":{ "href": "/api/orders/302" }, "self":{ "href": "/api/shipments/251" } }, "created_at": "2014-11-26T23:00:34+0000", "id": 251, "method":{ "_links":{ "self":{ "href": "/api/shipping-methods/120" }, "zone":{ "href": "/api/zones/120" } }, "calculator": "flexible_rate", "category_requirement":1, "configuration":{ "additional_item_cost": 500, "additional_item_limit": 10, "first_item_cost": 4000 }, "created_at": "2014-11-26T23:00:15+0000", "enabled": true, "id": 120, "name": "FedEx World Shipping", "updated_at": "2014-11-26T23:00:15+0000" }, "state": "backordered", "updated_at": "2014-11-26T23:00:34+0000" }

Deleting a shipment

You can delete a shipment from the system by making the following DELETE call:

3.1. The API Guide 99 Sylius, Release

DELETE /api/shipments/24

Response

STATUS: 204 NO CONTENT

3.1.10 Shipping Categories

These endpoints will allow you to easily manage shipping categories. Base URI is /api/shipping-categories. When you get a collection of resources, “Default” serialization group will be used and following fields will be exposed: Field Description id Id of shipping category name Name of shipping category code Unique shipping category identifier If you request for a more detailed data, you will receive an object with following fields: Field Description id Id of shipping category name Name of shipping category code Unique shipping category identifier description Description of shipping category

Note: Read more about Shipping Categories

Collection of Shipping Categories

You can retrieve the full shipment categories list by making the following request:

Deﬁnition

GET /api/shipping-categories/

Example curl http://sylius.dev/api/shipping-categories/ -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json”

100 Chapter 3. The API Guide Sylius, Release

Example Response

STATUS: 200 OK

{ "page":1, "limit": 10, "pages":1, "total":2, "_links":{ "self":{ "href": "\/api\/shipping-categories\/?page=1&limit=10" }, "first":{ "href": "\/api\/shipping-categories\/?page=1&limit=10" }, "last":{ "href": "\/api\/shipping-categories\/?page=1&limit=10" } }, "_embedded":{ "items":[ { "id":1, "code": "SC1", "name": "Regular", "_links":{ "self":{ "href": "\/api\/shipping-categories\/1" } } }, { "id":2, "code": "SC2", "name": "Heavy", "_links":{ "self":{ "href": "\/api\/shipping-categories\/2" } } } ] } }

Getting a Single Shipping Category

You can request detailed shipping category information by executing the following request:

Deﬁnition

GET /api/shipping-categories/{id}

3.1. The API Guide 101 Sylius, Release

Example curl http://sylius.dev/api/shipping-categories/1 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json”

Example Response

STATUS: 200 OK

{ "id":1, "code": "SC1", "name": "Regular", "description": "Regular weight items", "_links":{ "self":{ "href": "\/api\/shipping-categories\/1" } } }

Creating Shipping Category

Deﬁnition

POST /api/shipping-categories/

Parameter Parameter type Description Authorization header Token received during authentication name request Name of creating shipping category code request (unique) Shipping category identiﬁer description request (optional) Description of creating shipping category

Example curl http://sylius.dev/api/shipping-categories/ -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Content-Type: application/json"

102 Chapter 3. The API Guide Sylius, Release

-X POST --data' { "name": "Light", "description": "Light weight items", "code": "SC3" } '

Example Response

STATUS: 201 Created

{ "id":3, "code": "SC3", "name": "Light", "description": "Light weight items", "_links":{ "self":{ "href": "\/api\/shipping-categories\/3" } } }

If you try to create a resource without name or code, you will receive a 400 error.

Example curl http://sylius.dev/api/shipping-categories/-1 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json” -X POST

Example Response

STATUS: 400 Bad Request

{ "code": 400, "message": "Validation Failed", "errors":{ "children":{ "name":{ "errors":[ "Please enter shipping category name." ] }, "code":{

3.1. The API Guide 103 Sylius, Release

"errors":[ "Please enter shipping category code." ] }, "description": [] } } }

Updating Shipping Category

You can request full or partial update of resource. For full shipping category update, you should use PUT method.

Deﬁnition

PUT /api/shipping-categories/{id}

Parameter Parameter type Description Authorization header Token received during authentication id url attribute Id of requested resource name request Name of creating shipping category description request Description of creating shipping category

Example

curl http://sylius.dev/api/shipping-categories/3 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Content-Type: application/json" -X PUT --data' { "name": "Ultra light", "description": "Ultra light weight items" } '

Example Response

STATUS: 204 No Content

If you try to perform full shipping category update without all required ﬁelds speciﬁed, you will receive a 400 error.

Example

104 Chapter 3. The API Guide Sylius, Release

curl http://sylius.dev/api/shipping-categories/-1 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json” -X PUT

Example Response

STATUS: 400 Bad Request

{ "code": 400, "message": "Validation Failed", "errors":{ "children":{ "name":{ "errors":[ "Please enter shipping category name." ] }, "description": [] } } }

In order to perform a partial update, you should use a PATCH method.

Deﬁnition

PATCH /api/shipping-categories/{id}

Parameter Parameter type Description Authorization header Token received during authentication id url attribute Id of requested resource name request (optional) Name of creating shipping category description request (optional) Description of creating shipping category

Example curl http://sylius.dev/api/shipping-categories/3 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H "Content-Type: application/json" -X PATCH --data '{"name": "Light"}'

3.1. The API Guide 105 Sylius, Release

Example Response

STATUS: 204 No Content

Deleting Shipping Category

Deﬁnition

DELETE /api/shipping-categories/{id}

Parameter Parameter type Description Authorization header Token received during authentication id url attribute Id of requested resource

Example curl http://sylius.dev/api/shipping-categories/3 -H "Authorization: Bearer

˓→MWExMWM0NzE1NmUyZDgyZDJiMjEzMmFlMjQ4MzgwMmE4ZTkxYzM0YjdlN2U2YzliNDIyMTk1ZDhlNDYxYWE4Ng

˓→" -H “Accept: application/json” -X DELETE

Example Response

STATUS: 204 No Content

3.1.11 Payments API

Sylius payment API endpoint is /api/payments.

Index of all payments

You can retrieve the full list payment by making the following request:

GET /api/payments/

Parameters page Number of the page, by default = 1 limit Number of items to display per page criteria[channel] (optional) The channel id criteria[number] (optional) The order number criteria[billingAddress] (optional) First or last name of the customer bill to address

106 Chapter 3. The API Guide Sylius, Release criteria[createdAtFrom] (optional) Starting date criteria[createdAtTo] (optional) End date

Response

STATUS: 200 OK

{ "page":1, "limit":10, "pages":8, "total":80, "_links":{ "self":{ "href":"\/api\/payments\/?page=1" }, "first":{ "href":"\/api\/payments\/?page=1" }, "last":{ "href":"\/api\/payments\/?page=12" }, "next":{ "href":"\/api\/payments\/?page=2" } }, "_embedded":{ "items":[ {"to": "do"} ] } }

Getting a single payment

You can view a single payment by executing the following request:

GET /api/payments/251

Response

STATUS: 200 OK

{"to": "do"}

Deleting a payment

You can delete a payment from the system by making the following DELETE call:

3.1. The API Guide 107 Sylius, Release

DELETE /api/payments/99

Response

STATUS: 204 NO CONTENT

3.1.12 Promotions API

Sylius promotion API endpoint is /api/promotions.

Index of all promotions

You can retrieve the full list of promotionns by making the following request:

GET /api/promotions

Parameters page Number of the page, by default = 1 limit Number of items to display per page

Response

STATUS: 200 OK

{ "page":1, "limit":10, "pages":1, "total":3, "_links":{ "self":{ "href":"\/api\/promotions\/?page=1" }, "first":{ "href":"\/api\/promotions\/?page=1" }, "last":{ "href":"\/api\/promotions\/?page=12" }, "next":{ "href":"\/api\/promotions\/?page=2" } }, "_embedded":{ "items":[ { "_links":{

108 Chapter 3. The API Guide Sylius, Release

"coupons":{ "href": "/app_dev.php/api/promotions/1/coupons/" }, "self":{ "href": "/app_dev.php/api/promotions/1" } }, "actions":[ { "configuration":{ "amount": 500 }, "id":1, "type": "fixed_discount" } ], "coupon_based": false, "created_at": "2014-12-03T09:54:28+0000", "exclusive": false, "id":1, "name": "New Year", "priority":0, "rules":[ { "configuration":{ "count":3 }, "id":1, "type": "item_count" } ], "updated_at": "2014-12-03T09:54:28+0000", "used":0 } ] } }

Getting a single promotion

You can view a single promotion by executing the following request:

GET /api/promotions/1

Response

STATUS: 200 OK

{ "_links":{ "coupons":{ "href": "/app_dev.php/api/promotions/1/coupons/" }, "self":{

3.1. The API Guide 109 Sylius, Release

"href": "/app_dev.php/api/promotions/1" } }, "actions":[ { "configuration":{ "amount": 500 }, "id":1, "type": "fixed_discount" } ], "coupon_based": false, "created_at": "2014-12-03T09:54:28+0000", "exclusive": false, "id":1, "name": "New Year", "priority":0, "rules":[ { "configuration":{ "count":3 }, "id":1, "type": "item_count" } ], "updated_at": "2014-12-03T09:54:28+0000", "used":0 }

Deleting a promotion

You can delete a promotion from the system by making the following DELETE call:

DELETE /api/promotions/1

Response

STATUS: 204 NO CONTENT

Listing all coupons

You can get the coupons associated with given promotion by performing the following request:

GET /api/promotions/1/coupons

Parameters page Number of the page, by default = 1 limit Number of items to display per page

110 Chapter 3. The API Guide Sylius, Release

Response

STATUS: 200 OK

{ "_embedded":{ "items":[ { "_links":{ "promotion":{ "href": "/api/promotions/1" }, "self":{ "href": "/api/promotions/1/coupons/1" } }, "code": "XAETWESF", "id":1, "usage_limit":1, "used":0 } ] }, "_links":{ "first":{ "href": "/api/promotions/1/coupons/?page=1&limit=10" }, "last":{ "href": "/api/promotions/1/coupons/?page=1&limit=10" }, "self":{ "href": "/api/promotions/1/coupons/?page=1&limit=10" } }, "limit": 10, "page":1, "pages":1, "total":1 }

Adding new coupon

To create a new coupon for given promotion, you can execute the following request:

POST /api/promotion/1/coupons/

Parameters code Coupon code usageLimit The number of times that coupon can be used

3.1. The API Guide 111 Sylius, Release

Response

STATUS: 201 CREATED

{ "_links":{ "promotion":{ "href": "/api/promotions/1" }, "self":{ "href": "/api/promotions/1/coupons/2" } }, "code": "SUPER-AWESOME-SALE", "id":1, "usage_limit":3, "used":0 }

• Introduction to Sylius REST API • Authorization • Channels API • Orders API • Checkouts API • Products API • Users API • Customers API • Shipments API • Payments API • Promotions API • Introduction to Sylius REST API • Authorization • Channels API • Orders API • Checkouts API • Products API • Users API • Customers API • Shipments API • Payments API • Promotions API

112 Chapter 3. The API Guide CHAPTER 4

Cookbook

Speciﬁc solutions for speciﬁc needs.

4.1 Cookbook

4.1.1 Using the Installer commands

Sylius platform ships with the sylius:install command, which takes care of creating the database, schema, dumping the assets and basic store conﬁguration. This command actually uses several other commands behind the scenes and each of those is available for you:

Checking system requirements

You can quickly check all your system requirements and possible recommendations by calling the following command:

$ php app/console sylius:install:check-requirements

Database conﬁguration

Sylius can create or even reset the database/schema for you, simply call:

$ php app/console sylius:install:database

The command will check if your database schema exists. If yes, you may decide to recreate it from scratch, otherwise Sylius will take care of this automatically. It also allows you to load sample data.

Loading sample data

You can load sample data by calling the following command:

$ php app/console sylius:install:sample-data

113 Sylius, Release

Basic store conﬁguration

To conﬁgure your store, use this command and answer all questions:

$ php app/console sylius:install:setup

Installing assets and dumping Assetic

You can reinstall all web assets by simply calling:

$ php app/console sylius:install:assets

4.1.2 Using the registry in your bundle

We will to show you how to set up the sylius registry. In this example, we will register two price calculators.

˓→App\Component\Registry\ServiceRegistry

˓→App\Bundle\MyBundle\PriceCalculatorInterface

%app.price.calculator.interface%

namespace App\Bundle\MyBundle\DependencyInjection\Compiler; class RegisterCalculatorServicePass implements CompilerPassInterface { public function process(ContainerBuilder $container) { // You can check if your registry is defined if (!$container->hasDefinition('app.price.calculator.registry')) { return;

114 Chapter 4. Cookbook Sylius, Release

}

$registryDefinition= $container->getDefinition('app.price.calculator.registry

˓→');

// You can register your services like this $registryDefinition->addMethodCall( 'register', array( 'default', new Reference('app.price.calculator.default'), ) );

$registryDefinition->addMethodCall( 'register', array( 'custom', new Reference('app.price.calculator.default'), ) ); } }

Finally, you need to register your custom pass with the container namespace App\Bundle\MyBundle; use App\Bundle\MyBundle\DependencyInjection\Compiler\RegisterCalculatorServicePass; class AppMyBundleBundle extends Bundle { public function build(ContainerBuilder $container) { parent::build($container);

$container->addCompilerPass(new RegisterCalculatorServicePass()); } }

• Using the Installer commands • Using the registry in your bundle • Using the Installer commands • Using the registry in your bundle

4.1. Cookbook 115 Sylius, Release

116 Chapter 4. Cookbook CHAPTER 5

The Behat Guide

Learn how to write clean and reusable features, contexts and pages.

5.1 Behat guide

5.1.1 How to add a new context?

To add a new context it is needed to add an service in Behat container in etc/behat/services/contexts.xml ﬁle:

Then you can use it in your suite conﬁguration: default: suites: SUITE_NAME: contexts_as_services: -"sylius.behat.context.CONTEXT_CATEGORY.CONTEXT_NAME"

filters: tags:"@SUITE_TAG"

Note: The context categories are usually one of hook, setup, ui and domain.

5.1.2 How to add a new page object?

Sylius uses a solution inspired by SensioLabs/PageObjectExtension, which provides an infrastructure to create pages that encapsulates all the user interface manipulation in page objects. To create a new page object it is needed to add an service in Behat container in etc/behat/services/pages.xml ﬁle:

˓→parent="sylius.behat.symfony_page" scope="scenario" public="false" />

117 Sylius, Release

Note: There are some boilerplates for common pages, which you may use. The available par- ents are sylius.behat.page (Sylius\Behat\Page\Page) and sylius.behat.symfony_page (Sylius\Behat\Page\SymfonyPage). It is not required for a page to extend any class as pages are POPOs (Plain Old PHP Objects).

Then you will need to add that service as a regular argument in context service. The simplest Symfony-based page looks like:

use Sylius\Behat\Page\SymfonyPage;

class LoginPage extends SymfonyPage { public function logIn($email, $password) { $document= $this->getDocument();

$document->fillField('Email', $email); $document->fillField('Password', $password);

$document->pressButton('Login'); }

protected function getRouteName() { return 'sylius_user_security_login'; } }

5.1.3 How to deﬁne a new suite?

To define a new suite it is needed to create a suite configuration file in etc/behat/suites directory based on existing files in there and then register that file in etc/behat/suites.yml.

5.1.4 How to use transformers?

Behat provides many awesome features, and one of them are deﬁnitely transformers. They can be used to transform (usually widely used) parts of steps and return some values from them, to prevent unnecessary duplication in many steps’ deﬁnitions.

Basic transformer

Example is always the best way to clarify, so let’s look at this:

/** * @Transform :shippingMethodName shipping method * @Transform shipping method :shippingMethodName */ public function getShippingMethodByName($shippingMethodName) { $shippingMethod= $this->shippingMethodRepository->findOneByName(

˓→$shippingMethodName);

118 Chapter 5. The Behat Guide Sylius, Release

if (null === $shippingMethod){ throw new \Exception('Shipping method with name "'.$shippingMethodName.'"

˓→does not exist'); }

return $shippingMethod; }

This transformer is used to return ShippingMethod object from proper repository using it’s name. It also throws exception if such a method does not exist. It can be used in plenty of steps, that have shipping method name in it. But how to use it? It is as simple as that:

/** * @Given /^(shipping method "[^"]+") belongs to ("[^"]+" tax category)$/ */ public function shippingMethodBelongsToTaxCategory( ShippingMethodInterface $shippingMethod, TaxCategoryInterface $taxCategory ){ // some logic here }

If part of step matches transformer deﬁnition, it should be surrounded by parenthesis to be handled as whole expression. That’s it! As it is shown in the example, many transformers can be used in the same step deﬁnition.

Note: Transformer deﬁnition does not have to be implemented in the same context, where it is used. It allows to share them between many different contexts.

Transformers implemented in Sylius

Speciﬁed

There are plenty of transformers already implemented in Sylius. Most of them, are returns specific resources from theirs repository, for example: • tax category "Fruits" -> find tax category in their repository with name “Fruits” • "Chinese banana" variant of product "Banana" -> find variant of specific product etc. You’re free to use them in your own behat scenarios.

Note: All transformers deﬁnitions are currently kept in Sylius\Behat\Context\Transform namespace.

Warning: Remember to include contexts with transformers in custom suite to be able to use them!

Generic

Moreover, there are also some more generic transformers, that could be useful in many different cases. They are now placed in two contexts: LexicalContext and SharedStorageContext. What are they so awesome? Let’s describe them one by one:

5.1. Behat guide 119 Sylius, Release

LexicalContext • @Transform /^"(?:C|£|\$)((?:\d+\.)?\d+)"$/ -> tricky transformer used to parse price string with currency into integer (used to represent price in Sylius). It is used in steps like this promotion gives "C30.00" fixed discount to every order • @Transform /^"((?:\d+\.)?\d+)%"$/ -> similar one, transforming percentage string into ﬂoat (example: this promotion gives "10%" percentage discount to every order) SharedStorageContext

Note: SharedStorage is kind of container used to keep objects, which can be shared between steps. It can be used, for example, to keep newly created promotion, to use its name in checking existence step.

• @Transform /^(it|its|theirs)$/ -> amazingly useful transformer, that returns last resource saved in SharedStorage. It allows to simplify many steps used after creation/update (and so on) actions. Example: instead of writing When I create "Wade Wilson" customer/Then customer "Wade Wilson" should be registered just write When I create "Wade Wilson" customer/Then it should be registered • @Transform /^(?:this|that|the) ([^"]+)$/ -> similar to previous one, but returns resource saved with speciﬁc key, for example this promotion will return resource saved with promotion key in SharedStorage

5.1.5 Introduction to containers and scopes

In order to provide support for defining contexts and pages in Behat container with dependencies from Symfony application container, our service definitions may contain some extra features. There are 3 available containers: • behat (the default one) - the container which holds all Behat services, its extensions services, our contexts, pages and helper services used by them • symfony - the container which holds all the services defined in the application, the services retrieved from this container are isolated between scenarios, belongs to scenario scope • symfony_shared - the container which holds all the services defined in the application, created only once, the services retrieved from this container are not isolated between scenarios There is one additional scope, scenario, which ensures, that no service shared through entire Behat execution uses the one that is only available in specific scenario. Every service retrieved from symfony container has this scope. Usually, most of contexts and pages are defined in scenario scope as it’s the most safe decision. You would need a really got reason not to follow this convention. Right now, you can only inject services from foreign containers into the default containers. To do so, use container option within argument element:

120 Chapter 5. The Behat Guide Sylius, Release

5.1.6 Basic Usage

The best way of understanding how things work in detail is showing and analyzing examples, that is why this section gathers all the knowledge from the previous chapters. Let’s assume that we are going to implement the functionality of managing countries in our system. Now let us show you the ﬂow.

Describing features

Let’s start with writing our feature ﬁle, which will contain answers to the most important questions: Why (beneﬁt), who (actor using the feature) and what (the feature itself). It should also include scenarios, which serve as examples of how things supposed to work. features/addressing/managing_countries/adding_country.feature Scenario:

@managing_countries Feature: Adding a new country In order to sell my goods to different countries As an Administrator I want to add a new country to the store

Background: Given I am logged in as an administrator

@ui Scenario: Adding country Given I want to add a new country When I choose"France" And I add it Then I should be notified that it has been successfully created And the country"France" should appear in the store

Pay attention to the form of these sentences. From the developer point of view they are hiding the details of the feature’s implementation. Instead of describing “When I click on the select box And I choose France from the dropdown Then I should see the France country in the table” - we are using sentences that are less connected with the implementation, but more focused on the effects of our actions. A side effect of such approach is that it results in steps being really generic, therefore if we want to add another way of testing this feature for instance in the domain or api context, it will be extremely easy to apply. We just need to add a different tag (in this case “@domain”) and of course implement the proper steps in the domain context of our system. To be more descriptive let’s imagine that we want to check if a country is added properly in two ways. First we are checking if the adding works via frontend, so we are implementing steps that are clicking, opening pages, ﬁlling ﬁelds on forms and similar, but also we want to check this action regardlessly of the frontend, for that we need the domain, which allows us to perform actions only on objects.

Choosing a correct suite

After we are done with a feature ﬁle, we have to create a new suite for it. At the beginning we have decided that it will be a frontend/user interface feature, that is why we are placing it in “etc/behat/suites/ui/addressing/managing_countries.yml”. default: suites: ui_managing_countries: contexts_as_services: - sylius.behat.context.hook.doctrine_orm # This service is responsible for clearing database before each

˓→scenario, # so that only data from the current and its background is available.

5.1. Behat guide 121 Sylius, Release

- sylius.behat.context.transform.country - sylius.behat.context.transform.shared_storage # The transformer contexts services are responsible for all the

˓→transformations of data in steps: # For instance "And the country "France" should appear in the store"

˓→transforms "(the country "France")" to a proper Country object, which is from now

˓→on available in the scope of the step.

- sylius.behat.context.setup.geographical - sylius.behat.context.setup.security # The setup contexts here are preparing the background, adding

˓→available countries and users or administrators. # These contexts have steps like "I am logged in as an administrator"

˓→already implemented.

# Lights, Camera, Action! - sylius.behat.context.ui.admin.managing_countries - sylius.behat.context.ui.admin.notification # Those contexts are essential here we are placing all action steps

˓→like "When I choose "France" and I add it Then I should ne notified that...". filters: tags:"@managing_countries&& @ui"

A very important thing that is done here is the conﬁguration of tags, from now on Behat will be searching for all your features tagged with @managing_countries and your scenarios tagged with @ui. Second thing is contexts_as_services: in this section we will be placing all our services with step implementation. We have mentioned with the generic steps we can easily switch our testing context to @domain. Have a look how it looks: default: suites: domain_managing_countries: contexts_as_services: - sylius.behat.context.hook.doctrine_orm

- sylius.behat.context.transform.country - sylius.behat.context.transform.shared_storage

- sylius.behat.context.setup.geographical - sylius.behat.context.setup.security

- sylius.behat.context.domain.admin.managing_countries # Domain step

˓→implementation. filters: tags:"@managing_countries&& @domain"

We are almost finished with the suite configuration. Now we need to register our first Behat context as a service, but beforehand we need

Registering Pages

The page object approach allows us to hide all the detailed interaction with ui (html, javascript, css) inside. We have three kinds of pages:

122 Chapter 5. The Behat Guide Sylius, Release

• Page - First layer of our pages it knows how to interact with DOM objects. It has a method ->getUrl(array $urlParameters) where you can deﬁne a raw url to open it. • SymfonyPage - This page extends the Page. It has a router injected so that the ->getUrl() method generates a url from the route name which it gets from the ->getRouteName() method. • Base Crud Pages (IndexPage, CreatePage, UpdatePage) - These pages extend SymfonyPage and they are speciﬁc to the Sylius resources. They have a resource name injected and therefore they know about the route name. There are two ways to manipulate UI - by using ->getDocument() or ->getElement('your_element'). First method will return a DocumentElement which represents an html structure of the currently opened page, second one is a bit more tricky because it uses the ->getDefinedElements() method and it will return a NodeElement which represents only the restricted html structure. Usage example of ->getElement('your_element') and ->getDefinedElements methods.

class CreatePage extends SymfonyPage implements CreatePageInterface { // This method returns a simple associative array, where the key is the name of

˓→your element and the value is its locator. protected function getDefinedElements() { return array_merge(parent::getDefinedElements(), [ 'provinces' => '#sylius_country_provinces', ]); }

// By default it will assume that your locator is css. // Example with xpath. protected function getDefinedElements() { return array_merge(parent::getDefinedElements(), [ 'provinces' =>['xpath' => '// *[contains(@class, "provinces")]'] // Now ˓→your value is an array where key is your locator type. ]); }

// Like that you can easily manipulate your page elements. public function addProvince(ProvinceInterface $province) { $provinceSelectBox= $this->getElement('provinces');

$provinceSelectBox->selectOption($province->getName()); } }

Let’s get back to our main example and analyze our scenario. We have steps like “When I choose “France” And I add it Then I should be notiﬁed that it has been successfully created And the country “France” should appear in the store”.

namespace Sylius\Behat\Page\Admin\Country;

use Sylius\Behat\Page\Admin\Crud\CreatePage as BaseCreatePage; class CreatePage extends BaseCreatePage implements CreatePageInterface

5.1. Behat guide 123 Sylius, Release

{ /** * @param string $name */ public function chooseName($name) { $this->getDocument()->selectFieldOption('Name', $name); }

public function create() { $this->getDocument()->pressButton('Create'); } }

tableAccessor->getRowsWithFields($this->getElement('table

˓→'), $parameters); // Table accessor is a helper service which is responsible for all html

˓→table operations.

return 1 === count($rows); } catch (ElementNotFoundException $exception){ // Table accessor throws this

˓→exception when cannot find table element on page. return false; } } }

Warning: There is one small gap in this concept - PageObjects is not a concrete instance of the currently opened page, they only mimic its behaviour (dummy pages). This gap will be more understandable on the below code example.

// Of course this is only to illustrate this gap. class HomePage { // In this context on home page sidebar you have for example weather information

˓→in selected countries. public function readWeather()

124 Chapter 5. The Behat Guide Sylius, Release

{ return $this->getElement('sidebar')->getText(); }

protected function getDefinedElements() { return ['sidebar' =>['css' => '.sidebar']] }

protected function getUrl() { return 'http://your_domain.com'; } } class LeagueIndexPage { // In this context you have for example football match results. public function readMatchResults() { return $this->getElement('sidebar')->getText(); }

protected function getDefinedElements() { return ['sidebar' =>['css' => '.sidebar']] }

protected function getUrl() { return 'http://your_domain.com/leagues/' } } final class GapContext implements Context { private $homePage; private $leagueIndexPage;

/** * @Given I want to be on Homepage */ public function iWantToBeOnHomePage() // After this method call we will be on

˓→"http://your_domain.com". { $this->homePage->open(); //When we add @javascript tag we can actually see

˓→this thanks to selenium. }

/** * @Then I want to see the sidebar and get information about the weather in France */ public function iWantToReadSideBarOnHomePage($someInformation) // Still "http://

˓→your_domain.com". { $someInformation === $this->leagueIndexPage->readMatchResults() // This

˓→returns true, but wait a second we are on home page (dummy pages).

5.1. Behat guide 125 Sylius, Release

$someInformation === $this->homePage->readWeather() // This also returns true. } }

Registering contexts

As it was shown in the previous section we have registered a lot of contexts, so we will show you only some of the steps implementation. Scenario:

Given I want to add a new country And I add it Then I should be notified that it has been successfully created And the country"France" should appear in the store

Let’s start with essential one ManagingCountriesContext

Ui contexts

/** * @var CreatePageInterface */ private $createPage;

/** * @var UpdatePageInterface */ private $updatePage;

/** * @param IndexPageInterface $indexPage * @param CreatePageInterface $createPage * @param UpdatePageInterface $updatePage */ public function __construct( IndexPageInterface $indexPage, CreatePageInterface $createPage, UpdatePageInterface $updatePage ){ $this->indexPage= $indexPage; $this->createPage= $createPage; $this->updatePage= $updatePage; }

126 Chapter 5. The Behat Guide Sylius, Release

/** * @Given I want to add a new country */ public function iWantToAddNewCountry() { $this->createPage->open(); // This method will send request. }

/** * @When I choose :countryName */ public function iChoose($countryName) { $this->createPage->chooseName($countryName); // Great benefit of using page objects is that we hide html manipulation

˓→behind a interfaces so we can inject different CreatePage which implements

˓→CreatePageInterface // And have different html elements which allows for example chooseName(

˓→$countryName). }

/** * @When I add it */ public function iAddIt() { $this->createPage->create(); }

/** * @Then /^the (country "([^"]+)") should appear in the store$/ */ public function countryShouldAppearInTheStore(CountryInterface $country) // This

˓→step use Country transformer to get Country object. { $this->indexPage->open();

//Webmozart assert library. Assert::true( $this->indexPage->isSingleResourceOnPage(['code' => $country->getCode()]), sprintf('Country %s should exist but it does not', $country->getCode()) ); } }

5.1. Behat guide 127 Sylius, Release

/** * @param NotificationCheckerInterface $notificationChecker */ public function __construct(NotificationCheckerInterface $notificationChecker) { $this->notificationChecker= $notificationChecker; }

/** * @Then I should be notified that it has been successfully created */ public function iShouldBeNotifiedItHasBeenSuccessfullyCreated() { $this->notificationChecker->checkNotification('has been successfully created.

˓→', NotificationType::success()); } }

Transformer contexts

/** * @var RepositoryInterface */ private $countryRepository;

/** * @param CountryNameConverterInterface $countryNameConverter * @param RepositoryInterface $countryRepository */ public function __construct( CountryNameConverterInterface $countryNameConverter, RepositoryInterface $countryRepository ){ $this->countryNameConverter= $countryNameConverter; $this->countryRepository= $countryRepository; }

/** * @Transform /^country "([^"]+)"$/ * @Transform /^"([^"]+)" country$/ */ public function getCountryByName($countryName) // Thanks to this method we got in

˓→our ManagingCountries an Country object. { $countryCode= $this->countryNameConverter->convertToCode($countryName);

128 Chapter 5. The Behat Guide Sylius, Release

$country= $this->countryRepository->findOneBy(['code' => $countryCode]);

Assert::notNull( $country, 'Country with name %s does not exist' );

return $country; } }

/** * @param UpdatePageInterface $updatePage */ public function __construct(UpdatePageInterface $updatePage) { $this->updatePage= $updatePage; }

/** * @Given /^I want to create a new province in (country "[^"]+")$/ */ public function iWantToCreateANewProvinceInCountry(CountryInterface $country) { $this->updatePage->open(['id' => $country->getId()]);

$this->updatePage->clickAddProvinceButton(); } }

/** * @param ShippingMethodRepositoryInterface $shippingMethodRepository */

5.1. Behat guide 129 Sylius, Release

public function __construct(ShippingMethodRepositoryInterface

˓→$shippingMethodRepository) { $this->shippingMethodRepository= $shippingMethodRepository; }

/** * @Transform :shippingMethod */ public function getShippingMethodByName($shippingMethodName) { $shippingMethod= $this->shippingMethodRepository->findOneByName(

˓→$shippingMethodName); if (null === $shippingMethod){ throw new \Exception('Shipping method with name "'.$shippingMethodName.'"

˓→does not exist'); }

return $shippingMethod; } }

/** * @param UpdatePageInterface $updatePage */ public function __construct(UpdatePageInterface $updatePage) { $this->updatePage= $updatePage; }

/** * @Given I want to modify a shipping method :shippingMethod */ public function iWantToModifyAShippingMethod(ShippingMethodInterface

˓→$shippingMethod) { $this->updatePage->open(['id' => $shippingMethod->getId()]); } }

Warning: Contexts should have single responsibility and this segregation (Setup, Transformer, Ui, etc...) is not accidental. We shouldn’t create objects in transformer contexts.

130 Chapter 5. The Behat Guide Sylius, Release

Setup contexts

For setup context we need different scenario with more background steps and all preparing scene steps. Editing scenario will be great for this example: Scenario:

Given the store has disabled country"France" And I want to edit this country When I enable it And I save my changes Then I should be notified that it has been successfully edited And this country should be enabled

/** * @var FactoryInterface */ private $countryFactory;

/** * @var RepositoryInterface */ private $countryRepository;

/** * @var CountryNameConverterInterface */ private $countryNameConverter;

/** * @param SharedStorageInterface $sharedStorage * @param FactoryInterface $countryFactory * @param RepositoryInterface $countryRepository * @param CountryNameConverterInterface $countryNameConverter */ public function __construct( SharedStorageInterface $sharedStorage, FactoryInterface $countryFactory, RepositoryInterface $countryRepository, CountryNameConverterInterface $countryNameConverter ){ $this->sharedStorage= $sharedStorage; $this->countryFactory= $countryFactory; $this->countryRepository= $countryRepository; $this->countryNameConverter= $countryNameConverter; }

5.1. Behat guide 131 Sylius, Release

/** * @Given /^the store has disabled country "([^"]*)"$/ */ public function theStoreHasDisabledCountry($countryName) // This method save

˓→country in data base. { $country= $this->createCountryNamed(trim($countryName)); $country->disable();

$this->sharedStorage->set('country', $country); // Shared storage is an helper service for transferring objects between steps. // There is also SharedStorageContext which use this helper service to

˓→transform sentences like "(this country), (it), (its), (theirs)" into Country

˓→Object.

$this->countryRepository->add($country); }

/** * @param string $name * * @return CountryInterface */ private function createCountryNamed($name) { /** @var CountryInterface $country */ $country= $this->countryFactory->createNew(); $country->setCode($this->countryNameConverter->convertToCode($name));

return $country; } }

• How to add a new context? • How to add a new page object? • How to deﬁne a new suite? • How to use transformers? • Introduction to containers and scopes • Basic Usage • How to add a new context? • How to add a new page object? • How to deﬁne a new suite? • How to use transformers? • Introduction to containers and scopes • Basic Usage

132 Chapter 5. The Behat Guide CHAPTER 6

Bundles

Documentation of all Sylius bundles.

6.1 Symfony2 Bundles

6.1.1 Bundles General Guide

All Sylius bundles share the same architecture and this guide will introduce you these conventions. You’ll learn how to perform basic CRUD operations on the data and how to override models, controllers, repositories, validation mapping and forms.

Performing basic CRUD operations

Sylius is using the Doctrine Common persistence interfaces. This means that every model within Sylius bundles has its own repository and object manager. Some interfaces extend the Timestampable interface. This interface is deﬁned in the SyliusResourceBundle to not create a dependency on Doctrine ORM. They are however compatible with the GedmoDoctrineExtensions when using Doctrine ORM.

Retrieving resources

Retrieving any resource from database always happens via the repository, which implements Sylius\Bundle\ResourceBundle\Model\RepositoryInterface. If you have been using Doc- trine, you should already be familiar with this concept, as it extends the default Doctrine ObjectRepository interface. Let’s assume you want to load a product from database. Your product repository is always accessible via the sylius.repository.product service.

container->get('sylius.repository.product'); }

Retrieving many resources is as simple as calling the proper methods on the repository.

133 Sylius, Release

container->get('sylius.repository.product');

$product= $repository->find(4); // Get product with id 4, returns null if not

˓→found. $product= $repository->findOneBy( array('slug' => 'my-super-product')); // Get

˓→one product by defined criteria.

$products= $repository->findAll(); // Load all the products! $products= $repository->findBy( array('special' => true)); // Find products

˓→matching some custom criteria. }

Every Sylius repository supports paginating products. To create a Pagerfanta instance use the createPaginator method.

container->get('sylius.repository.product');

$products= $repository->createPaginator(); $products->setMaxPerPage(3); $products->setCurrentPage($request->query->get('page',1));

// Now you can returns products to template and iterate over it to get products

˓→from current page. }

Paginator can be created for a speciﬁc criteria and with desired sorting.

container->get('sylius.repository.product');

$products= $repository->createPaginator( array('foo' => true), array('createdAt'

˓→=> 'desc')); $products->setMaxPerPage(3); $products->setCurrentPage($request->query->get('page',1)); }

Creating a new resource object

To create a new resource instance, you can simply call the createNew() method on the repository. Now let’s try something else than product, we’ll create a new TaxRate model.

134 Chapter 6. Bundles Sylius, Release

{ $repository= $this->container->get('sylius.repository.tax_rate'); $taxRate= $repository->createNew(); }

Note: Creating resources via this factory method makes the code more testable, and allows you to change the model class easily.

Saving and removing resources

To save or remove a resource, you can use any ObjectManager which is capable of managing the class. Every model has its own manager alias, for example the sylius.manager.address is an alias to the ORM EntityMan- ager. Of course, it is also perfectly ﬁne if you use the doctrine.orm.entity_manager service name or any other appropriate manager service.

container->get('sylius.repository.address'); $manager= $this->container->get('sylius.manager.address'); // Alias to the

˓→appropriate doctrine manager service.

$address= $repository->createNew();

$address ->setFirstname('John') ->setLastname('Doe') ;

$manager->persist($address); $manager->flush(); // Save changes in database. }

To remove a resource, you also use the manager.

container->get('sylius.repository.shipping_method'); $manager= $this->container->get('sylius.manager.shipping_method');

$shippingMethod= $repository->findOneBy( array('name' => 'DHL Express'));

$manager->remove($shippingMethod); $manager->flush(); // Save changes in database. }

6.1. Symfony2 Bundles 135 Sylius, Release

Overriding Models

...

Extending base Models

All Sylius models live in Sylius\Component\Xyz\Model namespace together with the interfaces. As an example, for Sylius Taxation Component it’s TaxCategory and TaxRate. Let’s assume you want to add “zone” ﬁeld to the Sylius tax rates. Firstly, you need to create your own TaxRate class, which will extend the base model. namespace Acme\Bundle\ShopBundle\Entity; use Sylius\Component\Addressing\Model\ZoneInterface; use Sylius\Component\Taxation\Model\TaxRate as BaseTaxRate; class TaxRate extends BaseTaxRate { private $zone;

public function getZone() { return $this->zone; }

public function setZone(ZoneInterface $zone) { $this->zone= $zone;

return $this; } }

Secondly, deﬁne the entity mapping inside Resources/config/doctrine/TaxRate.orm.xml of your bundle.

˓→"Sylius\Component\Addressing\Model\ZoneInterface">

˓→>

Finally, you conﬁgure your class in app/config/config.yml ﬁle.

136 Chapter 6. Bundles Sylius, Release

sylius_taxation: driver: doctrine/orm classes: tax_rate: model: Acme\ShopBundle\Entity\TaxRate # Your tax rate entity.

Done! Sylius will now use your TaxRate model! What has happened? • Parameter sylius.model.tax_rate.class contains Acme\\Bundle\\ShopBundle\\Entity\\TaxRate. • sylius.repository.tax_rate represents Doctrine repository for your new class. • sylius.manager.tax_rate represents Doctrine object manager for your new class. • sylius.controller.tax_rate represents the controller for your new class. • All Doctrine relations to Sylius\\Component\\Taxation\\Model\\TaxRateInterface are using your new class as target-entity, you do not need to update any mappings. • TaxRateType form type is using your model as data_class. • Sylius\\Component\\Taxation\\Model\\TaxRate is automatically turned into Doctrine Mapped Superclass.

Overriding Controllers

All Sylius bundles are using SyliusResourceBundle as a foundation for database storage.

Extending base Controller

If you want to modify the controller or add your custom actions, you can do so by deﬁning a new controller class. By extending resource controller, you also get access to several handy methods. Let’s add to our custom controller a new method to recommend a product:

// src/Acme/ShopBundle/Controller/ProductController.php

namespace Acme\ShopBundle\Controller;

use Sylius\Bundle\ResourceBundle\Controller\ResourceController; use Symfony\Component\HttpFoundation\Request;

class ProductController extends ResourceController { public function recommendAction(Request $request, $id) { $product= $this->findOr404( array('id' => $id)); // Find product with given

˓→id or return 404! $product->incrementRecommendations(); // Add +1!

$this->persistAndFlush($product); // Save product.

return $this->redirect($this->generateUrl('acme_shop_homepage')); } }

6.1. Symfony2 Bundles 137 Sylius, Release

You also need to conﬁgure your controller class in app/config/config.yml.

# app/config/config.yml sylius_product: driver: doctrine/orm classes: product: controller: Acme\ShopBundle\Controller\ProductController

That’s it! Now sylius.controller.product:recommendAction is available. You can use it by deﬁning a new route.

# app/config/routing.yml acme_shop_product_recommend: path: /products/{id}/recommend defaults: _controller: sylius.controller.product:recommendAction

What has happened? • Parameter sylius.controller.product.class contains Acme\\Bundle\\ShopBundle\\Controller\\ProductController. • Controller service sylius.controller.product is using your new controller class.

Overriding Repositories

Overriding a Sylius model repository involves extending the base class and conﬁguring it inside the bundle conﬁgura- tion.

Extending base Repository

Sylius is using both custom and default Doctrine repositories and often you’ll need to add your own methods. Let’s assume you want to ﬁnd all orders for a given customer. Firstly, you need to create your own repository class

// src/Acme/ShopBundle/Repository/OrderRepository.php namespace Acme\ShopBundle\Repository; use Sylius\Bundle\ResourceBundle\Doctrine\ORM\EntityRepository; class OrderRepository extends EntityRepository { public function findByCustomer(Customer $customer) { return $this ->createQueryBuilder('o') ->join('o.billingAddress', 'billingAddress') ->join('o.shippingAddress', 'shippingAddress') ->join('o.customer', 'customer') ->where('o.customer = :customer') ->setParameter('customer', $customer)

138 Chapter 6. Bundles Sylius, Release

->getQuery() ->getResult() ; } }

Secondly, need to conﬁgure your repository class in app/config/config.yml.

# app/config/config.yml sylius_order: driver: doctrine/orm classes: order: repository: Acme\ShopBundle\Repository\OrderRepository

That’s it! Now sylius.repository.order is using your new class.

container->get('sylius.repository.order');

$orders= $repository->findByCustomer($customer); }

What has happened? • Parameter sylius.repository.order.class contains Acme\\ShopBundle\\Repository\\OrderRepository. • Repository service sylius.repository.order is using your new class.

Overriding Validation

All Sylius validation mappings and forms are using sylius as the default group.

Changing the validation group

You can conﬁgure your own validation for Sylius models. If the defaults do not ﬁt your needs, create validation.xml inside your bundle.

6.1. Symfony2 Bundles 139 Sylius, Release

You also need to conﬁgure the new validation group in app/config/config.yml. sylius_taxation: driver: doctrine/orm # Configure the doctrine orm driver used in documentation. validation_groups: tax_category: [acme]

Done! Now all Sylius forms will use acme validation group on all forms of tax category.

Overriding Forms

Every form type in Sylius holds its class name in a speciﬁc parameter. This allows you to easily add or remove ﬁelds by extending the base form class.

Extending base Forms

All Sylius form types live in Sylius\Bundle\XyzBundle\Form\Type namespace. Let’s assume you want to add “phone” and remove “company” ﬁelds to the Sylius address form. You have to create your own AddressType class, which will extend the base form type. namespace Acme\Bundle\ShopBundle\Form\Type; use Sylius\Bundle\AddressingBundle\Form\Type\AddressType as BaseAddressType; use Symfony\Component\Form\FormBuilderInterface; class AddressType extends BaseAddressType { public function buildForm(FormBuilderInterface $builder, array $options) { parent::buildForm($builder, $options); // Add default fields.

$builder->remove('company'); $builder->add('phone', 'text', array('required' => false)); } }

Now, deﬁne the new form class in the app/config/config.yml.

# app/config/config.yml

140 Chapter 6. Bundles Sylius, Release

sylius_addressing: driver: doctrine/orm classes: address: form: default: Acme\ShopBundle\Form\Type\AddressType

Done! Sylius will now use your custom address form everywhere! What has happened? • Parameter sylius.form.type.address.class contains Acme\\Bundle\\ShopBundle\\Form\\Type\\AddressType. • sylius.form.type.address form type service uses your custom class. • sylius_address form type uses your new form everywhere.

Mapping Relations

All Sylius bundles use the Doctrine RTEL functionality, which allows to map the relations using interfaces, not implementations.

Conﬁguration

In your AppKernel class, please register Sylius bundles before DoctrineBundle. This is important as we use listeners which have to be processed ﬁrst. If you do not register bundles in this order, Doctrine will throw Doctrine\Common\Persistence\Mapping\MappingException exceptions about missing classes.

Using interfaces

When defining relation to Sylius model, use the interface name instead of concrete class. It will be automatically replaced with the configured model, enabling much greater flexibility.

˓→"Sylius\Bundle\TaxationBundle\Model\TaxCategoryInterface">

˓→"true" />

Thanks to this approach, if the TaxCategory model has changed, you do not need to worry about remapping other entities.

6.1. Symfony2 Bundles 141 Sylius, Release

Events

All Sylius bundles are using SyliusResourceBundle, which has some built-in events.

Events reference

Event Description sylius..pre_create Before persist sylius..create After persist sylius..post_create After flush sylius..pre_update Before persist sylius..update After persist sylius..post_update After flush sylius..pre_delete Before remove sylius..delete After remove sylius..post_delete After flush

CRUD events example

Let’s take the Product model as an example. As you should already know, the product controller is represented by the sylius.controller.product service. Several useful events are dispatched during execution of every default action of this controller. When creating a new resource via the createAction method, 3 events occur. First, before the persist() is called on the product, the sylius.product.pre_create event is dispatched. Secondly, just before the database ﬂush is performed, Sylius dispatches the sylius.product.create event. Finally, after the data storage is updated, sylius.product.post_create is triggered. The same set of events is available for the update and delete operations. All the dispatches are using the GenericEvent class and return the Product object by the getSubject method.

Registering a listener

We’ll stay with the Product model and create a listener which updates Solr (search engine) document every time a product is updated.

namespace Acme\ShopBundle\EventListener;

use Symfony\Component\EventDispatcher\GenericEvent;

class SolrListener { // ... Constructor with indexer injection code.

public function onProductUpdate(GenericEvent $event) { $this->indexer->updateProductDocument($event->getSubject()); } }

Now you need to register the listener in services conﬁguration.

142 Chapter 6. Bundles Sylius, Release

˓→"Acme\ShopBundle\EventListener\SolrListener">

˓→method="onProductUpdate" />

Done! Every time a product is edited and the database updated, this listener will also use the indexer to update Solr index accordingly.

6.1.2 SyliusAddressingBundle

This bundle integrates the Addressing into Symfony2 and Doctrine. With minimal conﬁguration you can introduce addresses, countries, provinces and zones management into your project. It’s fully customizable, but the default setup should be optimal for most use cases. It also contains zone matching mechanisms, which allow you to match customer addresses to appropriate tax/shipping (or any other) zones. There are several models inside the bundle, Address, Country, Province, Zone and ZoneMember. There is also a ZoneMatcher service. You’ll get familiar with it in later parts of this documentation.

Installation

We assume you’re familiar with Composer, a dependency manager for PHP. Use following command to add the bundle to your composer.json and download package. If you have Composer installed globally.

$ composer require sylius/addressing-bundle

Otherwise you have to download .phar ﬁle.

$ curl -sS https://getcomposer.org/installer | php $ php composer.phar require sylius/addressing-bundle:*

Adding required bundles to the kernel

You need to enable the bundle inside the kernel. If you’re not using any other Sylius bundles, you will also need to add SyliusResourceBundle and its dependencies to kernel. Don’t worry, everything was automatically installed via Composer.

6.1. Symfony2 Bundles 143 Sylius, Release

// app/AppKernel.php public function registerBundles() { $bundles= array( new FOS\RestBundle\FOSRestBundle(), new JMS\SerializerBundle\JMSSerializerBundle($this), new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(), new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(),

new Sylius\Bundle\TranslationBundle\SyliusTranslationBundle(), new Sylius\Bundle\AddressingBundle\SyliusAddressingBundle(), new Sylius\Bundle\ResourceBundle\SyliusResourceBundle(),

// Other bundles... new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(), ); }

Note: Please register the bundle before DoctrineBundle. This is important as we use listeners which have to be processed ﬁrst.

Container conﬁguration

Put this conﬁguration inside your app/config/config.yml. sylius_addressing: driver: doctrine/orm # Configure the doctrine orm driver used in documentation.

You should also conﬁgure SyliusTranslationBundle, as SyliusAddressingBundle is dependant on it: sylius_translation: driver: doctrine/orm default_locale: en

As well as doctrine extensions which are used in assortment bundle: stof_doctrine_extensions: orm: default: timestampable: true

Routing conﬁguration

Import the routing conﬁguration by adding the following to your app/config/routing.yml. sylius_addressing: resource:"@SyliusAddressingBundle/Resources/config/routing.yml"

144 Chapter 6. Bundles Sylius, Release

Updating database schema

Run the following command.

$ php app/console doctrine:schema:update --force

Warning: This should be done only in dev environment! We recommend using Doctrine migrations, to safely update your schema.

Templates

This bundle provides some default bootstrap templates.

Note: You can check Sylius application to see how to integrate it in your application.

ZoneMatcher

This bundle exposes the ZoneMatcher as sylius.zone_matcher service.

$zoneMatcher= $this->get('sylius.zone_matcher');

$zone= $zoneMatcher->match($user->getBillingAddress());

Forms

The bundle ships with a set of useful form types for all models. You can use the defaults or override them with your own types.

Address form

The address form type is named sylius_address and you can create it whenever you need, using the form factory.

// src/Acme/ShopBundle/Controller/AddressController.php namespace Acme\ShopBundle\Controller; use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\HttpFoundation\Request; class DemoController extends Controller { public function fooAction(Request $request) { $form= $this->get('form.factory')->create('sylius_address');

6.1. Symfony2 Bundles 145 Sylius, Release

} }

You can also embed it into another form.

// src/Acme/ShopBundle/Form/Type/OrderType.php namespace Acme\ShopBundle\Form\Type; use Sylius\Bundle\OrderBundle\Form\Type\OrderType as BaseOrderType; use Symfony\Component\Form\FormBuilderInterface; class OrderType extends BaseOrderType { public function buildForm(FormBuilderInterface $builder, array $options) { parent::buildForm($builder, $options);

$builder ->add('billingAddress', 'sylius_address') ->add('shippingAddress', 'sylius_address') ; } }

Summary

Conﬁguration Reference sylius_addressing: # The driver used for persistence layer. driver: ~ resources: address: classes: model: Sylius\Component\Addressing\Model\Address interface: Sylius\Component\Addressing\Model\Addressinterface controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\AddressingBundle\Form\Type\AddressType validation_groups: default: [ sylius] country: classes: model: Sylius\Component\Addressing\Model\Country interface: Sylius\Component\Addressing\Model\CountryInterface controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\AddressingBundle\Form\Type\CountryType choice: Sylius\Bundle\AddressingBundle\Form\Type\CountryChoiceType

146 Chapter 6. Bundles Sylius, Release

validation_groups: default: [ sylius] province: classes: model: Sylius\Component\Addressing\Model\Province interface: Sylius\Component\Addressing\Model\ProvinceInterface controller:

˓→Sylius\Bundle\AddressingBundle\Controller\ProvinceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\AddressingBundle\Form\Type\ProvinceType choice:

˓→Sylius\Bundle\AddressingBundle\Form\Type\ProvinceChoiceType validation_groups: default: [ sylius] zone: classes: model: Sylius\Component\Addressing\Model\Zone interface: Sylius\Component\Addressing\Model\ZoneInterface controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\AddressingBundle\Form\Type\ZoneType choice: Sylius\Bundle\resourceBundle\Form\type\ResourceChoiceType validation_groups: default: [ sylius] zone_member: classes: model: Sylius\Component\Addressing\Model\ZoneMember interface: Sylius\Component\Addressing\Model\ZoneMemberInterface controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\AddressingBundle\Form\Type\ZoneMemberType validation_groups: default: [ sylius] zone_member_country: classes: model: Sylius\Component\Addressing\Model\ZoneMemberCountry controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\AddressingBundle\Form\Type\ZoneMemberCountryType validation_groups: default: [ sylius] zone_member_province: classes: model: Sylius\Component\Addressing\Model\ZoneMemberProvince controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\AddressingBundle\Form\Type\ZoneMemberProvinceType

6.1. Symfony2 Bundles 147 Sylius, Release

validation_groups: default: [ sylius] zone_member_zone: classes: model: Sylius\Component\Addressing\Model\ZoneMemberZone controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\AddressingBundle\Form\Type\ZoneMemberZoneType validation_groups: default: [ sylius]

Tests

$ composer install $ bin/phpspec run -fpretty --verbose

Bug tracking

This bundle uses GitHub issues. If you have found bug, please create an issue.

6.1.3 SyliusArchetypeBundle

This bundle provides easy integration of the Sylius Archetype component with any Symfony full-stack application. Sylius uses this bundle internally for its product catalog to manage and quickly create products with a predeﬁned set of attributes and options.

Installation

We assume you’re familiar with Composer, a dependency manager for PHP. Use the following command to add the bundle to your composer.json and download the package. If you have Composer installed globally.

$ composer require sylius/archetype-bundle

Otherwise you have to download .phar ﬁle.

$ curl -sS https://getcomposer.org/installer | php $ php composer.phar require sylius/archetype-bundle

Adding required bundles to the kernel

You need to enable the bundle inside the kernel. If you’re not using any other Sylius bundles, you will also need to add SyliusResourceBundle, SyliusAttributeBundle, SyliusVariationBundle and their dependencies to kernel. Don’t worry, everything was automatically installed via Composer.

148 Chapter 6. Bundles Sylius, Release

new Sylius\Bundle\AttributeBundle\SyliusAttributeBundle(), new Sylius\Bundle\VariationBundle\SyliusVariationBundle(), new Sylius\Bundle\ArchetypeBundle\SyliusArchetypeBundle(), new Sylius\Bundle\ResourceBundle\SyliusResourceBundle(),

// Other bundles... new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(), ); }

Note: Please register the bundle before DoctrineBundle. This is important as we use listeners which have to be processed ﬁrst.

Container conﬁguration

Put this conﬁguration inside your app/config/config.yml. sylius_archetype: driver: doctrine/orm # Configure the doctrine orm driver used in the

˓→documentation.

And conﬁgure doctrine extensions which are used by the bundle. stof_doctrine_extensions: orm: default: timestampable: true

Updating database schema

Run the following command.

$ php app/console doctrine:schema:update --force

Warning: This should be done only in dev environment! We recommend using Doctrine migrations, to safely update your schema.

Congratulations! The bundle is now installed and ready to use.

6.1. Symfony2 Bundles 149 Sylius, Release

Conﬁguration reference sylius_archetype: driver: ~ # The driver used for persistence layer. Currently only `doctrine/

˓→orm` is supported. resources: # `subject_name` can be any name, for example `product`, `ad`, or `blog_

˓→post` subject_name: subject: ~ # Required: The subject class implementing

˓→`ArchetypeSubjectInterface`. attribute: Sylius\Component\Attribute\Model\Attribute option: Sylius\Component\Variation\Model\Option archetype: classes: model: Sylius\Component\Archetype\Model\Archetype interface: Sylius\Component\Archetype\Model\ArchetypeInterface controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ # Required: The repository class for the archetype factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\ArchetypeBundle\Form\Type\ArchetypeType validation_groups: default: [ sylius] translation: classes: model:

˓→Sylius\Component\Archetype\Model\ArchetypeTranslation interface:

˓→Sylius\Component\Archetype\Model\ArchetypeTranslationInterface repository: ~ # Required: The repository class for the

˓→archetype translation factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\ArchetypeBundle\Form\Type\ArchetypeTranslationType fields: default: [ name]

6.1.4 SyliusAttributeBundle

This bundle provides easy integration of the Sylius Attribute component with any Symfony full-stack application. Sylius uses this bundle internally for its product catalog to manage the different attributes that are speciﬁc to each product.

Installation

150 Chapter 6. Bundles Sylius, Release

$ composer require sylius/attribute-bundle

Otherwise you have to download .phar ﬁle.

$ curl -sS https://getcomposer.org/installer | php $ php composer.phar require sylius/attribute-bundle

Adding required bundles to the kernel

// Other bundles... new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(), ); }

Note: Please register the bundle before DoctrineBundle. This is important as we use listeners which have to be processed ﬁrst.

Container conﬁguration

Put this conﬁguration inside your app/config/config.yml. sylius_attribute: driver: doctrine/orm # Configure the doctrine orm driver used in the

˓→documentation.

And conﬁgure doctrine extensions which are used by the bundle. stof_doctrine_extensions: orm: default: timestampable: true

6.1. Symfony2 Bundles 151 Sylius, Release

Updating database schema

Run the following command.

$ php app/console doctrine:schema:update --force

Warning: This should be done only in dev environment! We recommend using Doctrine migrations, to safely update your schema.

Congratulations! The bundle is now installed and ready to use.

Conﬁguration reference sylius_attribute: driver: ~ # The driver used for persistence layer. Currently only `doctrine/

˓→orm` is supported. resources: # `subject_name` can be any name, for example `product`, `ad`, or `blog_

˓→post` subject_name: subject: ~ # Required: The subject class implementing

˓→`AttributeSubjectInterface`. attribute: classes: model: Sylius\Component\Attribute\Model\Attribute interface: Sylius\Component\Attribute\Model\AttributeInterface repository:

˓→Sylius\Bundle\TranslationBundle\Doctrine\ORM\TranslatableResourceRepository controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\AttributeBundle\Form\Type\AttributeType choice:

˓→Sylius\Bundle\ResourceBundle\Form\Type\ResourceChoiceType validation_groups: default: [ sylius] translation: classes: model:

˓→Sylius\Component\Attribute\Model\AttributeTranslation interface:

˓→Sylius\Component\Attribute\Model\AttributeTranslationInterface controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ # Required: The repository class for the

˓→attribute translation. factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\AttributeBundle\Form\Type\AttributeTranslationType validation_groups: default: [ sylius]

152 Chapter 6. Bundles Sylius, Release

attribute_value: classes: model: ~ # Required: The model of the attribute value interface: ~ # Required: The interface of the attribute value controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ # Required: The repository class for the

˓→attribute value. factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\AttributeBundle\Form\Type\AttributeValueType validation_groups: default: [ sylius]

6.1.5 SyliusCartBundle

A generic solution for a cart system inside a Symfony2 application. It doesn’t matter if you are starting a new project or you need to implement this feature for an existing system - this bundle should be helpful. Currently only the Doctrine ORM driver is implemented, so we’ll use it here as an example. There are two main models inside the bundle, Cart and CartItem. There are also 2 main services, Provider and ItemResolver. You’ll get familiar with them in further parts of the documentation.

Installation

We assume you’re familiar with Composer, a dependency manager for PHP. Use the following command to add the bundle to your composer.json and download package. If you have Composer installed globally.

$ composer require sylius/cart-bundle

Otherwise you have to download .phar ﬁle.

$ curl -sS https://getcomposer.org/installer | php $ php composer.phar require sylius/cart-bundle

Adding required bundles to the kernel

First, you need to enable the bundle inside the kernel. If you’re not using any other Sylius bundles, you will also need to add the following bundles and their dependencies to the kernel: • SyliusResourceBundle • SyliusMoneyBundle • SyliusOrderBundle Don’t worry, everything was automatically installed via Composer.

6.1. Symfony2 Bundles 153 Sylius, Release

Note: Please register the bundle before DoctrineBundle. This is important as we use listeners which have to be processed ﬁrst. It is generally a good idea to place all of the Sylius bundles at the beginning of the bundles list, as it is done in the Sylius-Standard project.

// app/AppKernel.php

public function registerBundles() { $bundles= array( new Sylius\Bundle\ResourceBundle\SyliusResourceBundle(), new Sylius\Bundle\MoneyBundle\SyliusMoneyBundle(), new Sylius\Bundle\OrderBundle\SyliusOrderBundle(), new Sylius\Bundle\CartBundle\SyliusCartBundle(),

// Other bundles... new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(), new FOS\RestBundle\FOSRestBundle(), new JMS\SerializerBundle\JMSSerializerBundle($this), ); }

Creating your entities

This is no longer a required step in the latest version of the SyliusCartBundle, and if you are happy with the default implementation (which is Sylius\Bundle\CartBundle\Model\CartItem), you can just skip to the next section. You can create your CartItem entity, living inside your application code. We think that keeping the application- speciﬁc and simple bundle structure is a good practice, so let’s assume you have your AppBundle registered under App\AppBundle namespace.

// src/App/AppBundle/Entity/CartItem.php namespace App\AppBundle\Entity;

use Sylius\Component\Cart\Model\CartItem as BaseCartItem;

class CartItem extends BaseCartItem { }

Now we need to define a simple mapping for this entity to map its fields. You should create a mapping file in your AppBundle, put it inside the doctrine mapping directory src/App/AppBundle/Resources/config/doctrine/CartItem.orm.xml.

You do not have to map the ID ﬁeld because it is already mapped in the Sylius\Component\Cart\Model\CartItem class, together with the relation between Cart and Car- tItem. Let’s assume you have a Product entity, which represents your main merchandise within your webshop.

Note: Please remember that you can use anything else, Product here is just an obvious example, but it will work in a similar way with other entities.

We need to modify the CartItem entity and its mapping a bit, so it allows us to put a product inside the cart item.

// src/App/AppBundle/Entity/CartItem.php namespace App\AppBundle\Entity; use Sylius\Component\Cart\Model\CartItem as BaseCartItem; class CartItem extends BaseCartItem { private $product;

public function getProduct() { return $this->product; }

public function setProduct(Product $product) { $this->product= $product; } }

We added a “product” property, and a simple getter and setter. We have to also map the Product to CartItem, let’s create this relation in mapping ﬁles.

6.1. Symfony2 Bundles 155 Sylius, Release

Similarly, you can create a custom entity for orders. The class that you need to extend is Sylius\Component\Cart\Model\Cart. Carts and Orders in Sylius are in fact the same thing. Do not forget to create the mapping ﬁle. But, again, do not put a mapping for the ID ﬁeld — it is already mapped in the parent class. And that would be all about entities. Now we need to create a really simple service.

Creating ItemResolver service

The ItemResolver will be used by the controller to resolve the new cart item - based on a user request information. Its only requirement is to implement Sylius\Component\Cart\Resolver\ItemResolverInterface.

// src/App/AppBundle/Cart/ItemResolver.php namespace App\AppBundle\Cart; use Sylius\Component\Cart\Model\CartItemInterface; use Sylius\Component\Cart\Resolver\ItemResolverInterface; class ItemResolver implements ItemResolverInterface { public function resolve(CartItemInterface $item, $request) { } }

The class is in place, well done. We need to do some more coding, so the service is actually doing its job. In our example we want to put Product in our cart, so we should inject the entity manager into our resolver service.

// src/App/AppBundle/Cart/ItemResolver.php namespace App\AppBundle\Cart; use Sylius\Component\Cart\Model\CartItemInterface; use Sylius\Component\Cart\Resolver\ItemResolverInterface; use Doctrine\ORM\EntityManager; class ItemResolver implements ItemResolverInterface { private $entityManager;

public function __construct(EntityManager $entityManager) { $this->entityManager= $entityManager; }

public function resolve(CartItemInterface $item, $request) { }

156 Chapter 6. Bundles Sylius, Release

private function getProductRepository() { return $this->entityManager->getRepository('AppBundle:Product'); } }

We also added a simple method getProductRepository() to keep the resolving code cleaner. We must use this repository to ﬁnd a product with id, given by the user via the request. This can be done in various ways, but to keep the example simple - we’ll use a query parameter.

// src/App/AppBundle/Cart/ItemResolver.php namespace App\AppBundle\Cart; use Sylius\Component\Cart\Model\CartItemInterface; use Sylius\Component\Cart\Resolver\ItemResolverInterface; use Sylius\Component\Cart\Resolver\ItemResolvingException; use Doctrine\ORM\EntityManager; class ItemResolver implements ItemResolverInterface { private $entityManager;

public function __construct(EntityManager $entityManager) { $this->entityManager= $entityManager; }

public function resolve(CartItemInterface $item, $request) { $productId= $request->query->get('productId');

// If no product id given, or product not found, we throw exception with nice

˓→message. if (!$productId ||!$product= $this->getProductRepository()->find(

˓→$productId)) { throw new ItemResolvingException('Requested product was not found'); }

// Assign the product to the item and define the unit price. $item->setVariant($product); $item->setUnitPrice($product->getPrice());

// Everything went fine, return the item. return $item; }

private function getProductRepository() { return $this->entityManager->getRepository('AppBundle:Product'); } }

6.1. Symfony2 Bundles 157 Sylius, Release

Note: Please remember that item accepts only integers as price and quantity.

The bundle requires also a simple conﬁguration...

Container conﬁguration

Put this minimal conﬁguration inside your app/config/config.yml. sylius_cart: resolver: app.cart_item_resolver # The id of our newly created service. classes: ~ # This key can be empty but it must be present in the configuration. sylius_order: driver: doctrine/orm # Configure the doctrine orm driver used in documentation. sylius_money: ~

Or, if you have created any custom entities, use this: sylius_cart: resolver: app.cart_item_resolver # The id of our newly created service. classes: ~ # This key can be empty but it must be present in the configuration. sylius_order: driver: doctrine/orm # Configure the doctrine orm driver used in documentation. classes: order: model: App\AppBundle\Entity\Cart # If you have created a custom Cart

˓→entity. order_item: model: App\AppBundle\Entity\CartItem # If you have created a custom

˓→CartItem entity. sylius_money: ~

158 Chapter 6. Bundles Sylius, Release

Importing routing conﬁguration

Import the default routing from your app/config/routing.yml.

sylius_cart: resource:"@SyliusCartBundle/Resources/config/routing.yml" prefix: /cart

Updating database schema

Remember to update your database schema. For “doctrine/orm” driver run the following command.

$ php app/console doctrine:schema:update --force

Warning: This should be done only in dev environment! We recommend using Doctrine migrations, to safely update your schema.

Templates

We think that providing a sensible default template is really difﬁcult, especially when a cart summary is not the simplest page. This is the reason why we do not currently include any, but if you have an idea for a good starter template, let us know! The bundle requires only the summary.html.twig template for cart summary page. The easiest way to override the view is by placing it here app/Resources/SyliusCartBundle/views/Cart/summary.html.twig.

Note: You can use the templates from our Sylius app as inspiration.

The Cart and CartItem

Here is a quick reference of what the default models can do for you.

Cart

You can access the cart total value using the ->getTotal() method. The denormalized number of cart items is available via ->getTotalItems() method. Recalculation of totals can happen by calling ->calculateTotal() method, using the simplest possible math. It will also update the item totals. The carts have their expiration time - ->getExpiresAt() returns that time and ->incrementExpiresAt() sets it to +3 hours from now by default. The collection of items (Implementing the Doctrine\Common\Collections\Collection interface) can be obtained using the ->getItems().

CartItem

Just like for the cart, the total is available via the same method (->getTotal()), but the unit price is accessible using the ->getUnitPrice() Each item also can calculate its total, using the quantity (->getQuantity()) and the

6.1. Symfony2 Bundles 159 Sylius, Release

unit price. It also has a very important method called ->equals(CartItemInterface $item), which decides whether the items are “same” or not. If they are, it should return true, false otherwise. This is taken into account when adding an item to the cart. If the added item is equal to an existing one, their quantities are summed, but no new item is added to the cart. By default, it compares the ids, but for our example we would prefer to check the products. We can easily modify our CartItem entity to do that correctly.

// src/App/AppBundle/Entity/CartItem.php namespace App/AppBundle/Entity;

use Sylius\Bundle\Component\Cart\CartItem as BaseCartItem; use Sylius\Bundle\Component\Cart\CartItemInterface; class CartItem extends BaseCartItem { private $product;

public function getProduct() { return $this->product; }

public function setProduct(Product $product) { $this->product= $product; }

public function equals(CartItemInterface $item) { return $this->product === $item->getProduct(); } }

If the user tries to add the same product twice or more, it will just sum the quantities, instead of adding duplicates to the cart.

Routing and default actions

This bundle provides a quite simple default routing with several handy and common actions. You can see the usage guide below.

Cart summary page

To point user to the cart summary page, you can use the sylius_cart_summary route. It will render the page with the cart and form variables by default. The cart is the current cart and form is the view of the cart form.

Adding cart item

In our simple example, we only need to add the following link in the places where we need the “add to cart button”.

160 Chapter 6. Bundles Sylius, Release

Add product

˓→to cart

Clicking this link will add the selected product to the cart.

Removing item

On the cart summary page you have access to all the cart items, so another simple link will allow a user to remove items from the cart.

Remove from cart

Where item variable represents one of the cart.items collection items.

Clearing the whole cart

Clearing the cart is simple as clicking the following link.

Clear cart

Basic cart update

On the cart summary page, you have access to the cart form, if you want to save it, simply submit the form with the following action.

Save cart

You cart will be validated and saved if everything is alright.

Using the services

When using the bundle, you have access to several handy services. You can use them to manipulate and manage the cart.

Managers and Repositories

Note: Sylius uses Doctrine\Common\Persistence interfaces.

You have access to following services which are used to manage and retrieve resources. This set of default services is shared across almost all Sylius bundles, but this is just a convention. You’re interacting with them like you usually do with own entities in your project.

// ... public function saveAction(Request $request) { // ObjectManager which is capable of managing the Cart resource.

6.1. Symfony2 Bundles 161 Sylius, Release

// For *doctrine/orm* driver it will be EntityManager. $this->get('sylius.manager.cart');

// ObjectRepository for the Cart resource, it extends the base EntityRepository. // You can use it like usual entity repository in project. $this->get('sylius.repository.cart');

// Same pair for CartItem resource. $this->get('sylius.manager.cart_item'); $this->get('sylius.repository.cart_item');

// Those repositories have some handy default methods, for example... $item= $this->get('sylius.repository.cart')->createNew(); }

Provider and Resolver

There are also 3 more services for you. You use the provider to obtain the current user cart, if there is none, a new one is created and saved. The ->setCart() method also allows you to replace the current cart. ->abandonCart() is resetting the current cart, a new one will be created on the next ->getCart() call. This is useful, for example, when after completing an order you want to start with a brand new and clean cart.

// ... public function saveAction(Request $request) { $provider= $this->get('sylius.cart_provider'); // Implements the

˓→CartProviderInterface.

$currentCart= $provider->getCart(); $provider->setCart($customCart); $provider->abandonCart(); }

The resolver is used to create a new item based on the user request.

// ... public function addItemAction(Request $request) { $resolver= $this->get('sylius.cart_resolver'); $item= $resolver->resolve($this->createNew(), $request); }

Note: A more advanced example of a resolver implementation is available in Sylius Sandbox application on GitHub.

In templates

When using Twig as your template engine, you have access to 2 handy functions.

162 Chapter 6. Bundles Sylius, Release

The sylius_cart_get function uses the provider to get the current cart.

{% set cart= sylius_cart_get() %}

Current cart totals: {{ cart.total }} for {{ cart.totalItems }} items!

The sylius_cart_form returns the form view for the CartItem form. It allows you to easily build more complex actions for adding items to cart. In this simple example we allow to provide the quantity of item. You’ll need to process this form in your resolver.

{% set form= sylius_cart_form({'product': product}) %} {# You can pass options as an

˓→argument. #}

˓→"post"> {{ form_row(form.quantity)}} {{ form_widget(form._token) }}

Note: An example with multiple variants of this form can be found in Sylius Sandbox app. It allows for selecting a variation/options/quantity of the product. It also adapts to the product type.

Summary

Conﬁguration reference sylius_cart: # The driver used for persistence layer. driver: ~ # Service id of cart item resolver. resolver: ~ # Cart provider service id. provider: sylius.cart_provider.default # The id of cart storage for default provider. storage: sylius.cart_storage.session resources: cart: classes: controller: Sylius\Bundle\CartBundle\Controller\CartController form: Sylius\Bundle\CartBundle\Form\Type\CartType validation_groups: default: [ sylius] cart_item: classes: controller: Sylius\Bundle\CartBundle\Controller\CartItemController form: Sylius\Bundle\CartBundle\Form\Type\CartItemType validation_groups: default: [ sylius]

6.1. Symfony2 Bundles 163 Sylius, Release phpspec2 examples

$ composer install $ bin/phpspec run -f pretty

Bug tracking

This bundle uses GitHub issues. If you have found bug, please create an issue.

6.1.6 SyliusContactBundle

A generic solution for a contact form inside a Symfony2 application. There are two main models inside the bundle, ContactRequest and ContactTopic.

Conﬁguration reference sylius_attribute: driver: ~ # The driver used for persistence layer. Currently only `doctrine/

˓→orm` is supported. resources: contact_request: classes: model: Sylius\Component\Contact\Model\Request interface: Sylius\Component\Contact\Model\RequestInterface controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\ContactBundle\Form\Type\RequestType validation_groups: default: [ sylius] contact_topic: classes: model: Sylius\Component\Contact\Model\Topic interface: Sylius\Component\Contact\Model\TopicInterface controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: default: Sylius\Bundle\ContactBundle\Form\Type\TopicType validation_groups: default: [ sylius] translation: classes: model: Sylius\Component\Contact\Model\TopicTranslation interface:

˓→Sylius\Component\Contact\Model\TopicTranslationInterface controller:

˓→Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~

164 Chapter 6. Bundles Sylius, Release

factory: Sylius\Component\Resource\Factory\Factory form: default:

˓→Sylius\Bundle\ContactBundle\Form\Type\TopicTranslationType validation_groups: default: [ sylius]

6.1.7 SyliusFixturesBundle

Conﬁgurable ﬁxtures management for Symfony2 applications.

Installation

$ composer require sylius/fixtures-bundle

Otherwise you have to download .phar ﬁle.

$ curl -sS https://getcomposer.org/installer | php $ php composer.phar require sylius/fixtures-bundle

Adding required bundles to the kernel

You need to enable the bundle inside the kernel, usually at the end of bundle list.

// app/AppKernel.php

public function registerBundles() { $bundles= array( // Other bundles... new Sylius\Bundle\FixturesBundle\SyliusFixturesBundle(), ); }

Architecture

Flexibility is one of the key concepts of SyliusFixturesBundle. This article aims to explain what design decisions were made in order to achieve it.

Suites

Suites are collections of configured fixtures. They allow you to define different sets (for example - staging, development or big_shop) that can be loaded independently. They are defined through YAML configuration:

6.1. Symfony2 Bundles 165 Sylius, Release

sylius_fixtures: suites: my_suite_name: # Suite name as a key listeners: ~ fixtures: ~

Fixtures

Fixtures are just plain old PHP objects, that change system state during their execution - they can either persist some entities in the database, upload some ﬁles, dispatch some events or do anything you think is needed. sylius_fixtures: suites: my_suite_name: fixtures: my_fixture: # Fixture name as a key priority: 0 # The higher priority is, the sooner the fixture will

˓→be executed options: ~ # Fixture options

They implement the Sylius\Bundle\FixturesBundle\Fixture\FixtureInterface and need to be registered under the sylius_fixtures.fixture tag in order to be used in suite conﬁguration.

Note: The former interface extends the ConfigurationInterface, which is widely known from Configuration classes placed under DependencyInjection directory in Symfony bundles.

Listeners

Listeners allow you to execute code at some point of ﬁxtures loading. sylius_fixtures: suites: my_suite_name: listeners: my_listener: # Listener name as a key priority: 0 # The higher priority is, the sooner the fixture will

˓→be executed options: ~ # Listener options

They implement at least one of four interfaces: • Sylius\Bundle\FixturesBundle\Listener\BeforeSuiteListenerInterface - receives Sylius\Bundle\FixturesBundle\Listener\SuiteEvent as an arugment • Sylius\Bundle\FixturesBundle\Listener\BeforeFixtureListenerInterface - receives Sylius\Bundle\FixturesBundle\Listener\FixtureEvent as an arugment • Sylius\Bundle\FixturesBundle\Listener\AfterFixtureListenerInterface - receives Sylius\Bundle\FixturesBundle\Listener\FixtureEvent as an arugment • Sylius\Bundle\FixturesBundle\Listener\AfterSuiteListenerInterface - receives Sylius\Bundle\FixturesBundle\Listener\SuiteEvent as an arugment

166 Chapter 6. Bundles Sylius, Release

Note: The former interface extends the ConfigurationInterface, which is widely known from Configuration classes placed under DependencyInjection directory in Symfony bundles.

In order to be used in suite conﬁguration, they need to be registered under the sylius_fixtures.listener.

Custom ﬁxture

Basic ﬁxture

Let’s create a ﬁxture that loads all countries from the Intl library. We’ll extend the AbstractFixture in order to skip the conﬁguration part for now: namespace AppBundle\Fixture; use Sylius\Bundle\FixturesBundle\Fixture\AbstractFixture; use Sylius\Bundle\FixturesBundle\Fixture\FixtureInterface; final class CountryFixture extends AbstractFixture implements FixtureInterface { private $countryManager;

public function __construct(ObjectManager $countryManager) { $this->countryManager= $countryManager; }

public function getName() { return 'country'; }

public function load(array $options) { $countriesCodes= array_keys(\Intl::getRegionBundle()->getCountryNames());

foreach ($countriesCodes as $countryCode){ $country= new Country($countryCode);

$this->countryManager->persist($country); }

$this->countryManager->flush(); } }

The next step is to register this ﬁxture:

Fixture is now registered and ready to use in your suite:

6.1. Symfony2 Bundles 167 Sylius, Release

sylius_fixtures: suites: my_suite: fixtures: country: ~

Conﬁgurable ﬁxture

Loading all countries may be useful, but what if you want to load only some defined countries in one suite and all the countries in the another one? You don’t need to create multiple fixtures, a one configurable fixture will do the job!

// ...

final class CountryFixture extends AbstractFixture implements FixtureInterface { // ...

public function load(array $options) { foreach ($options['countries'] as $countryCode){ $country= new Country($countryCode);

$this->countryManager->persist($country); }

$this->countryManager->flush(); }

protected function configureOptionsNode(ArrayNodeDefinition $optionsNode) { $optionsNodeBuilder ->arrayNode('countries') ->performNoDeepMerging() ->defaultValue(array_keys(\Intl::getRegionBundle()->

˓→getCountryNames())) ->prototype('scalar') ; } }

Note: The AbstractFixture implements the ConfigurationInterface::getConfigTreeBuilder() and exposes a handy configureOptionsNode() method to reduce the boilerplate. It is possible to test this configuration using SymfonyConfigTest library. For examples of that tests have a look at Sylius Fixtures Configuration Tests.

Now, it is possible for the ﬁxture to create different outcomes by just changing its conﬁguration:

sylius_fixtures: suites: my_suite: fixtures: country: ~ # Creates all countries my_another_suite: fixtures:

168 Chapter 6. Bundles Sylius, Release

country: options: ~ # Still creates all countries my_customized_suite: fixtures: country: options: countries: # Creates only defined countries - PL - FR - DE

Custom listener

Basic listener

Let’s create a listener that removes the directory before loading the ﬁxtures. namespace AppBundle\Listener; use Sylius\Bundle\FixturesBundle\Listener\AbstractListener; use Sylius\Bundle\FixturesBundle\Listener\BeforeSuiteListenerInterface; use Sylius\Bundle\FixturesBundle\Listener\SuiteEvent; use Symfony\Component\Filesystem\Filesystem; final class DirectoryPurgerListener extends AbstractListener implements

˓→ListenerInterface { public function getName() { return 'directory_purger'; }

public function beforeSuite(SuiteEvent $suiteEvent, array $options) { (new Filesystem())->remove('/hardcoded/path/to/directory'); } }

The next step is to register this listener:

˓→"AppBundle\Listener\DirectoryPurgerListener">

Listener is now registered and ready to use in your suite: sylius_fixtures: suites: my_suite: listeners: directory_purger: ~

6.1. Symfony2 Bundles 169 Sylius, Release

Conﬁgurable listener

Listener that removes a hardcoded directory isn’t very useful. Allowing it to receive an array of directories would make this listener a lot more reusable.

// ... final class DirectoryPurgerListener extends AbstarctListener implements

˓→ListenerInterface { // ...

public function beforeSuite(SuiteEvent $suiteEvent, array $options) { (new Filesystem())->remove($options['directories']); }

protected function configureOptionsNode(ArrayNodeDefinition $optionsNode) { $optionsNodeBuilder ->arrayNode('directories') ->performNoDeepMerging() ->prototype('scalar') ; } }

Note: The AbstractListener implements the ConfigurationInterface::getConfigTreeBuilder() and exposes a handy configureOptionsNode() method to reduce the boilerplate. It is possible to test this conﬁguration using SymfonyConﬁgTest library.

Now, it is possible to remove different directories in each suite: sylius_fixtures: suites: my_suite: listener: directory_purger: options: directories: - /custom/directory - /another/custom/directory my_another_suite: listener: directory_purger: options: directories: - /path/per/suite

Built-in listeners

SyliusFixturesBundle comes with a few useful listeners.

170 Chapter 6. Bundles Sylius, Release

Logger (logger)

Provides output while running sylius:fixtures:load command.

# Without logger

$ app/console sylius:fixtures:load my_suite $ _

# With logger

$ app/console sylius:fixtures:load my_suite Running suite "my_suite"... Running fixture "country"... Running fixture "locale"... Running fixture "currency"... $ _

The logger does not have any conﬁguration options. It can be enabled in such a way:

sylius_fixtures: suites: my_suite: listeners: logger: ~

ORM Purger (orm_purger)

Purges the relational database. Uses delete purge mode and the default entity manager if not configured otherwise. Configuration options: • purge_mode - sets how databse is purged, available values: delete (default), truncate • managers - an array of entity managers’ names used to purge the database, [null] by default Example configuration:

sylius_fixtures: suites: my_suite: listeners: orm_purger: purge_mode: truncate managers: - custom_manager

PHPCR / MongoDB Purger (phpcr_purger / mongodb_purger)

Purges the document database. Uses the default document manager if not configured otherwise. Configuration options: • managers - an array of document managers’ names used to purge the database, [null] by default Example configuration:

6.1. Symfony2 Bundles 171 Sylius, Release

sylius_fixtures: suites: my_suite: listeners: phpcr_purger: managers: - custom_manager # Uses custom document manager mongodb_purger: ~ # Uses default document manager

Commands

Listing ﬁxtures

To list all available suites and ﬁxtures, use the sylius:fixtures:list command.

$ app/console sylius:fixtures:list

Available suites: - default - dev - test Available fixtures: - country - locale - currency

Loading ﬁxtures

To load a suite, use the sylius:fixtures:load [suite] command.

$ app/console sylius:fixtures:load default

Running suite "default"... Running fixture "country"... Running fixture "locale"... Running fixture "currency"...

Summary

Tests

$ composer install $ bin/phpspec run $ bin/phpunit

Bug tracking

This bundle uses GitHub issues. If you have found bug, please create an issue.

172 Chapter 6. Bundles Sylius, Release

6.1.8 SyliusFlowBundle

Wizards with reusable steps for Symfony2 applications. Suitable for building checkouts or installations.

Installation

$ composer require sylius/flow-bundle

Otherwise you have to download .phar ﬁle.

$ curl -sS https://getcomposer.org/installer | php $ php composer.phar require sylius/flow-bundle

Adding required bundles to the kernel

First, you need to enable the bundle inside the kernel. If you’re not using any other Sylius bundles, you will also need to add SyliusResourceBundle and its dependencies to the kernel. Don’t worry, everything was automatically installed via Composer.

// app/AppKernel.php public function registerBundles() { $bundles= array( new Sylius\Bundle\FlowBundle\SyliusFlowBundle(),

// Other bundles... ); }

Creating your steps

We will create a very simple wizard now, without forms, storage, to keep things simple and get started fast. Lets create a few simple steps:

6.1. Symfony2 Bundles 173 Sylius, Release

return $this->render('AcmeDemoBundle:Process/Step:first.html.twig'); }

public function forwardAction(ProcessContextInterface $context) { return $this->complete(); } }

render('AcmeDemoBundle:Process/Step:second.html.twig'); }

public function forwardAction(ProcessContextInterface $context) { return $this->complete(); } }

And so on, one class for each step in the wizard. As you can see, there are two actions in each step, display and forward. Usually, there is a form in a forward action where you can pick some data. When you do return $this->complete() the wizard will take you to the next step.

Creating scenario

To group steps into the wizard, we will implement ProcessScenarioInterface:

use ContainerAwareTrait;

public function build(ProcessBuilderInterface $builder) { $builder

174 Chapter 6. Bundles Sylius, Release

->add('first', new Step\FirstStep()) ->add('second', new Step\SecondStep()) // ... ; } }

As you can see, we just add each step to process builder with a desired name. The name will be used in the routes to navigate to particular step.

Registering scenario

In order for this to work, we need to register SyliusScenario and tag it as sylius.process.scenario:

or services: sylius.scenario.flow: class: Acme\DemoBundle\Process\SyliusScenario calls: -[setContainer,['@service_container']] tags: -{ name: sylius.process.scenario, alias: acme_flow}

The conﬁgured alias will be used later in the route parameters to identify the scenario as you can have more then one.

Routing conﬁguration

Import routing conﬁguration: acme_flow: resource:"@SyliusFlowBundle/Resources/config/routing.yml" prefix: /flow

If you take a look into imported routing conﬁguration, you will see that sylius_flow_start is a wizard entry point. sylius_flow_display displays the step with the given name, sylius_flow_forward forwards to the next step from the step with the given name. All routes have an scenarioAlias as a required parameter to identify the scenario.

Templates

Step templates are like any other action template, usually due to the nature of multi-step wizards, they have back and forward buttons:

6.1. Symfony2 Bundles 175 Sylius, Release

Welcome to second step

back

˓→ forward

Sylius Release

This Is My Headline

My Custom Headline

{{ 'sylius.ui.provinces'|trans }}

Welcome to second step