Makaira Connect Suite

🎯 Purpose

The Makaira Connect Suite consists of two powerful modules that integrate Shopware 6 with the Makaira platform:

• Makaira Connect Essential: Ensures robust synchronization and management of Shopware data (products, categories, manufacturers) with Makaira’s persistence layer.
  
  

• Makaira Connect Frontend: Powers storefront features such as search, autosuggest, product listings, and personalized recommendations via the Makaira API.
  
  

Together, they enable seamless backend data management and frontend experience optimization for Shopware-based e-commerce platforms.

✨ Key Features

Makaira Connect Essential

• 🔄 Sync Shopware data (Products, Categories, Manufacturers) with Makaira.
• 🛠️ Manage the Makaira persistence layer (rebuild, update, switch).
• 🌐 Multi-sales channel support with per-channel credentials.
• 📡 Real-time updates via event subscribers.

Makaira Connect Frontend

• 🔍 Fast and accurate search powered by Makaira.
• 💡 Real-time autosuggestions.
• 🛒 Product listings directly from Makaira.
• 🎯 Personalized product recommendations.
• 🌐 API client integration for seamless frontend functionality.

⚙️ Installation

Essential

composer require makaira/shopware6-connect-essential  
bin/console plugin:install --activate MakairaConnectEssential

Frontend

composer require makaira/shopware6-connect-frontend  
bin/console plugin:install --activate MakairaConnectFrontend

⚙️ Configuration

Shared Configuration (Both Modules)

• Base URL of Makaira API (makairaBaseUrl): e.g., https\://\<customer\>.makaira.io
• Makaira Instance (makairaInstance): e.g., live
• API Timeout (apiTimeout):
  • Essential default: 30
  • Frontend default: 5

Essential Module Specific

• Makaira Shared Secret (makairaSharedSecret)
• Makaira Customer (makairaCustomer)

Frontend Module Specific

🔍 Search Settings

• useForProductLists: Enable Makaira for product listings
• useForSearch: Enable Makaira search
• useForSuggest: Enable autosuggest

🎯 Recommendation Settings

• useForRecommendation: Enable recommendations
• recommendationId: ID for recommendation config
• recommendationProductLimit: Max products to return (default 10)

Configuration Steps

1. Go to Shopware Admin > Settings > Plugins.
2. Select Makaira Connect Essential or Frontend.
3. Configure per sales channel.
4. Save settings.

💡 Note: Some values must be configured per sales channel, like makairaSharedSecret and makairaInstance.

🛠️ Commands (Essential)

• makaira:persistence-layer:rebuild: Rebuild data (optional salesChannelId)
• makaira:persistence-layer:update: Push all data (optional salesChannelId)
• makaira:persistence-layer:switch: Activate rebuilt data (optional salesChannelId)

💡 Tip: Use these commands for manual control; otherwise, real-time sync happens automatically.

🧪 Development Setup

Clone & Initialize

Essential

git clone [email protected]:MakairaIO/shopware-connect-essential.git
cd shopware-connect-essential  
make init

Frontend

git clone [email protected]:MakairaIO/shopware-connect-frontend.git
cd shopware-connect-frontend  
make init

Useful Commands

• Start: make up
• Stop: make down
• SSH into container: make ssh

📢 Events

The Makaira Connect Frontend module provides several events that can be used to customize the request sent to the Makaira API. Below is a list of available events:

ModifierQueryRequestEvent

This event allows you to modify the query before it is sent to the Makaira API.

• Class: MakairaConnectFrontend\Events\ModifierQueryRequestEvent
• Namespace: MakairaConnectFrontend\Events
• Event Names:
  • makaira.request.modifier.query.search: Triggered for search queries.
  • makaira.request.modifier.query.autosuggester: Triggered for autosuggest queries.
  • makaira.request.modifier.query.category: Triggered for category-based search queries.
  • makaira.request.modifier.query.recommendation: Triggered for recommendation queries.
• Methods:
  • getQuery(): \ArrayObject: Returns the query as an ArrayObject for modification.

Usage Example:

<?php

declare(strict_types=1);

namespace YourNamespace\Subscriber;

use MakairaConnectFrontend\Events\ModifierQueryRequestEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CustomQueryModifierSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ModifierQueryRequestEvent::NAME_SEARCH => 'onSearchQueryModify',
        ];
    }

    public function onSearchQueryModify(ModifierQueryRequestEvent $event): void
    {
        $query = $event->getQuery();
        $query['customFilter'] = 'value'; // Add custom filter to the query
    }
}

🔧 Event: ModifierQueryRequestEvent (Essential)

The ModifierQueryRequestEvent provides developers with the ability to modify the query before it is sent to the Makaira API. This event can be used to customize or extend the data being sent for categories, products, variants, or manufacturers.

Event Names:

• Category: makaira.essential.request.modifier.category
• Product: makaira.essential.request.modifier.product
• Variant: makaira.essential.request.modifier.variant
• Manufacturer: makaira.essential.request.modifier.manufacturer

Example Usage:

To listen to and modify the query, create an event subscriber in your custom plugin:

<?php

declare(strict_types=1);

namespace YourNamespace\Subscriber;

use MakairaConnectEssential\Events\ModifierQueryRequestEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ModifierQuerySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ModifierQueryRequestEvent::NAME_PRODUCT => 'onModifyProductQuery',
        ];
    }

    public function onModifyProductQuery(ModifierQueryRequestEvent $event): void
    {
        $query = $event->getQuery();

        // Add location stock for Madrid and Paris
        $query['locationStock'] = [
            'Madrid' => 100,  // Example stock value for Madrid
            'Paris' => 150,   // Example stock value for Paris
        ];

        // Update the query
        $event->getQuery()->exchangeArray($query);
    }
}

💡 Note: You can subscribe to these events in your custom plugin to modify the query dynamically.