Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/unimapper/flexibee

Flexibee integration with Unimapper
https://github.com/unimapper/flexibee
adapter api flexibee orm unimapper
Last synced: about 2 months ago
JSON representation
Flexibee integration with Unimapper
Host: GitHub
URL: https://github.com/unimapper/flexibee
Owner: unimapper
License: mit
Created: 2014-02-12T15:53:31.000Z (almost 11 years ago)
Default Branch: master
Last Pushed: 2016-01-12T15:48:29.000Z (almost 9 years ago)
Last Synced: 2024-04-20T14:28:08.659Z (9 months ago)
Topics: adapter, api, flexibee, orm, unimapper
Language: PHP
Homepage:
Size: 126 KB
Stars: 8
Watchers: 7
Forks: 5
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        UniMapper Flexibee extension

============================

Flexibee API integration with [UniMapper](http://unimapper.github.io).

[![Build Status](https://secure.travis-ci.org/unimapper/flexibee.png?branch=master)](http://travis-ci.org/unimapper/flexibee)

# Usage

```php

$config = [

    // Required

    "host" => "http://localhost:5434"

    "company" => "name"

    // Optional authentization

    "user" => ,

    "password" => ,

    // Optional SSL version

    "ssl_version" => 3

];

$adapter = new UniMapper\Flexibee\Adapter($config);

// Create new contacts

$response = $adapter->put("adresar.json", ["adresar" => ["sumCelkem" => ....]);

// Read every created contact detail

foreach ($response->results as $result) {

    $adapter->get("adresar/" . $result->id . ".json");

}

```

For more inromation see the docs on official [Flexibee](http://www.flexibee.eu) site.

# Příklady z praxe

Takhle může být zadefinovaná evidence *objednavka-prijata* v plné kráse. Seznam všech lze najít například na https://demo.flexibee.eu/c/demo/evidence-list

## Entity

```

cashInvoices as $invoice) {

            $invoices[] = $invoice;

        }

        foreach ($this->advanceInvoices as $invoice) {

            $invoices[] = $invoice;

        }

        return $invoices;

    }

```

#### Doporučení

- **Identifikátory (zde například ID objednávky, addressBookId, ...) definujte VŽDY typu string.** Unimapper preferuje textový identifikátor z Flexibee před číselným. Tj. pokud si necháme vylistovat objednávky z Flexibee, jako ID dorazí něco ve stylu *code:OBP0001/2015*. Pokud Flexibee u dané evidence nedrží textový identifikátor, vrátí se číselný (avšak typově jako string).

- Proměnné, které si Flexibee vypočítává samo (například suma za celou objednávku) a nebo je zakázáno je do Flexibee posílat (viz. dokumentace Flexibee) je vhodné označit jako *@property-read*. Unimapper pak nebude tyto property do Flexibee zapisovat, pouze je z Flexibee načte.

- Pokud je v dokumentaci Flexibee proměnná definovaná jako *date*, nastavte typ i zde na *Date*. Nepoužívejte *DateTime*, vyvarujete se problémů při filtraci záznamů dle datumu (např. vypiš všechny včerejší objednávky).

#### Tipy

- Díky *m:enum* lze hlídat hodnoty ve výčtových typech. Unimapper vyhodí výjimku, pokud se hodnota nenachází v datech, která se vrací z Flexibee / posílají do Flexibee.

- Štítky (zde tags) si lze jednoduše převést do array pomocí *m:map-filter(mapStitky|unmapStitky)* a pak s nimi jednodušeji pracovat. Naopak při zápisu se z array vhodně přetransformují do podoby, kterou Flexibee akceptuje.

- Pokud chcete načítat i externí identifikátory, lze ala příklad použít *$externalIds*.

- Pomocí *m:assoc(M:N)* dokážete skoro kouzla. Například v *$advanceInvoices* budete mít rovnou kolekci navázaných zálohovek k této objednávce a v *$cashInvoices* kolekci navázaných faktur. Pokud byste to rovnou chtěli pohromadě v jedné kolekci (proformy i faktury), můžete využít další vychytávku Unimapperu a to je "computed" property.

- Pomocí *m:computed* můžete zařídit, že jakmile k takové property přistoupíte, bude obsahovat přesně ten obsah, který potřebujete. V příkladu s tím souvisí metoda *computeInvoices()*.

- Pokud upravujeme existující objednávku, je vhodné nastavit *$itemsRemoveAll* na *TRUE* a zároveň poslat všechny položky objednávky znovu (*$evidenceItems*). V opačném případě se nám budou s každou úpravou množit na objednávce položky (viz. dokumentace Flexibee).

## Repository

Pokud pak máme repository zadefinovanou takto:

```

namespace ProjectName\Repository;

class OrderRepository extends \UniMapper\Repository

{

```

můžeme tam vytvořit třeba tyhle metody:

- Přepíše "vlastníka" objednávky za předpokladu, že aktuálně patří adminovi a je v určitém stavu.

```

public function assignStaffToOrder($orderId, $staff)

{

    $this->query()

        ->update(array("staff" => $staff))

        ->where("id", "=", $orderId)

        ->where("status", "=", Order::STATE_FORAPPROVAL)

        ->where("staff", "=", "code:admin")

        ->run($this->connection);

}

```

- Pokud si chcete formou štítků poznamenávat důvod storna, může přijít vhod následující metoda, která vrátí seznam štítků. Vynikající je v tomto ohledu možnost zapnout kešování Unimapperu! Proč se ptát na neměnný číselník stále dokola? Každý dotaz do Flexibee má nějako tu režii.

```

public function getCancelReasons()

{

    return \Fik\Entity\Tag::query()

        ->select()

        ->where("tagGroup", "=", "code:STORNO")

        ->cached(

            true,

            [\UniMapper\Cache\ICache::TAGS => [self::CACHE_TAG_CODEBOOK]]

        )

        ->run($this->connection);

}

```

- Nevyhovuje standardní *save()*? Můžeme ji přetížit a udělat nějakou tu věc navíc. Tady třeba nastavit dnešní datum vzniku objednávky, pokud jde o novou objednávku (*ID === null*).

```

public function save(\UniMapper\Entity $order)

{

    if ($order->id === null) {

        $order->dateCreated = new \DateTime();

    }

    parent::save($order);

}

```

- Některá workflow Flexibee vyžadují trochu více snahy. Pokud chceme z objednávky udělat fakturu, budeme potřebovat určitě tuto pasáž kódu (dokumence Flexibee napoví):

```

$structure = array(

    "objednavka-prijata" => array(

        "@id" => "{$orderId}",

        "realizaceObj" =>

        array("@type" => "faktura-vydana",

            "polozkyObchDokladu" => $polozkyDokladu

        )

    )

);

$invoiceCreated = $this->getAdapter("Flexibee")->put(

    "objednavka-prijata.json",

    $structure

);

```

- Počty objednávek ke schválení? Žádný problém :-)

```

public function getTotalCountForApprove()

{

    $result = $this->query()

        ->count()

        ->where("status", "=", Order::STATE_FORAPPROVAL)

        ->where("staff", "=", "code:admin")

        ->run($this->connection);

    return $result + $this->query()

        ->count()

        ->where("documentType", "=", Order::DOCTYPE_CARD)

        ->where("staff", "=", "code:admin")

        ->run($this->connection);

}

```

- Vytvoření jednoduché objednávky:

```

    public function createTestOrder()

    {

        $order = new Order;

        $order->documentType = Order::DOCTYPE_CONSIGNMENT;

        $order->addressBookId = "code:FIRMA";

        $items = [];

        

        $item = new EvidenceItem; // entita vázaná na evidenci "objednavka-prijata-polozka"

        $item->itemPriceList = "code:KRABICE_DROG"; // property objednavka-prijata-polozka.cenik

        $item->itemAmount = 2.0; // property objednavka-prijata-polozka.mnozMj

        $items[] = $item;

        

        $item = new EvidenceItem;

        $item->itemPriceList = "code:KRABICE_ALKOHOLU";

        $item->itemAmount = 1.0;

        $items[] = $item;

        $order->evidenceItems = new \UniMapper\EntityCollection(

            "EvidenceItem", $items

        );

        $this->save($order);

        

        // v $order->id budu mít v tento moment identifikátor objednávky z Flexibee, tj. třeba "code:OBP0001/2015"

    }

```

- Vrácení PDF definované objednávky:

```

public function getOrderPdf($orderId)

{

    return $this->getAdapter("Flexibee")->get(

        "objednavka-vydana/" . rawurlencode($orderId) . ".pdf",

        "application/pdf"

    );

}

```

- Vytažení objednávky včetně asociací:

```

public function getOrder($orderId)

{

    $query = $this->query()->selectOne($orderId)->associate(["advanceInvoices", "cashInvoices"]);

    $order = $query->run($this->connection);

    return $order;

}

```

- Hledání textu v poznámce určitých objednávek:

```

use UniMapper\Entity\Filter;

$invoices = $this->query()

    ->where(

        [

            "note" => [Filter::CONTAIN => $tentoTextHledame]

            "documentType" => [Filter::EQUAL => ["code:PRIMA", "code:NEPRIMA"]]

        ]

    ->orderBy("id", "desc")

    ->limit(10)

    ->run($this->connection);

```

## Práce nad repository

I tady se toho nabízí spousta. Například tohle může být základ pro skript, který má odesílat nezaplacené proformy:

```

// vyber vsechny, co nejsou uhrazene a stornovane

$filter = [

    "canceled" => ["=" => false], // = faktura-vydana.storno

    "paymentStatus" => [ // = faktura-vydana.stavUhrK

        "!" => [

            Entity\Invoice::PAYMENT_STATUS_PAIDMANUALLY, // = faktura-vydana.stavUhr.uhrazenoRucne

            Entity\Invoice::PAYMENT_STATUS_PAID // = faktura-vydana.stavUhr.uhrazeno

        ]

    ]

];

// prvni upominka dva dny po splatnosti

foreach ($this->invoiceRepository->find(

    $filter + [

        "documentType" => ["=" => Entity\Invoice::DOCTYPE_PROFORMA], // = faktura-vydana.typDokl = "code:ZÁLOHA"

        "firstReminder" => ["=" => null], // faktura-vydana.datUp1

        "dueDate" => [

            "<" => new \DateTime("-1 day") // faktura-vydana.datSplat

        ]

    ]

) as $invoice) {

```

#### Doporučení pro úpravu stavů v entitě

Občas se nám může naskytnout situace, kdy máme například celou entitu objednávka načtenou a po nějakých těch operacích dospějeme k tomu, že je potřeba upravit pouze stav objednávky:

```

$order = $this->orderRepository->findOne("code:OBP0001/2015);

...

nějaké ty operace

...

$order->status = "stavDoklObch.hotovo";

$this->orderRepository->save($order);

```

**Výše uvedený postup je však nevhodný!**

Naopak to doporučujeme řešit takto:

```

$order = $this->orderRepository->findOne("code:OBP0001/2015);

...

nějaké ty operace

...

$this->orderRepository->save(

    new ProjectName\Entity\Order(

        ["id" => $order->id, "status" => "stavDoklObch.hotovo"]

    )

);

```

Takhle zajistíme, že Flexibee nebude celou objednávku přepočítávat (neboť v *$order->evidenceItems* budou i její položky! a že opravdu pouze změní status u definované objednávky (*id*).