English Version

Zurück zur Übersicht

ALTCHA: Erweiterbarkeit und Kompatibilität

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Eigene Schutzziele

Ein neues Schutzziel aus einem Plugin registrieren. Registriere am besten Mmd\SyliusAltchaPlugin\Target\ProtectionTarget direkt als Service, statt selbst ProtectionTargetInterface zu implementieren. Das Interface kann in einem Minor-Release neue Methoden bekommen, der Konstruktor von ProtectionTarget dagegen erhält am Ende höchstens optionale Parameter. Verwende benannte Argumente und einen Übersetzungs-Key als Label. Der Konstruktor hat die Parameter $code, $label, $formTypes, $routes, $events, $enabledByDefault und $requiresProof; nur $code und $label sind Pflicht:

services:
    App\Altcha\OrderFormTarget:
        class: Mmd\SyliusAltchaPlugin\Target\ProtectionTarget
        arguments:
            $code: order_form
            $label: app.altcha.target.order_form
            $events: ['app.order_form.pre_submit']
        tags: ['mmd_sylius_altcha.protection_target']

Erst der Tag bringt das Schutzziel in die Admin-Liste. Ein Service, der ProtectionTargetInterface implementiert, bekommt ihn nur dann automatisch, wenn Autoconfiguration aktiv ist.

Ein Schutzziel legt fest, wie es durchgesetzt wird: über einen Formulartyp, einen Routennamen oder ein ablehnbares Event deines Plugins. Das Event braucht getRequest(): Request und reject(?string $reason). Ein optionales getSource(): BackedEnum mit dem Wert registration oder admin nimmt diese Einstiegspunkte von der Prüfung aus. Codes mit dem Präfix custom_ sind für Formulare reserviert, die im Admin angelegt werden.

Das Widget muss im Template des Formulars platziert werden, bevor das Schutzziel angehakt wird, siehe Storefront-Integration.

Dekorieren statt ableiten

Erweitere das Verhalten, indem du die öffentlichen Interfaces dekorierst (SubmissionGuardInterface, RateLimiterInterface, ReplayGuardInterface, AltchaVerifierInterface, DisposableEmailGuardInterface, GibberishGuardInterface und weitere), statt von den Klassen zu erben.

Abwärtskompatibilität

Von Semantic Versioning abgedeckt sind:

• Die Interfaces (ProtectionTargetInterface, SubmissionGuardInterface, RateLimiterInterface, ReplayGuardInterface, AltchaVerifierInterface, ChallengeGeneratorInterface, SecretCipherInterface, AltchaSettingsProviderInterface, DisposableEmailGuardInterface, DisposableDomainListInterface, GibberishGuardInterface, GibberishScorerInterface) zusammen mit den Typen, die sie nach außen verwenden: Rejection (seine Fälle sind der reason einer Ablehnung der Shop API; in einem Minor-Release können neue Fälle dazukommen), VerificationResult, AltchaSettings und AltchaOrg\Altcha\Challenge (ein Typ aus einer Fremd-Library: Ein Major-Sprung von altcha-org/altcha ist auch für dieses Plugin ein Major-Sprung).
• Das Value-Object ProtectionTarget einschließlich seines Konstruktors: Reihenfolge und Namen der Parameter sind fest, nur optionale Parameter kommen am Ende dazu.
• Der Event-Vertrag (per Duck-Typing), den dieses Plugin von Events anderer Plugins erwartet (getRequest(): Request, reject(?string), optional getSource(): BackedEnum), und der Service-Tag mmd_sylius_altcha.protection_target.
• Die öffentlichen Methoden von ProtectionTargetRegistry (all, find, findByFormType, findByRoute, staticTargets, reset), ProtectionResolver (isProtected, isChannelEnabled), FormToken (issue, ageInSeconds) und ChannelSettingsFactory (createForChannel, generateEncryptedSecret), erreichbar über die öffentlichen Service-IDs (mmd_sylius_altcha.target_registry, .protection_resolver, .form_token, .channel_settings_factory, .secret_cipher).
• Die Namen der Twig-Funktion und der Hooks, die Routennamen, die Codes der Schutzziele (sie werden pro Channel gespeichert), die Übersetzungs-Keys und die Namen der Konsolenbefehle.

Nicht abgedeckt sind die Konstruktoren aller Klassen außer dem von ProtectionTarget, geschützte Member jeder Klasse, sonstige öffentliche Methoden sowie jede Klasse und jedes Interface mit der Markierung @internal. Auch die Persistenzschicht fällt heraus: Die Interfaces ChannelSettingsRepositoryInterface, DynamicTargetSourceInterface und DisposableDomainOverrideRepositoryInterface tragen @internal, die Entities ChannelSettings und DisposableDomainOverride zählen als sonstige Klassen. Die mitgelieferte Wegwerf-Domain-Liste ist Inhalt, keine API: Pfad, Format und die enthaltenen Domains können sich jederzeit ändern, auch in einem Patch-Release.