English Version

Zurück zur Übersicht

Sylius SEO Suite Pro: Installation

Diese Seite führt Dich von composer require bis zum laufenden Plugin. Die Einstellungen im Admin-Bereich findest Du auf der Seite Konfiguration.

Voraussetzungen

Prüfe vor der Installation die Versionen in der Anforderungen-Tabelle der Übersicht. Wichtig: Das Plugin läuft nur auf MySQL 8 oder MariaDB. Auf anderen Datenbanken werden die Migrationen übersprungen und die Tabellen des Plugins nicht angelegt.

Installation

Packeton

Das Plugin liegt in einem privaten Composer-Repository. Trage es in der composer.json Deines Shops ein:

{
    "repositories": [
        { "type": "composer", "url": "https://packeton.markus-michalski.net" }
    ]
}

Danach installierst Du das Paket:

composer require mmd/sylius-seo-suite-pro-plugin

Die Zugangsdaten für das Repository erhältst Du nach dem Kauf. Wie Du sie hinterlegst, zeigt der zweite Tab.

Zugangsdaten (auth.json)

Schreibe die Zugangsdaten in eine auth.json neben der composer.json (nicht ins Repository einchecken):

{
    "http-basic": {
        "packeton.markus-michalski.net": {
            "username": "<Benutzername>",
            "password": "<Token>"
        }
    }
}

Alternativ speicherst Du sie einmalig global:

composer config --global --auth http-basic.packeton.markus-michalski.net <Benutzername> <Token>

Schritt 1: Bundle registrieren

Trage das Bundle in config/bundles.php ein:

Mmd\SyliusSeoSuiteProPlugin\MmdSyliusSeoSuiteProPlugin::class => ['all' => true],

Schritt 2: Routen importieren

Lege die Datei config/routes/mmd_sylius_seo_suite_pro.yaml mit den beiden Imports an:

mmd_sylius_seo_suite_pro_admin:
    resource: "@MmdSyliusSeoSuiteProPlugin/config/routes/admin.yaml"

mmd_sylius_seo_suite_pro_shop:
    resource: "@MmdSyliusSeoSuiteProPlugin/config/routes/shop.yaml"

Die Shop-Routen musst Du auf oberster Ebene importieren, nicht unter dem /{_locale}-Präfix der Sylius-Shop-Routen. Crawler fragen /robots.txt direkt am Root des Hosts ab. Dasselbe gilt für die Route der OG-Bilder unter /seo/og/....

Die Admin-Routen liegen unter dem Pfad, den der Parameter %sylius_admin.path_name% vorgibt (Standard admin).

Fehlen die Admin-Routen, bleibt der Menüeintrag im Admin-Bereich stillschweigend aus. Das ist kein Fehler im Menü, sondern der Hinweis, dass der Import fehlt.

Schritt 3: Setup ausführen

Das Setup legt die Tabellen des Plugins an:

bin/console mmd:seo-suite-pro:setup

Der Command macht Folgendes:

• Er prüft zuerst, ob die Routen mmd_sylius_seo_suite_pro_admin_audit und mmd_sylius_seo_suite_pro_robots_txt importiert sind. Fehlen sie, gibt er den YAML-Ausschnitt aus Schritt 2 aus. In Deine config/ schreibt er nie, und der Lauf bricht dabei nicht ab.
• Er führt ausschließlich die noch offenen Migrationen dieses Plugins aus, nie die offenen Migrationen Deiner Anwendung oder anderer Plugins.
• Er ist idempotent: Doctrines Tabelle doctrine_migration_versions ist die einzige Quelle dafür, was schon gelaufen ist. Ohne neue Migration meldet er "Migrations are already up to date." und tut nichts.
• Sind noch Sylius-Core-Migrationen offen, bricht er mit einer Fehlermeldung ab. Führe dann zuerst bin/console doctrine:migrations:migrate aus und danach den Setup-Command erneut.
• Sind die Migrationen des Plugins Doctrine nicht bekannt, bricht er ebenfalls ab. Prüfe dann, ob das Bundle aktiv ist und sylius_core.prepend_doctrine_migrations nicht auf false steht.
• Im interaktiven Lauf fragt Doctrine vor dem Ausführen nach einer Bestätigung. In Skripten und Deployments übergibst Du --no-interaction.

Es entstehen neun Tabellen, alle mit dem Präfix mmd_sylius_seo_suite_pro_: Channel-Einstellungen, SEO-Templates, Schema-, hreflang- und OG-Bild-Einstellungen, Redirects, 404-Log sowie zwei Audit-Tabellen. Fremdschlüssel auf Sylius-Core-Tabellen gibt es nicht. Die Details stehen auf der Seite Technische Details.

Du kannst stattdessen auch selbst doctrine:migrations:migrate ausführen. Der Setup-Command ist die schonendere Variante, weil er nichts anderes anfasst.

Schritt 4: Assets und Cache

Das Plugin bringt keine eigenen Frontend-Assets mit, ein assets:install ist für das Plugin nicht nötig. Leere nach der Installation den Cache:

bin/console cache:clear

Schritt 5: Felder pro Produkt und Kategorie freischalten (optional)

Meta-Title, Canonical-Pfad und die Robots-Angaben pro Seite liegen als Spalten in den Übersetzungstabellen von Produkt und Kategorie. Ein Plugin kann die Doctrine-Modelle Deines Shops nicht selbst austauschen, deshalb schaltest Du diese Felder bewusst selbst frei. Das ist dieselbe Vorgehensweise, die Sylius für jedes zusätzliche Feld an Core-Modellen beschreibt.

Ohne diesen Schritt funktioniert alles andere weiter: Titel fallen auf den Namen (oder ein SEO-Template) zurück, Seiten sind index, follow, und der Admin-Bereich zeigt die Felder pro Produkt und Kategorie einfach nicht an.

1. Modelle erweitern und das Trait einbinden. Core-Produkte und -Kategorien erzeugen ihre Übersetzung fest per new, deshalb brauchen auch Product und Taxon eine Unterklasse:

// src/Entity/Product/ProductTranslation.php
namespace App\Entity\Product;

use Doctrine\ORM\Mapping as ORM;
use Mmd\SyliusSeoSuiteProPlugin\Model\SeoAwareTranslationInterface;
use Mmd\SyliusSeoSuiteProPlugin\Model\SeoAwareTranslationTrait;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_product_translation')]
class ProductTranslation extends \Sylius\Component\Core\Model\ProductTranslation implements SeoAwareTranslationInterface
{
    use SeoAwareTranslationTrait;
}

// src/Entity/Product/Product.php
namespace App\Entity\Product;

use Doctrine\ORM\Mapping as ORM;
use Sylius\Component\Product\Model\ProductTranslationInterface;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_product')]
class Product extends \Sylius\Component\Core\Model\Product
{
    protected function createTranslation(): ProductTranslationInterface
    {
        return new ProductTranslation();
    }
}

Für Kategorien gehst Du genauso vor: App\Entity\Taxon\Taxon erweitert Sylius\Component\Core\Model\Taxon (Tabelle sylius_taxon), App\Entity\Taxon\TaxonTranslation erweitert Sylius\Component\Taxonomy\Model\TaxonTranslation (Tabelle sylius_taxon_translation). Interface und Trait kommen jeweils aus dem Namespace Mmd\SyliusSeoSuiteProPlugin\Model.

2. Die Klassen als Resource-Modelle registrieren:

# config/packages/_sylius.yaml
sylius_product:
    resources:
        product:
            classes:
                model: App\Entity\Product\Product
            translation:
                classes:
                    model: App\Entity\Product\ProductTranslation

sylius_taxonomy:
    resources:
        taxon:
            classes:
                model: App\Entity\Taxon\Taxon
            translation:
                classes:
                    model: App\Entity\Taxon\TaxonTranslation

3. Migration erzeugen und ausführen. Die Spalten gehören zu Deinen Tabellen, deshalb gehört auch die Migration in Deine Anwendung und nicht ins Plugin:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

Die Migration ergänzt jede der beiden Übersetzungstabellen um vier Spalten. Das Ergebnis entspricht diesem SQL (für sylius_product_translation und sylius_taxon_translation):

ALTER TABLE sylius_product_translation
    ADD mmd_seo_suite_pro_meta_title VARCHAR(255) DEFAULT NULL,
    ADD mmd_seo_suite_pro_canonical_path_override VARCHAR(255) DEFAULT NULL,
    ADD mmd_seo_suite_pro_robots_index TINYINT(1) DEFAULT 1 NOT NULL,
    ADD mmd_seo_suite_pro_robots_follow TINYINT(1) DEFAULT 1 NOT NULL;

Die Standardwerte sind index, follow. Bestehende Seiten ändern sich durch die Migration also nicht.

Der Canonical-Pfad muss ein Pfad auf Deinem Shop sein (ein führender Slash, keine volle URL, kein //host). Das Plugin setzt Schema und Host der aktuellen Seite davor.

Optional: Meta-Description für Kategorien. Produkte haben im Sylius-Core bereits eine Meta-Description, deshalb bekommen sie kein zweites Feld. Kategorien haben keine. Um sie nachzurüsten, implementierst Du an der TaxonTranslation zusätzlich MetaDescriptionAwareTranslationInterface mit MetaDescriptionAwareTranslationTrait, und nur dort, nicht an der Produkt-Übersetzung:

use Mmd\SyliusSeoSuiteProPlugin\Model\MetaDescriptionAwareTranslationInterface;
use Mmd\SyliusSeoSuiteProPlugin\Model\MetaDescriptionAwareTranslationTrait;
use Mmd\SyliusSeoSuiteProPlugin\Model\SeoAwareTranslationInterface;
use Mmd\SyliusSeoSuiteProPlugin\Model\SeoAwareTranslationTrait;
use Sylius\Component\Taxonomy\Model\TaxonTranslation as BaseTaxonTranslation;

class TaxonTranslation extends BaseTaxonTranslation implements SeoAwareTranslationInterface, MetaDescriptionAwareTranslationInterface
{
    use SeoAwareTranslationTrait;
    use MetaDescriptionAwareTranslationTrait;
}

Deine Migration braucht dann eine weitere Spalte an sylius_taxon_translation:

ALTER TABLE sylius_taxon_translation ADD mmd_seo_suite_pro_meta_description VARCHAR(512) DEFAULT NULL;

Das Feld erscheint im Admin als einzeiliges Textfeld am Kategorie-Formular (maximal 512 Zeichen). Ohne das Feld bekommen Kategorie-Seiten keine Meta-Description, außer ein SEO-Template greift.

Update

1. Aktualisiere das Plugin:

   composer update mmd/sylius-seo-suite-pro-plugin
   

2. Führe das Setup erneut aus, weil ein Composer-Update keine Migrationen startet:

   bin/console mmd:seo-suite-pro:setup
   

3. Leere den Cache:

   bin/console cache:clear
   

Bis das Setup gelaufen ist, bleibt der Shop funktionsfähig. Fehlt eine Tabelle, verhält sich die Storefront so, als gäbe es das jeweilige Feature nicht (zum Beispiel keine Templates, ein normales 404 statt eines Redirects), und es wird eine Warnung geloggt. Nur die zugehörigen Admin-Screens antworten mit einem Fehler.

Geplante Aufgaben (Cronjobs)

Vier Commands sind für den regelmäßigen Betrieb gedacht. Der Setup-Command gehört nicht dazu, er läuft nur bei Installation und Update.

Ein Beispiel für die Crontab des Shop-Benutzers:

# SEO Suite Pro
15 2 * * *  cd /var/www/shop && php bin/console mmd:seo-suite-pro:audit:run --env=prod --no-interaction
45 2 * * *  cd /var/www/shop && php bin/console mmd:seo-suite-pro:og-image:generate --env=prod --no-interaction
30 3 * * 0  cd /var/www/shop && php bin/console mmd:seo-suite-pro:og-image:prune --env=prod --no-interaction
40 3 * * 0  cd /var/www/shop && php bin/console mmd:seo-suite-pro:redirects:prune-log --days=90 --env=prod --no-interaction

Zwei weitere Commands (redirects:export und redirects:import) sind für den manuellen Einsatz gedacht, siehe Redirects. Die Optionen der OG-Bild-Commands erklärt die Seite OG-Bilder, die des Audits die Seite SEO-Audit.

Deinstallation

Gehe in dieser Reihenfolge vor, solange das Bundle noch registriert ist:

1. Entferne Deinen eigenen Code, der das Plugin benutzt: Aufrufe der Twig-Funktionen mmd_seo_suite_pro_seo() und mmd_seo_suite_pro_json_ld(), eigene Hooks und Templates sowie eigene Klassen, die Interfaces des Plugins implementieren. Hast Du die Felder pro Produkt und Kategorie freigeschaltet, entfernst Du auch Interface und Trait aus den Übersetzungsklassen und löschst die mmd_seo_suite_pro_*-Spalten mit einer eigenen Migration.

2. Mache die Migrationen des Plugins rückgängig, mit noch registriertem Bundle, eine Version pro Aufruf und die neueste zuerst:

   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261005100000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261004160000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261004140000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261004120000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261004100000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261003140000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261003120000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusSeoSuiteProPlugin\Migrations\Version20261003100000'
   

3. Entferne die Datei config/routes/mmd_sylius_seo_suite_pro.yaml und den Eintrag in config/bundles.php.

4. Entferne das Paket:

   composer remove mmd/sylius-seo-suite-pro-plugin
   

Mit den Migrationen verschwinden alle Daten des Plugins: Channel-Einstellungen, SEO-Templates, Redirects und das 404-Log. Exportiere Deine Redirects vorher per mmd:seo-suite-pro:redirects:export, wenn Du sie behalten willst.