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

před 2 lety od David Grudl  

S potěšením oznamujeme vydání Nette Utils 4.0! Tato aktualizace přináší mnoho novinek a posun v programátorském stylu, které si nyní podrobně představíme. Zároveň by měla být plně kompatibilní s předchozí verzí, krom odstranění několika zastaralých funkcí a úprav Finderu.

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::PRETTYpretty, Json::ESCAPE_UNICODE → asciiSafe
  • Json::decode(): Json::FORCE_ARRAYforceArrays
  • Arrays::grep(): PREG_GREP_INVERTinvert
  • Image::resize(): Image::SHRINK_ONLYshrinkOnly
  • Strings::split(), match(), matchAll():
    • PREG_SPLIT_NO_EMPTYskipEmpty
    • PREG_OFFSET_CAPTUREcaptureOffset
    • PREG_UNMATCHED_AS_NULLunmatchedAsNull
    • PREG_PATTERN_ORDERpatternOrder

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"