|
6 days ago | |
---|---|---|
.circleci | 2 years ago | |
.github | 3 weeks ago | |
Examples | 7 months ago | |
debian | 4 months ago | |
nbproject | 4 months ago | |
src/FlexiPeeHP | 2 months ago | |
static | 2 months ago | |
testing | 4 months ago | |
tools | 4 months ago | |
.gitattributes | 2 years ago | |
.gitignore | 5 months ago | |
.scrutinizer.yml | 5 months ago | |
.travis.yml | 2 years ago | |
CODE_OF_CONDUCT.md | 2 years ago | |
CONTRIBUTING.md | 2 years ago | |
Dockerfile | 2 years ago | |
LICENSE | 6 months ago | |
Makefile | 6 months ago | |
README.md | 6 days ago | |
Vagrantfile | 2 years ago | |
bootstrap-centos.sh | 2 years ago | |
bootstrap-debian.sh | 2 years ago | |
build.xml | 2 years ago | |
composer.json | 4 months ago | |
php-flexibee.spec | 2 years ago | |
phpunit.xml | 2 years ago | |
project-icon-400.png | 1 year ago | |
project-logo.png | 1 year ago | |
project-logo.svg | 1 year ago | |
release.sh | 2 years ago | |
spoje-net_logo.gif | 2 years ago |
README.md
FlexiBeeHP
PHP7.1+ Based Library for easy interaction with Czech accounting system FlexiBee.
CZ: PHP Knihovna pro snadnou práci s českým ekonomickým systémem FlexiBee
❗ Tato knihovna byla z důvodu požadavků composeru 2.0+ přejmenována na spojenet/flexibee ❗
❗ Věnujte prosím pozornost změnám v připravované nové verzi knihovny přinášející spoustu novinek: https://github.com/Spoje-NET/php-abraflexi/compare/2.0 ❗
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 / FlexiBee 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 Flexibee API
*/
define('FLEXIBEE_URL', 'https://flexibee-dev.spoje.net:5434');
/*
* Uživatel FlexiBee API
*/
define('FLEXIBEE_LOGIN', 'apiuser');
/*
* Heslo FlexiBee API
*/
define('FLEXIBEE_PASSWORD', 'apipass');
/*
* Společnost v FlexiBee
*/
define('FLEXIBEE_COMPANY', 'test_s_r_o_');
/*
* Nebo pokud nechceme používat jméno a heslo
*/
define('FLEXIBEE_AUTHSESSID', '6QuifebMits'); //Volitelné
/*
* Pomalý server, velká databáze a přes modem k tomu
*/
define('FLEXIBEE_TIMEOUT', 60); //Volitelné
/*
* Pomalý server, velká databáze a přes modem k tomu
*/
define('FLEXIBEE_EXCEPTIONS', true); //Vracet PHP vyjímku v případě že FlexiBee vrátí chybu
Pokud nejsou konstanty nastaveny, pouší se třídy také o konfiguraci ze stejnojmených proměnných prostředí. např getenv('FLEXIBEE_URL')
Taktéž je možné přihlašovací údaje zadávat při vytváření instance třídy.
$invoicer = new \FlexiPeeHP\FakturaVydana(null,[
'company' => 'Firma_s_r_o_',
'url' => 'https://flexibee.firma.cz/',
'user' => 'rest',
'password' => '-dj3x21xaA_'
]);
Tento způsob nastavení má vyšší prioritu než výše uvedené definovaní konstant.
$order = new \FlexiPeeHP\ObjednavkaPrijata('code:OBP0034/2019',['companyUrl'=> $_GET['companyUrl'], 'authSessionId'=>$_GET['authSessionId'] ])
Takto se ke flexibee 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 FlexiBeeRO, která je schopna pomocí PHP rozšíření curl komunikovat s REST Api FlexiBee.
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.flexibee.eu/c/demo/merna-jednotka/properties Vlastnosti evidence
*/
class MernaJednotka extends /FlexiPeeHP/FlexiBee
{
/**
* 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->getAllFromFlexiBee() );
Pokud chceme aby nově vytvořená třída uměla do flexibee i zapisovat, je třeba jí odvodit od předka FlexiBeeRW.
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.flexibee.eu/c/demo//properties.json respektive https://demo.flexibee.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 FlexiBee často nemění FlexiPeeHP 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 FlexiBee.
Položku v seznamu evidencí https://demo.flexibee.eu/c/demo/evidence-list je pak možné kdykoliv snadno ukázat:
echo \FlexiPeeHP\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(\FlexiPeeHP\FlexiBeeRO::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 FlexiPeeHPtest
Ladicí režim
Pokud v objektech FlexiPeeHP nastavíte $this->debug na true, budou se před odesláním dat do FlexiBee 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 flexibee a jejich odpovědi
Knihovna obsahuje mechanizmus pro odesílání zaznamenaných chyb při běhu FlexiBee vývojářům:
Pokud FlexiBee 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 FlexiBee 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.
Testování
PHPUnit testy se nachází ve složce testing. Pokud chcete testovat proti jinému serveru než je oficální http://demo.flexibee.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 FlexiBee.)
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 FlexiPeeHP a k těmto třídám napíšete testy také poděděné z FlexiPeeHP např:
class HookRecieverTest extends \Test\FlexiPeeHP\ChangesTest
Přidejte do vašeho composer.json i cesty k původním testům:
"autoload-dev": {
"psr-4": {
"Test\\": "vendor/spoje.net/php-flexibee/testing/src/FlexiPeeHP/testing/",
"Test\\Ease\\": "vendor/vitexsoftware/ease-framework/tests/src/Ease",
"Test\\FlexiPeeHP\\": "vendor/spoje.net/php-flexibee/testing/src/FlexiPeeHP/",
}
}
Ukázka
Ve složce Examples jsou tyto ukázky použití:
Soubor | Popis |
---|---|
AttachmentSaveToFile.php | uložení přílohy do souboru |
AttachmentUpload.php | nahrání přílohy |
AuthSessionIdUsage.php | Ukázka autentizace AuthSessionId |
AuthentizeContact.php | autentizace kontaktu |
BatchOperation.php | Použití filtru při dávkových operacích |
CreateLabel.php | práce se štítky |
DryRun.php | Testovací uložení (dry-run) |
DownloadInvoicePDF.php | stažení PDF faktury |
Error404.php | práce s neexistujícími záznamy |
FindOverdueInvoices.php | najdi faktury po splatnosti |
GetRecordWithRelation.php | Získání záznamu včetně dat z podevidence |
GetBankAccountForCompany.php | Získání bankovního účtu k firmě z adresáře |
InvoiceLockUnlock.php | Zamykání a odemykání záznamu |
InvoiceCopy.php | vytvoření daňového dokladu ze zálohy |
LoginLogout | přihlášení uživatele a jeho odhlášení |
NajdiDanovyDokladKzalohovemu.php | dohledání dokladu |
Naskladnění.php | Naskladní produkt se sériovými čísly |
NewInvoice.php | Nová faktura se splatností vypsaná jako json |
ObjectChaining.php | Řetězení objektů pro více operací v jenom pořadavku |
ObjectCooperation.php | Sdílení data a parametrů připojení mezi objekty |
PerformingActions.php | Jak vykonávat akce nad dokladem akce. např. storno |
ReadAddressColumns.php | vrať konkrétní sloupečky |
sendInvoiceByMail.php | odeslání faktury mailem |
SendReminders.php | odeslání upomínek |
SetContactAuth.php | nastavení autentizace |
TestConnection.php | kontrola spojení |
Příklady použití:
- Flexplorer Vývojářský nástoj a editor záznamů
- FlexiProXY Modifikátor webového rozhraní FlexiBee
- Upomínač Odesílač upomínek
- Matcher Párovač fakur
- Redmine2FlexiBee Generuje faktury z odpracovaného času v Redmine
- FlexiPeeHP-Bricks Příklady a často požívaní třídy při práci s FlexiBee
- TestingTools Nástroje pro testování FlexiBee aplikací
Reference:
- Import dat z FAPI do FlexiBee - blahasoft.cz
- Import dat z iDokladu do FlexiBee - blahasoft.cz
Docker
docker pull vitexsoftware/flexipeehp
Debian/Ubuntu
Pro Linux jsou k dispozici .deb balíčky. Prosím použijte repo:
sudo apt install lsb-release wget
echo "deb http://repo.vitexsoftware.cz $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/vitexsoftware.list
sudo wget -O /etc/apt/trusted.gpg.d/vitexsoftware.gpg http://repo.vitexsoftware.cz/keyring.gpg
sudo apt update
sudo apt install php-spojenet-flexibee
V tomto případě je potřeba do souboru composer.json vaší aplikace přidat:
"require": {
"deb/ease-core": "*",
"deb/flexibee": "*"
},
"repositories": [
{
"type": "path",
"url": "/usr/share/php/flexibee",
"options": {
"symlink": true
}
},
{
"type": "path",
"url": "/usr/share/php/EaseCore",
"options": {
"symlink": true
}
}
]
Takže při instalaci závislostí bude vypadat nějak takto:
Loading composer repositories with package information
Installing dependencies from lock file
- Installing ease-framework (1.1.3.3)
Symlinked from /usr/share/php/Ease
- Installing flexipeehp (0.2.1)
Symlinked from /usr/share/php/FlexiPeeHP
A aktualizaci bude možné dělat globálně pro celý systém prostřednictvím apt-get.
Generujeme také balíček php-spojenet-flexibee-doc, obsahující vývojářskou dokumentaci generovanou pomcí programu ApiGen. Dokumnentace je online k nahlédnutí na adrese http://vitexsoftware.cz/php-flexibee/namespaces/flexipeehp.html
Testování:
cd /usr/share/doc/FlexiPeeHP/
composer install
php -f flexibeeping.php
Sestavení
Debianí balíček vytvoříme spuštěním make deb
Obraz pro Docker:
docker build -t vitexsoftware/flexipeehp
FlexiBee 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)