Installation¶
The Sylius main application can serve as an end-user app, as well as a foundation for your custom e-commerce application.
To create your Sylius-based application, first make sure you use PHP 8.1 or higher and have Composer installed.
Initiating A New Sylius Project¶
To begin creating your new project, run this command:
composer create-project sylius/sylius-standard acme
Tip
We are about to release a new major version of Sylius, which is going to be 2.0. Worry not, upgrading from 1.x to 2.x will be possible. It is currently recommended to start with 1.x and upgrade the project once 2.0 is there, but if you’d like to start playing around with the still-in-progress version, you can use this command to set the environment on Sylius 2.0-ALPHA.X/BETA.X.
composer composer create-project --stability=dev sylius/sylius-standard:2.0.x-dev acme
Note
Make sure to use PHP ^8.1. Using an older PHP version will result in installing an older version of Sylius.
This will create a new Symfony project in the acme
directory. Next, move to the project directory:
cd acme
Sylius uses environment variables to configure the connection with database and mailer services.
You can look up the default values in .env
file and customise them by creating .env.local
with variables you want to override.
For example, if you want to change your database name from the default sylius_%kernel.environment%
to my_custom_sylius_database
,
the contents of that new file should look like the following snippet:
DATABASE_URL=mysql://username:password@host/my_custom_sylius_database
Warning
Specific Sylius versions may support various Symfony versions. To make sure the correct Symfony version will be installed (Symfony 6.0 for example) use:
composer config extra.symfony.require "^6.0"
composer update
Otherwise, you may face the problem of having Symfony components of the wrong version installed.
After everything is in place, run the following command to install Sylius:
php bin/console sylius:install
Warning
During the sylius:install
command you will be asked to provide important information, but also its execution ensures
that the default currency (USD) and the default locale (English - US) are set.
They can be changed later, respectively in the “Configuration > Channels” section of the admin and in the config/services.yaml
file. If you want
to change these before running the installation command, set the locale
and sylius_installer_currency
parameters in the config/services.yaml
file.
From now on all the prices will be stored in the database in USD as integers, and all the products will have to be added with a base american english name translation.
Configuring Mailer¶
In order to send emails you need to configure Mailer Service. Basically there are multiple ways to do it:
We are recommending to use Symfony Mailer where out of the box, you can deliver emails by configuring the
MAILER_DSN
variable in your .env file.In Symfony Mailer use the 3rd Party Transports
(deprecated) Use SwiftMailer with this short configuration:
Create an account on a mailing service.
In your
.env
file modify/add theMAILER_URL
variable.
MAILER_URL=gmail://username:password@local
Note
Email delivery is disabled for test, dev and staging environments by default. The prod environment has delivery turned on.
You can learn more about configuring mailer service in How to configure mailer?
Installing assets¶
In order to see a fully functional frontend you will need to install its assets.
Sylius uses Webpack to build frontend assets using Yarn as a JavaScript package manager.
Note
If you want to read more, you can read a chapter of our Book devoted to the Sylius’ frontend.
Having Yarn installed, go to your project directory to install the dependencies:
yarn install
Then build the frontend assets by running:
yarn build
Accessing the Shop¶
We strongly recommend using the Symfony Local Web Server by running the symfony server:start
command and then accessing https://127.0.0.1:8000
in your web browser to see the shop.
Note
Get to know more about using Symfony Local Web Server in the Symfony server documentation. If you are using a built-in server check here.
You can log to the administrator panel located at /admin
with the credentials you have provided during the installation process.
How to start developing? - Project Structure¶
After you have successfully gone through the installation process of Sylius-Standard you are probably going to start developing within the framework of Sylius.
In the root directory of your project you will find these important subdirectories:
config/
- here you will be adding the yaml configuration files including routing, security, state machines configurations etc.var/log/
- these are the logs of your applicationvar/cache/
- this is the cache of you projectsrc/
- this is where you will be adding all you custom logic in theApp
public/
- there you will be placing assets of your project
Tip
As it was mentioned before we are basing on Symfony, that is why we’ve adopted its approach to architecture. Read more in the Symfony documentation. Read also about the best practices while structuring your project.
Running asynchronous tasks¶
To enable asynchronous tasks (for example for Catalog Promotions), remember about running messenger consumer in a separate process, use the command: php bin/console messenger:consume main
For production environments, we suggest usage of more robust solution like Supervisor, which will ensure that the process is still running even if some failure will occur. For more information, please visit Symfony documentation.
You can learn more about Catalog Promotions Here
Contributing¶
If you would like to contribute to Sylius - please go to the Contribution Guide