getting-started.md

Getting started

Setup an admin panel

The Sylius Stack comes with a bunch of components that work great independently, but when they come together, that's when the stack's magic truly operates! Indeed, the highlight of this project is the ability to configure an admin panel UI within minutes.

Create a new project

You can set up the Sylius Stack on existing Symfony projects, but in the case you are starting from scratch, here is what you need to do.

# With Composer:
composer create-project symfony/skeleton:"8.0.*" my_project_directory
cd my_project_directory
composer require webapp

# Or with Symfony CLI:
symfony new my_project_directory --version="8.0.*" --webapp
cd my_project_directory

Allow Contrib Recipes

Sylius Stack recipes are hosted in the symfony/recipes-contrib repository. To ensure Symfony Flex installs them automatically, enable contrib recipes before requiring the packages:

composer config extra.symfony.allow-contrib true

Install the package using Composer and Symfony Flex

Go to your project directory and run the following command:

composer require -W \
  doctrine/orm \
  doctrine/doctrine-bundle \
  pagerfanta/doctrine-orm-adapter \
  symfony/asset-mapper \
  sylius/bootstrap-admin-ui \
  sylius/ui-translations

Type "a" or "p" to configure the packages via Symfony Flex.

Do not forget to set your application secret environment variable: {% code title=".env" %}

# ...
APP_SECRET=UseYourOwnSecretPlease

{% endcode %}

Run your web server

docker compose up -d
symfony serve -d

The admin panel is ready to use. Now, it's your turn!

Using AssetMapper

To prevent duplicate Ajax calls, disable the auto-initialized Stimulus app and Symfony UX stylesheets from the sylius/bootstrap-admin-ui package, so you can take control of Stimulus initialization in your own code.

Disabling Stimulus app & Symfony UX stylesheets from third party package

First, you need to disable the Stimulus App started by the sylius/bootstrap-admin-ui package and add a custom javascript app hook for the asset mapper.

{% tabs %} {% tab title="YAML" %} {% code lineNumbers="true" %}

# config/packages/sylius_bootstrap_admin_ui.yaml
# ...
sylius_twig_hooks:
    hooks:
        # ...
        # Disabling Symfony UX stylesheets
        'sylius_admin.base#stylesheets':
            symfony_ux:
                enabled: false    
           
        'sylius_admin.base#javascripts':
            app:
                priority: 200
                template: 'base/javascripts/app.html.twig'
            # Disabling Stimulus App
            symfony_ux:
                enabled: false

{% endcode %} {% endtab %}

{% tab title="PHP" %} {% code title="config/packages/sylius_bootstrap_admin_ui.php" lineNumbers="true" %}

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    // ...

    $containerConfigurator->extension('sylius_twig_hooks', [
        'hooks' => [
            'sylius_admin.base#stylesheets' => [
                // Disabling Symfony UX stylesheets
                'symfony_ux' => [
                    'enabled' => false,
                ],
            ],
            
            'sylius_admin.base#javascripts' => [
                // New hook
                'app' => [
                    'priority' => 200,
                    'template' => 'base/javascripts/app.html.twig',
                ],                
                // Disabling Stimulus App        
                'symfony_ux' => [
                    'enabled' => false,
                ],
            ],
        ],    
    ]);
};

{% endcode %} {% endtab %} {% endtabs %}

{% code title="base/javascripts/app.html.twig" lineNumbers="true" %}

{{ importmap('app') }}

{% endcode %}

Starting Stimulus App

// assets/bootstrap.js
import { startStimulusApp } from '@symfony/stimulus-bundle';

const app = startStimulusApp();
// register any custom, 3rd party controllers here
// app.register('some_controller_name', SomeImportedController);

// assets/app.js
import './bootstrap.js';
// ...