Documentation

ShopBite Plugin Installation

This chapter guides you through the installation of the ShopBite Plugin in your Shopware 6 system.

Prerequisites

  • Shopware 6.7.0 or higher (installed and functional)
  • PHP 8.4 or higher
  • Composer 2.0 or higher
  • Database access with sufficient permissions

Installation Methods

1. Installation via Composer (recommended)

# Install plugin via Composer
composer require shopbite-de/shopware-plugin

# Activate plugin
bin/console plugin:install --activate ShopBite

# Clear cache
bin/console cache:clear

2. Installation via Shopware Plugin Store

  1. Open Shopware Administration
  2. Navigate to Extensions > Store
  3. Search for "ShopBite"
  4. Click Install
  5. Click Activate

3. Manual Installation

# Download plugin
wget https://github.com/shopbite-de/shopware-plugin/releases/latest/download/shopbite-plugin.zip
unzip shopbite-plugin.zip -d custom/plugins/ShopBite

# Install and activate plugin
bin/console plugin:refresh
bin/console plugin:install --activate ShopBite

# Run database migrations
bin/console database:migrate --all ShopBite

# Clear cache
bin/console cache:clear

Installation Process in Detail

Step 1: Download Plugin

# Composer method (recommended)
composer require shopbite-de/shopware-plugin

# Manual method
wget https://github.com/shopbite-de/shopware-plugin/releases/latest/download/shopbite-plugin.zip
unzip shopbite-plugin.zip -d custom/plugins/ShopBite

Step 2: Register Plugin

# Update plugin list
bin/console plugin:refresh

# Install plugin
bin/console plugin:install ShopBite

Step 3: Activate Plugin

# Activate plugin
bin/console plugin:activate ShopBite

# Check status
bin/console plugin:list | grep ShopBite

Step 4: Run Database Migrations

# Run migrations
bin/console database:migrate --all ShopBite

# Check migrations
bin/console database:migrate:status

Step 5: Cache and Assets

# Clear cache
bin/console cache:clear

# Update theme cache
bin/console theme:compile

# Update administration cache
bin/console administration:build

Step 6: Check Permissions

# Set directory permissions
sudo chown -R www-data:www-data custom/plugins/ShopBite
sudo chmod -R 755 custom/plugins/ShopBite

# Cache permissions
sudo chmod -R 777 var/cache

Post-Installation

Administration Interface

  1. Open Shopware Administration
  2. Navigate to Extensions > My Extensions
  3. Find ShopBite Plugin and click Configure
  4. Perform basic configuration

Set Up API Access

# Create API integration
bin/console integration:create:admin --name="ShopBite Storefront" --description="API access for ShopBite Storefront"

# Set permissions
bin/console acl:role:create --name="ShopBite API Role" --description="API role for ShopBite"
bin/console acl:role:assign --name="ShopBite API Role" --resource="order:read,order:write,product:read"

Order Printer Role

On install and on every update the plugin creates the ACL role order-printer with exactly the privileges the order printer needs, and nothing else:

PrivilegeUsed for
order:read, state_machine_state:readPOST /api/search/order (open orders)
order_delivery:read, order_line_item:read, order_address:read, shipping_method:readPOST /api/search/order-delivery (receipt contents)
order:updatePOST /api/_action/order/{id}/state/process (mark in progress)

A second install or update changes nothing; if a plugin version changes the list, the role is updated. The role is only removed on uninstall without "keep user data", because integrations reference it.

To connect an order printer: Settings > System > Integrations > Add integration, choose the role order-printer, and copy the access key ID and secret access key (the secret is only shown once).

Backoffice accounts

The ShopBite backoffice is the simple admin for a restaurant's staff. Everyone logs in with their own Shopware user. Install and every update create two ACL roles for it:

RoleMay
ShopBite ManagementMenu (dishes, prices, variants, extras, sections, SEO), opening hours, orders of all branches
ShopBite PersonalToday's orders, done/cancel, pausing online orders, delivery time, only for their own branch

Don't edit the roles by hand, an update resets them. Create accounts on the command line (the backoffice itself may not create users):

# Owner, sees all branches
bin/console shopbite:staff:create owner --role=management --name="Anna Rossi"

# Staff of one branch (sales channel id from bin/console sales-channel:list)
bin/console shopbite:staff:create counter --role=personal --branch=<salesChannelId> --generate-password

bin/console shopbite:staff:list
bin/console shopbite:staff:update counter --branch=<otherSalesChannelId>   # move to another branch
bin/console shopbite:staff:update counter --generate-password              # new password
bin/console shopbite:staff:update counter --deactivate                     # block the login

Without --generate-password the command asks for the password (hidden); a generated password is shown exactly once. Staff need at least one branch (--branch, repeatable), otherwise the backoffice refuses them. Management without a branch sees all branches. The branches are stored in the user custom field shopbite_sales_channel_ids.

Fingerprint login for the backoffice

In the backoffice, everyone can log in with fingerprint or Face ID after setting up their device once under "Mein Zugang" (passkey). Enter in the plugin configuration, card Backoffice passkeys:

  • Relying party id: the host name of the backoffice without https://, e.g. backoffice.pizzeria-lafattoria.de
  • Allowed origins: its full address, e.g. https://backoffice.pizzeria-lafattoria.de

Without both, fingerprint login is off. A deactivated user cannot log in with a passkey either, and a passkey only works for that one address.

Allergens and additives

For online orders, allergens and additives that must be declared have to be visible before ordering. Install and update create two property groups for this:

  • Allergene: the 14 allergens of the EU food information regulation, cereals containing gluten and nuts by name (Weizen, Haselnüsse, ...), with the codes A to R
  • Zusatzstoffe: e.g. "mit Farbstoff", "koffeinhaltig", numbered 1 to 12

The code is stored in the option's custom field shopbite_code. On the dish, the custom field "Allergens and additives checked" (shopbite_allergens_checked) marks that the lists are complete, also when nothing is selected. The easiest place to maintain both is the backoffice. If one of the groups already exists, the plugin adopts it instead of creating a duplicate.

Configure Sales Channel

  1. Navigate to Settings > Sales Channels
  2. Create New Sales Channel
  3. Configure ShopBite-specific settings
  4. Assign API access

Installation Verification

Check Plugin Status

# Show plugin status
bin/console plugin:list | grep ShopBite

# Show plugin details
bin/console plugin:info ShopBite

Check Database

# Check tables
mysql -u shopware -p shopware -e "SHOW TABLES LIKE 'shopbite_%';"

# Check data
mysql -u shopware -p shopware -e "SELECT * FROM shopbite_business_hour LIMIT 5;"

Test API Endpoints

# API test (replace URL and token)
curl -X GET "https://Your-Shopware-Domain.de/store-api/shopbite/business-hour" \
  -H "Authorization: Bearer YourAPIToken" \
  -H "sw-access-key: YourAccessKey"

Common Installation Issues

Problem: Plugin Not Visible in Administration

Symptoms:

  • Plugin is installed but not visible
  • Error: "Plugin not found"

Solutions:

# Clear cache
bin/console cache:clear

# Update plugin list
bin/console plugin:refresh

# Check permissions
sudo chown -R www-data:www-data custom/plugins/ShopBite

Problem: Database Migrations Failed

Symptoms:

  • Error: "Migration failed"
  • Tables not created

Solutions:

# Run migrations manually
bin/console database:migrate --all ShopBite --force

# Check database permissions
mysql -u root -p
GRANT ALL PRIVILEGES ON shopware.* TO 'shopware'@'localhost';
FLUSH PRIVILEGES;

Problem: API Endpoints Not Reachable

Symptoms:

  • 404 error on API calls
  • Endpoints not available

Solutions:

# Clear route cache
bin/console router:cache:warmup

# Re-activate plugin
bin/console plugin:deactivate ShopBite
bin/console plugin:activate ShopBite

# Check API permissions
bin/console acl:role:list

Problem: Composer Installation Failed

Symptoms:

  • Error: "Could not find package shopbite-de/shopware-plugin"
  • Composer installation aborts

Solutions:

# Clear Composer cache
composer clear-cache

# Update Packagist
composer update

# Manual installation
wget https://github.com/shopbite-de/shopware-plugin/releases/latest/download/shopbite-plugin.zip

Uninstallation

Deactivate Plugin

# Deactivate plugin
bin/console plugin:deactivate ShopBite

Uninstall Plugin

# Uninstall plugin
bin/console plugin:uninstall ShopBite

# Clean data (optional)
bin/console plugin:uninstall ShopBite --keep-user-data=false

Manual Cleanup

# Remove plugin directory
rm -rf custom/plugins/ShopBite

# Clear cache
bin/console cache:clear

# Clean database (optional)
mysql -u shopware -p shopware -e "DROP TABLE IF EXISTS shopbite_business_hour, shopbite_holiday, shopbite_wishlist_item;"

Next Steps