Nette Utils 4.0: UTF-8, Finder a pojmenované argumenty

Finder

Finder je nyní součástí Utils 4.0. Tento přesun byl logický, jelikož třída Nette\Utils\Finder patří podle namespace právě sem. Pokud jste v Composeru používali nette/finder, nyní jej můžete odstranit.

Finder byl zároveň od základu přepsaný a přináší řadu novinek, kterým se věnuje samostatný článek.

Flagy vs pojmenované argumenty

Nette Utils vylepšuje programátorský styl, a to tím, že tzv. flagy nahrazuje za pojmenované argumenty.

Co jsou to ony flagy? Jde o konstanty používané pro upřesnění chování funkce:

Json::encode($value, Json::PRETTY | Json::ESCAPE_UNICODE);

Jednou z jejich nevýhodou je, že není z API zřejmé, jaké flagy lze ve které funkci použít. Například si můžete klást otázku, zda lze Json::FORCE_ARRAY použít u Json::encode() nebo decode()? A také je s každým flagem potřeba v kódu opakovat jméno třídy.

Nette Utils 4.0 je proto nahrazují za pojmenované argumenty, které tyto nevýhody nemají:

Json::encode([1, 2, 3], pretty: true, asciiSafe: true)

Tahle změna je zcela zpětně kompatibilní, což znamená, že původní zápis stále funguje. Ale není preferovaný.

Přechod na pojmenované argumenty se týká těchto metod a flagů:

• Json::encode(): Json::PRETTY → pretty, Json::ESCAPE_UNICODE → asciiSafe
• Json::decode(): Json::FORCE_ARRAY → forceArrays
• Arrays::grep(): PREG_GREP_INVERT → invert
• Image::resize(): Image::SHRINK_ONLY → shrinkOnly
• Strings::split(), match(), matchAll():
  • PREG_SPLIT_NO_EMPTY → skipEmpty
  • PREG_OFFSET_CAPTURE → captureOffset
  • PREG_UNMATCHED_AS_NULL → unmatchedAsNull
  • PREG_PATTERN_ORDER → patternOrder

Konstanta Json::ESCAPE_UNICODE se mění na asciiSafe, které lépe vystihuje její smysl (tedy že výstup má být v rozsahu ASCII) a je konzistentní s nově doplněným parametrem htmlSafe.

Regulární výrazy v UTF-8 režimu

Vylepšená podpora UTF-8 režimu pro regulární výrazy v Nette Utils 4.0 vám zjednodušší práci s multilingválním obsahem.

Všechny metody třídy Strings pro práci s regulárními výrazy, tj. split(), match(), matchAll() a replace(), mají nový parametr $utf8, který přepne fungování do UTF-8 režimu. Také ovlivňuje i vstupní parametr $offset a výstupní hodnoty offsetů při captureOffset. Tyto hodnoty pak nebudou v bajtech, ale ve znacích, což usnadňuje další manipulaci s texty:

Strings::matchAll(
	'žluťoučký kůň',
	'~\w+~',   // \w matchuje i znaky s diakritikou
	utf8: true,
	offset: 2, // začne od znaku 'u'
	captureOffset: true,
);

/*
array (2)
   0 => array (1)
   |  0 => array (2)
   |  |  0 => 'uťoučký'
   |  |  1 => 2 // pozice 2. znak
   1 => array (1)
   |  0 => array (2)
   |  |  0 => 'kůň'
   |  |  1 => 10 // pozice 10. znak
*/

Další novinky

K dispozici je několik nových metod:

• Nette\Utils\FileSystem::unixSlashes() převede lomítka na unixová
• Nette\Utils\FileSystem::platformSlashes() převede lomítka na systémová, tj \ na windows
• Nette\Utils\Strings::ord() funkce ord() pro utf-8
• Nette\Utils\Helpers::compare() porovnání pomocí operátoru

Přidány nové parametry:

• Json::encode(): parametry $htmlSafe a $forceObjects
• Strings::split(): parametr $limit
• Strings::replace() parametery $captureOffset a $unmatchedAsNull

Rozšířil se i interface Nette\Localization\Translate (viz diff) a tato změna je zpětně kompatibilní.

Odstraněné věci

Třída Nette\Utils\Reflection poskytovala metody pro práci s typy getParameterType(), getPropertyType() a getReturnType(). Metody vznikly v době, kdy PHP nemělo union, intersection nebo nejnovější disjunctive normal form typy, se kterými už nefungují a nahradila je třída Type. Od verze 4.0 jsou tyto metody zrušené. Metoda Nette\Utils\Reflection::getParameterDefaultValue() je deprecated, protože nativní ReflectionParameter::getDefaultValue() už funguje správně.

Zrušená je proměnná Nette\Utils\Html::$xhtml.

Instalace

Pro instalaci Nette Utils 4.0 je potřeba aktualizovat i RobotLoader na verzi 4, pokud jej používáte, a odstranit balíček nette/finder:

composer remove nette/finder
composer require "nette/utils:^4.0"  "nette/robot-loader:^4.0"