diff --git a/utils/cs/@home.texy b/utils/cs/@home.texy index 5dbdc24034..faf238ab84 100644 --- a/utils/cs/@home.texy +++ b/utils/cs/@home.texy @@ -5,6 +5,7 @@ Nástroje V balíčku `nette/utils` najdete sadu užitečných tříd pro každodenní použití: | [Callback] | Nette\Utils\Callback +| [Bezpečné přetypování |cast] | Nette\Utils\Cast | [Datum a čas |datetime] | Nette\Utils\DateTime | [Finder] | Nette\Utils\Finder | [HTML elementy |html-elements] | Nette\Utils\Html diff --git a/utils/cs/@left-menu.texy b/utils/cs/@left-menu.texy index 387fe25685..23a7f13938 100644 --- a/utils/cs/@left-menu.texy +++ b/utils/cs/@left-menu.texy @@ -1,6 +1,7 @@ Balíček nette/utils ******************* - [Callbacky |callback] +- [Bezpečné přetypování |cast] - [Datum a čas |datetime] - [Finder] - [Floats] diff --git a/utils/cs/cast.texy b/utils/cs/cast.texy new file mode 100644 index 0000000000..5cf08bc4b6 --- /dev/null +++ b/utils/cs/cast.texy @@ -0,0 +1,135 @@ +Bezpečné přetypování +******************** + +.[perex] +[api:Nette\Utils\Cast] je třída poskytující bezpečné a bezztrátové přetypování. Na rozdíl od standardních PHP operátorů přetypování vyhodí TypeError, pokud by konverze vedla ke ztrátě dat. Podporuje typy bool, int, float, string a array. + +Instalace: + +```shell +composer require nette/utils +``` + +Všechny příklady předpokládají vytvořený alias: + +```php +use Nette\Utils\Cast; +``` + + +Motivace +======== + +Běžné přetypování v PHP může být zrádné a vést k neočekávaným výsledkům: + +```php +(int) '123abc' === 123; // část vstupu byla ignorována +(int) 123.4 === 123; // dochází ke ztrátě informace +(string) 0.0 === '0'; // dochází ke ztrátě informace +(bool) false === ''; // neočekávané, jelikož (bool) true === '1' +``` + +Třída `Cast` řeší tyto problémy tím, že poskytuje striktní a bezpečné metody přetypování: + +```php +Cast::toInt('123abc'); // vyhodí TypeError +Cast::toInt(123.4); // vyhodí TypeError +Cast::toString(0.0) === '0.0'; +Cast::toString(false) === '0'; +``` + +Metody třídy `Cast` zajišťují, že: + +1. Nedojde ke ztrátě dat nebo přesnosti +2. Neplatné vstupy nejsou tiše převedeny na neočekávané hodnoty +3. Komplexní typy (např. objekty) nejsou implicitně převedeny na jednoduché typy + + +Pravidla přetypování +==================== + +Třída `Cast` funguje podobně jako nativní type-juggling v PHP, ale s několika důležitými rozdíly: + +- **přísnější kontrola řetězců:** při převodu na čísla, vyžaduje přesný formát bez dodatečných znaků +- **pole a objekty:** neumožňuje přetypování polí ani objektů na skalární typy +- **převod objektů na pole:** vrátí pole obsahující objekt +- **přesnější převod na řetězec:** + +```php +Cast::toString(false) === '0'; // (string) false === '' +Cast::toString('1.0') === '1.0'; (string) 1.0 === '1' +``` + +Tyto rozdíly činí Cast bezpečnější a předvídatelnější alternativou k nativnímu přetypování v PHP, zejména v situacích, kde je kritická integrita dat a typová bezpečnost. + +Následující tabulka shrnuje, jak jednotlivé metody přetypovávají různé typy vstupních hodnot: + +| Vstupní typ | toBool() | toInt() | toFloat() | toString() | toArray() | +|-------------|----------|---------|-----------|------------|-----------| +| bool | ✓ | ✓ | ✓ | ✓ | ✓ | +| int | ✓ | ✓ | ✓ | ✓ | ✓ | +| float | ✓ | ✓* | ✓ | ✓ | ✓ | +| string | ✓ | ✓* | ✓* | ✓ | ✓ | +| array | ✗ | ✗ | ✗ | ✗ | ✓ | +| object | ✗ | ✗ | ✗ | ✗ | ✗ | +| null | ✓ | ✓ | ✓ | ✓ | ✓ | + +✓ - Přetypování je vždy povoleno +✓* - Přetypování je povoleno pokud nedojde ke ztrátě informace +✗ - Přetypování není povoleno, vyhodí TypeError + + +Metody pro přetypování +====================== + +Třída `Cast` poskytuje následující metody pro bezpečné přetypování: + +- `toBool(mixed $value): bool` +- `toInt(mixed $value): int` +- `toFloat(mixed $value): float` +- `toString(mixed $value): string` +- `toArray(mixed $value): array` + +Každá z těchto metod má také variantu `...OrNull()`, která vrací null, pokud je vstupní hodnota null. Tedy nedochází k přetypování null: + +- `toBoolOrNull(mixed $value): ?bool` +- `toIntOrNull(mixed $value): ?int` +- `toFloatOrNull(mixed $value): ?float` +- `toStringOrNull(mixed $value): ?string` +- `toArrayOrNull(mixed $value): ?array` + + +Další metody +============ + +Třída také poskytuje obecné metody pro přetypování: + + +to(mixed $value, string $type): mixed .[method] +----------------------------------------------- +Bezpečně převede hodnotu na zadaný typ. Podporované typy jsou `'bool'`, `'int'`, `'float'`, `'string'` a `'array'`. + +```php +$result = Cast::to($value, 'int'); +``` + + +toOrNull(mixed $value, string $type): mixed .[method] +----------------------------------------------------- +Bezpečně převede hodnotu na zadaný typ, ale vrací null, pokud je vstupní hodnota null. Podporované typy jsou `'bool'`, `'int'`, `'float'`, `'string'` a `'array'`. + +```php +$result = Cast::toOrNull($value, 'int'); +``` + + +falseToNull(mixed $value): mixed .[method] +------------------------------------------ +Převede `false` na `null`, ostatní hodnoty nemění. Tato metoda je užitečná při práci se staršími PHP funkcemi, které v případě neúspěchu vracejí `false`, a umožňuje elegantně převést staré rozhraní na modernější API používající `null`. + +```php +$row = Cast::falseToNull($pdo->fetch(PDO::FETCH_ASSOC)); +if ($row === null) { + echo 'Žádné další řádky'; +} +``` diff --git a/utils/cs/helpers.texy b/utils/cs/helpers.texy index 198009371c..ef867bac20 100644 --- a/utils/cs/helpers.texy +++ b/utils/cs/helpers.texy @@ -53,13 +53,7 @@ Helpers::compare(10, '<', 20); // true falseToNull(mixed $value): mixed .[method] ------------------------------------------ - -Převádí `false` na `null`, jiné hodnoty nemění. - -```php -Helpers::falseToNull(false); // null -Helpers::falseToNull(123); // 123 -``` +Použijte [Cast::falseToNull()|Cast#falseToNull]. getLastError(): string .[method]