Getting Started with Sylius

I first heard about Sylius at the 2014 Symfony Live Conference and it definitely intrigued me. The basics of it is that it’s an ecommerce platform built using the Symfony PHP framework. Out of the box it already has a pretty awesome structuring. All the components are separated out meaning each is extendable, the layouts are easily modified with themes and to top it off the project itself is bundled with thousands of behaviour driven tests. That’s no simple feat for a complex application framework to provide out of the box.

Currently the project is in the beta stages of its first release and it looks good so far. One of the only slight problems I will say is the documentation. It’s not bad by any means but it’s very developer focused and doesn’t necessarily have much of a walk through in how to get started or how to evaluate the framework for your own needs.

Prerequisites

Firstly you’ll need Git, Vagrant and VirtualBox installed so you can run the virtual machine image. You don’t necessarily need to use the virtual machine if you’ve got your own setup for PHP applications but you will then need a modern version of PHP (5.6 >), Composer and a MySQL server where you can create a database. Using the vagrant image saves a lot of time. While trying out the project directly on my Mac I had PHP config issues, it became simpler to say I’m just going to try it out and go from there.

Once you have all of this ready, create a folder for your project and then clone the vagrant setup up and enter the direct.

git clone git@github.com:Sylius/Vagrant.git sylius
cd sylius
vagrant up

The vagrant command will possibly require a password when booting up so keep an eye out for it.

It’s advised as well to add a host lookup line to your /etc/hosts file to make life a bit easier.

# etc/hosts
10.0.0.200 sylius.dev www.sylius.dev

At this point we should be able to access the Sylius web app via http://www.sylius.dev/app_dev.php and see the storefront using the example data. We can also access the admin panel via http://www.sylius.dev/app_dev.php/admin. The login for the admin panel is example@sylius.org and the password is simply sylius.

By the time we’re up and running, inside the folder sylius we now have a sites folder and inside that another sylius folder than contains our project’s code.

How to configure a store?

It’s now worth while having a look around at what’s on offer. Namely Channels, in Sylius a channel is the interface or site which will let customers use the right configuration for them. For example if you have customers in the US and the UK you’re potentially going to want a channel for each. These channels can take on lots of different settings to do with languages, currencies and even tax regions. At this point it might be worth familiarising yourself with the admin interface to understand the different things you can configure.

Starting from fresh

Now there is a slight problem with the site we have so far. If you’re like me and want a shop for the UK the already configured channel is using US Dollars and I need to use British Pounds. Once channels are added the base currency is non changeable through the dashboard for what I believe are sensible reasons. The channel code is also fixed. In fact it appears that you can’t even delete the original channel for the setup at the moment.

Instead we’ll setup a new store with a clean database. We can do this by making a few changes and then running a fresh install of the project’s database. While we’re at it, we’ll make sure our project is up to date as well.

Firstly, lets check that the default language for our shop is set. For me, I want British English rather than American English which is the default.

First in the project let’s add the following setting to app/config/parameters.yml and app/config/parameters.yml.dist

locale: en_GB

This will define make sure the default settings are for the UK language wise.

Next we need to get a console on our vagrant box so we can run the commands. We can do this with the commands:

vagrant ssh
cd /var/www/sites/sylius
bin/console cache:clear
bin/console doctrine:database:destroy --force --env dev
bin/console doctrine:database:create --env dev
bin/console sylius:install

Then after we’ll be prompted to provide some information. Namely to provide the currency. For me it’s going to be GBP, again the default for American Dollars would be USD. We’ll also be asked for an email address and password for our new admin account.

Once this is done we can again access the admin dashboard and this time see that there’s no financial data or any products available. What we do have is our default channel.

Customising the look of your store

A few thing’s you’ll notice about your store from the start is that there’s some parts of the design like the logo and the links and information in the footer that require changing. We’re going to change those now by adding some basic templates and a translation file to our project. We won’t be creating a theme this time, instead we’re going to extend the current default one.

Firstly we need to add two new folders to our project under the app/Resources folder. The first being SyliusShopBundle and then inside that we need a twig folder.

Now we our own footer template, _footer.html.twig:

<footer id="footer" class="ui inverted vertical footer segment">
<div class="ui container">
<div class="ui inverted divided equal height stackable grid">
{{ sonata_block_render_event('sylius.shop.layout.before_footer') }}

<div class="three wide column">
<h4 class="ui inverted header">{{ 'sylius.ui.your_store'|trans }}</h4>
<div class="ui inverted link list">
<a href="#" class="item">{{ 'sylius.ui.about'|trans }}</a>
<a href="#" class="item">{{ 'sylius.ui.terms_and_conditions'|trans }}</a>
<a href="#" class="item">{{ 'sylius.ui.privacy_policy'|trans }}</a>
</div>
</div>
<div class="three wide column">
<h4 class="ui inverted header">{{ 'sylius.ui.customer_care'|trans }}</h4>
<div class="ui inverted link list">
<a href="{{ path('sylius_shop_contact_request') }}" class="item">{{ 'sylius.ui.contact_us'|trans }}</a>
<a href="#" class="item">{{ 'sylius.ui.faqs'|trans }}</a>
<a href="#" class="item">{{ 'sylius.ui.delivery_and_shipping'|trans }}</a>
<a href="#" class="item">{{ 'sylius.ui.returns_policy'|trans }}</a>
</div>
</div>
<div class="eight wide column">
<h4 class="ui inverted header">&copy; {{ 'sylius.ui.your_store'|trans }}</h4>
<p>{{ 'sylius.ui.powered_by'|trans }} <a href="http://sylius.org" target="_blank" style="color: #1abb9c;">Sylius</a>.</p>
</div>

{{ sonata_block_render_event('sylius.shop.layout.after_footer') }}
</div>
</div>
</footer>

You can then edit the contents of _footer.html.twig, such as at current the href attribute for several of the links don’t point to anything. You might want to change those to view actual pages containing contact information or delivery info. At the moment there’s no built in functionality for these but we can come back to this another time.

You will notice also in the footer where it says:

{{ 'sylius.ui.your_store'|trans }}

This is using Symfony’s build in translation library to output the name of the store so to keep using the translation system but set the name of ‘your_store’, you need to add your own translations to the project you’ve started.

This can be done by creating a folder called translations under the app/Resources folder. Inside that, then add a new file called messages.en.yml. The contents should then look like the following.

sylius:
ui:
your_store:
My Awesome Store

If the change doesn’t take place right away when you edit or add templates or translation files, try running bin/console cache:clear again to ensure it uses the correct files.

Summary

Using Sylius isn’t a silver bullet, it’s a very complex system. Symfony as a web framework is often time consuming to pick up compared to say Laravel but it’s also very sturdy when it comes to enterprise applications. What I’ve covered in this is more for exploring currently. I hope to follow up this piece with other articles, beginning with how to run the test suite associated with the Sylius framework and how to add small features to your store front.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.