Start Building Your Application¶
Installation of Shopsys Platform is complete and now you can start building your application. Here are first steps you should start with.
Note
If you don't have a working application, install it first.
Set up timezone to display dates¶
Dates are internally stored in UTC. That supports portability and eases integration with other systems.
To see dates properly in the desired timezone, you can change timezone
setting in config/domains.yaml
file.
Note: Read more about working with date-time values
Set up domains¶
A domain can be understood as one instance of the shop. For example, just furniture can be bough on the domain shopsys-furniture.com while only electronics can be found on the domain shopsys-electro.com.
Note: Learn more about domain concept fully in Domain, Multidomain, Multilanguage article.
When you install new project, domains are set like this
shopsys
on the URLhttp://127.0.0.1:8000
2.shopsys
on the URLhttp://127.0.0.2:8000
Read settings and working with domain to learn how to set your domains correctly. If you have project with only one domain, read how to create a single domain application. If you have project with more than two domains, read how to add a new domain.
We highly recommend to set up domains in the beginning of your project correctly. It will save you a lot of time.
Note
If you add a domain, please create and upload an icon for the new domain (Administration > Settings > E-shop identification). You'll make shop administrators happy.
Set up locales¶
A locale is a combination of language and national settings like a collation of language-specific characters.
We use ISO 639-1 codes to specify locale (e.g., cs
, de
, en
, sk
).
Every domain has defined one locale and also administration has defined its locale.
When you install new project, locales are set like this
shopsys
(1st domain):en
2.shopsys
(2nd domain):cs
- administration:
en
In case you want to change domain locale read locale settings or in case you want to change default administration locale read locale in administration.
Set up domain type¶
Each domain can be configured with a type.
The type can be either b2c
(Business-to-Consumer) or b2b
(Business-to-Business).
This option is set using the type
parameter in the domain configuration.
By default, if the type
parameter is not present, the domain is considered as b2c
.
Here is an example of how to set up the domain type:
domains:
- id: 1
name: shopsys
locale: en
url: http://127.0.0.1:8000
type: b2c
- id: 2
name: 2.shopsys
locale: cs
url: http://127.0.0.2:8000
type: b2b
In this example, the first domain is set as B2C and the second domain is set as B2B.
Note
Switching a domain to b2b
brings some new features. For example, the company number becomes unique throughout the domain.
This means that no two companies on the same domain can have the same company number.
Set up Elasticsearch¶
We use Elasticsearch on the frontend for product searching, filtering and for fast listing of products to provide better performance. You are likely to adjust the Elasticsearch configuration for example, if you have a technical shop where the inflection of product names doesn't make sense (we use inflection during searching by default).
Note
Find more in detailed article about Elasticsearch usage.
Every domain has defined one Elasticsearch index. Definition of this index can be found in src/Resources/definition/<domain_id>.json
files.
The most often change is adding fields and changing analysis to justify search behavior.
Set up routing¶
Routing is a mechanism that maps URL path to controllers and methods.
You are likely to adjust routing when you need translated routes for a new locale (e.g., when you have a domain with German localization, and want to have a list of orders under URL /befehle
).
We use Symfony routing, so please find more in the official documentation
You can adjust the routing in config/shopsys-routing/routing_friendly_url.yaml
file and locale specific in config/shopsys-routing/routing_front_xx.yaml
files.
Set up default currency¶
A default currency is a currency that is displayed when showing a price in a certain part of the system. The default currency is different for administration and for each of domains and you can adjust the default currency for each one individually.
The administration default currency is used in twig templates e.g., as {{ value|priceWithCurrencyAdmin }}
.
The default currency for domain is used e.g., as {{ cartItemDiscount.priceWithVat|price }}
.
Note: Read more in a dedicated article about price filters and administration price filter.
When you install new project, default currencies are set like this
shopsys
(1st domain):CZK
2.shopsys
(2nd domain):EUR
- administration:
CZK
You can change default currencies in administration Pricing > Currencies
, but this change will not last after application rebuild (operation that you do often during development).
How to set default currency permanently¶
You can adjust the demo data to match your project. This takes a bit more effort but once you adjust demo data, the change will be applied every time application is rebuilded.
How to set administration default currency¶
Class SettingValueDataFixture
, method load()
+ $eurCurrency = $this->getReference(CurrencyDataFixture::CURRENCY_EUR);
+ $this->setting->set(PricingSetting::DEFAULT_CURRENCY, $eurCurrency->getId());
How to set first domain default currency¶
Class SettingValueDataFixture
, method load()
+ $eurCurrency = $this->getReference(CurrencyDataFixture::CURRENCY_EUR);
+ $this->setting->setForDomain(PricingSetting::DEFAULT_DOMAIN_CURRENCY, $eurCurrency->getId(), Domain::FIRST_DOMAIN_ID);
How to set next domains default currency¶
Class SettingValueDataFixture
, method setDomainDefaultCurrency()
- $defaultCurrency = $this->getReference(CurrencyDataFixture::CURRENCY_EUR);
+ $defaultCurrency = $this->getReference(CurrencyDataFixture::CURRENCY_CZK);
or you can even use switch logic to provide different default currencies for different domains like
switch ($domainId) {
case 2: $defaultCurrency = $this->getReference(CurrencyDataFixture::CURRENCY_EUR); break;
case 3: $defaultCurrency = $this->getReference(CurrencyDataFixture::CURRENCY_CZK); break;
...
Fine-tune your configuration¶
If all developers working on your project use the same version of PHP (e.g., because all use Shopsys Platform via Docker), you can use higher versions of the libraries and tools installed via Composer.
To do so, remove the config.platform.php
option from your composer.json
:
"config": {
"preferred-install": "dist",
- "component-dir": "project-base/web/components",
- "platform": {
- "php": "8.3"
- }
+ "component-dir": "project-base/web/components"
},
Run composer update
to install updated versions of your dependencies (versions that don't support the lowest PHP version supported by Shopsys Platform).
Then commit the changed composer.json
and composer.lock
so all the devs can share the same configuration.
If you're interested in why we use the forced PHP version in the first place, read our FAQ.
On the other hand, if you're planning to run your project in production on a natively installed PHP, you should respect the version installed on that server.
We recommend using the same version in your php-fpm
's Dockerfile
, so that developers using Docker run the app in the same environment.
After all, your production server is the one that matters the most.
First, run php -v
on your server to find our the exact version, for example:
PHP 8.3.2 (cli)
Copyright (c) The PHP Group
Zend Engine v4.1.3, Copyright (c) Zend Technologies
with Zend OPcache v8.1.3, Copyright (c), by Zend Technologies
Then change the version in your docker/php-fpm/Dockerfile
:
- FROM php:8.3-fpm-bullseye as base
+ FROM php:8.3.2-fpm-bullseye as base
After running docker compose up -d --build
you'll have the application running on the same PHP.
Now you can modify the version in your composer.json
as well so all packages will always be installed in a compatible version.
"platform": {
- "php": "8.3"
+ "php": "8.3.2"
}
To apply the new setting, execute composer update
and commit the changes.