Lean Mapper – tenké ORM nad dibi

Ahoj,

další taková novinka se týká vylepšení chování příznaku m:passThru.

Nově se při čtení z property zaregistrovaná metoda volá bezprostředně po získání hodnoty z Row a při zapisování do property se zaregistrovaná metoda volá těsně před zapsáním do hodnoty do Row. Důsledek to má takový, že všechny další kontroly (typ property, nullable…) se aplikují až na hodnotu, která tou metodou prošla.

To především rozvazuje ruce co se typů property týče. Řekněme například, že bychom u entity Book chtěli mít nějakou informaci uloženou v databáze nestrukturovaně jako JSON v jednom sloupci, ale v aplikaci bychom chtěli pracovat s dekódovanou hodnotou – při čtení z property i při zápisu do ní.

/**
 * @property int $id
 * @property string $name
 * @property array $data m:passThru(decode|encode)
 */
class Book extends \LeanMapper\Entity
{

    /**
     * @param string $value
     */
    protected function decode(&$value)
    {
        $value = json_decode($value, true);
    }

    /**
     * @param array $value
     */
    protected function encode(&$value)
    {
        $value = json_encode($value);
    }

}

Smysl výše uvedeného kódu by měl být jasný: v databázi mám hodnotu uloženou jako JSON, ale v aplikaci při přístupu k položce data dostanu pole. Pole se do ní má také přiřazovat.

Možná jste si všimli, že v ukázce předávám parametr referencí. To je změna oproti stable verzi a také BC break. Důvod je následující: jsem přesvědčen, že příznak m:passThru se tak v 95 % případů používá pro validaci přiřazované/čtené hodnoty. A u takového použití mi ve stable verzi přichází otravné, že na závěr metody je nezbytně nutné volat return $value. Nově Lean Mapper s návratovou hodnotou nijak nepracuje a pokud ji v metodě zaregistrované přes m:passThru potřebujete změnit (jako v tom mém výše uvedeném příkladě), předejte si parametr referencí.

Nápad, že by Lean Mapper nějakým způsobem přímo rozšiřoval typy, které vrací dibi, zatím dávám k ledu. Také vznikl nápad, že by se v m:passThru volaly statické metody, ale tomu osobně nejsem moc nakloněn. Jednak si vážím toho, že se Lean Mapper aktuálně bez statických volání kompletně obejde (výjimkou je pár factory metod), a také si to každý může naimplementovat sám v __call v nějaké BaseEntity.

@Tharos: Ahoj. Když v metodě Mapper::getImplicitFilters předám anonymní filtr, tak v metodě Repository::createFluent je pak tento callback argumentem ve funkci array_key_exists() na řádku 95, která požaduje jen string nebo integer.

Použil jsem to jako v téhle ukázce . Dělám něco špatně, nebo je to neošetřený vstup?

@Tharos:

To předávání referencí se mi nelíbí. Je to zbytečný (a poměrně zásadní) BC break, který nepřidává nic nového. To, že se ti to líbí více novým způsobem podle mě není moc důvod k takovému kroku. A popravdě jsem podobný nápad nikde moc neviděl, return je prostě přímočařejší, častěji používanější a intuitivnější (IMHO). A myslím, že to neposkytuje ani výkonnostní výhody (a nebo neměřitelné). Představ si třeba, že by Nette\Forms\Container::getValues() v Nette muselo fungovat přes reference…(není nejlepší příklad)

Editoval Casper (28. 11. 2013 14:04)

@Casper:

Určitě se nebráním hezčímu řešení, pokud nějaké vymyslíme.

Motivací k provedené úpravě mi bylo hlavně to, že třeba já osobně příznak m:passThru používám v naprosté většině případů k validaci a psát return na konci takovýchto metod mě vcelku otravovalo:

protected function validateEmail($email)
{
    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
        throw new InvalidArgumentException("Invalid e-mail address given: $email.");
    }
    return $email; // tohle je pruda
}

Napadly mě následující způsoby, jak ten return u čistě validačních funkcí odstranit:

1) Automaticky detekovat, jestli metoda něco vrátila nebo ne. To je sice nejelegantnější, ale bohužel nemožné v PHP. :) Bohužel v něm neexistuje nic jako void nebo undefined a není způsob, jak odlišit, jestli metoda vrátila null nebo nic…

2) Zavést nový příznak (snad m:validate), který by se volal těsně před m:passThru a neočekávalo by se, že zaregistrovaná metoda má vrátit nějakou hodnotu. Tohle by z navržených řešení jako jediné nezpůsobilo BC break.

3) Umožnit, aby v obsahu příznaku m:passThru šlo říct, zda se u dané metody má návratová hodnota použít nebo ne. Napadlo mě následující řešení:

m:passThru(validateEmail)  návratová hodnota se nepoužívá
m:passThru(encodeValue~)  návratová hodnota se používá /tilda vyjadřuje, že hodnota má „protéct“ metodou :)/

4) Řešení skrze předání proměnné referencí.

Zatím jsem zvolil řešení 4, protože s sebou samozřejmě nenese žádný overhead (jedná se o využití něčeho, co v PHP už existuje).

Které řešení by se Ti nejvíce líbilo? Anebo Tě napadá ještě něco jiného? Díky!

Editoval Tharos (4. 12. 2013 8:00)

@Casper: Tak fajn. :) Dneska jsem o tom ještě přemýšlel a aktuálně mi řešení přes nový příznak také přijde jako nejlepší.

On by to pro někoho BC break být mohl – je totiž možné, že se trefím do názvu příznaku, který někdo používá jako vlastní příznak, ale beztak bude verze 2.1 obsahovat hned několik BC breaků, takže tohle bych prostě podstoupil.

Co ještě řeším je, jak by se ten příznak měl jmenovat. Samozřejmě se nabízí m:validate, ale metody, které v něm kdy budu registrovat, také většinou budou začínat slovem „validate“ (validateEmail, validateAge…). Není úplně hezké mít to vše pak vedle sebe: m:validate(validateEmail), m:validate(validateAge) atp.

Jak ten příznak pojmenovat? Nebo to udělat tak, že příznak m:validate u položky email bude automaticky volat metodu validateEmail? S tím, že pokud by byl uveden nějaký název metody v závorkách, použila by se ta metoda? Velmi podobně funguje m:useMethods, jen zde bych asi nezaváděl to, že by se ta metoda volala i bez uvedení příznaku (jak se děje u get<Name> a set<Name> metod).

@Michal III:

Jestli tomu dobře rozumím, tak varianta 2 by způsobovala, že by existovali 2 příznaky na tutéž věc, ovšem s rozdílem reference/return…

Víceméně ano. Mně se prostě jenom nelíbí psát na konec metody validateEmail konstrukci return $email… nemá tam žádnou logiku.

Pak mně ještě napadlo, že by se použila návratová hodnota jen v případě, že by se nezměnila vstupní hodnota coby reference, což by však bylo WTF chování

Co je ta vstupní hodnota coby reference? :)

Kdyby existovalo m:validate tak, jak jsem ho popsal výše, tak přidaná hodnota oproti použití m:passThru by v případě validace hodnoty byla, že ta validační metoda nemusí vracet hodnotu, a také to, že název validační metody vůbec nemusí být uveden (ale můžu).

Tohle by se mi i vcelku líbilo:

/**
 * @property int $id
 * @property string $email m:validate
 */
class Author extends \LeanMapper\Entity
{

    /**
     * @param string $email
     */
    protected function validateEmail($email)
    {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException("Invalid e-mail address given: $email.");
        }
    }

}

Jak vám?

Editoval Tharos (28. 11. 2013 21:47)

@Tharos:

Víceméně ano. Mně se prostě jenom nelíbí psát na konec metody validateEmail konstrukci return $email… nemá tam žádnou logiku.

Tomu rozumím. Já osobně s implementací 4 problém nemám, zvykl bych jsi. Ale mám výhodu, že jsem zasvěcen. Noví uživatelé by asi logicky předpokládali, že by se hodnota vracela přes return. Proto se mi právě docela líbil ten návrh, že by se použilo. m:passThru(&validateEmail), protože nezasvěcení by tam & nedávali, kdežto zasvěcení by věděli, co dělají.

Pak mně ještě napadlo, že by se použila návratová hodnota jen v případě, že by se nezměnila vstupní hodnota coby reference, což by však bylo WTF chování

Co je ta vstupní hodnota coby reference? :)

Tím jsem myslel tu property, která se předá jako parametr té „passThru“ funkce. Tedy chtěl bych validovat property $email, tak bych si uložil její hodnotu, pak bych ji protáhl skrz passThru a potom bych porovnal uloženou hodnotu s tou „protaženou“, jestli nedošlo ke změně, ke které by mohlo dojít pouze, pokud by callback funkce přijímala referenci. Nicméně opravdu se mi to nezdá jako šikovné řešení… (Je to patrné už při Tvé ukázce, kdy se email validuje, ale nemění.)

Kdyby existovalo m:validate tak, jak jsem ho popsal výše, tak přidaná hodnota oproti použití m:passThru by v případě validace hodnoty byla, že ta validační metoda nemusí vracet hodnotu, a také to, že název validační metody vůbec nemusí být uveden (ale můžu).

Tohle by se mi i vcelku líbilo:

/**
 * @property int $id
 * @property string $email m:validate
 */
class Author extends \LeanMapper\Entity
{

    /**
     * @param string $email
     */
    protected function validateEmail($email)
    {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
          throw new InvalidArgumentException("Invalid e-mail address given: $email.");
      }
    }

}

Jako přidanou hodnotu m:validate tedy vidím, že se nemusí uvádět jméno té funkce. Je to ale za cenu toho, že by pro téměř tutéž věc existovaly 2 příznaky. Nebo by se příznak validate používal jen a pouze na validaci, kdy by nedošlo k samotné změně hodnoty, kdežto passThru by hodnotu měnila?

Ještě jsem se nedostal k tomu, že bych používal vlastní příznaky. Zeptám se tedy, bylo by možné pomocí eventů nějak zapříčit, abych si například vytvořil vlastní příznak m:email, který by způsoboval, že se provede m:passThru(validateEmail) (m:validate)? Tohle je zrovna asi špatný příklad, ale mohla by existovat často používaná funkce v BaseEntity, kterou bych potom volal takto snadno.

Dokonce mě napadlo, že i existující příznaky (alespoň některé) by byly nějaké protected metody, které by si mohl uživatel případně dle své potřeby předefinovat sám. Nevím, jestli už nezacházím příliš daleko…

Zdravím,

lámu si tu hlavu s jednou věcí a stále ne a ne pochopit jak se k tomu dostat. Vím že to budu muset udělat v Entitě, ale netuším jak. Mám tabulku setting(id, collection_id), collection(id, name), collection_values(id, collection_id, value) a už je vám asi jasné co potřebuju. Chci vytáhnout řádek z setting a získat všechny možné values přiřazené ke kolekci. Tedy aby to pak bylo nějak takhle $setting->values ← tady potom budou řádky z collection_values.

Díky za nakopnutí.

@Tharos: Wow, tak to ja paráda! Máš u mě velké díky.

@Ripper: Nemáš vůbec zač.

Ještě mě dneska napadlo, že Ty to vlastně vůbec nemusíš řešit takhle „low level“. :) Následující řešení je ekvivalentní a já osobně bych ho určitě upřednostnil:

<?php

namespace Model\Entity;

/**
 * @property int $id
 * @property Collection $collection m:hasOne
 * @property CollectionValue[] $collectionValues m:useMethods
 */
class Setting extends \LeanMapper\Entity
{

    /**
     * @return CollectionValue[]
     */
    public function getCollectionValues()
    {
        $collectionValues = array();
        foreach ($this->collection->collectionValues as $collectionValue) {
            $collectionValues[] = $collectionValue;
        }
        return $collectionValues;
    }

}

@Casper: Pro multi insert jisté řešení existuje. Co si mám představit pod „multi update“? :) Zajímalo by mě, jak vypadá takový jeden SQL dotaz.

Přiznám se, že se mi současná podoba té persist metody docela líbí. Připadá mi hezky přehledá. Je z ní na první pohled jasné, co vše se při persistování děje, k čemu a kdy se volají metody Repository::insertIntoDatabase, Repository::updateInDatabase atp. A bojím se, aby jí nějaký „multi dotaz“ zbytečně neznepřehlednil.

@Tharos: Děkuji za navedení :-).

Jinak nestálo by za to dekomponovat __get metodu Entity do více protected či private metod, je-li to možné, aby i nadále mohl uživatel používat některou její funkcionalitu, ačkoli si get metodu entity napíše sám a nevyužije při tom anotace?

Já jsem zrovna narazil na to, že jsem potřeboval něco složitějšího a musel si tak napsat vlastní metodu v entitě, ale přitom jsem chtěl využít implicitní filtry.

@Ripper: K tomu fetchPairs: V BaseRepository si můžeš v metodě createCollection transformovat pole do nějakého objektu (například ArrayHash). Když si vytvoříš vlastní objekt, který bude dědit třeba od toho ArrayHash, můžeš si tam vytvořit funkci fetchPairs sám.

Editoval Michal III (1. 12. 2013 15:22)

@Ripper: Můj objekt pro kolekci vypadá zhruba takto (respektive v současné době ho mám trochu komplikovanější, ale tahle triviální implementace postačí):

namespace Model;

use Nette\ArrayHash;

class Collection extends ArrayHash
{

    /**
     * Creates $key => $value pairs from entity collection.
     *
     * @param string|NULL $key
     * @param string $value
     * @return array
     */
    public function fetchPairs($key, $value)
    {
        $pairs = array();

        foreach ($this as $entity) {
            if ($key === NULL) {
                $pairs[] = $entity->$value;
            } else {
                $pairs[$entity->$key] = $entity->$value;
            }
        }
        return $pairs;
    }
}

V BaseRepository mám potom toto:

protected function createCollection(array $entities)
{
    return Collection::from($entities);
}

Co se týče konvencí pojmenování tabulek a sloupců, lze to vyřešit v mapperu takto:

/**
 * Converts camelConvention to snake_convetion.
 *
 * @param string $str
 * @return string
 */
public static function camel2Snake($str)
{
    return strtolower(preg_replace('/(?<=[a-z])([A-Z])/', '_$1', $str));
}

/**
 * Converts snake_convetion to camelConvention.
 *
 * @param string $str
 * @return string
 */
public static function snake2Camel($str)
{
    $words = explode('_', $str);
    $return = $words[0];
    unset($words[0]);
    foreach ($words as $word) {
        $return .= ucfirst($word);
    }
    return $return;
}

public function getColumn($entityClass, $field)
{
    return self::camel2Snake($field);
}

public function getEntityField($table, $column)
{
    return self::snake2Camel($column);
}

public function getEntityClass($table, \LeanMapper\Row $row = null)
{
    $class = '';
    switch ($table) {
        default:
            if (strpos($table, $this->defaultTablePrefix) === 0) {
                $class = ucfirst(self::snake2Camel(substr($table, strlen($this->defaultTablePrefix))));
            } else {
                return parent::getEntityClass($table, $row);
            }
    }

    return "$this->defaultEntityNamespace\\$class";
}

public function getTableByRepositoryClass($repositoryClass)
{
    $matches = array();
    if (preg_match('#([a-z0-9]+)repository$#i', $repositoryClass, $matches)) {
        $table = self::camel2Snake($matches[1]);
        switch ($table) {
            default:
                return $this->defaultTablePrefix . $table;
        }
    }
    throw new InvalidStateException('Cannot determine table name.');
}

Toto by mělo zajišťovat převod název tabulek a sloupců z foo_bar na fooBar a obráceně.

PS. omlouvám se za ten kód toho mapperu. Je to vytržené z jednoho projektu, takže se ve Tvém případě nejspíše dá celkem obejít bez operování s defaultTablePrefix, sloužící pro nastavení výchozího prefixu tabulek.

@Ripper: Není zač :-). Pokud si definuješ vazební property v anotacích přes příznaky m:hasMany nebo m:belongsToMany, tak se k ní dostaneš $setting->collectionValues->fetchPairs('key', 'value') (o to se postará právě funkce createCollection v BaseRepository. Pokud je definuješ pomocí metod, jako jsi to řešil výše, musíš se o to postarat sám asi takto:

/**
 * @return CollectionValue[]
 */
public function getCollectionValues()
{
    $collectionValues = array();
    foreach ($this->collection->collectionValues as $collectionValue) {
        $collectionValues[] = $collectionValue;
    }

    // Právě zde převedeš pole $collectionValues na Tvou kolekci.
    return \Model\Collection::from($collectionValues);
}

@Michal III:

Jinak nestálo by za to dekomponovat __get metodu Entity do více protected či private metod, je-li to možné, aby i nadále mohl uživatel používat některou její funkcionalitu, ačkoli si get metodu entity napíše sám a nevyužije při tom anotace?

Já jsem zrovna narazil na to, že jsem potřeboval něco složitějšího a musel si tak napsat vlastní metodu v entitě, ale přitom jsem chtěl využít implicitní filtry.

Sestavování implicitních filtrů by pravděpodobně dekomponovat šlo, podívám se na to.

Narazil jsi v praxi ještě na něco, co jsi musel překopírovávat z Entity?

Jsem nakloněn „dekomponování v rámci možností“, přičemž bych se ale rád primárně zaměřil na ty části, u kterých to má reálný smysl.

Napadla mě jedna taková věc…

Nyní existují metody Repository::createCollection a také „duplicitní“ Entity::createCollection, což není vůbec hezké a už nějakou dobu mě to štve. Jednoduchým řešením by samozřejmě bylo vytvoření nějaké ICollectionFactory, kterou by si každý naimplementoval podle gusta, ale vzniklou „službu“ by zase bylo zapotřebí všude možně injektovat a ono je to bez DI kontejneru docela otrava.

Dlouho nebylo, kam tu metodu „šoupnout“, ale došlo mi, že teď už přece je: co takhle rozšířit IEntityFactory o metodu createCollection? Ta by fungovala identicky jako současné Repository::createCollection či Entity::createCollection (ty bych samozřejmě zrušil).

Výhody

• Nepovede to k duplicitám v kódu
• Výhodně se využije již hotového injektování závislostí
• Zmizí „ošlivá“ template method z Entity a Repository (každý eliminovaný výskyt toho vzoru považuji za bod k dobru)

Nevýhody

• BC break :)

Osobně bych s přítomností takové metody v IEntityFactory neměl nejmenší problém, protože tam má svou logiku.

Editoval Tharos (2. 12. 2013 20:46)

BC breaky bych neřešil. Kromě pár nadšenců je aktuální LM těžko pokročile použitelné (dokud nebude dokumentace), takže verze 2.x se klidně ještě může dopilovávat.

@Michal III: Nicméně, dám sem ještě jednu podobu té metody:

<?php

namespace Model\Entity;

use LeanMapper\Caller;
use LeanMapper\Filtering;

/**
 * @property int $id
 * @property-read ContactPerson[] $contactPersons m:belongsToMany m:useMethods
 */
class Organization extends \LeanMapper\Entity
{

    public function getContactPersons()
    {
        $property = $this->getCurrentReflection()->getEntityProperty('contactPersons');
        $entityClass = $property->getType();
        $implicitFilters = $this->createImplicitFilters($entityClass, new Caller($this, $property));

        $relationship = $property->getRelationship();
        $rows = $this->row->referencing($relationship->getTargetTable(), $relationship->getColumnReferencingSourceTable(), new Filtering($implicitFilters->getFilters(), null, $this, $property, $implicitFilters->getTargetedArgs()));
        $value = array();
        foreach ($rows as $row) {
            $entity = $this->entityFactory->createEntity($entityClass, $row);
            $entity->makeAlive($this->entityFactory);
            $value[] = $entity;
        }
        return $this->entityFactory->createCollection($value);
    }

}

Tohle řešení super výhodně spojuje sílu anotací a metod. Ty si nadefinuješ vazbu v anotaci, čímž za Tebe PropertyFactory určí název tabulky, vazebního sloupce, název cílové entity… a pak to v té metodě jenom zužitkuješ.

Tohle řešení netrpí nedostatky, kterými trpělo předchozí řešení („hard coded“ názvy). Jelikož máš v rukou reflexi property, velmi snadno se sestaví plnohodnotný Caller i Filtering (které také o reflexi té property má zájem, protože se eventuálně může auto-wirovat do nějakého filtru).

No, doufám, že jsem názorně předvedl další silné stránky Lean Mapperu. I v těchto věcech je totiž velmi flexibilní.

Edit: Opravil jsem tunu překlepů v obou mých posledních příspěvcích. :)

Editoval Tharos (2. 12. 2013 23:32)

@Tharos: Ano, je to srozumitelné :-). Mnohokrát děkuji za vysvětlení. Myslím, že co se týče rozčlenění té __get metody, takto je to opravdu dostačující. Pokud ještě někdy na něco podobného narazím, určitě se ozvu. Ono má opravdu smysl dekomponovat pouze to, co má smysl, a je asi opravdu těžké uvědomit si to bez nějakého use case. Ještě jednou děkuji.

Ještě se zeptám, jestli má smysl měnit obsah těch get<Name>Value metod? Jestli by neměly být final.

@Michal III:

Ještě se zeptám, jestli má smysl měnit obsah těch get<Name>Value metod? Jestli by neměly být final.

U nich už si nedokážu moc dobře představit, k čemu by bylo jejich přetížení dobré.

Kolem poledne jsem ještě provedl drobnou revizi… API těch get<RelationshipType>Value metod nebylo uzpůsobené k tomu, aby se staly protected. Předávalo se jim pár parametrů z jakýchsi mikro-optimalizačních důvodů – $targetTable i $relationship jde zjistit z Property, ale optimalizace spočívá v tom, že se to nezjišťuje znovu, když už se to zjišťovalo v Entity::__get… Z toho důvodu také bylo možné těm metodám dodat nesmyslná data, například zavolat getHasOneValue s Property s vazbou M:N… Což samozřejmě u neprivátních už metod vadí.

A proto vznikla metoda Entity::getValueByPropertyWithRelationship, která je protected a tohle optimálně řeší. Až tahle metoda volá relevantní get<RelationshipType>Value, které prostě zůstávají privátní.

Diskutovanou entitu lze tedy finálně zapsat následovně:

<?php

namespace Model\Entity;

use LeanMapper\Caller;
use LeanMapper\Filtering;

/**
 * @property int $id
 * @property-read ContactPerson[] $contactPersons m:belongsToMany m:useMethods
 */
class Organization extends \LeanMapper\Entity
{

    public function getContactPersons()
    {
        $property = $this->getCurrentReflection()->getEntityProperty('contactPersons');
        $entityClass = $property->getType();
        $implicitFilters = $this->createImplicitFilters($entityClass, new Caller($this, $property));
        $filtering = new Filtering($implicitFilters->getFilters(), null, $this, $property, $implicitFilters->getTargetedArgs());

        return $this->getValueByPropertyWithRelationship($property, $filtering);
    }

}

Což považuji za optimální výsledek. Všimněte si, že jediná „hard coded“ informace v té metodě je název property při získávání reflexe.

Entity::__get velmi prokoukla. Jsem s její podobou vcelku spokojen a víc už do těchto magických metod vrtat nebudu (__set jsem vylepšoval nedávno, o tom sem taky ještě něco napíšu). To, co je teď v develop větvi, je de facto ready k testování/používání. :)

Editoval Tharos (3. 12. 2013 14:00)

@Tharos: Paráda, jsem rovněž spokojen. Děkuji.

@Michal III: Je super, že o tom píšeš. Já totiž zavádějící chybové hlášky beru skoro jako bug a snažím se je kontinuálně eliminovat. Takže na tohle se určitě podívám.

Jinak mi s tím pomáhá Casper, od kterého mám na toto téma otevřenou issue. Jakmile v praxi narazíš na jakoukoliv chybovou hlášku, která není na první pohled srozumitelná, klidně mi o tom dej vědět.

@Tharos: Skvělé! Děkuji :-).

@Michal III: Není zač. :) Už jenom pár drobností a konečně otevřu release větev 2.1. Vlastně už mám na seznamu jenom jedinou věc, a tou je dopilování m:passThru příznaku…

Plus kdybyste ještě někdo něco měli na srdci do verze 2.1, sem s tím… :)