README

A comprehensive PHP utility library providing type conversion, validation, formatting, and helper functions for modern PHP applications.

Requirements

PHP 8.3 or higher
nette/utils ^4.0

Installation

Install via Composer:

composer require pinkava/utils

Features

Type Converters: Safe type conversions with strict typing
Array Converters: Batch array transformations with type safety
Date/Time Utilities: Date conversion and formatting
Image Utilities: Data URI conversion for images
Byte Converters: Human-readable file size conversions
HTML Utilities: HTML attribute manipulation and tag conversion
Text Validators: String validation helpers
URL Validators: URL pattern matching and validation
Localization: Simple static translator implementation

API Documentation

Converter\Scalar

Type conversion utilities for scalar values with strict type checking.

use Pinkava\Utils\Converter\Scalar;

// String conversions
Scalar::toString(123);              // "123"
Scalar::toStringOrNull("");         // null
Scalar::toStringOrNull("hello");    // "hello"

// Integer conversions
Scalar::toInt("42");                // 42
Scalar::toIntOrNull("");            // null
Scalar::toIntOrNull("42");          // 42

// Boolean conversions
Scalar::toBool(1);                  // true
Scalar::toBoolOrNull("");           // null

// Float conversions
Scalar::toFloat("3.14");            // 3.14
Scalar::toFloatOrNull("");          // null

// Mixed conversions
Scalar::toStringOrInt("123");       // 123 (as int)
Scalar::toStringOrInt("abc");       // "abc" (as string)
Scalar::toStringOrIntOrNull("");    // null

// Import value processing (useful for CSV/Excel imports)
Scalar::processImportValue("  123  ", returnInt: true);    // 123
Scalar::processImportValue("1.234,56", returnFloat: true); // 1234.56
Scalar::processImportValue("  text  ");                    // "text"

Converter\Arrays

Batch array transformations with type safety. Supports both single-level and multi-level arrays.

use Pinkava\Utils\Converter\Arrays;

// String conversions
$data = [1 => 123, 2 => 456];
Arrays::toString($data);            // ["1" => "123", "2" => "456"]
Arrays::toStringOrNull([1, ""]);    // [0 => "1", 1 => null]

// Multi-level conversions
$nested = ["key" => ["subkey" => 123]];
Arrays::toStringMulti($nested);     // ["key" => ["subkey" => "123"]]

// Integer conversions
Arrays::toInt(["1", "2", "3"]);     // [1, 2, 3]
Arrays::toIntList(["1", "2", "3"]); // [1, 2, 3] (list)

// Mixed conversions
Arrays::toStringOrInt(["123", "abc"]);              // [123, "abc"]
Arrays::toStringOrIntOrNull(["123", ""]);           // [123, null]
Arrays::toStringOrIntOrNullMulti([["1", ""], [2]]); // [[1, null], [2]]

Converter\Date

Date and time conversion utilities with type safety.

use Pinkava\Utils\Converter\Date;

// Convert to DateTimeImmutable
Date::toDateTimeImmutable("2024-03-01");          // DateTimeImmutable object
Date::toDateTimeImmutable(new DateTimeImmutable); // Returns same object

// Nullable conversions
Date::toDateTimeImmutableOrNull("2024-03-01");    // DateTimeImmutable object
Date::toDateTimeImmutableOrNull(null);            // null
Date::toDateTimeImmutableOrNull("invalid");       // null (graceful handling)

Converter\Byte

Convert between human-readable file sizes and bytes.

use Pinkava\Utils\Converter\Byte;

// Human to bytes
Byte::human2byte("10k");         // 10240
Byte::human2byte("10K");         // 10240
Byte::human2byte("10kb");        // 10240
Byte::human2byte("10 KB");       // 10240
Byte::human2byte("1M");          // 1048576
Byte::human2byte("1G");          // 1073741824

// Bytes to human-readable
Byte::byte2human(10240);         // "10.00kB"
Byte::byte2human(10240, 0);      // "10kB"
Byte::byte2human(1048576);       // "1.00MB"
Byte::byte2human(1073741824, 1); // "1.0GB"

Converter\Image

Convert base64 data URI strings to Nette Image objects.

use Pinkava\Utils\Converter\Image;

// Convert data URI to Image
$dataUri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
$image = Image::fromDataUri($dataUri);

// Now you can use Nette\Utils\Image methods
$image->resize(100, 100);
$image->save("output.png");

Formatter\Date

Format date ranges with smart year handling.

use Pinkava\Utils\Formatter\Date;
use DateTimeImmutable;

// Same day, different times
$from = new DateTimeImmutable("2024-03-01 14:00");
$to = new DateTimeImmutable("2024-03-01 16:00");
Date::formatDateRange($from, $to); // "1. 3. 14:00 - 16:00"

// Different days, same year
$from = new DateTimeImmutable("2024-03-01 14:00");
$to = new DateTimeImmutable("2024-03-15 16:00");
Date::formatDateRange($from, $to); // "1. 3. 14:00 - 15. 3. 2024 16:00"

// Different years
$from = new DateTimeImmutable("2024-12-31 14:00");
$to = new DateTimeImmutable("2025-01-01 16:00");
Date::formatDateRange($from, $to); // "31. 12. 2024 14:00 - 1. 1. 2025 16:00"

Checker\Text

Simple text validation helpers.

use Pinkava\Utils\Checker\Text;

// Check if string is filled (not null and not empty)
Text::isFilledString("hello");  // true
Text::isFilledString("");       // false
Text::isFilledString(null);     // false

Html\Converter

Convert HTML tags to plain text representations.

use Pinkava\Utils\Html\Converter;

// Convert <br> tags to newlines
Converter::br2nl("Hello<br>World<br/>Test"); // "Hello\nWorld\nTest"

// Convert <p> tags to newlines
Converter::p2nl("<p>Paragraph 1</p><p>Paragraph 2</p>");
// "Paragraph 1\nParagraph 2"

Html\Attribute

Extract and manipulate HTML attributes.

use Pinkava\Utils\Html\Attribute;

// Extract attribute value from HTML tag
$html = '<a href="https://example.com" class="link">Click</a>';
Attribute::getValue('href', $html);  // "https://example.com"
Attribute::getValue('class', $html); // "link"

// Insert attributes into HTML tags
$html = '<img src="photo.jpg"><img src="photo2.jpg">';
Attribute::insertToHtmlTag($html, 'img', 'class', 'responsive');
// '<img src="photo.jpg" class="responsive"><img src="photo2.jpg" class="responsive">'

// Add to existing attributes
$html = '<img src="photo.jpg" class="thumb">';
Attribute::insertToHtmlTag($html, 'img', 'class', 'responsive');
// '<img src="photo.jpg" class="responsive thumb">'

Validator\Url

Regular expression patterns for URL validation.

use Pinkava\Utils\Validator\Url;

// Use patterns for validation
$pattern = Url::FacebookUrlPattern;
// '(https?:\/\/)?(www\.)?facebook\.com\/[A-Za-z0-9\.]{5,}\/?'

$instagramPattern = Url::InstagramNamePattern;
// '[a-zA-Z0-9](?:[a-zA-Z0-9._]{0,28}[a-zA-Z0-9])?'

// Example usage with preg_match
if (preg_match('#' . Url::FacebookUrlPattern . '#', $url)) {
    // Valid Facebook URL
}

Localization\StaticTranslator

Simple static translator implementing Nette's Translator interface.

use Pinkava\Utils\Localization\StaticTranslator;

// Create translator with messages
$messages = [
    'en' => [
        'hello' => 'Hello',
        'goodbye' => 'Goodbye',
    ],
    'cs' => [
        'hello' => 'Ahoj',
        'goodbye' => 'Nashledanou',
    ],
];

$translator = new StaticTranslator('cs', $messages);

$translator->translate('hello');    // "Ahoj"
$translator->translate('goodbye');  // "Nashledanou"
$translator->translate('unknown');  // "unknown" (fallback)
$translator->getLocale();           // "cs"

String\StringableString

Simple wrapper implementing Nette's HtmlStringable interface.

use Pinkava\Utils\String\StringableString;

$string = new StringableString("Hello World");
echo $string; // "Hello World"

// Useful when you need an object that implements HtmlStringable
function render(HtmlStringable $content) {
    echo $content;
}

render(new StringableString("Content"));

Development

Running Tests

composer tester

Code Quality

# PHPStan static analysis
composer phpstan

# Generate PHPStan baseline
composer phpstan:generate-baseline

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This is a proprietary library for private use.

Author

Marek Pinkava - pinkavam@gmail.com

pinkava / utils

Maintainers

Package info

Statistics

Security