App Scripts: eigen logica voor Shopware-apps zonder eigen server

App Scripts zijn kleine programma’s in Twig-syntaxis die een Shopware-app rechtstreeks in de webshop uitvoert, zonder eigen server. Ze reageren op hooks zoals de berekening van de winkelwagen of het openen van een pagina en maken logica mogelijk die anders alleen met plugins mogelijk was.

Het app-systeem van Shopware 6 scheidt extensies van de webshop: apps draaien buiten de shop en communiceren via API en webhooks. Dat heeft een nadeel: logica die tijdens een request moet draaien, bijvoorbeeld een toeslag in de winkelwagen, liet zich zo niet realiseren. App Scripts dichten deze kloof sinds Shopware 6.4.8. Een app levert scriptbestanden mee, Shopware voert ze uit in een beveiligde Twig-omgeving, synchroon en binnen de webshop. Daardoor werken App Scripts ook in de Shopware Cloud, waar geen eigen PHP-code mag worden uitgevoerd.

Elk script hangt aan een hook, die bepaalt wanneer het draait en welke gegevens het ziet. De belangrijkste:

• cart: bij elke berekening van de winkelwagen. Toegang tot orderregels, prijzen, klant en context; typische hook voor toeslagen, kortingen of gratis artikelen.
• product-page-loaded, product-listing-loaded, checkout-confirm-page-loaded en andere Storefront-hooks: de gegevens van de pagina uitbreiden, bijvoorbeeld met aanvullende informatie uit een ander systeem.
• api en custom-endpoint: eigen endpoints in de Admin-API en Store-API die een script beantwoordt.
• storefront-custom-page: eigen pagina’s in de Storefront renderen.
• order-placed en andere gebeurtenishooks: reageren na een gebeurtenis, bijvoorbeeld gegevens naar de app sturen.

De scripts staan in de app onder Resources/scripts//; de mapnaam bepaalt de hook.

Een script is een Twig-bestand dat met de gegevens van de hook werkt en via services toegang krijgt tot Shopware. Een voorbeeld voor een toeslag voor kleine bestelhoeveelheden in de winkelwagen:

{# Resources/scripts/cart/mindermengenzuschlag.twig #}
{% if hook.cart.price.totalPrice < 30 %}
    {% do services.cart.products.add("ID_DES_ZUSCHLAGARTIKELS") %}
{% endif %}

Beschikbare services zijn onder andere services.repository voor het lezen van entiteiten, services.cart voor acties in de winkelwagen, services.config voor de appconfiguratie, services.response voor eigen endpoints en services.writer voor schrijftoegang via de Data Abstraction Layer. Welke services een hook beschikbaar stelt, documenteert Shopware in de scriptreferentie.

• Prijslogica in de winkelwagen: toeslagen, staffels, gratis extra’s, minimale bestelwaarden per klantgroep.
• Gegevens verrijken: productpagina’s aanvullen met informatie uit systemen van derden of berekende waarden.
• Eigen endpoints: kleine query’s voor Storefront-JavaScript of externe diensten zonder omweg via de app.
• Validatie: bestellingen blokkeren wanneer niet aan voorwaarden wordt voldaan.
• Cloudcompatibiliteit: logica die in de Shopware Cloud moet draaien, waar plugins niet zijn toegestaan.

• Geen willekeurige PHP-code: scripts draaien in een sandbox met vastgelegde services; bestandssysteem, database en externe bibliotheken zijn niet bereikbaar.
• Externe diensten: scripts bereiken systemen van derden alleen via de daarvoor bedoelde wegen; omvangrijke query’s tijdens de berekening van de winkelwagen vertragen de checkout.
• Performance: cartscripts draaien bij elke berekening. Complexe logica of veel repositoryquery’s vertragen de webshop.
• Debugging: fouten verschijnen in de logs; een eigen ontwikkelomgeving met geactiveerde scriptdebug maakt het werk aanzienlijk gemakkelijker.

Plugins draaien als PHP in de webshop, hebben volledige toegang tot Symfony-services, events en de database en zijn bij complexe of prestatiekritische logica de betere keuze. App Scripts winnen wanneer de extensie als app moet worden gedistribueerd, in de cloud moet draaien of de logica overzichtelijk is. Veel bureaus combineren beide: een app voor cloudklanten, een plugin voor zelf gehoste projecten. Hoe wij extensies realiseren, leest u op onze pagina over Shopware-pluginontwikkeling; het verschil tussen de formaten legt het item App: cloud-native pluginformaat uit.

Twig, Event (hook), Webhooks, Extensie-SDK en Store-extensies. Alle begrippen in het Shopware woordenboek.