RandomStringManager

1. Einleitung

Der RandomStringManager ist ein einfach zu handhabendes Tool des APF, womit der Entwickler schnell und einfach zufällige formatierte und unformatierte Zeichenfolgen erzeugen kann. Die zu verwendenen Zeichen sowie die Länge des Endergebnisse können vom Entwickler konfiguriert werden. Sofern keine Konfiguration mitgegeben wird, wird ein interner Standardwert genutzt.

Sonderzeichen werden immer UTF-8 codiert zurück gegeben. Eine individuelle Einstellung ist im Moment nicht möglich.

2. Erstellung zufälliger Zeichenfolgen

Der RandomStringManager enthält zwei Methoden zur Erstellung zufälliger Zeichenfolgen (Strings):

  • createHash()
  • advancedCreateHash()

2.1. Standardwerte

Werden dem RandomStringManager keine speziellen Definitionen über den Initialisierungs-Parameter übergeben, verwendet er folgende Standardwerte:

  • Zeichenfolge: 1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
  • Länge: 16

Das bedeutet, dass eine Zeichenfolge der Länge 16 Zeichen aus den möglichen Zeichen 1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ erstellt wird.

2.2. Methode createHash()

Die Methode createHash() erstellt bei jedem Aufruf eine zufällige Zeichenkette und gibt diese zurück. Nachfolgend ein Anwendungsbeispiel:

PHP-Code
// Initialisierung des Managers $randomString = $this->getAndInitServiceObject( 'APF\tools\string\RandomStringManager', array('length' => '10') ); // Zeichenkette erstellen $hash = $randomString->createHash();

Die obige Code-Box kann wie folgt interpretiert werden:

Zur Erstellung werden die Zeichen 1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ verwendet. Dies entspricht dem Standardwert da keine andere Konfiguration vergegeben wurde. Die Länge ist auf 10 Zeichen festgelegt. Ein Ergebnis wäre damit beispielsweise kJ9i7zjC98.

2.3. Methode advancedCreateHash()

Ein weiterer Anwendungsfall ist die Erzeugung eines für die Applikation tatsächlich eindeutigen Schlüssels. Das ist zwar durch die zufällige Erzeugung und eine entsprechend groß gewählte Länge bereits sichergestellt, trotzdem ist ein doppeltes Vorkommen möglich.

Möchte der Entwickler wirklich sicher gehen, dass es den zufälligen String nur einmal gibt, kann die erweitere advancedCreateHash()-Methode verwendet werden. Diese führt nach der Erstellung des String eine Datenbankabfrage nach den vorgegebenen Kriterien durch. Ist das Ergebins positiv wird ein neuer String erstellt. Erst ein negatives Ergebnis wird von der Methode zurück gegeben. Somit kann der Entwickler sicher sein, dass es den String nur einmal gibt.

Die folgende Box zeigt die Anwendung der genannten Methode:

PHP-Code
// Initialisierung des Managers $randomString = $this->getAndInitServiceObject( 'APF\tools\string\RandomStringManager', array('chars' => '0123456789ABCDEF', 'length' => 3) ); // Zeichenkette erstellen und Abgleich mit Datenbank $hash = $randomString->advancedCreateHash('SELECT id,allHex FROM hexcode WHERE allHex =', 'database-1');

Die obige Code-Box kann wie folgt interpretiert werden:

Der Methode advancedCreateHash() müssen zwei weitere Parameter übergeben werden. Das erste Statement ist die SQL-Abfrage, die durchgeführt wird, um zu überprüfen, ob der String bereits existiert. Das zweite Statement legt den ConnectionKey für die Datenbank-Verbindung fest. Details dazu können Sie im Kapitel ConnectionManager nachlesen.

Zur Erstellung werden die Zeichen verwendet 0123456789ABCDEF verwendet. Die Länge ist auf 3 Zeichen festgelegt. Ein Ergebnis wäre damit beispielsweise 0DF.

3. Erstellung von zufälligen Zeichenketten mit Formatierung (Seriennummer)

Anhand des RandomStringManager können auch zufällige Zeichenfolgen mit vorgegebener Formatierung erzeugt werden. Praktische Szenarion dafür sind beispielsweise

  • Erstellung von Seriennummern
  • Erstellung von Gutschein-Codes

3.1. Standardwerte

Werden dem RandomStringManager keine speziellen Definitionen über den Initialisierungs-Parameter übergeben, verwendet er folgende Standardwerte für die Erstellung von formatierte Zeichenfolgen:

  • Zeichenfolge: 1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
  • Trennzeichen (Delimiter): -
  • Formatierung (Schema): XXX9-XX99-X99X-99XX

Die verwendeten Zeichen für das Schema werden Ihnen nachfolgend aufgezeigt und die Modifikationsmöglichkeiten erläutert:

  • X: an dieser Position wird ein zufälliger Grossbuchstabe gesetzt
  • x: an dieser Position wird ein zufälliger Kleinbuchstabe gesetzt
  • 9: an dieser Position wird eine zufällige Zahl gesetzt
  • -: an dieser Position wird das Trennzeichen gesetzt
Definition des Trennzeichens sowie verwendetes Trennzeichen müssen identisch sein! Um anstelle eines "-" ein "." zu verwenden müssen Sie das Trennzeichen zuerst definieren (Delimiter) und anschliessend die Position im Schema angeben!

Das heisst: Es wird eine Seriennummer bestehend aus 4 Blöcken, getrennt von einem "-" erzeugt, bei dem nur grosse Buchstaben sowie Zahlen zum Einsatz kommen.

3.2. Methode createSerial()

Über die Methode createSerial() wird anhand Ihrer Vorgabe oder der Standard-Definition eine zufällige Zeichenfolge mit entsprechender Formatierung zurück gegeben.
Zum Vermeiden der Verwechslungsgefahr, insbesondere in Print-Medien bedenken Sie bitte, Zeichen nicht zu verwenden, die ähnlich aussehen können:
1, i, l, L, 0, O, o

Nachfolgend ein Anwendungsbeispiel:

PHP-Code
$randomString = $this->getAndInitServiceObject('APF\tools\string\RandomStringManager', array()); echo $randomString->createSerial();

Die obige Code-Box kann wie folgt interpretiert werden:

Für die Erstellung der Seriennummer wird der Standard-Zeichensatz verwendet, da keine anders lautende Zeichenfolge übergeben wurde: 1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ. Das Schema mit Trennzeichen sieht folgend aus: XXX9-XX99-X99X-99XX. Folglich wäre ein Ergbnis beispielsweise: TZE4-YM12-Q88B-97QA

Ein weiteres Beispiel, bei dem anhand folgender Seriennummer die Konfiguration erläutert werden soll:
f.bb.rre.2964.YTCN

PHP-Code
$config = array( 'chars' => '23456789abcdefghkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ', 'delimiter' => '.', 'scheme' => 'x.xx.xxx.9999.XXXX' ); $randomString = $this->getAndInitServiceObject('APF\tools\string\RandomStringManager', $config); echo $randomString->createSerial();

Um Verwechslungsgefahr mit ähnlich aussehenden Zeichen zu vermeiden, wird der Standard-Zeichensatz durch einen Zeichensatz ohne diese Zeichen überschrieben.
Als Trennzeichen (Delimiter) wurde anstatt des "-" (Bindestrich) der "." (Punkt) angegeben.
Das Schema wird auf "x.xx.xxx.9999.XXXX" festgelegt.

4. Beziehen des RandomStringManager als DIService

Der RandomStringManager kann auch über den DIServiceManager bezogen werden. Der Vorteil dabei ist die direkte Konfiguartion on the fly, ohne Änderungen im Controller/Einsatzort des RandomStringManager vornehmen zu müssen und der sehr schlanke Aufruf.

Beispiel:

PHP-Code
$string = $this->getDIServiceObject('VENDOR\services', 'string-service'); // Erstelle Hash echo $string->createHash(); // Erstelle Seriennummer echo $string->createSerial();

Beispielkonfiguration:

APF-Konfiguration
[string-service] class = "APF\tools\string\RandomStringManager" servicetype = "SINGLETON" ; necessary configuration for creating random strings and serial numbers conf.chars.method = "setChars" conf.chars.value = "23456789abcdefghkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ" conf.length.method = "setLength" conf.length.value = "16" ; necessary configuration for creating serial numbers conf.delimiter.method = "setDelimiter" conf.delimiter.value = "-" conf.scheme.method = "setScheme" conf.scheme.value = "XXX9-XX99-X99X-99XX" ; X = big letter, , x = small letter, 9 = number, - = delimiter (must be equal to value of method setDelimiter!!) ; necessary configuration to check existing random strings in database conf.conn.method = "setConnectionKey" conf.conn.value = "database-2"

Mögliche Ausgabe:
Hash: DeHVvQVCGTHWxTu7
Seriennummer: AR2-PH26-L88Q-45MC
Für weitere Informationen bezüglich des DIServiceManager konsultieren Sie bitte die offizielle Dokumenatation sowie die Beiträge im Wiki.

Im Forum gibt es eine Diskussion zur Entstehung des RandomStringManager mit anschliessender Umlaute- und Sonderzeichen-Problematik:

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
Für diesen Artikel liegen aktuell keine Kommentare vor.