App Scripts

Search…
v6.4.0 (stable)
App Scripts
App Scripts allow your app to include logic that is executed inside the Shopware execution stack. It allows you to build richer extensions that integrate more deeply with Shopware.
Note that app scripts were introduced in Shopware 6.4.8.0, and are not supported in previous versions.
Script Hooks
The entry point for each script are the so-called "Hooks". You can register one or more scripts inside your app, that should be executed whenever a specific hook is triggered. Through the hook your script gets access to the data of the current execution context and can react to or manipulate the data in some way.
See the Hooks reference for a complete list of all available.
Scripts
At the core App Scripts are twig files that are executed in a sandboxed environment. Based on which hook the script is registered to, the script has access to the data of that hook, and pre-defined services, that can be used to execute your custom logic.
Apps scripts are placed in the Resources/scripts directory of your app. For each hook you want to execute a script on, create a new subdirectory. The name of the subdirectory needs to match the name of the hook.
You can place one or more .twig files inside each of these subdirectories, that will be executed when the hook gets triggered.
The file structure of your apps should look like this:
1
└── DemoApp
2
    ├── Resources
3
    │   └── scripts                         // all scripts are stored in this folder
4
    │       ├── product-page-loaded         // each script in this folder will be executed when the `product-page-loaded` hook is triggered
5
    │       │   └── my-first-script.twig
6
    │       ├── cart
7
    │       │   ├── first-cart-script.twig
8
    │       │   └── second-cart-script.twig // you can execute multiple scripts per hook
9
    │       └── ...
10
    └── manifest.xml
Copied!
Including scripts
Sometimes scripts can become more complex or you want to extract common functionaltiy. Thus it is handy to split your scripts into smaller parts that can later be included in other scripts.
In order to do that you can compose your reusable scripts into twig macros, put them inside a dedicated include folder and then import them using the twig import functionality.
1
└── DemoApp
2
    ├── Resources
3
    │   └── scripts                         
4
    │       ├── include    
5
    │       │   └── media-repository.twig         // this script may be included into the other scripts
6
    │       ├── cart
7
    │       │   ├── first-cart-script.twig
8
    │       └── ...
9
    └── manifest.xml
Copied!
Note that app scripts can use the return keyword to return values to the caller.
A basic example may look like this:
Resources/scripts/include/media-repository.twig
1
{% macro getById(mediaId) %}
2
    {% set criteria = {
3
        'ids': [ mediaId ]
4
    } %}
5
    
6
     {% return services.repository.search('media', criteria).first %}
7
{% endmacro %}
Copied!
Resources/scripts/cart/first-cart-script.twig
1
{% import "include/media-repository.twig" as mediaRepository %}
2
​
3
{% set mediaEntity = mediaRepository.getById(myMediaId) %}
Copied!
Interface Hooks
Some "Hooks" describe interfaces this means that your scripts for that hook need to implement one or more functions. E.g. the store-api-hook defines a cache_key and a response function. Those functions are closely related, but are executed separately. To implement the different functions, you use different twig blocks with the name of the function:
1
{% block cache_key %}
2
    // provide a cacheKey for the incoming request
3
{% endblock %}
4
​
5
{% block response %}
6
    // produce the response for the request
7
{% endblock %}
Copied!
Some functions are optional whereas others are required, in the above example the cache_key function is optional. That means you can omit that block in your script without an error (but caching for the endpoint won't work in that case). The response function is required, which means that if your script does not provide a response block it will lead to an error.
Note that for each function you get access to different input data or services, so in the cache_key block you don't necessarily have access to the same data and services as in the response block. The available data and services are described for each hook (or each function in InterfaceHooks) in the reference documentation.
Translation
Inside the app script you have access to the storefront translation mechanism, by using the |trans-filter.
1
{% set translated = 'my.snippet.key'|trans %}
2
​
3
{% do call.something('my.snippet.key'|trans) %}
Copied!
Extended syntax
In addition to the default twig syntax, app scripts can also use a more PHP-flavoured syntax.
Equals check with ===
Instead of using the rather verbose `
` you can use the more dense `===` equality checks.
1
{% if var === 1 %}
2
    ...
3
{% endif %}
Copied!
Additionally, you can also use the !== not equals operator as well.
1
{% if var !== 1 %}
2
    ...
3
{% endif %}
Copied!
Loops with foreach
Instead of the for...in syntax for loops you can also use a foreach tag.
1
{% foreach list as entry %}
2
    {{ entry }}
3
    {% break %}
4
{% endforeach %}
Copied!
Instance of checks with is
You can use a is check to check the type of a variable.
1
{% if var is string %}
2
    ...
3
{% endif %}
Copied!
The following types are supported:
true
false
boolean / bool
string
scalar
object
integer / int
float
callable
array
Type casts with intval
You can cast variables into different types with the intval filter.
1
{% if '5'|intval === 5 %}
2
    {# always evaluates to true #}
3
{% endif %}
Copied!
The following type casts are supported:
intval
strval
boolval
floatval
conditions with && and ||
Instead of using AND or OR in if-conditions, you can use the && or || shorthands.
1
{% if condition === true && condition2 === true %}
2
    ...
3
{% endif %}
Copied!
return tag
You can use the return tag to return values from inside macros.
1
{% macro foo() %} 
2
     {% return 'bar' %}
3
{% endmacro %}
Copied!
Available services
Depending on the hook that triggered the execution of you script you get access to different services, you can use inside your scripts e.g. to access data inside Shopware or to manipulate the cart. Take a look at the hook reference to get a complete list of all available services per hook.
Additionally, we added a ServiceStubs-class, that can be used as typehint in your script, so you get auto-completion features of your IDE.
1
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
2
​
3
{% set configValue = services.config.app('my-app-config') %}
Copied!
The stub class contains all services, but depending on the hook not all of them are available.
Example Script - loading media entities
Assuming your app adds a custom field set for the product entity with a custom media entity select field.
When you want to display the file of the media entity in the storefront, it is not easily possible, because in the template's data you only get the id of the media entity, but not the url of the media file itself.
For this case you can add an app script on the product-page-loaded-hook, that loads the media entity by id and adds it to the page object, so the data is available in templates.
Resources/scripts/product-page-loaded/add-custom-media.twig
1
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
2
​
3
{% set page = hook.page %}
4
{# @var page \Shopware\Storefront\Page\Product\ProductPage #}
5
​
6
{% if page.product.customFields.myCustomMediaField is not defined %}
7
    {% return %}
8
{% endif %}
9
​
10
{% set criteria = {
11
    'ids': [ page.product.customFields.myCustomMediaField ]
12
} %}
13
​
14
{% set media = services.repository.search('media', criteria).first %}
15
​
16
{% do page.addExtension('swagMyCustomMediaField', media) %}
Copied!
For a more detailed example on how to load additional data, please refer to the data loading guide.
Alternatively take a look at the cart manipulation guide to get an in-depth explanation on how to manipulate the cart with scripts.
Developing / Debugging Scripts
You can get information about what scripts were triggered on a specific storefront page inside the Symfony debug toolbar.
The debug toolbar is only visible if your Shopware installation is in APP_ENV = dev, please ensure you set the correct env - e.g. in your .env file - when developing app scripts .
You can find all hooks that are triggered and the scripts that are executed for each by clicking on the script icon.
Symfony Debug Toolbar
That will open the Symfony profiler in the script detail view, where you can see all triggered hooks and the count of the scripts that were executed for each script at the top.
Script Debug Toolbar
Additionally, you can use the debug.dump() function inside your scripts to dump data to the debug view. A script like this:
1
{% do debug.dump(hook.page) %}
Copied!
Will dump the page object to the debug view.
Output of debug.dump()