spojenet / flexibee
Library for easy interaction with czech economic system AbraFlexi.
Installs: 37 597
Dependents: 4
Suggesters: 0
Security: 0
Stars: 24
Watchers: 4
Forks: 8
Open Issues: 11
Requires
- ext-curl: *
- ext-gettext: *
- ext-json: *
- vitexsoftware/ease-core: ^1.45
Requires (Dev)
- ext-iconv: *
- ergebnis/composer-normalize: ^2.43
- ergebnis/php-cs-fixer-config: ^6.34
- friendsofphp/php-cs-fixer: ^3.61
- phing/phing: *
- phpstan/phpstan: *
- phpunit/phpunit: *
- roave/security-advisories: dev-latest
This package is auto-updated.
Last update: 2024-12-10 22:30:28 UTC
README
PHP7.1+ Based Library for easy interaction with Czech accounting system AbraFlexi.
CZ: PHP Knihovna pro snadnou práci s českým ekonomickým systémem AbraFlexi
Poděkování
Vznik této knihovny by nebyl možný bez laskavé podpory společnosti Spoje.Net, která hradila vývoj řešení pro propojení LMS / AbraFlexi a importu skladu. 👍
Dále chci poděkovat technické podpoře společnosti ABRA Flexi s.r.o. za jejich svatou trpělivost při reakcích na mé ne vždy bystré otázky a bugreporty.
Parsování výsledků pro účely GDPR logování bylo dopracováno za laskavé podpory <PureHTML>
Instalace
composer require spojenet/flexibee
pokud váš výsledný composer.json bude vypadat zhruba takto:
{ "name": "vendor/projectname", "description": "Test", "type": "project", "require": { "spojenet/flexibee": "*" }, "license": "MIT", "authors": [ { "name": "Vítězslav Dvořák", "email": "info@vitexsoftware.cz" } ], "minimum-stability": "stable" }
spustí se příkazem composer install instalace:
Konfigurace
Konfigurace se provádí nastavením následujících konstant:
/* * URL AbraFlexi API */ define('ABRAFLEXI_URL', 'https://abraflexi-dev.spoje.net:5434'); /* * Uživatel AbraFlexi API */ define('ABRAFLEXI_LOGIN', 'apiuser'); /* * Heslo AbraFlexi API */ define('ABRAFLEXI_PASSWORD', 'apipass'); /* * Společnost v AbraFlexi */ define('ABRAFLEXI_COMPANY', 'test_s_r_o_'); /* * Nebo pokud nechceme používat jméno a heslo */ define('ABRAFLEXI_AUTHSESSID', '6QuifebMits'); //Volitelné /* * Pomalý server, velká databáze a přes modem k tomu */ define('ABRAFLEXI_TIMEOUT', 60); //Volitelné /* * Pomalý server, velká databáze a přes modem k tomu */ define('ABRAFLEXI_EXCEPTIONS', true); //Vracet PHP vyjímku v případě že AbraFlexi vrátí chybu
Pokud nejsou konstanty nastaveny, pouší se třídy také o konfiguraci ze stejnojmených proměnných prostředí. např getenv('ABRAFLEXI_URL')
Taktéž je možné přihlašovací údaje zadávat při vytváření instance třídy.
$invoicer = new \AbraFlexi\FakturaVydana(null,[ 'company' => 'Firma_s_r_o_', 'url' => 'https://abraflexi.firma.cz/', 'user' => 'rest', 'password' => '-dj3x21xaA_' ]);
Tento způsob nastavení má vyšší prioritu než výše uvedené definovaní konstant.
$order = new \AbraFlexi\ObjednavkaPrijata('code:OBP0034/2019',['companyUrl'=> $_GET['companyUrl'], 'authSessionId'=>$_GET['authSessionId'] ])
Takto se ke abraflexi a konrétní objednávce může připojit aplikace vyvolaná uživatelským tlačítkem předávajícím hodnoty companyUrl a authSessionId
Jak to celé funguje ?
Ústřední komponentou celé knihovny je Třída RO, která je schopna pomocí PHP rozšíření curl komunikovat s REST Api AbraFlexi.
Z ní jsou pak odvozeny třídy pro jednotlivé evidence, obsahující metody pro často používané operace, například "Zaplať" v případě přijatých faktur.
Nová odvozená třída vzniká tak, že jméno třídy je název evidence avšak bez pomlček. Ty jsou ve jméně nahrazeny velkým písmenem.
function evidenceToClass($evidence) { return str_replace(' ', '', ucwords(str_replace('-', ' ', $evidence))); }
Tzn. Pokud chceme odvodit novou třídu pro evidenci "Měrné jednotky" bude vypadat takto:
<?php /** * @link https://demo.abraflexi.eu/c/demo/merna-jednotka/properties Vlastnosti evidence */ class MernaJednotka extends /AbraFlexi/RW { /** * Evidence užitá objektem. * * @var string */ public $evidence = 'merna-jednotka'; }
A poté je již snadné si vypsat měrné jednotky na 2 řádky:
$jednotky = new MernaJednotka(); print_r( $jednotky->getAllFromAbraFlexi() );
Pokud chceme aby nově vytvořená třída uměla do abraflexi i zapisovat, je třeba jí odvodit od předka AbraFlexiRW.
Více příkladů použití je možné najít v samostatném projektu
Struktura Evidencí, Akcí a vztahů
V některých případech je dobré znát jaké můžeme provádět akce, či jáká je struktura evidence. Tyto informace je možno získat voláním https://demo.abraflexi.eu/c/demo/*/properties.json respektive https://demo.abraflexi.eu/c/demo/*/actions.json avšak jedná se o relativně časově náročné operace. Jelikož se struktura evidencí a Akce či vztahy mezi evidencemi AbraFlexi často nemění AbraFlexi disponuje mechanizmem který umožní pracovat s těmito údaji bez nutnosti dotazovat se na ně serveru.
Struktura je uložena ve třídě Structure (Actions,Relations) která obsahuje staticky definované pole obsahující informace které by jinak bylo nutné získat z AbraFlexi.
Položku v seznamu evidencí https://demo.abraflexi.eu/c/demo/evidence-list je pak možné kdykoliv snadno ukázat:
echo \AbraFlexi\Structure::$evidence['faktura-vydana'];
Sturktury jednotlivých evidencí jsou pak uloženy ve statických proměnných. Jejich jméno se řídí stejnými pravidly jako jsou pro vytváření jména nové třídy jen s tím rozdílem, že první písmeno je malé. Tzn.:
lcfirst(\AbraFlexi\RO::evidenceToClassName($evidence))
V případě potřeby je možné tyto třídy pak možné vygenerovat s aktuálním obsahem následujícím příkazem:
cd tools/
./update_all.sh
Operace trvá několik minut. Zobrazit průběh můžeme takto:
tail -f /var/log/syslog | grep AbraFlexitest
Ladicí režim
Pokud v objektech AbraFlexi nastavíte $this->debug na true, budou se před odesláním dat do AbraFlexi provedeny dodatečné testy. Kontrolují se tyto možné chyby:
- Existuje vkládané políčko definované pro evidenci ?
- Je vkládané políčko Pouze pro čtení ?
- Pokud je vkládané políčko vazbou, je i polem ?
V ladícím režimu se také ukládají do složky /tmp všechny požadavky na abraflexi a jejich odpovědi
Knihovna obsahuje mechanizmus pro odesílání zaznamenaných chyb při běhu AbraFlexi vývojářům:
Pokud AbraFlexi vrátí Internal Server Error 500, je odeslán vývojářům email obsahující chybovou zprávu.
V případě že je použito AbraFlexi běžící na stejném serveru a je možné číst chybové logy je z nich vypreparován patřičný fragment a i ten je přidán do těla mailu.
Email obsahuje také dodatečné informace o licenci a povolených modulech.
Jako přílohy jsou také připojeny soubory obsahující tělo dotazu na server, tělo jeho odpovědi a soubor obsahující informace o curl.
Během života objektu se chyby evidují a odesílá se pouze první každého druhu.
Aktualizace na verzi 2.0
Oproti 1.x se změnilo následující:
- Zmizely Třídy FlexiBeeRO a FlexiBeeRW (nově RO a RW)
- Data z AbraFlexi jsou typovaná (už ne jenom strig)
- Všechno FlexiBee bylo přejmenováno na AbraFlexi
- Při chybě ze serveru se vyhodí Exeption (předtím se pouze zalogovalo)
- Požadavky nespecifikují počet výsledků, (je třeba explicitně požadovat limit 0 pro všechny výsledky požadavku na api)
- již se nepužívá starý zápis polí array()
Výchozí Nativní typy se projevují tak že ze serveru ve chlívečku obsahující datum obdržíte php objekt DateTime. ve sloupečku 'id' integer a pod.
Toto chování je možné vypnout pomocí parametru konstruktoru ['nativeTypes' = false]
new \AbraFlexi\FakturaVydaná( 'code:VF2-12345', ['nativeTypes'=>false,'debug'=>true,'ignore404'=>false] );
Viz.: constructor RO
Je možno zadat některé z těchto parametrů:
* user,password,authSessionId - autentifikace
* company,url,evidence - vynucení parametrů přístupu
* prefix - pro url začínající jinak než '/c/' pro company
* defaultUrlParams - pole vlastností pak automaticky přidávané
* debug - pro zapnutí ladícího režimu
* detail - pro specifikaci požadované [úrovně detailů](https://www.flexibee.eu/api/dokumentace/ref/detail-levels/).
* offline - nevykonávají se žádné síťové operace ( nepřiřipojit se při instancování objektu )
* filter - viz [Filtrování](https://www.flexibee.eu/api/dokumentace/ref/filters}
* ignore404 - v případě že nevím zdali požadovaný záznam existuje nastavte na true aby to nevyhodilo chybu
* nativeTypes - pokud chci všecho ze serveru vracet jako stringy
* timeout - trpělivost než se vyhodí chyba síťové komunikace (předáváno do cURL)
* companyUrl - načte si z řetězce všechny náležitosti k připojení (heslo pro API atd..)
* ver - vynucení verze api (pokud chcete volat funkce určené pro nové webové rozhraní)
* throwException - vyhodit vyjímku při každé vhodné příležitosti
Autoloading dat
Pokud se konstruktoru objektu předá ID typu int nebo kódem (code:..) záznamu zavolá tento funkci loadFromAbraFlexi(id) Poté je možné k načteným hodnotám se dostat za použití metod $this->getData() a RO::getDataValue('nazev')
Datové typy
Jelikož API vrací vše víceméně jako řetězec, knihovna provádí automatické konverze datových typů:
Testování
PHPUnit testy se nachází ve složce testing. Pokud chcete testovat proti jinému serveru než je oficální http://demo.abraflexi.eu/ , je třeba změnit nastavení v souboru bootstrap.php.
Obsah proměnné $testServer určuje která z předvolených nastavení budou použita. A samozřejmě si můžete nadefinovat i vlastní. Jako příklad je zde uveden testovací server spoje.net.
Pro testování vytvořte prosím nejprve testovací firmu TESTING s.r.o. a nastavte přístupové údaje uživatele s oprávněním používat REST API. (Což je uživatel administrátora zadaný při instalaci AbraFlexi.)
Upozornění: testování proti firmě s množstvím faktur a připojenou bankou může trvat nějakou dobu, jelikož se testuje i zavolání automatického párování dokladů.
Pokud se ve vašem projektu rozhodnete podědit AbraFlexi a k těmto třídám napíšete testy také poděděné z AbraFlexi např:
class HookRecieverTest extends \Test\AbraFlexi\ChangesTest
Přidejte do vašeho composer.json i cesty k původním testům:
"autoload-dev": { "psr-4": { "Test\\": "vendor/spojenet/php-abraflexi/test/src/AbraFlexi/test/", "Test\\Ease\\": "vendor/vitexsoftware/ease-core/tests/src/Ease", "Test\\AbraFlexi\\": "vendor/spojenet/php-abraflexi/test/src/AbraFlexi/", } }
Ukázka
Ve složce Examples jsou tyto ukázky použití:
Příklady použití:
- Flexplorer Vývojářský nástoj a editor záznamů
- FlexiProXY Modifikátor webového rozhraní AbraFlexi
- Upomínač Odesílač upomínek
- Matcher Párovač fakur
- Redmine2AbraFlexi Generuje faktury z odpracovaného času v Redmine
- FlexiPeeHP-Bricks Příklady a často požívaní třídy při práci s AbraFlexi
- AbraFlexi Tools Nástroje pro skriptování AbraFlexi z příkazové řádky
Reference:
- Import dat z FAPI do AbraFlexi - blahasoft.cz
- Import dat z iDokladu do AbraFlexi - blahasoft.cz
AbraFlexi knihovny pro další jazky:
- Flexipy (Python) Dokumentace
- Flexibee.rb (Ruby)
- UniMapper Flexibee extension (PHP)
- Flexibee client (PHP)
- flexibee-client (PHP)
- flexibee-client (PHP)
- Flexibee (Java)
Statistiky práce na projektu WakaTime Statistiky práce na projektu před přejmenováním (cca 250h)