Martinus Devs - zbierka zákonov

# 11 - V ORM v query builder treba vždy k názvu stĺpca pridať aj názov tabuľky

2020-06-24T14:16:00+00:00

V CakePHP ORM v query builder treba vždy k názvu stĺpca pridať aj názov (alebo alias) tabuľky. Aby neskôr zbytočne nevznikali kolizie v názvoch stĺpcoch.

Prečo je to dôležité?

Ak chceme neskôr pridať nejakým spôsobom do query contain (join na inú tabuľku), tak treba ku stĺpcom manuálne dopĺňať názov tabuľky.

Ešte horšie je to v prípade, že sa contain pridá hromadne na veľa miest. Napríklad ak sa pridá do finder-a, ktorý je použitý na viac miestach. Alebo cez beforeFind – tak to napríklad robí TranslateBehavior. Pri bežných stĺpcoch (napr. id, created alebo modified), ktoré má veľa tabuliek, potom databáza nevie, ktorú tabuľku má použiť.

# 01 - Dodržiavať CakePHP Coding Standards

2020-02-17T13:15:50+00:00

V PHP kóde dodržiavame CakePHP Coding Standards. Všetky budúce zmeny budeme dodržiavať tiež.

# 10 - Každý argument funkcie akceptuje iba hodnoty jedného typu

2020-02-17T13:15:50+00:00

Každý argument funkcie alebo metódy musí mať definovaný iba 1 typ. Funkcie/metódy teda nesmú pre 1 argument akceptovať hodnoty rôznych dátových typov (2 a viac rôznych dátových typov).

Zákon umožňuje 1 výnimku – ak akceptovanie viacerých rôznych typov zjednodušuje navrhnuté API. A to iba za podmienky, že autor preukázateľne dokáže, že funckia bude fungovať správne pre všetky možné primitívne typy a objekty. Správne fungovanie môže byť aj exception pre nepodporované typy argumentov. Najlepší spôsob, ako autor preukázateľne dokáže, že funckia bude fungovať, sú testy.

PHP

V PHP ľahko vynútiteľné cez type hinting, takže podzákon pre PHP: Každý argument PHP funckie/metódy musí mať type hint.

Akceptovať 1 typ alebo null (v PHP type hinting s ?type) je povolené.

# 02 - Nepoužívať implicitné typové konverzie

2020-02-17T13:15:50+00:00

Implicitné typové konverzie sú niekedy zvláštne. A aj keď sa objektívne dajú vysvetliť, málokto v nich má prehľad a nikto si na všetky prípady nedáva pozor.

Jeden príklad za všetky:

var_dump("1" == "01"); // 1 == 1 -> true

Síce (subjektívne) zriedkavo, ale niekedy vyústia v zbytočné chyby, ktoré by sme nemuseli mať. Preto si používanie implicitných konverzii typov zakazujeme.

Pod implicitnými typovými konverziami myslíme:

PHP operátory sa môžu používať len s takými hodnotami/premennými, aby nedošlo k implicitnej typovej konverzii, napr.:
- logické operátory !, && alebo || sa môžu použiť iba s typom boolean,
- aritmetické operátory +, -, * alebo / sa môžu použiť iba s typmi int alebo float,
porovnávacie operátory ==, != a <> sú zakázané, treba namiesto nich použiť === a !==,
zakázané sú aj verzie funkcií, ktoré robia implicitné typové konverzie,
- napr. in_array($a, $b) alebo in_array($a, $b, false), povolené je iba volanie in_array($a, $b, true),
zakázané empty() - premenná by mala mať hodnoty iba v 1 type - tým pádom sa pre každý typ dá napísať “empty()” podmienka ručne/explicitne; a na overenie, či existuje kľúč v poli treba použiť isset(),
isset() sa môže použiť len na overenie, či v poli existuje kľúč (alebo field v objekte, alebo lokálna premenná, …), ak kľúč/field/premenná existuje, na overenie jej hodnoty treba použiť === null, !== null, alebo is_null().

Zákon umožňuje 1 výnimku - a to ak implicitné typové konverzie zjednodušujú navrhnuté API knižnice/modulu/triedy alebo implementáciu. A to iba za podmienky, že autor preukázateľne dokáže, že funkcia bude fungovať správne pre všetky možné typy/konverzie. Správne fungovanie môže byť aj exception pre nepodporované typy/konverzie. Najlepší spôsob, ako autor preukázateľne dokáže, že funkcia bude fungovať správne, sú unit testy.

Referencie:

# 03 - Na ukladanie časov a dátumov do DB používame typ TIMESTAMP alebo typ DATETIME s hodnotami v UTC

2020-02-17T13:15:50+00:00

Existujú len 2 možnosti ako správne ukladať do databázy dátumy a časy:

TIMESTAMP - lebo MySQL/MariaDB interne ukladajú hodnotu nezávislú na timezone (TODO ako?),
DATETIME s hodnotami v UTC.

Je to dôležité pre ďalšie operácie s dátami (napr. počítanie časového rozdielu medzi udalosťami, alebo zoraďovanie podľa toho, kedy udalosť nastala).

Prečo je DATETIME v UTC nezávislý na timezone?

We use UTC because it has an offset of 00:00: in other words, it has no timezone offset. Other timezones are offset from UTC, not the other way around.

Akákoľvek iná timezone môže mať offset a ten sa môže meniť (jednorazovo sa región presunie do inej tz, alebo pravidelne - letný čas). Pri ukladaní hodnôt v inej tz sa teda môžu nejaké časy preskočiť, alebo opakovať. Operácie s takými dátami sa budú robiť ťažko.

Pri preskočení času o 1 hodinu dopredu bude napr. nesprávny rozdiel medzi časmi. Reálne uplynulo 5 minút, rozdiel ale bude 1 hodina a 5 minút. Pri posunutí času o 1 hodinu dozadu sa nebudú dať časy správne chronologicky zoradiť.

UTC timezone má jediná offset 0 a navždy bude mať.

Povolené výnimky

Dátumy a časy nezávislé na timezone, napríklad:
- dátum narodenia, narodeniny (12.4.1985) - bez ohľadu na timezone, je to vždy konkrétny dátum/rok,
- sviatky, inak významné dátumy (4.7., 24.12., …),
- (fiktívny príklad) začiatok platnosti nového zákona v EU (v každej krajine začne platiť 1.10.2025 0:00 podľa lokálnej timezone krajiny) a pod.
Každý záznam/riadok ma vlastnú timezone:
- tabuľka musí obsahovať stringové fully qualified timezone name v ďalšom stĺpci.

Prečo stringové fully qualified timezone name?

Instead of a numeric offset, use a string. Specifically, use the full qualified name in the Olson database, so something like Australia/Adelaide or America/Los_Angeles. These are standardized descriptors of the timezones used in the world, and you can use these in pretty much every programming language ever used in the last few decades.

Zlý spôsob:

One way to do this is to treat this column as an integer; say, store -240 in a row to represent a shift of 4 hours (4*60 minutes). That’s cool, and it does get you closer, but again, we’re talking about a use case where it actually does matter to be as accurate as possible (and being off an hour might lead to nonsensical data). Just having a numerical offset doesn’t give you fidelity of location. Was it during Daylight Saving Time? What about comparing that to today’s time; do we account for DST or not? Also, do we need to account for changes in timezones that might have happened since that point in time?

https://zachholman.com/talk/utc-is-enough-for-everyone-right#properly-storing-timezone-aware-times

# 04 - Náhodné identifikátory majú minimálne 22 znakov v 64 znakovej abecede

2020-02-17T13:15:50+00:00

128 bitové náhodné číslo (inými slovami 128 bitov entropite) je dosť na to, aby sa nedali nikdy¹ vyskúsať všetky možnosti.

To vychádza na 22 znakov v 64 znakovej abecede. Lebo 64 znakov je 6 bitov (2^6 = 64). 6 bitov * 22 znakov = 132 náhodných bitov (na porovnanie, 6 bitov * 21 znakov je iba 126 bitov).

Dôležitý predpoklad je, aby boli naozaj náhodné.

V PHP treba použiť funkciu openssl_random_pseudo_bytes. V Martinus PHP na to máme class \Martinus\Utils\Code\StringIdentifiersGenerator.

Príkladom 64 znakovej abecedy je base 64: a-z, A-Z, 0-9, +, /. Pre potreby URL sa viac hodí nahradiť znaky + a / za niečo iné. StringIdentifiersGenerator používa znaky - a _. V 16 znakovej abecede (hexadecimálne čísla) musí byť dĺžka strignu 32 znakov (16 = 2^4, 32 * 4 = 128).

Referencie:

https://security.stackexchange.com/questions/6141/amount-of-simple-operations-that-is-safely-out-of-reach-for-all-humanity/6149#6149
https://en.wikipedia.org/wiki/Password_strength

¹ 128 náhodných bitov je dosť preto, lebo iba samotná iterácia všetkých možností bude podľa odhadov v roku 2040 vyžadovať všetku energetickú produkciu Zeme a trvať 10 rokov.

² Tip: je to dobré pravidlo aj pre náhodne generované heslá.

# 05 - Minimálne požiadavky na commit message

2020-02-17T13:15:50+00:00

VSC/Git commit message sú minimálne 2 holé vety (4 slová, 2x podmet a 2x prísudok), pričom odpovedajú na otázky:

veta: čo sa zmenilo,
veta: prečo bolo potrebné takúto zmenu spraviť.

# 06 - Time, Date a FrozenDate sú zakázané, vždy používať iba FrozenTime

2020-02-17T13:15:50+00:00

Time, Date a FrozenDate sú zakázané. Vždy treba používať iba FrozenTime. Pretože:

Time a Date sú mutable,
FrozenDate a Date nepodporujú timezone-y a zároveň majú niektoré metódy, ktoré na timezone závisia (napr. isToday()), je to Chronos bug.

Výnimka:

Historicky FrozenTime neexistoval, písali sme kód, ktorý využíval mutable Time. Ak to vyžaduje existujúci kód, je povolené použiť Time. Týka sa to hlavne ORM.

Ako najlepšie pracovať s existujúcim mutable Time?

$entity = $this->Table->get($id);
$created = new FrozenTime($entity->created);

Prečo používať immutable FrozenTime namiesto Time?

Názov je trochu menej elegantný ako Time, ale je menej náchylný na chyby, ak si ho zvykneme používať.

Vzorová situácia: $tomorrow = $now->addDay();

Time verzia:

keďže Time je mutable, dá sa mu meniť hodnota,
volanie addDay() zmení hodnotu toho objektu, na ktorom sa zavolá - čiže hodnotu objektu $now posunie o 1 deň,
zároveň ten istý objekt priradíme do premennej $tomorrow,
výsledkom je, že $now aj $tomorrow budú ukazovať na 1 inštanciu, v ktorej bude zajtrajší dátum.

FrozenTime verzia:

keďže FrozenTime je immutable, nedá sa mu meniť hodnota,
volanie addDay() teda musí vytvoriť nový objekt, do ktorého nastaví hodnotu posunutú o 1 deň,
nový objekt sa priradí do premennej $tomorrow,
výsledkom je, že $now a $tomorrow budú 2 rôzne inštancie s rôznymi hodnotami, v jednej dnešný, v druhej zajtrajší dátum,
stane sa teda to, čo by sme na pohľad očakávali.

S FrozenTime ako základnou verziou sa vyhneme týmto chybám a o nič neprídeme.

Immutable object: https://en.wikipedia.org/wiki/Immutable_object

Aj na prácu s dátumom bez času treba používať FrozenTime

Chronos Date a FrozenDate nemajú timezone (vždy sa pri vytvorení použije UTC - Chronos 1, alebo timezone servera - Chronos 2). To z istého uhla pohľadu dáva zmysel. 14. marca je proste 14. marca v USA aj v Japonsku rovnako.

Problém je, že Date a FrozenDate majú celé API rovnaké ako Time a FrozenTime. Vrátane takých funkcií, ktoré dátum porovnávajú s aktuálnym UTC dátumom a časom - napr. isToday().

// now:
// 2020-01-28 00:30:00 Europe/Bratislava
// 2020-01-27 23:30:00 UTC

$date = new FrozenDate('2020-01-28'); 
// => 2020-01-28 00:00:00 UTC

$date->isToday(); 
// => false

// Vysvetlenie: implementácia isToday():
// return $this->toDateString() === static::now($this->tz)->toDateString();

$first = $date->toDateString(); 
// => 2020-01-28

$date->tz; 
// => UTC

$now = static::now($this->tz); 
// => 2020-01-27 23:30:00 UTC

$second = $now->toDateString(); 
// => 2020-01-27

$first === $second;
// => false

Výsledkom je bug, ktorý sa deje iba 1 hodinu denne, keď nikto nepracuje, a nedá sa dobre nasimulovať ani debugovať.

Čiže ak dátum uložíme do FrozenTime s časom 00:00:00 a so správnou timezone, vyhneme sa tomuto bugu.

Ako pracovať s dátumami, ktoré nemajú timezone?

Účtovníctvo: AccountingDate

Ostatné?

🤷‍♂️

Zákon nateraz nešpecifikuje. Niektoré z možností:

môžu ostať ako stringy,
alebo si spravíme vlastný Date,
alebo použijeme FrozenTime s nejakou rozumnou timezone (napr. rozumná timezone pre moje narodeniny je taká, kde práve žijem - narodeninový email by som nemal dostať skôr alebo neskôr).

# 07 Stav meniace HTTP služby sa nesmú dať spustiť cez GET metódu

2020-02-17T13:15:50+00:00

Zmena stavu je vykonanie nejakej trvalej zmeny/operácie. Štandardne tam patrí pridanie, editácia alebo zmazanie nejakého “resource”.

HTTP služby spravené cez GET metódu by nemali robiť žiadne zo stav meniacich operácií, kvôli:

náchylnosti na druhy chýb/probémov, ktoré nemáme pod kontrolou my,
bezpečnosti používateľov.

1. Náchylnosť na chyby/problémy, ktoré nemáme pod kontrolou

HTTP služby spravené cez GET sú bežne interpretované ako read-only. Preto sa dajú link-ovať, bookmark-ovať, cache-ovať alebo refresh-ovať. Predpoklad je, že GET služby/linky sa môžu bezstarostne spúštať dookola a nič sa nestane. Cache si napríklad môže načitať novú verziu stránky, prehliadač môže zavolať bookmarknutý link aby zobrazil používateľovi náhľad stránky. Používateľ môže dookola stáčať F5/refresh, atď.

Ak teda GET služba bude meniť stav, môžu vznikať bugy, ktoré sa budú javiť vzácne a nevysvetliteľné. Napríklad používateľovi vždy záhladne zmiznú rovnaké 2 knižky z wishlistu, alebo produkty, ktoré používateľ nehodnotil, budú mať 5 hviezdičiek, atď. A jediná možná oprava je tak či tak iba prepísať operáciu na inú HTTP metódu než GET.

Aby sme teda zabránili neočakávanému správaniu, operácie, ktoré nejakým spôsobom menia stav, nesmú byť spustiteľné cez GET. Tieto operácie sa vďaka tomu nebudú dať link-ovať, bookmark-ovať, cache-ovať ani refresh-ovať. Používateľ musí explicitne stlačiť button na to, aby sa vykonali.

2. Bezpečnosť používateľov

POST, PUT, PATCH, DELETE requesty vedia mať ďalšie úrovne ochrany - napr. CSRF prevention, form tampering prevention. GET requesty ich nevedia mať. Ak teda GET requesty menia stav, vie ich zneužiť útočník (napr. vložiť sebe do stránky ako obrázky linky, ktoré vymažú wishlisty na Martinuse, hodnotia nejaký produkt, …). Jediné možné riešenie je prepísať operáciu na inú HTTP metódu než GET (a pridať CSRF ochranu).

Povolené výnimky

Ak GET služba využíva nejakú formu autentifikácie/overenia, ktorá zabráni opätovnému vykonaniu danej služby - ideálne nejaký jednorazový token, ktorý nepoužitý expiruje - napríklad schválenie dovolenky z email-u alebo rozdelenie objednávky z email-u. Proste link sa bude dať použiť iba raz a nepoužitý link expiruje.
Ak je to žiadaná feature aplikácie, ktorá sa nedá implementovať inak - napríklad link na vloženie produktu do košíka alebo link na odhlásenie.

# 08 - Podmienky musia byť napísané jednoducho

2020-02-17T13:15:50+00:00

Pod podmienkami sa myslia všetky boolean expressions. Komplikované podmienky sa ťažko čítajú, ťažko chápu a sú náchylné na chyby.

Presné pravidlá

1. V jednej podmienke je zakázané miešať AND a OR operátory

Nesprávne:

if (((!is_null($deliveryType) && $deliveryType->id == DeliveryType::POST_SK_FOREIGN) || (!is_null($deliveryAddress) && !($deliveryAddress->isSlovakia() || $deliveryAddress->isCzechRepublic()))) && (!is_null($paymentType) && $paymentType->isCash())) {
    // ...
}

Správne:

$isDeliveryForeign = !is_null($deliveryType) 
    && $deliveryType->id == DeliveryType::POST_SK_FOREIGN;

$isAddressForeign = !is_null($deliveryAddress) 
    && !$deliveryAddress->isSlovakia() 
    && !$deliveryAddress->isCzechRepublic();

$isOrderForeign = $isDeliveryForeign || $isAddressForeign;

$isPaymentCash = !is_null($paymentType) && $paymentType->isCash();

if ($isOrderForeign && $isPaymentCash) {
    // ...
}