PHPackages dschuppelius/php-common-toolkit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. dschuppelius/php-common-toolkit ActiveLibrary[Utility & Helpers](/categories/utility) dschuppelius/php-common-toolkit =============================== Project description. v1.23.1(2w ago)13.3k↑745.5%5MITPHPPHP >=8.1 <8.6CI passing Since Mar 10Pushed 1mo ago2 watchersCompare [ Source](https://github.com/DSchuppelius/php-common-toolkit)[ Packagist](https://packagist.org/packages/dschuppelius/php-common-toolkit)[ RSS](/packages/dschuppelius-php-common-toolkit/feed)WikiDiscussions main Synced 1w ago READMEChangelog (10)Dependencies (26)Versions (181)Used By (5) php-common-toolkit ================== [](#php-common-toolkit) General-purpose PHP utility toolkit providing platform-agnostic helpers, CSV processing, and executable wrappers. [![PHP](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://php.net)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE) --- Features -------- [](#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 --- Architecture ------------ [](#architecture) ``` src/ ├── Builders/ # Fluent document builders (CSV, XML) ├── Contracts/ # Abstract base classes and interfaces ├── Entities/ # Immutable domain models (CSV, Executables, XML) ├── Enums/ # Typed enums with factory methods ├── Generators/ # Code generators ├── Helper/ # Utility classes (Data, FileSystem, Shell) ├── Parsers/ # Document parsers (CSV) └── Traits/ # Reusable traits ``` --- Requirements ------------ [](#requirements) The following tools are required to successfully run `dschuppelius/php-common-toolkit`: ### 1. TIFF Tools [](#1-tiff-tools) Required for processing and handling TIFF files. - **Windows**: [GnuWin32 TIFF Tools](https://gnuwin32.sourceforge.net/packages/tiff.htm) - **Debian/Ubuntu**: ``` apt install libtiff-tools ``` ### 2. Xpdf [](#2-xpdf) Required for handling PDF files. - **Windows**: [Xpdf Download](https://www.xpdfreader.com/download.html) - **Debian/Ubuntu**: ``` apt install xpdf ``` ### 3. ImageMagick [](#3-imagemagick) For converting and processing image files. - **Windows**: [ImageMagick Installer](https://imagemagick.org/archive/binaries/ImageMagick-7.1.1-39-Q16-HDRI-x64-dll.exe) - **Debian/Ubuntu**: ``` apt install imagemagick-6.q16hdri ``` ### 4. muPDF Tools [](#4-mupdf-tools) For processing PDF and XPS documents. - **Debian/Ubuntu**: ``` apt install mupdf-tools ``` ### 5. QPDF [](#5-qpdf) For advanced PDF manipulation and processing. - **Windows**: [QPDF Download](https://github.com/qpdf/qpdf/releases) - **Debian/Ubuntu**: ``` apt install qpdf ``` ### Install the Toolkit into your Project [](#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](http://getcomposer.org). ``` composer require dschuppelius/php-common-toolkit ``` --- Usage Examples -------------- [](#usage-examples) ### Value Objects [](#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()`. ``` use CommonToolkit\Enums\CurrencyCode; use CommonToolkit\ValueObjects\{Decimal, ExchangeRate, Money, Percentage, Quantity}; // Decimal: exakte bcmath-Arithmetik, kein float Decimal::of('0.1')->plus(Decimal::of('0.2'))->getValue(); // "0.3" Decimal::of('1.234,56')->getValue(); // "1234.56" (DE-Format) Decimal::of('10')->dividedBy(Decimal::of('3'), 2)->getValue(); // "3.33" // Percentage: delegiert Geldrechnung an Money $vat = Percentage::of(19); $vat->amountOf(Money::of('8.15', CurrencyCode::Euro))->getAmount(); // "1.55" $vat->addTo(Money::of('100.00', CurrencyCode::Euro))->getAmount(); // "119.00" // Quantity: Menge + Einheit, Arithmetik nur bei gleicher Einheit $hours = Quantity::of('2,5', 'h')->plus(Quantity::of('0.25', 'h')); $hours->format(); // "2,75 h" // ExchangeRate: eindeutige Kursrichtung, ISO-Zielskala $rate = ExchangeRate::of(CurrencyCode::Euro, CurrencyCode::SwissFranc, '0.9385'); $rate->convert(Money::of('100.00', CurrencyCode::Euro))->getAmount(); // "93.85" ``` ``` use CommonToolkit\ValueObjects\{DateRange, DateTimeRange, EmailAddress, Iban, PhoneNumber}; // DateRange: Kalendertage, beidseitig inklusiv $july = DateRange::fromStrings('2026-07-01', '2026-07-31'); $july->calendarDays(); // 31 $july->contains(new DateTimeImmutable('2026-07-31')); // true // DateTimeRange: halboffen [start, end) — Folgebuchungen überlappen nicht $morning = DateTimeRange::between(new DateTimeImmutable('08:00'), new DateTimeImmutable('12:00')); // Sensible Identifikatoren: validiert, maskierbar, kein implizites Leaken $iban = Iban::of('de89 3704 0044 0532 0130 00'); $iban->formatted(); // "DE89 3704 0044 0532 0130 00" $iban->masked(); // "DE89XXXXXXXXXXXXXX3000" EmailAddress::of('Max@EXAMPLE.com')->masked(); // "m**@example.com" PhoneNumber::of('089 / 12 34 56 78')->getValue(); // "+498912345678" (E.164) ``` ``` use CommonToolkit\ValueObjects\{ByteSize, Duration, Gtin, IpAddress}; // Gtin: EAN/UPC mit Prüfziffer (Längen 8/12/13/14) $gtin = Gtin::of('4006381-333931'); $gtin->getValue(); // "4006381333931" $gtin->toGtin14(); // "04006381333931" (Prüfziffer bleibt gültig) // IpAddress: sensibel — kein implizites Leaken, DSGVO-Anonymisierung $ip = IpAddress::of('192.168.2.77'); $ip->isPrivate(); // true $ip->anonymized()->getValue(); // "192.168.2.0" (/24; IPv6: /48) // ByteSize: exakte Bytes statt float-Umrechnung ByteSize::parse('1,5 GB')->getBytes(); // 1610612736 ByteSize::ofBytes(1572864)->format(); // "1.5 MB" // Duration: exakte Sekunden für Zeiterfassung und Salden $work = Duration::of(8, 30); $work->toClock(); // "8:30" $work->minus(Duration::ofHours(9))->toClock(); // "-0:30" Duration::fromIso8601('PT8H30M')->equals($work); // true ``` ### CSV Processing [](#csv-processing) ``` use CommonToolkit\Builders\CSVDocumentBuilder; $document = CSVDocumentBuilder::create() ->setDelimiter(';') ->setEnclosure('"') ->addHeaderLine(['Name', 'Amount', 'Date']) ->addDataLine(['Max Mustermann', '1000.00', '2025-01-15']) ->addDataLine(['John Doe', '2500.00', '2025-01-16']) ->build(); echo $document->toString(); ``` ### Bank Validation [](#bank-validation) ``` use CommonToolkit\Helper\Data\BankHelper; // IBAN Validation $isValid = BankHelper::isValidIBAN('DE89370400440532013000'); // true // BIC Validation $isValid = BankHelper::isValidBIC('COBADEFFXXX'); // true // Get Bank Name by BLZ $bankName = BankHelper::getBankNameByBLZ('37040044'); // "Commerzbank" ``` ### Bankleitzahl-/BIC-Daten (BLZ/BIC data) [](#bankleitzahl-bic-daten-blzbic-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: ``` use CommonToolkit\Helper\Data\BankHelper; // Online-Aktualisierung hart abschalten -> garantiert offline (nur ausgelieferte Datei) BankHelper::setNetworkEnabled(false); $bic = BankHelper::bicFromBLZ('10040000'); // "COBADEBBXXX" – kein Netzabruf // Effektiven Schalter abfragen (Override > config network_enabled > Default true) BankHelper::isNetworkEnabled(); // false // Zurück auf Config-Default; clearCache() setzt den Override ebenfalls zurück BankHelper::setNetworkEnabled(null); BankHelper::clearCache(); ``` **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. ### Currency Formatting [](#currency-formatting) ``` use CommonToolkit\Helper\Data\CurrencyHelper; use CommonToolkit\Enums\CurrencyCode; $formatted = CurrencyHelper::format(1234.56, CurrencyCode::Euro); // "1.234,56 €" ``` ### Enum Usage [](#enum-usage) ``` use CommonToolkit\Enums\CurrencyCode; use CommonToolkit\Enums\CountryCode; use CommonToolkit\Enums\CreditDebit; // Currency from Symbol $currency = CurrencyCode::fromSymbol('€'); // CurrencyCode::Euro // Country from Code $country = CountryCode::fromStringValue('DE'); // CountryCode::Germany // Credit/Debit from MT940 Code $creditDebit = CreditDebit::fromMt940Code('C'); // CreditDebit::CREDIT ``` ### Configured Helper mit CommandBuilder [](#configured-helper-mit-commandbuilder) Das Toolkit nutzt den `CommandBuilder` aus dem `php-config-toolkit` für elegantes Command-Building mit externen Tools: ``` use CommonToolkit\Helper\FileSystem\FileTypes\PdfFile; // PDF-Metadaten abrufen (nutzt intern pdfinfo) $metadata = PdfFile::getMetaData('/path/to/document.pdf'); echo $metadata['Title']; echo $metadata['Pages']; // Prüfen ob PDF verschlüsselt ist if (PdfFile::isEncrypted('/path/to/document.pdf')) { // PDF entschlüsseln PdfFile::decrypt('/path/to/encrypted.pdf', '/path/to/decrypted.pdf', 'password'); } // PDF validieren if (PdfFile::isValid('/path/to/document.pdf')) { echo "PDF ist gültig!"; } ``` ### Eigene Helper mit Executable-Konfiguration [](#eigene-helper-mit-executable-konfiguration) Erstelle eigene Helper-Klassen die externe Tools nutzen: ``` use CommonToolkit\Contracts\Abstracts\ConfiguredHelperAbstract; use CommonToolkit\Helper\Shell; class MyImageHelper extends ConfiguredHelperAbstract { protected const CONFIG_FILE = __DIR__ . '/../config/image_executables.json'; public static function convertToJpeg(string $input, string $output): bool { $command = self::getConfiguredCommand('convert', [ '[INPUT]' => $input, '[OUTPUT]' => $output ]); if ($command === null) { return false; } return Shell::executeShellCommand($command); } public static function isToolAvailable(string $toolName): bool { return self::isExecutableAvailable($toolName); } } ``` Mit passender Konfigurationsdatei (`config/image_executables.json`): ``` { "shellExecutables": { "tiffconvert": { "path": "tiffconvert", "required": false, "description": "ImageMagick Converter", "package": "imagemagick", "arguments": ["[INPUT]", "-quality", "85", "[OUTPUT]"] } } } ``` --- Executable Configuration ------------------------ [](#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 [](#verfügbare-methoden-in-configuredhelperabstract) MethodeBeschreibung`getConfiguredCommand($name, $params)`Baut einen Shell-Befehl mit Platzhalter-Ersetzung`getConfiguredJavaCommand($name, $params)`Baut einen Java-Befehl (java -jar ...)`isExecutableAvailable($name)`Prüft ob ein Tool verfügbar ist`getExecutablePath($name)`Gibt den konfigurierten Pfad zurück`getResolvedExecutableConfig($name, $params)`Gibt die vollständige Tool-Konfiguration zurück--- License ------- [](#license) This project is licensed under the **MIT License**. **Daniel Joerg Schuppelius**📧 ### Health Score 56 — FairBetter than 97% of packages Maintenance94 Actively maintained with recent releases Popularity25 Limited adoption so far Community19 Small or concentrated contributor base Maturity75 Established project with proven stability Bus Factor1 Top contributor holds 97.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~3 days Total 180 Last Release 14d ago Major Versions v0.9.33 → v1.02026-01-21 PHP version history (4 changes)v0.1.0PHP ^7.4 || ^8.0 v0.8PHP >=8.2 <8.5 v1.5.8.1PHP >=8.2 <=8.5 v1.5.8.2PHP >=8.1 <8.6 ### Community Maintainers ![](https://www.gravatar.com/avatar/9d648df75b8ca254b14377de6aa7c37daff5bc21e9e8742ef7687c7091c7bc94?d=identicon)[l0gtr0n](/maintainers/l0gtr0n) --- Top Contributors [![DSchuppelius](https://avatars.githubusercontent.com/u/19145058?v=4)](https://github.com/DSchuppelius "DSchuppelius (39 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/dschuppelius-php-common-toolkit/health.svg) ``` [![Health](https://phpackages.com/badges/dschuppelius-php-common-toolkit/health.svg)](https://phpackages.com/packages/dschuppelius-php-common-toolkit) ``` ### Alternatives [moodle/moodle Moodle - the world's open source learning platform 7.3k90.1k150](/packages/moodle-moodle)[aknife/ip 获取ip信息，支持ipv4和 ipv6 253.4k1](/packages/aknife-ip) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)