Download the PHP package dschuppelius/php-common-toolkit without Composer

php-common-toolkit

General-purpose PHP utility toolkit providing platform-agnostic helpers, CSV processing, and executable wrappers.

Features

• CSV Processing: Fluent builders and parsers for CSV documents with strict field typing
• Executable Wrappers: Platform-agnostic integration with external tools (ImageMagick, TIFF tools, PDF tools)
• Helper Utilities: Bank validation (IBAN, BIC, BLZ), currency formatting, string manipulation
• Enum Support: Typed enums with factory methods (CurrencyCode, CountryCode, CreditDebit, LanguageCode)
• XML Builders: Extended DOM document builder for structured XML generation
• Bundesbank Data: Auto-downloading BLZ/BIC data with expiry tracking
• Identifier & URL Checks: StringHelper::isUuid(), WebLinkHelper::isAbsoluteIri() and ::origin() for IRI/URL validation
• Fuzzy Matching: StringHelper::similarity() returns a normalised similarity score for two strings
• iCalendar: ICalendarParser reads .ics data (folding, escapes, TZID incl. Windows names, all-day, DURATION); Document::expand() resolves series (RRULE DAILY/WEEKLY/MONTHLY/YEARLY with BYDAY/BYMONTHDAY/BYMONTH/BYSETPOS, EXDATE, RECURRENCE-ID)
• Creditor Reference (ISO 11649): CreditorReferenceHelper::create() / ::isValid() / ::format() / ::extract() — build RF references from an identifier, check MOD 97-10 digits, print in groups of four and find them in remittance text
• CEF (SIEM): CEFGenerator::line() writes Common Event Format lines with header and extension escaping
• ZIP Entry Filtering: ZipFile::readEntries() / ::skipEntry() — inspect archives entry by entry and skip unsafe or unwanted members before extraction
• Value Objects: typed wrappers such as WasteCode (European waste catalogue)
• Data URLs: DataUrlHelper::decode() / ::parse() / ::encode() — strict RFC 2397 decoding with size limit and content-based type check (e.g. signature images from a canvas)

Architecture

Requirements

The following tools are required to successfully run dschuppelius/php-common-toolkit:

1. TIFF Tools

Required for processing and handling TIFF files.

• Windows: GnuWin32 TIFF Tools
• Debian/Ubuntu:

2. Xpdf

Required for handling PDF files.

• Windows: Xpdf Download
• Debian/Ubuntu:

3. ImageMagick

For converting and processing image files.

• Windows: ImageMagick Installer
• Debian/Ubuntu:

4. muPDF Tools

For processing PDF and XPS documents.

• Debian/Ubuntu:

5. QPDF

For advanced PDF manipulation and processing.

• Windows: QPDF Download
• Debian/Ubuntu:

Install the Toolkit into your Project

The Toolkit requires a PHP version of 8.1 or higher. The recommended way to install the SDK is through Composer.

Usage Examples

Value Objects

Immutable, exakt rechnende Value Objects unter CommonToolkit\ValueObjects — Konstruktion über benannte Factories (of() wirft bei ungültiger Eingabe, tryFrom()/ofNullable() liefern null). Sensible Identifikatoren (Iban, EmailAddress, PhoneNumber, VatNumber, CreditorIdentifier, GermanTaxId, GermanTaxNumber) implementieren bewusst weder Stringable noch JsonSerializable — Klarwert nur über getValue(), Anzeige über masked().

iCalendar

CSV Processing

Bank Validation

Creditor Reference (RF, ISO 11649)

CEF Lines (SIEM)

Bankleitzahl-/BIC-Daten (BLZ/BIC data)

Die Bundesbank-Datendateien werden mit dem Paket ausgeliefert, daher funktionieren BankHelper::bicFromIBAN(), bicFromBLZ(), blzFromBIC() und checkBIC() out-of-the-box auch offline – ohne vorherigen Online-Lauf:

• data/blz-aktuell-txt-data.txt (Bankleitzahlen, ~2,3 MB)
• data/verzeichnis-der-erreichbaren-zahlungsdienstleister-data.csv (BIC-Verzeichnis)

Bei Ablauf (expiry_days in config/helper.json, Default 365 Tage) werden die Daten beim nächsten Zugriff online von bundesbank.de aktualisiert. Schlägt die Aktualisierung fehl (z.B. offline), wird die vorhandene – ggf. veraltete, aber gültige – ausgelieferte Datei weiterverwendet (Stale-Fallback) statt leerer Ergebnisse.

Den Netzzugriff kannst du programmatisch steuern:

Manuelles Aktualisieren: Die beiden Dateien in data/ können jederzeit durch die aktuellen Versionen von bundesbank.de ersetzt werden (URLs in config/helper.json unter Bundesbank.resourceurl bzw. Zahlungsdienstleister.resourceurl). Nach dem Ersetzen BankHelper::clearCache() aufrufen, falls der Prozess weiterläuft.

MIME-Typ ohne Datei (Byte-basiert)

File::mimeType() braucht einen Pfad. Liegt der Inhalt nur im Speicher (Upload, HTTP-Antwort, entpackter Archiv-Eintrag), erkennt File::mimeTypeFromContent() den Typ direkt aus den Bytes – gleiche Rückgabe-Semantik (string|false):

Erkannt wird primär über finfo::buffer(). Fehlt ext-fileinfo oder liefert es kein belastbares Ergebnis (application/x-empty, application/octet-stream), greift File::mimeTypeFromMagicBytes() – eine deterministische Magic-Bytes-Tabelle (PDF, PNG, JPEG, GIF, ZIP, TIFF, GZIP, BMP, RIFF/WebP) plus Inhaltsheuristik für XML, HTML, JSON und Text. Unbekannter Binärinhalt ergibt application/octet-stream, ein leerer String false.

Data-URLs (Bilder aus dem Browser)

Eine Zeichenfläche oder ein eingefügter Screenshot kommt als data:image/png;base64,… beim Server an – also als Eingabe vom Client. DataUrlHelper::decode() dekodiert streng, begrenzt die Größe und prüft den Typ am Inhalt, nicht an der Angabe in der URL:

Reines Base64 ohne data:-Präfix wird ebenfalls angenommen. Die Fehlermeldung bleibt Sache des Aufrufers: decode() liefert false statt einer Exception.

Currency Formatting

Enum Usage

Configured Helper mit CommandBuilder

Das Toolkit nutzt den CommandBuilder aus dem php-config-toolkit für elegantes Command-Building mit externen Tools:

Eigene Helper mit Executable-Konfiguration

Erstelle eigene Helper-Klassen die externe Tools nutzen:

Mit passender Konfigurationsdatei (config/image_executables.json):

Executable Configuration

Das Toolkit nutzt JSON-Konfigurationsdateien für externe Tools. Die Konfiguration ermöglicht:

• Platzhalter-Ersetzung: [INPUT], [OUTPUT] werden zur Laufzeit ersetzt
• Pfad-Validierung: Automatische Prüfung ob Tools installiert sind
• Cross-Platform: Unterschiedliche Pfade für Windows/Linux möglich
• Zentrale Verwaltung: Alle Tool-Konfigurationen an einem Ort

Verfügbare Methoden in ConfiguredHelperAbstract

Externe Programme und nicht vertrauenswürdige Dateien

MediaHelper, OfficeHelper, ImageCropHelper und TifFile reichen Dateien des Aufrufers an FFmpeg, LibreOffice und ImageMagick weiter. Diese Programme folgen von sich aus Verweisen im Dateiinhalt. Stammt die Datei von Dritten (Upload), kann sie den Rechner so eine eigene Datei lesen oder eine ausgehende Anfrage stellen lassen. Die Helper begrenzen das wie folgt:

FFmpeg (MediaHelper)

convert(), getAudioInfo() und getVideoInfo() starten FFmpeg mit -protocol_whitelist file,pipe vor -i. Die Eingabe ist damit eine lokale Datei: eine präparierte Playlist oder ein Container mit Verweisen öffnet weder Netz- noch Fremdprotokolle (http, tcp, concat, subfile, crypto, data …), und eine Netzadresse als $input wird abgelehnt. Wer ffmpeg-info in einer eigenen Konfiguration überschreibt, bekommt die Grenze trotzdem (eine eigene -protocol_whitelist bleibt stehen).

transcribeWhisper() reicht die Datei an Whisper weiter; Whisper startet sein eigenes FFmpeg ohne diese Grenze. Fremde Dateien deshalb vorher mit MediaHelper::convert() in WAV wandeln und die WAV-Datei transkribieren.

LibreOffice (OfficeHelper)

Jeder Aufruf startet mit einem eigenen Profil, das die Einträge aus config/libreoffice/registrymodifications.xcu trägt, und mit --norestore --nolockcheck --nodefault:

• Verknüpfte Inhalte (Bilder, Abschnitte, Tabellen, OLE) aus dem Dokument werden nicht geladen, es gibt keine vertrauenswürdigen Orte, Verknüpfungen werden nie aktualisiert.
• Makros sind abgeschaltet, die Inhaltsanbieter für Netzadressen (http/https/WebDAV, CMIS, GIO) entfernt.

Folge für die Ausgabe: verknüpfte Inhalte fehlen, eingebettete bleiben. Ohne die mitgelieferte Datei startet kein Aufruf (convert() liefert false). Den Netzwerk-Egress des Prozesses selbst kann ein Profil nicht sperren — das gehört in den Betrieb (z. B. systemd IPAddressDeny=).

ImageMagick (ImageCropHelper, TifFile)

ImageMagick wählt den Coder aus Inhalt und Endung der Datei. Eine Datei mit Bild-Endung kann so als Zeichen-, Skript- oder Dokumentformat gelesen werden (SVG/MVG mit Verweisen auf andere Dateien, PostScript über Ghostscript). Zwei Maßnahmen gehören zusammen:

1. Coder festnageln. Die crop*-Methoden und getImageDimensions() nehmen als letzten Parameter den Coder der Eingabe ("png" oder "png:"); ImageMagick liest die Datei dann ausschließlich als dieses Format. Der Coder kommt aus dem geprüften Typ der Datei, nicht aus ihrem Namen:

Ohne den Parameter bleibt das Verhalten wie bisher (ImageMagick wählt selbst) — das ist nur für Dateien aus eigener Quelle gedacht. TifFile::repair() setzt den Coder selbst (jpeg: bzw. tiff:), weil die Methode den MIME-Typ ohnehin prüft.

2. Restriktive policy.xml. Der Coder schützt nur die Eingabe selbst. Was ImageMagick darüber hinaus darf (Fremdprogramme starten, Netzadressen abrufen, Dateien per @datei oder text: lesen), regelt die Policy. Eine eigene Datei in einem eigenen Ordner ablegen und den Ordner vor dem Aufruf über MAGICK_CONFIGURE_PATH bekannt machen — die Helper starten ImageMagick über die Shell, die Umgebung des PHP-Prozesses gilt also:

ImageMagick liest diese Datei zusätzlich zur policy.xml des Systems; gibt die System-Policy einen dieser Coder ausdrücklich frei, gewinnt sie. Prüfen: MAGICK_CONFIGURE_PATH=/pfad/zum/ordner convert -list policy.

License

This project is licensed under the MIT License.

Daniel Joerg Schuppelius 📧 [email protected]

Versions

2.6 — Externe Programme gehärtet (FFmpeg, LibreOffice, ImageMagick)

• MediaHelper: FFmpeg öffnet für die Eingabe nur noch lokale Dateien (-protocol_whitelist file,pipe). Eine Netzadresse als Eingabe von convert() wird abgelehnt.
• OfficeHelper: jeder Aufruf läuft mit einem gehärteten Profil (config/libreoffice/registrymodifications.xcu) und --norestore --nolockcheck --nodefault. Verknüpfte Inhalte eines Dokuments (Bilder, Abschnitte, Tabellen) werden nicht mehr geladen, Makros nicht ausgeführt; eingebettete Inhalte bleiben. Die Profilvorlage liegt jetzt unter <tmp>/commontoolkit-lo-template-<uid>-<fingerabdruck> — das alte Verzeichnis ohne Fingerabdruck wird nicht mehr benutzt und kann gelöscht werden.
• ImageCropHelper: optionaler letzter Parameter $coder in den crop*-Methoden und getImageDimensions(); ohne ihn unverändert. TifFile::repair() liest die Eingabe mit dem Coder ihres geprüften MIME-Typs.
• Signaturen bleiben kompatibel. Einzelheiten und die empfohlene ImageMagick-Policy stehen unter „Externe Programme und nicht vertrauenswürdige Dateien“.

2.0 — Money::of() ist streng

• Money::of() wirft jetzt eine InvalidArgumentException bei Leerstring und nicht deutbarer Eingabe. Bis 1.x ergab das still 0.00 — ein falsch gelesenes Betragsfeld fiel so nie auf. Für „nicht angegeben“ gibt es Money::ofNullable() (liefert null, unverändert nachsichtig).
• Ein Währungscode in der Eingabe muss zur angeforderten Währung passen (Money::of('12.34 USD', CurrencyCode::Euro) wirft).
• Neu: Money, Percentage und Quantity lesen ihre eigene Textform ("12.34 EUR", "19.00 %", "2.500 Stk") in of()/ofNullable()/tryFrom(). Eine fremde Einheit ("2.5 kg" für Stk) gilt als nicht deutbar.

Migration: Aufrufer, die leere oder fremde Strings an Money::of() geben, auf Money::ofNullable() umstellen oder den Fall vorher behandeln.

Releases are tagged in Git; git tag --sort=-v:refname lists them (latest: v2.6.1). There is no separate changelog file — the tags and the commit history are the record.