Download the PHP package vs-point/moneys3 without Composer

vs-point/moneys3

Striktně typovaná PHP knihovna pro komunikaci s účetním softwarem Money S3 (Seyfor) přes jeho GraphQL API. Poskytuje typovaný PHP interface pro čtení a zápis dokladů, adresáře, skladů, deníků a dalších agend — bez ručního skládání GraphQL řetězců.

• 🔒 Striktně typované — vstupy (mutace) i filtry jsou PHP objekty, ne pole/řetězce.
• 🧠 Inteligentní GraphQL builder — typované objekty se samy serializují do platné GraphQL syntaxe (literály, enum tokeny, vnořené objekty, seznamy).
• 🔌 Framework-agnostické jádro + tenký Symfony bundle.
• ☁️ Cloud i lokál — CloudClient ({domain}.api.moneys3.eu) a Client (localhost:85).

Money S3 API je GraphQL-based s OAuth2 autentizací. Čtení je synchronní; zápis je asynchronní — doklad vstupuje do importní fronty a mutace vrací guid + isSuccess. Oficiální dokumentace: https://money.cz/navod/api-v-money-s3-pro-vyvojare/, interaktivní schéma: https://s3api.api.moneys3.eu/graphql/.

Požadavky

• PHP >= 8.2
• Money S3 s nainstalovaným a zakoupeným API modulem
• Vygenerovaný API klíč (Client ID + Client Secret) a Application ID ([email protected])

Instalace

Při použití Dockeru je potřeba GitLab token:

Připojení

Knihovna nabízí dvě konkrétní třídy klienta se společným předkem MoneyS3Api, takže si explicitně volíte, ke které instanci se připojujete:

Cloud

Lokální Money S3

Autentizace

Token se získá přes connect/token, drží se v paměti a automaticky obnovuje před expirací.

Použití

Klient přímo vystavuje jednu službu na agendu:

Čtení (query) — typované DTO

$result je Collection<JournalTransaction> — typovaná, iterovatelná, s first(), count(), isEmpty().

Filtrování (where) — typované atributy

Pole se nikdy nezadávají stringem — odkazují se přes per-agenda atributový enum implementující FieldName (např. CashJournalAttribute, IssuedInvoiceAttribute, WarehouseStockAttribute). Díky tomu nelze odkázat na pole, které neexistuje:

Stejně tak řazení: Order::by(CashJournalAttribute::date, OrderDirection::desc).

IDE i PHPStan tak hlídají správnost: CashJournalAttribute::yaer se nezkompiluje. Názvy polí v enumech jsou navíc ověřené proti živému schématu (filter input typy) — viz Validace proti schématu.

Pro pole, které zatím nemá atributový enum, existuje únikový poklop Where::path('nejake.pole', …) / Order::path('nejake.pole', …).

Operátory (FilterOperator): eq, neq, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, nstartsWith, endsWith, nendsWith.

Vlastní výběr polí

Read-only agendy mají výchozí selekci pokrývající celé DTO, ale můžete si zvolit vlastní:

U dokladových agend (faktury, banka, …) je query() typově bezpečný „raw" čteč — zvolíte selekci a hodnoty čtete přes Data:

Vytvoření dokladu (mutace)

Datová pole přijímají string ("2026-03-02"), DateTimeInterface i Brick\DateTime\LocalDate. Peněžní/číselné hodnoty přijímají int|float|string i Brick\Math\BigNumber.

Skladová položka faktury

Úprava dokladu

Update používá stejné vstupní DTO jako create; doklad se identifikuje přes guid (případně documentNumber/symboly podle nastavení importu):

Smazání dokladu

Přehled agend a CRUD

Stav byl ověřen proti živému schématu (s3api.api.moneys3.eu/graphql/) — viz Validace proti schématu. Zápis je vždy asynchronní (importní fronta), mutace vrací { guid, isSuccess }.

Money S3 GraphQL API vystavuje create / update / delete + query pro desítky dalších agend (adresář companies, kmenové karty articles, dodací listy, nabídky, poptávky, interní doklady, závazky/pohledávky, číselníky…). Ty zatím nemají vlastní typované DTO, ale jdou číst generickým query(fields: […]) patternem a snadno doplnit — viz Rozšíření o další agendu.

Validace proti schématu

Knihovna je ověřena proti živému GraphQL schématu Money S3 pomocí introspekce (__schema / __type nevyžadují OAuth token). Testovací sada Schema (tests/Schema/LiveSchemaContractTest.php) kontroluje, že:

• všechny query root fieldy (issuedInvoices, journalTrs, …) ve schématu existují,
• všechny create* / update* / delete* mutace agend existují,
• enum tokeny, které knihovna posílá (PriceType, AbsenceType, řazení SortEnumType), jsou platné hodnoty schématu,
• pole vstupu IssuedInvoiceInput odpovídají schématu,
• názvy polí v atributových enumech (CashJournalAttribute, IssuedInvoiceAttribute, …) jsou reálná filtrovatelná pole (I…FilterInput).

Pokud je endpoint nedostupný (offline CI), se test sám přeskočí (markTestSkipped), takže nikdy nerozbije pipeline. Spuštění jen této sady:

Jak funguje typovaný GraphQL builder

Jádro je v src/GraphQL:

• InputObject — kontrakt: toGraphQL(): array vrací mapu pole => hodnota. Implementují ho všechna vstupní DTO (IssuedInvoiceInput, Address, ShortCutRef, …).
• ValueEncoder — serializuje PHP hodnoty do GraphQL literálů (ne JSON): řetězce v uvozovkách s escapováním, čísla/bool/null bez uvozovek, enumy jako holé tokeny (WITHOUT_VAT), InputObject/vnořená pole jako { key: value }, seznamy jako [ … ]. null pole se vynechávají.
• Field — uzel selekce (documentNumber nebo company { identificationNumber }).
• QueryBuilder / MutationBuilder — složí celý dokument: query { root(where: …, order: …, skip: …, take: …) { items { …fields } } }, resp. mutation { createX(x: { … }, definitionXMLTransfer: { … }) { guid isSuccess } }.
• Where / Order (src/Filter) — kompozičně skládané, typované argumenty.

Enumy, které vyžadují jiný token než název case, implementují GraphQLEnumValue. Pro ojedinělý surový fragment existuje RawGraphQL (používat střídmě).

Symfony bundle

Jádro je framework-agnostické; bundle jen registruje a autowiruje připojení.

Autowiruje se MoneyS3Api i konkrétní třída (CloudClient / Client) podle connection.

Rozšíření o další agendu

1. Atributový enum v src/DTO/{Agenda}/{Agenda}Attribute.php implementující FieldName (mapuje PHP název → reálné GraphQL filtrovatelné pole, vnořené přes tečku) — pro typované Where / Order.
2. Vstupní DTO v src/DTO/{Agenda}/ implementující InputObject (jen toGraphQL() s pole => hodnota; null pole se automaticky vynechají).
3. Response DTO (u read agend) s public static fromData(Data $d): self a public static fields(): array (selekce Field[]).
4. Služba v src/Agenda/ rozšiřující AbstractAgendaService — query() přes queryCollection() / queryRaw(), create() / update() / delete() přes mutate().
5. Přidat public readonly property + inicializaci do src/Client/MoneyS3Api.php.

Přesné názvy root fieldů, mutací, vstupních polí a enum tokenů ověřte v interaktivním schématu: https://s3api.api.moneys3.eu/graphql/ („Browse Schema").

Vývoj

Vše běží přes Docker image z CI (vspoint/php:8.5-fpm-alpine):

Testy jsou unit — neprovádějí žádné síťové volání (HTTP je mockované přes Guzzle MockHandler, transport přes RecordingTransport). Ověřují sestavování GraphQL dokumentů, serializaci typovaných vstupů, parsování odpovědí, OAuth2 a resolving endpointů.

CI (.gitlab-ci.yml) má fáze analyse (validate + phpstan + ecs) a test (phpunit).

Licence

MIT