README

Sammlung von Hilfsfunktionen für die übrigen Schachbulle-Erweiterungen: Datumsumwandlungen für die Schachdatenbanken, ein einfacher dateibasierter Cache, eine Formularhilfe und zwei Insert-Tags.

Entwickler

Frank Hoppe

Voraussetzungen

PHP 7.4 oder neuer
Contao 4.13 oder Contao 5

Ab Fassung 2.0.0 läuft das Bundle unter beiden Contao-Versionen. Wer noch Contao 4.4 bis 4.12 einsetzt, bleibt bei 1.8.12.

Insert-Tags

Insert-Tag	Ergebnis
`{{alter::TT.MM.JJJJ}}`	Alter in vollen Jahren. Auch `MM.JJJJ` und `JJJJ` sind zulässig
`{{figur::wB}}`	Grafik einer Schachfigur; mit `{{figur::wB/32}}` in 32 Pixeln

Zu jedem Tag gibt es eine Zweitschreibweise mit dem Präfix cache_ (etwa {{cache_alter::15.03.1990}}) für Seiten, die zwischengespeichert werden.

Figurenkürzel: w bzw. s für Weiß/Schwarz, dann K König, D Dame, T Turm, L Läufer, S Springer, B Bauer.

Entfallene Tags

Die Wertungs-Tags {{dwz::…}}, {{elo::…}}, {{ftitel::…}} und {{verein::…}} sind mit Fassung 3.0.0 entfallen, ebenso die Einstellung Insert-Tag verein (Ersetzungen für Vereinsnamen). Sie fragten die abgeschaltete DeWIS-Schnittstelle mit der DeWIS-ID ab und werden vom contao-wertungsportal-bundle übernommen, dort mit der NU-Nummer als Wert. Ohne das Wertungsportal verschwinden die Tags unter Contao 4.13 kommentarlos aus der Seite; Contao 5 lässt sie als Text stehen und vermerkt „Unknown insert tag" im Systemlog.

Simple PHP Cache für Contao

Information

Die Cache-Klasse ist eine Anpassung für Contao. Sie basiert auf Simple PHP Cache.

Die Cache-Dateien liegen unter system/cache/schachbulle/. Ab Fassung 2.0.0 wird das Verzeichnis über den Container-Parameter kernel.project_dir bestimmt und steht damit auch bei Cronjobs und Konsolenbefehlen zur Verfügung.

Anwendung

<?php
    // Standardcache aktivieren, das Standardverzeichnis ist system/cache/schachbulle
    // Die Schlüssel werden in der Standardcachedatei "default" abgelegt, wenn kein Parameter
    // (hier 'Name') angegeben wird
    $cache = new \Schachbulle\ContaoHelperBundle\Classes\Cache('Name');

    // String erstellen, es sind aber beliebige Datentypen möglich - auch Objekte und Arrays
    $result = "Hallo";
    // String im Cache mit dem Schlüssel "ablage" speichern, Cachelebenszeit 3600s = 1h  
    $cache->store('ablage', $result, 3600);

    // Cache mit dem Schlüssel "ablage" laden
    $daten = $cache->retrieve('ablage');

    // Cache mit allen Schlüsseln laden
    $daten = $cache->retrieveAll();

    // Cache mit allen Schlüsseln und Metadaten laden
    $daten = $cache->retrieveAll(true);

    // Cache mit dem Schlüssel "ablage" löschen
    $cache->erase('ablage');

    // Cache mit allen Schlüsseln löschen
    $cache->eraseAll();

    // Cache mit den abgelaufenen Schlüsseln löschen
    $cache->eraseExpired();

    // Cache mit Schlüssel "ablage" auf Existenz prüfen und wenn vorhanden in Variable $result laden
    if($cache->isCached('ablage'))
    {
        $result = $cache->retrieve('ablage');
    }

    // Cache mit einem neuen Dateinamen 'Test' generieren
    // Die Schlüssel werden jetzt in dieser Datei verwaltet.
    $cache2 = new \Schachbulle\ContaoHelperBundle\Classes\Cache('Test');

    // Möglich ist der Wechsel des Cachenamens auch so, ohne ein neues Objekt anzulegen
    $cache->setCache('Test');

?>

Alter berechnen

<?php
    // Parameter $string: TT.MM.JJJJ oder MM.JJJJ oder JJJJ
    // Rückgabe: Alter in vollen Jahren, oder false wenn die Eingabe kein Datum ist
    $alter = \Schachbulle\ContaoHelperBundle\Classes\Alter::Jahre($string);
?>

Fehlt der Tag oder auch der Monat, wird auf den Monatsersten bzw. den 1. Januar aufgefüllt; das ermittelte Alter ist dann die Obergrenze.

Weitere Hilfsfunktionen (Klasse Helper)

Alle Methoden sind statisch und ohne Typangaben in der Signatur, weil sie aus rund zwanzig Erweiterungen heraus mit Werten direkt aus der Datenbank aufgerufen werden.

Datumsumwandlungen

Die Schachdatenbanken legen unvollständige Datumsangaben als Zahl ab und füllen die fehlenden Teile mit Nullen: 20260315 ist der 15. März 2026, 20260300 der März 2026, 20260000 das Jahr 2026.

<?php
    // Eingabe aus dem Backend in die Datenbankschreibweise JJJJMMTT wandeln
    // Parameter: 'TT.MM.JJJJ', 'MM.JJJJ', 'JJJJ' oder ein Unix-Zeitstempel
    $wert = \Schachbulle\ContaoHelperBundle\Classes\Helper::putDate('15.03.2026'); // 20260315

    // Datenbankwert in die Anzeigeform TT.MM.JJJJ / MM.JJJJ / JJJJ wandeln
    $anzeige = \Schachbulle\ContaoHelperBundle\Classes\Helper::getDate(20260315); // '15.03.2026'

    // Wie getDate(), aber mit ausgeschriebenem deutschen Monatsnamen
    $lang = \Schachbulle\ContaoHelperBundle\Classes\Helper::getDateString(20260315); // '15. März 2026'

    // Anfangs- und Endzeitpunkt eines Termins zu einer Anzeige zusammenfassen,
    // gleiche Bestandteile werden nur einmal genannt ('3. - 5.03.2026')
    $termin = \Schachbulle\ContaoHelperBundle\Classes\Helper::getEventdate($startdate, $enddate, true, $starttime, $endtime);
?>

Zeichenketten und Arrays

<?php
    // Namen aus der Datenbankschreibweise "Nachname,Vorname,Titel" drehen
    $name = \Schachbulle\ContaoHelperBundle\Classes\Helper::NameDrehen('Müller,Hans,Dr.'); // 'Dr. Hans Müller'

    // Startnummernlisten mit Bereichsangaben auflösen ('1,3-7,34' -> einzelne Werte)
    $nummern = \Schachbulle\ContaoHelperBundle\Classes\Helper::StringToArray('1,3-7,34');

    // String auf eine feste Anzahl Zeichen kürzen (zeichen-, nicht bytebasiert)
    $kurz = \Schachbulle\ContaoHelperBundle\Classes\Helper::StringKuerzen('Bad Wörishofen', 3); // 'Bad'

    // Mehrdimensionales Array nach mehreren Feldern zugleich sortieren
    $sortiert = \Schachbulle\ContaoHelperBundle\Classes\Helper::sortArrayByFields(
        $daten,
        array('jahrgang' => SORT_DESC, 'nachname' => array(SORT_ASC, SORT_STRING))
    );

    // Prüft, ob eine Zeichenkette gültiges UTF-8 enthält
    $istUtf8 = \Schachbulle\ContaoHelperBundle\Classes\Helper::is_utf8($text);

    // Alias für Adresszeilen über Contaos Slug-Dienst erzeugen (nur mit laufendem Container)
    $alias = \Schachbulle\ContaoHelperBundle\Classes\Helper::generateAlias('Schachverein Süd e.V.'); // 'schachverein-sued-e-v'
?>

Bildunterschriften mit Copyright

In eckigen Klammern notierte Copyright-Vermerke lassen sich aus einer Bildunterschrift herauslösen oder voranstellen:

<?php
    $unterschrift = 'Siegerehrung [Foto: Meier]';

    // Nur den Copyright-Vermerk lesen, ohne Klammern
    $copyright = \Schachbulle\ContaoHelperBundle\Classes\Helper::getCopyright($unterschrift); // 'Foto: Meier'

    // Copyright als eigenen Block voranstellen
    $html = \Schachbulle\ContaoHelperBundle\Classes\Helper::replaceCopyright($unterschrift);
    // '<div class="rechte">Foto: Meier</div>Siegerehrung'
?>

DeWIS-Vergleichsschreibweise

ANSI_gross() wandelt einen Text in Großbuchstaben um und ersetzt dabei Akzentzeichen durch ihre Grundbuchstaben, entsprechend der Schreibweise in den mit _g endenden Feldern des DeWIS-Datenbestands. Erwartet wird die Eingabe in ANSI/ISO-8859-1; die Methode dient als Vergleichsgrundlage für vorhandene DeWIS-Daten und wird deshalb trotz zweier bekannter Einschränkungen unverändert weitergeführt (siehe Kommentar in der Klasse).

Formulare ohne Contao-Formulargenerierung (Klasse Form)

Baut einfache Formulare zusammen, etwa Melde- und Suchformulare in eigenen Modulen. Die erzeugte Auszeichnung entspricht der von Contao (widget-Klassen, formbody).

<?php
    $form = new \Schachbulle\ContaoHelperBundle\Classes\Form('/melden');

    $form->addField(array('typ' => 'text', 'name' => 'nachname', 'label' => 'Nachname', 'mandatory' => true));
    $form->addField(array(
        'typ'     => 'select',
        'name'    => 'turnier',
        'label'   => 'Turnier',
        'options' => array('Jugend' => array('1' => 'U18')), // gruppiert (optgroup)
    ));
    $form->addField(array('typ' => 'submit', 'name' => 'los', 'label' => 'Absenden'));

    // Formular ausgeben
    echo $form->generate();

    // Nach dem Absenden die Werte einlesen
    if($form->validate())
    {
        $daten = $form->fetchAll(); // array('nachname' => ..., 'turnier' => ...)
    }
?>

Unterstützte Feldtypen: fieldset, hidden, text, explanation, submit, textarea, select, radio, checkbox. Der Schlüssel mandatory macht ein Feld zum Pflichtfeld, chosen bindet die mitgelieferte Chosen-Auswahlhilfe an — die JavaScript-Bibliothek selbst muss die aufrufende Erweiterung einbinden.

validate() prüft nur, ob überhaupt abgeschickt wurde (FORM_SUBMIT); eine inhaltliche Prüfung der Werte, auch bei Pflichtfeldern, übernimmt die aufrufende Erweiterung selbst.

Tests

vendor/bin/phpunit

Die Tests kommen ohne Contao aus. Läuft PHPUnit an anderer Stelle, wird die Konfiguration mitgegeben:

php ../../tools/phpunit9/vendor/phpunit/phpunit/phpunit --configuration phpunit.xml.dist

schachbulle / contao-helper-bundle

Package info

Security

Statistics