ZADÁNÍ BAKALÁŘSKÉ PRÁCE
Název: Knihovna pro tvorbu REST API v PHP
Student: Martin Fabík
Vedoucí: Ing. Jiří Chludil Studijní program: Informatika
Studijní obor: Webové a softwarové inženýrství Katedra: Katedra softwarového inženýrství Platnost zadání: Do konce letního semestru 2020/21
Pokyny pro vypracování
1. Analyzujte nejčastěji používané knihovny pro tvorbu REST API v jazyce PHP a porovnejte je (použitelnost, podpora, limitace, apod...).
2. Analyzujte nejčastěji požadované a nejčastěji chybějící funkcionality ve stávajících řešeních.
3. Na základě provedených analýz navrhněte vlastní knihovnu, která bude pokrývat nejčastější chybějící funkcionality.
4. Implementujte navrženou knihovnu v jazyce PHP, včetně vhodných testů (unit, integrační, apod...).
5. Navrhněte vhodnou referenční implementaci vytvořené knihovny, včetně vhodné ukázkové REST API služby.
Seznam odborné literatury
Dodá vedoucí práce.
Bakal´ aˇrsk´ a pr´ ace
Knihovna pro tvorbu REST API
Martin Fab´ ık
Prohl´ aˇ sen´ı
Prohlaˇsuji, ˇze jsem pˇredloˇzenou pr´aci vypracoval(a) samostatnˇe a ˇze jsem uvedl(a) veˇsker´e pouˇzit´e informaˇcn´ı zdroje v souladu s Metodick´ym pokynem o etick´e pˇr´ıpravˇe vysokoˇskolsk´ych z´avˇereˇcn´ych prac´ı.
Beru na vˇedom´ı, ˇze se na moji pr´aci vztahuj´ı pr´ava a povinnosti vypl´yvaj´ıc´ı ze z´akona ˇc. 121/2000 Sb., autorsk´eho z´akona, ve znˇen´ı pozdˇejˇs´ıch pˇredpis˚u.
V souladu s ust. § 46 odst. 6 tohoto z´akona t´ımto udˇeluji nev´yhradn´ıopr´avnˇen´ı (licenci) k uˇzit´ı t´eto moj´ı pr´ace, a to vˇcetnˇe vˇsech poˇc´ıtaˇcov´ych program˚u, jeˇz jsou jej´ı souˇc´ast´ı ˇci pˇr´ılohou, a veˇsker´e jejich dokumentace (d´ale souhrnnˇe jen
”D´ılo“), a to vˇsem osob´am, kter´e si pˇrej´ı D´ılo uˇz´ıt. Tyto osoby jsou opr´avnˇeny D´ılo uˇz´ıt jak´ymkoli zp˚usobem, kter´y nesniˇzuje hodnotu D´ıla, a za jak´ymkoli
´uˇcelem (vˇcetnˇe uˇzit´ı k v´ydˇeleˇcn´ym ´uˇcel˚um). Toto opr´avnˇen´ı je ˇcasovˇe, teri- tori´alnˇe i mnoˇzstevnˇe neomezen´e. Kaˇzd´a osoba, kter´a vyuˇzije v´yˇse uvedenou licenci, se vˇsak zavazuje udˇelit ke kaˇzd´emu d´ılu, kter´e vznikne (byt’ jen zˇc´asti) na z´akladˇe D´ıla, ´upravou D´ıla, spojen´ım D´ıla s jin´ym d´ılem, zaˇrazen´ım D´ıla
ˇCesk´e vysok´e uˇcen´ı technick´e v Praze Fakulta informaˇcn´ıch technologi´ı
© 2020 Martin Fab´ık. Vˇsechna pr´ava vyhrazena.
Tato pr´ace vznikla jako ˇskoln´ı d´ılo na ˇCesk´em vysok´em uˇcen´ı technick´em v Praze, Fakultˇe informaˇcn´ıch technologi´ı. Pr´ace je chr´anˇena pr´avn´ımi pˇredpisy a mezin´arodn´ımi ´umluvami o pr´avu autorsk´em a pr´avech souvisej´ıc´ıch s pr´avem autorsk´ym. K jej´ımu uˇzit´ı, s v´yjimkou bez´uplatn´ych z´akonn´ych licenc´ı a nad r´amec opr´avnˇen´ı uveden´ych v Prohl´aˇsen´ı na pˇredchoz´ı stranˇe, je nezbytn´y sou- hlas autora.
Odkaz na tuto pr´aci
Fab´ık, Martin. Knihovna pro tvorbu REST API. Bakal´aˇrsk´a pr´ace. Praha:
ˇCesk´e vysok´e uˇcen´ı technick´e v Praze, Fakulta informaˇcn´ıch technologi´ı, 2020.
Abstrakt
C´ılem pr´ace je anal´yza st´avaj´ıch moˇznost´ı pro tvorbu REST API sluˇzeb do- stupn´ych v r˚uzn´ych PHP frameworc´ıch a na z´akladˇe vznikl´e anal´yzy iden- tifikovat nejˇcastˇeji chybˇej´ıc´ı funkcionality a navrhnout ˇreˇsen´ı poˇzadovan´ych funkcionalit. Praktick´ym v´ystupem t´eto pr´ace bude nez´avisl´a PHP knihovna, kter´a nab´ıdne n´astroje a moˇznosti pro tvorbu REST API sluˇzeb. V p´ısemn´e ˇc´asti se autor zab´yv´a pˇrev´aˇznˇe anal´yzou st´avaj´ıc´ıh ˇreˇsen´ı spolu s rozborem poˇzadavk˚u a n´avrhem konkr´etn´ı podoby v´ysledn´e knihovny.
Kl´ıˇcov´a slova REST API, REST frameworky, REST API n´astroje, n´avrh API, OpenAPI, PHP knihovna
Abstract
The goal of this thesis is to analyze the existing possibilities for creating REST API services in various PHP frameworks and identify the most frequently missing functionalities based on provided analysis and then propose solution for the required functionalities. The practical output of this work will be an independent PHP library that will offer various tools for creating REST API services. In written part, the author deals mainly with the analysis of existing solutions and analysis of requirements and proposes design of the resulting library.
Keywords REST API, REST frameworks, REST API tools, API design, OpenAPI, PHP library
vi
Obsah
Uvod´ 1
1 C´ıl pr´ace 3
2 REST 5
2.1 Z´aklady RESTu . . . 5
2.2 ´Urovnˇe RESTu . . . 6
2.2.1 The Swamp of POX . . . 6
2.2.2 Resources . . . 6
2.2.3 HTTP Verbs . . . 7
2.2.4 Hypermedia Controls . . . 8
3 Anal´yza 9 3.1 V´ybˇer dostupn´ych ˇreˇsen´ı . . . 9
3.1.1 Dostupn´e frameworky . . . 9
3.1.1.1 Laravel[6] . . . 9
3.1.1.2 Symfony[7] . . . 9
3.1.1.3 Magento 2[8] . . . 9
3.1.1.4 Nette[9] . . . 10
3.2 Zhodnocen´ı dostupn´ych ˇreˇsen´ı . . . 10
3.2.1 V´ybˇer hodnot´ıc´ıch krit´eri´ı . . . 10
3.2.2 Hodnocen´ı ˇreˇsen´ı . . . 11
3.3.3 Mapov´an´ı do objektov´e reprezentace . . . 17
3.3.4 Validace vstupu . . . 18
3.3.5 Autentizace uˇzivatele . . . 18
3.4 Dotazn´ıkov´e ˇsetˇren´ı . . . 18
3.4.1 ˇClenˇen´ı dotazn´ıku . . . 19
3.4.2 V´ysledky dotazn´ıku . . . 20
4 N´avrh 21 4.1 Platforma . . . 21
4.2 Verzov´an´ı . . . 21
4.2.1 Centralized workflow . . . 21
4.2.2 Feature branching workflow . . . 22
4.2.3 Gitflow workflow . . . 22
4.2.4 Forking workflow . . . 23
4.2.5 Zvolen´e ˇreˇsen´ı . . . 24
4.3 Composer . . . 24
4.4 OOP Design a principy . . . 24
4.4.1 Princip jedn´e odpovˇednosti . . . 24
4.4.2 Princip otevˇrenosti a uzavˇrenosti . . . 25
4.4.3 Liskovov´e princip zamˇenitelnosti . . . 25
4.4.4 Princip oddˇelen´ı rozhran´ı . . . 25
4.4.5 Princip obr´acen´ı z´avislost´ı . . . 25
4.5 PHP-FIG PSR . . . 25
4.5.1 PSR-1 . . . 26
4.5.2 PSR-4 . . . 26
4.5.3 PSR-7 . . . 26
4.5.4 PSR-11 . . . 26
4.6 Implementaˇcn´ı n´avrh j´adra knihovny . . . 26
4.6.1 J´adro knihovny . . . 27
4.6.2 Form´aty . . . 28
4.6.3 Reflexe . . . 29
4.6.4 Mapov´an´ı vstupn´ıch dat . . . 29
4.6.5 Mapov´an´ı v´ystupn´ıch dat . . . 30
4.6.6 Zpracov´an´ı poˇzadavku . . . 30
4.6.7 Pˇr´ıklady budouc´ıho uˇzit´ı . . . 31
5 Realizace 33 5.1 Postup realizace . . . 33
5.2 Instalaˇcn´ı pˇr´ıruˇcka . . . 34
5.3 Program´atorsk´a dokumentace . . . 34
5.4 Zhodnocen´ı v´ysledn´e knihovny . . . 35
6 Testov´an´ı 37 6.1 Jednotkov´e testov´an´ı . . . 37
viii
7 Referenˇcn´ı implementace 39 7.1 V´ybˇer vhodn´e platformy . . . 39 7.2 Realizace . . . 39
Z´avˇer 41
Bibliografie 43
A Seznam pouˇzit´ych zkratek 45
B Obsah pˇriloˇzen´eho CD 47
Seznam obr´ azk˚ u
2.1 ˇCtyˇri ´urovnˇe pohledu na REST[4] . . . 6 4.1 Sch´ema Gitflow . . . 23
Seznam tabulek
2.1 HTTP metody pouzivane v souvislosti s REST . . . 7 3.1 Pˇrehled hodnocen´ı jednotliv´ych framework˚u . . . 16 3.2 Pr˚umˇern´e zhodnocen´ı poˇzadovan´ych vlastnost´ı dle responsend˚u . . 20
Uvod ´
V souˇcasnosti, kdy se ˇc´ım d´al t´ım v´ıce subjekt˚u na internetu snaˇz´ı vyuˇz´ıvat v´yhod REST API sluˇzeb[1], je d˚uleˇzit´e, aby mˇeli v´yvoj´aˇri k dispozici kvalitn´ı n´astroje pro v´yvoj pr´avˇe REST API sluˇzeb. V pr´aci proto c´ıl´ım pˇrev´aˇznˇe na anal´yzu moˇznost´ı, kter´e m´a v souˇcasnosti v´yvoj´aˇr k dispozici a n´aslednˇe navrhuji knihovnu, kter´a pokr´yv´a d˚uleˇzit´e chybˇej´ıc´ı funkcionality.
V ´uvodu pr´ace se zab´yv´am podrobnˇejˇs´ı anal´yzou dostupn´ych framework˚u z r˚uzn´ych odvˇetv´ı, se kter´ymi se v´yvoj´aˇr m˚uˇze potkat. Bˇehem anal´yzy zkoum´am dostupn´a ˇreˇsen´ı z pohledu tvorby REST API serveru, tedy pˇredevˇs´ım jejich zach´azen´ı s daty. Z tohoto pohledu jsem v pr˚ubˇehu anal´yzy pˇri seznamov´an´ı se s frameworky vyuˇzil jak drobn´ych implementac´ı, tak revize k´odu.
Pr´ace je strukturovan´a tak, aby ˇcten´aˇri pˇrehlednˇe a srozumitelnˇe poskytla v´ystupy jednotliv´ych ˇc´ast´ı tvorby softwaru. Bˇehem anal´yzy se tedy zab´yv´am identifikac´ı kl´ıˇcov´ych funkcionalit, kter´e povaˇzuji za d˚uleˇzit´e a kter´e ve vˇetˇsinˇe ˇreˇsen´ıchyb´ı, nebo r˚uzn´e frameworky poskytuj´ıimplementaci na rozd´ıln´e ´urovni.
Jako ovˇeˇren´ı m´ych hypot´ez byl proveden tak´e pr˚uzkum mezi v´yvoj´aˇri. tento pr˚uzkum c´ılil na jejich potˇreby a jejich st´avaj´ıc´ıˇreˇsen´ı. V´ystupem pr´ace je pot´e samostatn´a PHP knihovna jako n´astroj umoˇzˇnuj´ıc´ı efektivn´ı tvorbu REST API sluˇzby stejnˇe tak jako referenˇcn´ı pouˇzit´ı t´eto knihovny ve frameworku Nette.
Kapitola 1
C´ıl pr´ ace
C´ılem t´eto pr´ace je na z´akladˇe analytick´e ˇc´asti pr´ace navrhnout a realizovat PHP knihovnu pro tvorbu REST API sluˇzeb (serverov´e ˇc´asti).
C´ılem analytick´e ˇc´asti pr´ace je vytipovat a analyzovat zaj´ımav´e PHP fra- meworky a posoudit moˇznosti tvoby REST API v tˇechto frameworc´ıch. D´ale identifikovat klady a z´apory zvolen´ych ˇreˇsen´ı a vytipov´an´ı a konkr´etn´ı spe- cifikace uˇziteˇcn´ych funkcionalit. Na z´akladˇe vyspecifikovan´ych funkcionalit posl´eze navrhnout samostatnˇe pouˇzitelnou PHP knihovnu, kter´a poslouˇz´ı jako n´astroj pro tvoru REST API sluˇzeb.
C´ılem praktick´e ˇc´asti je realizace v´yˇse zm´ınˇen´e knihovny v jazyce PHP, jej´ı otestov´an´ı a tak´e uk´azkov´a implementace a pouˇzit´ı novˇe vzniknuvˇs´ı knihovny.
Kapitola 2
REST
Pˇred samotn´ym zkoum´an´ım dostupn´ych ˇreˇsen´ıa tvorbou vlastn´ıch poˇzadavk˚u, je nutn´e nejdˇr´ıve zn´at, co REST API obn´aˇs´ı, na jak´ych principech je posta- veno a jakou pouˇz´ıv´a architekturu. V tomto kr´atk´em, avˇsak d˚uleˇzit´em ´uvodu se budu zab´yvat pˇrev´aˇznˇe serverovou ˇc´ast´ı REST API, avˇsak je nutn´a tak´e znalost z pohledu klienta.
2.1 Z´ aklady RESTu
REST [2] (Representational State Transfer) je architektonick´y styl, kter´y je na- rozd´ıl od tehdy dosupn´ych technologi´ı, jako napˇr´ıklad XML-RPC nebo SOAP, datovˇe orientov´an. Prim´arn´ım zamˇeˇren´ım REST API jsou rozhran´ı v distri- buovan´em prostˇred´ı, pˇriˇcemˇz”se zamˇeˇruje na jednotn´y a snadn´y pˇr´ıstup ke zdroj˚um (resources). Zdroj m˚uˇze b´yt prakticky cokoliv, koncept nem´a ˇz´adn´a omezen´ı. M˚uˇze to b´yt napˇr´ıklad nˇejak´y konkr´etn´ı objekt v datab´azi, dokument, v´ysledek nˇejak´eho v´ypoˇctu nebo webov´a str´anka“ [3].
Jelikoˇz se tato pr´ace zaob´ır´a n´avrhem a implementac´ı REST API sluˇzeb z pohledu RESTu se jedn´a o n´avrh a definov´an´ızdroj˚u.
2. REST
2.2 Urovnˇ ´ e RESTu
[4] Pro pˇrehlednost je v´yhodn´e si REST zn´azornit v ´urovn´ıch jako na obr´azku 2.1:
Obr´azek 2.1: ˇCtyˇri ´urovnˇe pohledu na REST[4]
2.2.1 The Swamp of POX
Jedn´a se o ´uroveˇn, na kter´e pohl´ıˇz´ıme na samotn´y pˇrenos mezi serverem a kli- entem. Nejˇcastˇeji se pouˇz´ıv´a protokol HTTP, avˇsak samotn´y REST se nev´aˇze jen na tento konkr´etn´ı protokol. V t´eto pr´aci se vˇsak budu zab´yvat pouze pˇrenosem pomoc´ı HTTP protokolu, jelikoˇz se jedn´a o pr´aci pojedn´avaj´ıc´ı o tvorbˇe REST API v prostˇred´ı webu.
2.2.2 Resources
Pˇri pr´aci s REST API nejsou poˇzadavky z pohledu klienta pos´ıl´any na je- den centr´aln´ı bod a d´ale rozliˇsov´any podle obsahu, ale jsou klientem zas´ıl´any na jednotliv´e, jednoznaˇcnˇe identifikovan´e zdroje. Zdrojem m˚uˇze b´yt cokoli, tedy r˚uzn´e dokumenty, obr´azky, ale nejˇcastˇeji se jedn´a o strukturovan´a data, napˇr´ıklad data z datab´aze.
D´ale je klient˚um umoˇznˇeno pˇristupovat k jednotliv´ym instanc´ım jednoho zdroje (m˚uˇzeme si tak´e pˇredstavit jako prvky kolekce). Napˇr´ıklad.:
6
2.2. ´Urovnˇe RESTu
• /article - manipulace se seznamem ˇcl´ank˚u (kolekce)
• /article/:id- manipulujeme s jedn´ım konkr´etn´ım prvkem kolekce, iden- tifikovan´ym podle:id
Pokud pracujeme se strukturovan´ymi daty, t´emˇeˇr vˇzdy naraz´ıme na probl´em, jak ˇreˇsit relace. Aˇckoli samotn´y REST nedefinuje zp˚usob, jak relace ˇreˇsit (klade pouze poˇzadavek na to, aby byl kaˇzd´y zdroj jednoznaˇcnˇe identifikov´an), je nepsan´ym pravidlem uv´adˇet relace v n´asleduj´ıc´ım tvaru:
<zdroj>/:idZdroj/<relace>/:idRelace. Pokud toto prom´ıtnu v konkr´etn´ıch pˇr´ıpadech, pak:
• /article/1/comment- seznam vˇsech koment´aˇr˚u pro ˇcl´anek 1 (kolekce)
• /article/1/comment/2 - konkr´etn´ı koment´aˇr ke konkr´etn´ımu ˇcl´anku Pro tuto konkr´etn´ı pr´aci jiˇz z t´eto definice vypl´yv´a d˚uleˇzit´a a nutn´a vlast- nost, a tou je pr´ace s parametrick´ymi URL.
2.2.3 HTTP Verbs
Jelikoˇz se zab´yv´ame pˇrenosem dat pomoc´ı protokolu HTTP, pˇredstav´ıme si v t´eto kapitole, jak´e metody n´am HTTP protokol nab´ız´ı a kter´e jsou RESTem pouˇz´ıvan´e. V tabulce 2.1 naleznete n´azev a v´yznam pouˇzit´ych metod.
GET Z´ısk´an´ı dat POST Vytvoˇren´ı dat
PUT ´Uprava dat DELETE Odstranˇen´ı dat
PATCH ˇC´asteˇcn´a ´uprava dat
Tabulka 2.1: HTTP metody pouzivane v souvislosti s REST
Kromˇe tˇechto definic se m˚uˇzeme setkat jeˇstˇe s vyj´adˇren´ım, ˇze metoda GET jesafe. To znamen´a, ˇze pˇri vol´an´ı t´eto metody nedoch´az´ı k ˇz´adn´e zmˇenˇe
2. REST
rozˇs´ıˇren´ı dodateˇcnˇe [5]. Z pohledu RESTu je pak nutn´e implementovat ˇctyˇri z´akladn´ı operace, oznaˇcovan´e jako CRUD. Jedn´a se o Create, Retrieve, Up- date a Delete. Jak vid´ıme, protokol HTTP je zcela dostaˇcuj´ıc´ı pro pokryt´ı poˇzadovan´ych metod.
Kromˇe r˚uzn´ych metod, kter´e lze pouˇz´ıt pˇri dotazov´an´ı se na zdroj n´am HTTP poskytuje tak´e sadu stavov´ych k´od˚u pro odpovˇed’. Jejich kompletn´ı seznam spoleˇcnˇe s v´yznamem je k dispozici v ofici´aln´ı dokumentaci.
2.2.4 Hypermedia Controls
Posledn´ı ´uroveˇn je zn´ama pod akronymem HATEOAS (Hypertext as the En- gine of Application State). Popisuje princip, kdy kaˇzd´y zdroj kromˇe samo- stn´ych dat poskytne tak´e seznam operac´ı, kter´e lze vyuˇz´ıt v souvislosti s dan´ym poˇzadavkem. To pˇrin´aˇs´ı ˇradu v´yhod, napˇr´ıklad odpad´a nutnost udrˇzovat na stranˇe klienta vˇsechny adresy zdroj˚u, ale po prvotn´ım dotazu na server klient z´ısk´a seznam dostupn´ych operac´ı.
Aˇckoli vˇsak tento pˇr´ıstup pˇrin´aˇs´ı sv´e v´yhody, v souˇcasnosti nen´ı aˇz na drobn´e v´yjimky vyuˇz´ıv´an zejm´ena d´ıky chybˇej´ıc´ım n´astroj˚um jak efektivnˇe pˇren´aˇset tyto odkazy.
8
Kapitola 3
Anal´ yza
Bˇehem anal´yzy se zamˇeˇruji na vydefinov´an´ı oˇcek´avan´e funkcionality a po- rovn´an´ıs dostupn´ymi ˇreˇsen´ımi. Mezi dostupn´a ˇreˇsen´ıse snaˇz´ım vybrat zaj´ımav´e frameworky, se kter´ymi se m˚uˇze v´yvoj´aˇr v r˚uzn´ych odvˇetv´ıch setkat.
3.1 V´ ybˇ er dostupn´ ych ˇ reˇ sen´ı
V t´eto kapitole porovn´av´am aktu´alnˇe dostupn´a ˇreˇsen´ı, kter´a se snaˇz´ım vyb´ırat z r˚uzn´ych odvˇetv´ı, jelikoˇz ne vˇzdy m´a program´ator moˇznost zvolit si fra- mework, ve kter´em bude sv´e ˇreˇsen´ı implementovat.
3.1.1 Dostupn´e frameworky 3.1.1.1 Laravel[6]
Tento framework se ˇrad´ı mezi ty popul´arnˇejˇs´ı frameworky a je velice obl´ıben pro svou jednoduchost a tedy je vhodn´y pro rychl´e prototypov´an´ı. Laravel s´am o sobˇe obsahuje sv˚uj vlastn´ı ORM framework Eloquent. Vybral jsem jej zejm´ena kv˚uli jeho obl´ıbenosti mezi v´yvoj´aˇri.
3.1.1.2 Symfony[7]
Dlouhodobˇe stabiln´ı s pomˇernˇe rozˇs´ıˇren´y framework, kter´y je postaven na sadˇe
3. Anal´yza
na komponent´ach ostatn´ıch framework˚u, jako je Zend nebo Symfony. Fra- mework poskytuje mimo jin´e tak´e velmi propracovan´y podp˚urn´y syst´em pro tvorbu REST API a proto byl zahrnut do t´eto pr´ace.
3.1.1.4 Nette[9]
Mezi v´yvoj´aˇri v ˇcesk´e republice velice popul´arn´ıframework postaven´y na MVC architektuˇre. Je jednoduch´y, snaˇz´ı se o pouˇz´ıv´an´ı komponent a je tak´e velmi snadno pouˇziteln´y. Do t´eto pr´ace jsem jej zahrnul pro svou obl´ıbenost na ˇcesk´em trhu. Pro ´uˇcely t´eto pr´ace bylo hodnoceno nette s rozˇs´ıˇren´ım Apitte, kter´e jsem shledal asi nejlepˇs´ım rozˇs´ıˇren´ım pro REST API pro tento fra- mework.
3.2 Zhodnocen´ı dostupn´ ych ˇ reˇ sen´ı
V t´eto kapitole se zab´yv´am zhodnocen´ım v´yˇse uveden´ych framework˚u a kniho- ven podle definovan´ych krit´eri´ı.
3.2.1 V´ybˇer hodnot´ıc´ıch krit´eri´ı
Neˇz bude moˇzn´e zhodnotit vybran´a ˇreˇsen´ı, je nutn´e si stanovit hodnot´ıc´ı krit´eria. Hodnocen´ı bude prob´ıhat na ˇsk´ale od 1 do 5, jako ve ˇskole. Tedy 1 znamen´a nejlepˇs´ı a 5 nejhorˇs´ı.
Dokumentace
Pro spr´avn´e a efektivn´ı pouˇz´ıv´an´ı frameworku/knihovny potˇrebuji kvalitn´ı do- kumentaci. Pokud zvolen´e ˇreˇsen´ı nem´a kvalitnˇe vypracovanou dokumentaci a j´a naraz´ım na probl´em, m˚uˇze se mi pouˇz´ıv´an´ı znaˇcnˇe zkomplikovat. Stejnˇe tak pokud nem´am informaci o vˇsech moˇznostech dan´eho ˇreˇsen´ı, nemus´ım plnˇe vyuˇz´ıt jeho potenci´al. Z tohoto d˚uvodu ze pˇri hodnocen´ı dokumentace zamˇeˇruji na:
• Obs´ahlost – tedy zda obsahuje dostatek informac´ıpotˇrebn´ych pro pouˇz´ıv´an´ı dokumentace
• Zda dokumentace obsahuje pˇr´ıklady pouˇzit´ı u jednotliv´ych koncept˚u, pˇr´ıpadnˇe v jak´e m´ıˇre
• Pˇrehlednost – tedy jestli je dokumentace pˇrehlednˇe strukturovan´a, zda m´a logick´e ˇclenˇen´ı a zda se dostanu vˇsude tam, kam potˇrebuji
10
3.2. Zhodnocen´ı dostupn´ych ˇreˇsen´ı
Jednoduchost pouˇz´ıv´an´ı
Knihovnu/framework si vyb´ır´am proto, aby mi pomohla. Pokud budu nucen pˇri n´avrhu REST API ˇreˇsit vˇeci, kter´e pˇr´ımo nesouvisej´ı s n´avrhem, pak je dan´e ˇreˇsen´ı hodnoceno negativnˇe. Jednoduchost pouˇz´ıv´an´ı je zde posuzov´ana z pohledu usnadnˇen´ı n´avrhu REST API (jak mi framework pom´ah´a pˇri jeho tvorbˇe).
Podpora r˚uzn´ych form´at˚u
Rozˇsiˇritelnost z hlediska podpory r˚uzn´ych aplikaˇcn´ıch form´at˚u, nejˇcastˇeji JSON nebo XML. Od vybran´eho ˇreˇsen´ı oˇcek´av´am flexibiln´ı podporu v´ıce form´at˚u, jako i jejich jednoduchou rozˇsiˇritelnost. Tato vlastnost je v REST API termi- nologii oznaˇcov´ana jakoContent Negotiation[10].
Pr´ace s daty
Toto krit´erium hodnot´ısamotnou pr´aci s daty. Tedy zda je k dat˚um pˇristupov´ano strukturovanˇe, jsou-li data validovan´a (ˇreˇsen´ıpodporuje validaci data na ´urovni vstupu) a jak sloˇzit´e datov´e struktury je schopno dan´e ˇreˇsen´ı pojmout.
Moˇznosti konfigurace
Zde se hodnot´ı moˇznost flexibiln´ıho pouˇz´ıv´an´ı. Zejm´ena se pak ˇreˇs´ı ot´azka, zda ˇreˇsen´ı vyˇzaduje urˇcit´e jmenn´e konvence nebo je moˇzn´e tyto konfigurovat (napˇr´ıklad zda je vyˇzadov´ano implementovat metodu read() a nebo je moˇzn´e vyuˇz´ıvat i jinou metodu pro z´ısk´an´ı dat).
Celkov´e zhodnocen´ı
Obecn´e hodnocen´ı dan´eho ˇreˇsen´ı. Shrnut´ı pˇredchoz´ıch bod˚u s ohledem na dalˇs´ı vlastnosti zvolen´eho ˇreˇsen´ı, kter´e je dobr´e br´at v ´uvahu. Tak´e pˇr´ıpadn´e vyzdvihnut´ı pozitivn´ıch vlastnost´ı, kter´e by bylo dobr´e m´ıt ve sv´em fin´aln´ım ˇreˇsen´ı.
3.2.2 Hodnocen´ı ˇreˇsen´ı
3. Anal´yza
Jednoduchost pouˇz´ıv´an´ı
Framework poskytuje n´astroje a moˇznosti pro tvorbu API a urˇcitˇe se snaˇz´ı program´atorovi pomoct s n´avrhem a pouˇz´ıv´an´ım. Nastaven´ı routov´an´ı je jed- noduch´e a nav´ıc framework dok´aˇze poskytnout instanci objektu pokud mu poskytneme data ve strukturovan´e podobˇe. Hodnocen´ı je tedy veskrze pozi- tivn´ı:2.
Podpora r˚uzn´ych form´at˚u
Laravel v z´akladu poskytuje podporu JSON form´atu, kter´y je v oblasti REST API nejpouˇz´ıvanˇejˇs´ım form´atem (uveden´ı zdroje). D´ale je moˇzn´e rozˇs´ıˇrit funk- cionalitu frameworku o form´at XML a stejnˇe tak i dalˇs´ı uvaˇzovan´e form´aty dle libosti, d´ıky konceptu middleware, kter´y m˚uˇze kdokoli vyuˇz´ıt. Hodnocen´ı je stejn´e jako v pˇredchoz´ım bodˇe, tedy 2.
Pr´ace s daty
Framework s daty pracuje pomˇernˇe uspokojivˇe – parsuje data do objektov´e reprezentace, i kdyˇz tato nen´ı definovan´a uˇzivatelem (jedn´a se pouze o obec- nou tˇr´ıdu). N´asledn´e pouˇz´ıv´an´ı vstup˚u je objektov´e, avˇsak pokud vyˇzaduji striktnˇejˇs´ı validace, nevyhnu se tomu, abych si nepsal vlastn´ı pˇr´ımo v obsluˇzn´e metodˇe. N´avratov´e hodnoty mohou b´yt tak´e objekty, coˇz znaˇcnˇe zjednoduˇs´ı pr´aci, protoˇze uˇzivatel potom nen´ı nucen ruˇcnˇe volat transformace. Hodnocen´ı je tedy kladn´a 2.
Moˇznosti konfigurace
Framework je konfigurov´an ve vyˇclenˇen´em PHP souboru, kde se odkazuji na r˚uzn´e direktivy. Z hlediska pˇrehlednosti bych jako v´yvoj´aˇr ocenil m´ıt samo- statn´y konfiguraˇcn´ı soubor, ve kter´em by se veˇsker´a konfigurace odehr´avala.
Nen´ı zde moˇznost urˇcit si pˇr´ıpadn´e mapov´an´ı parametr˚u (myˇsleno query string) nebo jejich validace. Hodnocen´ı je za3.
Celkov´e zhodnocen´ı
Framework jako takov´y se mi l´ıb´ı, je minimalistick´y a v´ykonn´y. Poskytuje tak´e vˇetˇsinu standardn´ıch n´astroj˚u pro v´yvoj webu. V oblasti REST API jsou zde nedostatky pˇredevˇs´ım ohlednˇe konfigurace, nicm´enˇe celkovˇe se d´a framework povaˇzovat za jeden z tˇech lepˇs´ıch pro v´yvoj REST API. Na frameworku se mi l´ıbilo mapov´an´ı vstupu pˇr´ımo na entity, avˇsak za dodrˇzen´ı urˇcit´ych pravidel a pouze pro jednoduch´e struktury. Celkovˇe tedy hodnot´ım za3.
12
3.2. Zhodnocen´ı dostupn´ych ˇreˇsen´ı
3.2.2.2 Hodnocen´ı Magento 2 Dokumentace
Framework poskytuje obs´ahlou dokumentaci online. Do dokumentace pˇrisp´ıv´a komunita. Aˇckoli se jedn´a o pomˇernˇe obs´ahlou a na pˇr´ıklady bohatou doku- mentaci, mnoh´e funkcionality, kter´e nejsou ˇcasto vyuˇz´ıvan´e, uˇzivatel dohled´a aˇz pˇri samotn´em pouˇz´ıv´an´ı. Toto m˚uˇze ˇcinit nesn´aze pˇri pouˇz´ıv´an´ı a proto hodnot´ım za3.
Jednoduchost pouˇz´ıv´an´ı
Zde je nejvˇetˇs´ı slabina tohoto frameworku, jelikoˇz jej mnoz´ı hodnot´ı jako n´aroˇcn´y na pouˇz´ıv´an´ı. Toto je pravda zejm´ena v poˇc´atc´ıch v´yvoje, jelikoˇz samotn´y framework pracuje s pomˇernˇe odliˇsn´ymi koncepty, neˇz ostatn´ı do- stupn´e PHP frameworky a to i v oblasti REST API. Nicm´enˇe celkovou pr´aci s frameworkem hodnot´ım neutr´alnˇe, tedy za3.
Podpora r˚uzn´ych form´at˚u
Zde je framework naprosto vyhovuj´ıc´ı. V z´akladu poskytuje podporu pro form´aty JSON a XML, nicm´enˇe je moˇzn´e dodat podporu vlastn´ıho form´atu, framework v tomto ohledu nepˇrin´aˇs´ı ˇz´adn´e omezen´ı. Celkovˇe se mi podpora form´at˚u u tohoto frameworku l´ıbila a hodnot´ım velmi kladnˇe, tedy 1.
Pr´ace s daty
V t´eto oblasti je framework Magento 2 tak´e velmi n´apomocen, jelikoˇz veˇsker´e vstupn´ı data se snaˇz´ı namapovat na objekty. Jako vstupn´ı objekt do REST API m˚uˇze uˇzivatel pouˇz´ıt jak model entity v datab´azi, tak vlastn´ı model nez´avisl´y na datab´azi. Z obluˇzn´e metody pro REST API je moˇzn´e vr´atit tak´e objekt, kter´y je d´ale pˇreveden do reprezentace urˇcen´e pro klienta, nen´ı tedy nutn´e vlastnoruˇcnˇe pˇrev´adˇet data do asociativn´ıho pole. Oproti ostatn´ım fra- mework˚um nen´ı nutn´a ani ˇz´adn´a ´uprava vr´acen´eho objektu, jelikoˇz data jsou z objektu extrahov´ana pomoc´ı getter˚u. Hodnocen´ı je stejn´e jako v pˇredchoz´ım bodˇe, tedy 1.
3. Anal´yza
Celkov´e zhodnocen´ı
Tento framework poskytuje ˇradu moˇznost´ı jak zadefinovat REST API end- point a jak jej pouˇz´ıvat. Jako v´yvoj´aˇr oceˇnuji moˇznosti mapov´an´ı vstupn´ıch a v´ystupn´ıch dat z/do objekt˚u a to i sloˇzitˇejˇs´ıch struktur. Rovnˇeˇz oceˇnuji to, ˇze nen´ı nutn´e modfikovat objekty do/ze kter´ych m´a b´yt mapov´an´ı provedeno.
Framework totiˇz pouˇz´ıv´a vˇsem dobˇre zn´am´e getry a setry a dan´e objekty tak neobsahuj´ı nic nav´ıc. Celkov´a zn´amka, kterou tomuto frameworku udˇeluji je tedy 2.
3.2.2.3 Hodnocen´ı Nette Dokumentace
Dokumentace Nette samotn´eho je na tom o nˇeco h˚uˇre, neˇz dokumentace knihovny, kterou jsem zvolil pro tvorbu REST API. V porovn´an´ı s ostatn´ımi frameworky mi u Nette frameworku vad´ı nedostateˇcn´a dokumentace jednak k´odu (chybˇej´ıc´ıPHPDoc) a tak´e chybˇej´ıc´ı pˇr´ıklady pro bˇeˇzn´e ´ukony. U pouˇzit´e knihovny pro REST API byla dokumentace na webu dostateˇcn´a, avˇsak chybˇej´ıc´ı PHPDoc, kter´y by objasnil ´uˇcel nˇekter´ych metod/tˇr´ıd st´ale chyb´ı. Celkovˇe tedy mus´ım udˇelit4.
Jednoduchost pouˇz´ıv´an´ı
Samotn´e rozbˇehnut´ı projektu a n´asledn´e pouˇz´ıv´an´ı je u tohoto frameworku pomˇernˇe jednoduch´e. Pouˇz´ıv´an´ıREST API sluˇzeb (za pouˇzit´ıknihovnyApitte) je pomˇernˇe jednoduch´e a uˇzivatel se ve struktuˇre snadno orientuje. Zde udˇeluji hodnocen´ı shodn´e s frameworkem Laravel - tedy 2.
Podpora r˚uzn´ych form´at˚u
Pro Nette existuje spousta knihoven pro tvorbu REST API, kdy mnoh´e knihovny neposkytuj´ı jin´e form´aty neˇzJSON. Mnou pouˇzit´a knihovnaApitte vˇsak pod- poruje jak JSON, tak XML a CSV, aˇckoli to vyˇzaduje jist´a specifika. Je tak´e moˇzn´e doplnit vlastn´ı form´at pomˇernˇe jednoduˇse zaregistrov´an´ım dalˇs´ıho rozˇs´ıˇren´ı. Celkovˇe tedy hodnot´ım zn´amkou1.
Pr´ace s daty
Rozˇs´ıˇren´ı Apitte poskytuje n´astroj, jak vyuˇz´ıt mapov´an´ı do objektov´e repre- zentace, avˇsak toto mapov´an´ı mus´ı specifikovat samostatnˇe v´yvoj´aˇr. Dalˇs´ı nev´yhodou v tomto ohledu je nutnost dˇedˇen´ı z abstraktn´ı entity pro kaˇzdou vlastn´ı entitu, kter´a m´a b´yt renderovateln´a pro klienta. Toto omezen´ı ˇc´ın´ı pr´aci s entitami n´aroˇcnˇejˇs´ı a pokud bychom chtˇeli pouˇz´ıt z´akladn´ı moˇznosti pr´ace s daty, pak se jedn´a o pˇr´ıstup k obsahu odpovˇedi pˇr´ımo pˇres obecn´y getter, proto hodnot´ım zn´amkou 2.
14
3.2. Zhodnocen´ı dostupn´ych ˇreˇsen´ı
Moˇznosti konfigurace
Samotn´a Apitte knihovna pro Nette se konfiguruje pomoc´ı anotac´ı a ty po- skytuj´ı pestrou paletu moˇznost´ı. Pomoc´ı anotac´ı je moˇzn´e nakonfigurovat mapov´an´ı vstupu do entity, validace a pˇr´ıpadn´e dalˇs´ı vlastnosti. Je moˇzn´e pouˇz´ıvat tak´e rozˇs´ıˇren´e funkce jako vlastn´ı valid´ator pomoc´ıSymfonyValida- tor avˇsak pro tento je zapotˇreb´ı instalace dalˇs´ıch bal´ıˇck˚u. Konfigurace je za mˇe zcela dostaˇcuj´ıc´ı a tedy hodnot´ım zn´amkou 1
Celkov´e zhodnocen´ı
U Nette frameworku a rozˇs´ıˇren´ı Apitte je velice pozitivn´ı pˇr´ıstup k dat˚um.
Oproti jin´ym knihovn´am a pˇredchoz´ım verz´ım nette je vidˇet posun v kvalitˇe proveden´ı. Velmi kladnˇe hodnot´ım moˇznost v´ıce form´at˚u stejnˇe jako moˇznosti konfigurace. Celkovˇe framework hodnot´ım zn´amkou 2
3.2.2.4 Hodnocen´ı Symfony Dokumentace
Dokumentace samotn´eho Symfony frameworku je obs´ahl´a, avˇsak postr´ad´am zde rozs´ahlejˇs´ı uk´azky k´odu. Pˇri orientaci v dokumentaci mne pˇrekvapila nemoˇznost zobrazit kompletn´ı strukturu dokumentace. Nav´ıc pˇri orientaci v dokumentaci se menu mˇen´ı, a tedy v´ysledn´y efekt je matouc´ı. Samotn´a obs´ahlost a mnoˇzstv´ıinformac´ıv dokumentaci obsaˇzan´e jsou dostateˇcn´e, nicm´enˇe d´ıky nekonzistentn´ı orientaci v dokumentaci hodnot´ım negativnˇe - tedy 4. Jednoduchost pouˇz´ıv´an´ı
N´aroˇcnost pouˇz´ıv´an´ı bych hodnotil jako n´aroˇcnˇejˇs´ı a to zejm´ena z d˚uvodu vysok´e modularity syst´emu. Podobnˇe jako u Magento 2 frameworku, je i zde probl´em s poˇc´ateˇcn´ım pouˇz´ıv´an´ım frameworku, nicm´enˇe po ˇcase je pouˇzit´ı pˇrehlednˇejˇs´ı. Z tohoto d˚uvodu hodnot´ım n´aroˇcnost pouˇzit´ı za3.
Podpora r˚uzn´ych form´at˚u
Framework s rozˇs´ıˇren´ım podporuje spoustu form´at˚u, vˇcetnˇe standardn´ıhoJSON a XML form´atu. Stejnˇe tak nechyb´ı ani moˇznost doplnit form´at vlastn´ı, tedy
3. Anal´yza
Podobn´ym mechanismem je pot´e obejtkov´a reprezentace zpracov´av´ana do v´ystupu, kter´y je opˇet moˇzn´e vracet z obsluˇzn´e metody. Zde hodnot´ı o nˇeco l´epe, neˇz pˇredchoz´ı ˇreˇsen´ı, tedy 1.
Moˇznosti konfigurace
Na tomto frameworku se mi l´ıb´ımoˇznost zvolit si zp˚usob konfigurace. Na v´ybˇer jeyaml,xml a tak´ephp. U cest pro REST API a oblusˇzn´ych metod je moˇzn´e vyuˇz´ıvat tak´e anotac´ı, kter´e urˇcuj´ı transformace na nejniˇzˇs´ı ´urovni. Z tohoto pohledu je framework naprosto dostaˇcuj´ıc´ı. Hodnocen´ı je tedy nejlepˇs´ı, tedy 1.
Celkov´e zhodnocen´ı
Celkovˇe se mi na frameworku l´ıbilo smˇeˇrov´an´ı smˇerem k modularizaci a zno- vupouˇzitelnosti komponent, jako samostatn´e jednotky. D´ıky tomuto konceptu, je moˇzn´e vyp´ınat/zap´ınat jednotliv´e bal´ıˇcky dle potˇreby a dynamicky si obo- hatit sv´e REST API o dalˇs´ı funkcionality. Ovˇsem d´ıky sloˇzitˇejˇs´ımu pouˇzit´ı a pro mˇe ne pˇr´ıliˇs dobˇre strukturovan´e dokumentaci mus´ım hodnotit celkovˇe za 2.
3.2.3 Z´avˇer hodnocen´ı
V tabulce 3.1 m˚uˇzeme nal´ezt pˇrehled hodnocen´ı:
Laravel Magento 2 Nette Symfony
Dokumentace 2 3 4 4
Jednoduchost pouˇz´ıv´an´ı 2 3 2 3
Podpora r˚uzn´ych form´at˚u 2 1 1 1
Pr´ace s daty 2 1 2 1
Moˇznosti konfigurace 3 1 1 1
Celkov´e zhodnocen´ı 3 2 2 2
Tabulka 3.1: Pˇrehled hodnocen´ı jednotliv´ych framework˚u
Z pˇrehledu hodnocen´ı vid´ıme, ˇze kromˇe frameworku Laravel je hodnocen´ı napˇr´ıˇc kategoriemi zhruba stejn´e, u zb´yvaj´ıc´ıch framework˚u byla nejvˇetˇs´ı sla- binou dokumentace a d´ale jednoduchost pouˇz´ıv´an´ı. Zejm´ena u jednoduchosti pouˇz´ıv´an´ı je komplikac´ı tak´e to, ˇze kaˇzd´y framework pouˇz´ıv´a trochu odliˇsn´e koncepty a d´ıky tomu v´yvoj´aˇri mus´ı vˇenovat v´ıce ˇcasu a ´usil´ı pro samotn´e pouˇz´ıv´an´ı r˚uzn´ych framework˚u.
Dalˇs´ı zaj´ımavost´ı je, ˇze aˇckoli u ORM framework˚u, kde je nejrozˇs´ıˇrenˇejˇs´ım frameworkem Docrtine 2, kterou lze pouˇz´ıt napˇr´ıˇc r˚uzn´ymi projekty, mnohdy dokonce se stejn´ymi entitami (existuje jist´a pˇrenostielnost mezi projekty), pro 16
3.3. Poˇzadovan´a funkcionalita REST API podobn´y framework nen´ı k dispozici. Jednou z moˇzn´ych pˇr´ıˇcit m˚uˇze b´yt uzˇs´ı prov´azanost REST API na j´adro frameworku a business logiku, ovˇsem v kombinaci s pˇrenositeln´ym ORM frameworkem vid´ım potenci´al v samostatnˇe pouˇziteln´e knihovnˇe.
3.3 Poˇ zadovan´ a funkcionalita
C´ılem t´eto podkapitoly je hrubˇe nast´ınit poˇzadavky na funkcionality a fin´aln´ı pouˇzit´ı, kter´e se pokus´ım dos´ahnout ve vlastn´ım ˇreˇsen´ı.
3.3.1 Oddˇelen´ı REST API a web kontroler˚u
Pokud porovn´am Nette framework s Magento 2 frameworkem, tak si m˚uˇzu vˇsimnout z´asadn´ıho rozd´ılu ve zp˚usobu zpracov´an´ı poˇzadavk˚u. T´ım rozd´ılem je pˇr´ıstup ke zpracov´an´ı poˇzadavk˚u. Zat´ım v Nette frameworku se setk´ame s pˇr´ıstupem, kdy REST API kontroler je rozˇs´ıˇren´ım klasick´eho web kontro- leru (v mnoh´ych pˇr´ıpadech, net´yk´a se ovˇsem Appite rozˇs´ıˇren´ı), v Magento 2 frameworku je tomu pˇresnˇe naopak. Tedy REST API sluˇzby vyuˇz´ıvaj´ı jin´y mechanismus zpracov´an´ı a jsou oddˇeleny od klasick´ych kontroler˚u.
Ve vlastn´ım ˇreˇsen´ı bude upˇrednostnˇen pˇr´ıstup s oddˇelen´ym REST API a webov´ym kontrolerem. T´ım bude do jist´e m´ıry zajiˇstˇena nez´avislost na dan´em frameworku a celkovˇe to pˇrispˇeje k znovupouˇzitelnosti komponent vytvoˇren´ych pro vlastn´ı knihovnu.
3.3.2 Podpora v´ıce form´at˚u
Vˇsechny porovn´avan´e frameworky nˇejak´ym zp˚usobem nab´ızej´ı podporu v´ıce form´at˚u, kter´e m˚uˇze uˇzivatel vyuˇz´ıt. Jedn´a se o velmi uˇziteˇcnou funkciona- litu, kterou bych chtˇel zachovat i ve fin´aln´ım ˇreˇsen´ı. Nejl´epe propracovanou stukturu vid´ım u frameworku Symfony, kdy je moˇzn´e pomˇernˇe snadno dopl- nit dalˇs´ı form´at vyuˇziteln´y proREST API. Podpora form´at˚u by pak mˇela b´yt zachov´ana jak na vstupu, tak na v´ystupu.
Vlastnosti, kdy server vr´at´ı klientovi odpovˇed’ v poˇzadovan´em form´atu se ˇr´ık´aContent negotiation[10] , konkr´etnˇe v t´eto knihovnˇe budeme vyuˇz´ıvat tzv.
Server-driven content negotiation[10]. Rozliˇsen´ı, jak´y form´at bude pouˇzit se
3. Anal´yza
v´ystup. Dalˇs´ım poˇzadavkem je moˇznost zpracov´avat sloˇzit´e datov´e struktury a tedy nutnost zajistit mapov´an´ı nejen skal´arn´ıch hodnot, ale tak´e sloˇzitˇejˇs´ıch objektov´ych struktur.
Mapov´an´ı v tomto pˇr´ıpadˇe bude prov´adˇeno pomoc´ı getter˚u a setter˚u, je- likoˇz to d´ale umoˇzˇnuje v´yvoj´aˇri rozˇs´ıˇren´ı funkcionality, napˇr´ıklad pokroˇcilejˇs´ı transformace pˇr´ımo v obejktu na z´akladˇe hodnot. Tento pˇr´ıstup pouˇz´ıv´a fra- meworkMagento 2 a hodnot´ım jej velmi kladnˇe, proto byl zvolen pro v´ysledn´e ˇreˇsen´ı.
D´ıky tomuto z´ısk´a v´yvoj´aˇr pˇresnˇejˇs´ı kontrolu nad daty a v´ysledn´a im- plementace v obsluˇzn´e metodˇe se m˚uˇze zab´yvat ˇcistˇe logikou specifickou pro aplikaci.
3.3.4 Validace vstupu
Validace dat jsou velmi d˚uleˇzit´e snad v kaˇzd´em API rozhran´ı(nejenom REST).
C´ılem validace je zajistit, aby dan´a pˇr´ıchoz´ı data byla platn´a a nevznikaly probl´emy napˇr´ıklad s datovou konzistenc´ı. Vstup bude ve v´ysledn´em ˇreˇsen´ı typovˇe validov´an jeˇstˇe pˇred mapov´an´ım do obejktov´e reprezentace. Dalˇs´ı po- kroˇcilejˇs´ıvalidace (napˇr´ıklad platnost relac´ına jin´e entity), bude moˇzn´e zajistit d´ıky mapov´an´ı pomoc´ı setter˚u, jak bylo zm´ınˇeno v podkapitole 3.3.3.
3.3.5 Autentizace uˇzivatele
Pokud chceme poskytovat rozs´ahlejˇs´ı REST API, kter´e umoˇzˇnuje tak´e ´upravu entit, avˇsak nechceme aby tato ´uprava byla provediteln´a k´ymkoli, je nutn´e zav´est jist´y zp˚usob autentizace. K tomuto ´uˇcelu bude knihovna samotn´a ps´ana jako mezi vrstva – tzv. middleware – aby bylo moˇzn´e zaˇradit zpracov´an´ı knihovny aˇz po definovan´e autentizaˇcn´ı mechanismy. Tento mechanismus bude velice podobn´y tomu, kter´y pouˇz´ıv´a knihovnaApitte proNette. Samotn´a au- tentizace nem˚uˇze b´yt souˇc´ast´ı v´ysledn´e knihovny, jelikoˇz by to pˇrineslo pˇr´ıliˇsn´e prov´az´an´ı s c´ılov´ym ˇreˇsen´ım.
3.4 Dotazn´ıkov´ e ˇ setˇ ren´ı
Za ´uˇcelem ovˇeˇren´ı d˚uleˇzitosti r˚uzn´ych vlastnost´ı v´ysledn´e knihovny, jsem vy- pracoval dotazn´ık zamˇeˇruj´ıc´ı se na zkuˇsenosti a oˇcek´av´an´ı v´yvoj´aˇr˚u pˇri tvorbˇe REST API sluˇzeb. Sbˇer dat prob´ıhal v obdob´ı od 10.3.2020 do 15.4.2020.
Bˇehem t´eto doby na dotazn´ık odpovˇedˇelo celkem 35 responsent˚u.
Dotazn´ıkov´e ˇsetˇren´ı bylo zvoleno aby bylo moˇzn´e porovnat vyspecifikovan´e poˇzedavky s re´alnou potˇrebou uˇzivatel˚u, jelikoˇz v t´eto pr´aci vych´az´ım pˇrev´aˇznˇe z potˇreb, kter´e vn´ım´am na r˚uzn´ych pozic´ıch v posledn´ıch letech. C´ılem do- tazn´ıku je tedy z´ısk´an´ı ˇsirˇs´ıho pohledu na vˇec a v´ysledky dotazn´ıku poslouˇz´ı 18
3.4. Dotazn´ıkov´e ˇsetˇren´ı jako ukazatel, na kterou z vydefinovan´ych funkcionalit se ve v´ysledn´em ˇreˇsen´ı zamˇeˇrit.
Dotazn´ık byl rozesl´an na poˇc´atku bˇrezna 2020 tˇremi hlavn´ımi informaˇcn´ımi kan´aly, a to sice:
• Pomoc´ı firemn´ı platformy Slack (ve spoleˇcnosti, kde jsem v dobˇe ro- zesl´an´ı dotazn´ıku p˚usobil)
• Pˇres Facebook skupiny, mezi spoluˇz´aky na FIT ˇCVUT
• Pomoc´ı emailov´ych kontakt˚u na starˇs´ı spolupracovn´ıky a spoluˇz´aky ze SPˇSEI Ostrava
3.4.1 Clenˇˇ en´ı dotazn´ıku
Dotazn´ık je rozˇclenˇen do ˇctyˇr sekc´ı a to podle druhu informac´ı, kter´y se v dan´e sekci snaˇz´ım z´ıskat. Jedn´a se o n´asleduj´ıc´ı sekce s uveden´ym v´yznamem:
Uvod´
C´ıl´ıpˇredevˇs´ım na z´akladn´ı ´udaje o profilu program´atora, tedy s jak´ymi n´astroji zat´ım pracoval, zda se aktivnˇe vˇenuje v´yvoji v PHP a dalˇs´ı ot´azky smˇeˇrovan´e na jeho aktu´aln´ı stav. Na z´akadˇe odpovˇed´ı zde uveden´ych se d´ale urˇc´ı, zda je nutn´e aby zodpov´ıdal ot´azky v sekci druh´e, nebo pˇrejde rovnou do sekce tˇret´ı.
Tvorba REST API sluˇzeb v jazyce PHP
Snahou t´eto sekce je z´ıskat informace o tom, jak je konkr´etn´ı v´yvoj´aˇr spokojen s postupem tvorby REST API sluˇzeb v jazyce PHP, jak´y framework povaˇzuje za nejlepˇs´ı a zda byly dan´e n´astroje vyb´ır´any s ohledem na budouc´ı tvorbu REST API sluˇzeb.
Oˇcek´av´an´ı od n´astroj˚u
Jak´a jsou hlavn´ı oˇcek´av´an´ı od n´astroj˚u pro tvorbu REST API, bez ohledu
3. Anal´yza
3.4.2 V´ysledky dotazn´ıku
Z celkov´eho dotazn´ıku bych nyn´ı zd˚uraznil pˇredevˇs´ım sekci ˇc´ıslo 3, jelikoˇz v n´ı se pojedn´av´a o oˇcek´av´an´ı, kter´a m´a v´yvoj´aˇr od zvolen´eho ˇreˇsen´ı a jakou hraj´ı roli. V tabulce 3.2 je vidˇet pˇrehled moˇznost´ı a jakou v´ahu jim pˇrikl´adaj´ı responsenti:
Vlastnost Hodnocen´ı
Moˇznost definovat validace nad daty 4,14
Rozs´ahlost dokumentace 3,86
Moˇznost si flexibilnˇe zadefinovat obsluˇzn´e metody 3,57
Podpora striktn´ıho typov´an´ı 3,51
Vyˇsˇs´ı m´ıra abstrakce - n´avrh na ´urovni interface 3,43
Snadn´a instalace ˇreˇsen´ı 3,43
Podpora r˚uzn´ych datov´ych form´at˚u 3,34 Co vˇse si m˚uˇzu konfigurovat bez z´asahu do k´odu 2,94
Tabulka 3.2: Pr˚umˇern´e zhodnocen´ı poˇzadovan´ych vlastnost´ı dle responsend˚u D´ale v t´eto sekci byla moˇznost pˇridat vlastn´ı poˇzadovan´e funkcionality. Je- den respondent zd˚uraznil potˇrebu podpory ORM entit, jeden oceˇnuje moˇznost generov´an´ı serveru i klienta z definice REST API (napˇr´ıklad ze specifikace OpenAPI). D´ale pak jeden resnpodent vyj´adˇril oˇcek´av´an´ı podpory n´astroj˚u pro integraˇcn´ı testov´an´ı.
Komplent´ı v´ysledky dotazn´ıku je moˇzn´e nal´ezt na pˇriloˇzen´em m´ediu jako pˇr´ılohu.
20
Kapitola 4
N´ avrh
Tato kapitola se zab´yv´a podrobn´ym n´avrhem knihovny, vˇcetnˇe vˇec´ı s t´ım souvijec´ıch, jako napˇr´ıklad pouˇzit´ı verzovac´ıch n´astroj˚u, zapracov´av´an´ı dalˇs´ıch verz´ı a celkovˇe proces˚u t´ykaj´ıch se v´ysledn´e knihovny.
4.1 Platforma
V´ysledn´a knihovna bude ps´ana pro jazyk PHP ve verzi 7.2 kompatibiln´ı. Vzhle- dem k povaze knihovny nen´ı nutn´e vyb´ırat datab´azi.
4.2 Verzov´ an´ı
Jelikoˇz pl´anuji knihovnu d´ale upravovat, pˇr´ıpadnˇe zveˇrejnit, je vhodn´e zvolit vyhovuj´ıc´ı verzovac´ı strategii jiˇz na zaˇc´atku projektu. Za t´ımto ´uˇcelem byl zvolen n´astroj Git, kter´y poskytuje velice efektivn´ı spr´avu verz´ı a umoˇznuje zapojen´ı v´ıce autor˚u.
[13]V souˇcasn´e dobˇe existuje v´ıce strategi´ı, jak verzovat k´od, j´a se pokus´ım nejˇcastˇejˇs´ı z nich popsat a vybrat takov´e, kter´e bude tomuto projektu nejv´ıce vyhovovat.
4. N´avrh
verz´ı z´aroveˇn. Z tohoto pohledu se toto workflow jev´ı z dlouhodob´eho hledika jako naprosto nevhodn´e, avˇsak v poˇc´ateˇcn´ı f´azi v´yvoje, zem´ena jedn´a-li se projekt udrˇzov´an jedn´ım v´yvoj´aˇrem, jako je tato pr´ace, svou jednoduchost´ı zcela dostaˇcuje.
4.2.2 Feature branching workflow
Jedn´a se v podstatˇe o rozˇs´ıˇren´ıcentralizovan´eho workflow. Hlavn´ım rozd´ılem je to, ˇze veˇsker´y novˇe vyv´yjen´y k´od je udrˇzov´an v samostatn´e vˇetvi, tzv.feature branch. Jakmile je nov´a funkcionalita vyvinuta, je nejprve otestov´ana a teprve pot´e zahrnuta do hlavn´ı vˇetve, tzv.master branch.
V´yhodou je tedy ˇcist´a vˇetev master, kter´a by nemˇela obsahovat chybn´y k´od a mˇela by b´yt vˇzdy provozu schopn´a. Dalˇs´ı v´yhodou je eliminace konflikt˚u pˇri v´yvoji v t´ymu.
Z pohledu t´eto z´avˇereˇcn´e pr´ace je vˇsak i toto workflow z dlouhodb´eho hlediska nev´yhodn´e, a to sice z d˚uvodu obt´ıˇzn´e podpory v´ıce funkˇcn´ıch verz´ı z´aroveˇn. Nevyhovuje ani v poˇc´ateˇcn´ı f´azi v´yvoje, jelikoˇz se nejedn´a o skupi- novou pr´aci.
4.2.3 Gitflow workflow
Jedn´a se o pomˇernˇe propracovan´e workflow poskytuj´ıc´ı podporu pro rychl´e opravy v k´odu u jiˇz zveˇrejnˇen´ych verz´ı, tzv. hotfix. Lze na nˇej pohl´ıˇzet jako na rozˇs´ıˇren´ıFeature branching workflow, avˇsak vˇetev, do kter´e v´yvoj´aˇr zapra- cov´av´a sv´e zmˇeny nen´ımaster, ale jedn´a se odevelop, kter´y nemus´ıobsahovat vˇzdy spustiteln´y k´od, ale do kter´eho se integruj´ı vˇsechny vyvinut´e funkciona- lity pˇred zveˇrejnˇen´ım nov´e verze.
Toto workflow se d´a d´ale jednoduˇse rozˇs´ıˇrit o moˇznost podpory v´ıce verz´ı souˇcasˇe a to vyuˇzit´ımreleaseverz´ıne jen jako integraˇcn´ıch a testovac´ıch vˇetv´ı pˇred zaˇclenˇen´ım domastervetve, ale vyuˇz´ıv´an´ım tˇechto vˇetv´ı i po zaˇclenen´ı domastervˇetve jako z´azem´ı pro pˇr´ıpadn´e opravy ve chv´ıli, kdy je jiˇz vyd´ana novˇejˇs´ı verze.
Pro tento projekt se jedn´a o ide´aln´ı workflow ve chv´ıli, kdy bude dokonˇcena prvn´ı verze a knihovna bude zpˇr´ıstupnˇena pro veˇrejnost a dalˇs´ı pˇrispˇevatele.
D´ıkyfeaturevˇetv´ım je moˇzn´e kontrolovat, kter´e funkcionality budou zaˇclenˇeny do nov´e verze, stejnˇe tak kontrolovat pˇr´ıpadn´e bugfixy.
Kompletn´ı sch´ema tohoto workflow lze nal´ezt na obr´azku 4.1:
22
4.2. Verzov´an´ı
4. N´avrh
k synchronizaci k´odu s ostatn´ımi v´yvoj´aˇri. Kaˇzd´y v´yvoj´aˇr zapojen´y do pro- jektu pracuje jednak na sv´e lok´aln´ı kopii projektu, ale tak´e vystavuje veˇrejnou podobu repozit´aˇre, kter´y mohou ostatn´ı v´yvoj´aˇri vyuˇz´ıt.
Toto workflow je ovˇsem proti z´amˇeru t´eto pr´ace a to poskytnout v´yvoj´aˇr˚um knihvnu. Ta totiˇz mus´ı b´yt nˇekde pˇr´ıstupn´a a z pohledu t´eto pr´ace by ned´avalo smysl aby byla distribuov´ana takto decentralizovanˇe. Proto nebude tohoto workflow nijak vyuˇzito.
4.2.5 Zvolen´e ˇreˇsen´ı
Jelikoˇz z poˇc´atku v´yvoje (obdob´ı tvorby t´eto pr´ace) budu na projektu praco- vat pouze j´a a jelikoˇz se jedn´a o nov´y projekt, nem´a smysl udrˇzovat sloˇzit´e workflow a tedy bude vyuˇzito Centralized workflow. V okamˇziku pˇr´ıpadn´eho zeveˇrejnˇen´ı zdrojov´ych k´od˚u pro veˇrejnost a umoˇznˇen´ı ostatn´ım v´yvoj´aˇr˚um rozˇs´ıˇren´ı knihovny o dalˇs´ı funkcionality, bude toto jednoduch´e workflow na- hrazeno sofistikovan´ymGitflow tak, jak bylo pops´ano v kapitole 4.2.3.
4.3 Composer
Jedn´a se o n´astroj pro spr´avu z´avislost´ı. V komunitˇe PHP v´yvoj´aˇr˚u je hojnˇe vyuˇz´ıv´an a um´ı pracovat tak´e s n´astrojem GIT, kter´y byl pops´an v kapitole 4.2. D´ıky Composeru, je moˇzn´e efektivnˇe spravovat z´avislosti na extern´ıch knihovn´ach, ˇr´ıdit jejich verze, pˇr´ıpadnˇe publikovat vlastn´ı knihovnu pro ˇsirˇs´ı komunitu. Jelikoˇz je hojnˇe vyuˇz´ıv´an, budu jej pouˇz´ıvat i ve v´ysledn´e knihovnˇe pr´avˇe pro spr´avu verz´ı knihovny.
4.4 OOP Design a principy
Vytvoˇren´a knihovna bude ps´ana objektovˇe orientovan´ym pˇr´ıstupem. To s se- bou pˇrin´aˇs´ı tak´e zodpovˇednost za dodrˇzov´an´ı spr´avn´eho n´avrhu architektury.
V t´eto podkapitole se budu vˇenovat d˚uleˇzit´ym OOP princip˚um, kter´e je tˇreba dodrˇzet za ´uˇcelem dosaˇzen´ı pokud moˇzno vˇsech vyspecifikovan´ych poˇzadavk˚u.
Z´akladn´ı principy pˇri n´avrhu v OOP jsou tzv. SOLID[14] principy, kter´e struˇcnˇe pop´ıˇsi v t´eto kapitole.
4.4.1 Princip jedn´e odpovˇednosti
Jedn´a se o velice jednoduch´y princip, kter´y ˇr´ık´a, ˇze kaˇzd´a tˇr´ıda by mˇela m´ıt pouze jednu zodpovˇednost (jeden d˚uvod ke zmˇenˇe). Pouˇzit´ı tohoto principu vede na mnoho menˇs´ıch tˇr´ıd, kter´e pak lze samostatnˇe udrˇzovat a to vede k vˇetˇs´ı udrˇzitelnosti syst´emu. Rovnˇeˇz pˇrisp´ıv´a k moˇzn´e modularitˇe syst´emu, jelikoˇz nab´ız´ı v´ıce moˇznost´ı k rozdˇelen´ı n´avrhu na jednotliv´e oblasti.
24
4.5. PHP-FIG PSR
4.4.2 Princip otevˇrenosti a uzavˇrenosti
Tento princip n´am ˇr´ık´a, ˇze tˇr´ıdy by mˇely b´yt navrˇzeny tak, aby bylo moˇzn´e je rozˇs´ıˇrit ide´alnˇe bez z´asahu do existuj´ıc´ıho k´odu. D´ıky tomuto se sn´ıˇz´ı riziko, ˇze pˇri pˇrepisov´an´ı jedn´e ˇc´asti aplikace poˇskod´ıme ˇc´asti jin´e. Kl´ıˇcem pro spr´avnou aplikaci tohoto principu je hojn´e vyuˇzit´ı abstrakce a polymorfismu.
4.4.3 Liskovov´e princip zamˇenitelnosti
Velice jednoduch´y, ale velice jednoduˇse poruˇsiteln´y princip, kter´y n´am ˇr´ık´a, ˇze pokud m´ame nˇejakou b´azovou tˇr´ıdu, kterou nahrad´ım jej´ım potomkem, pak bude implementace fungovat korektnˇe i s t´ımto potomkem. D´ıky tomuto prin- cipu je jasn´e, ˇze kaˇzd´a podtˇr´ıda mus´ı b´yt schopna poskytnout stejn´e vlastnosti jako tˇr´ıda b´azov´a. Pr´avˇe d´ıky t´eto vlastnosti je moˇzn´e efektivnˇe a jednoduˇse rozˇsiˇrovat v´ysledn´y syst´em/knihovnu.
4.4.4 Princip oddˇelen´ı rozhran´ı
V z´asadˇe ˇr´ık´a, ˇze v´ıce r˚uzn´ych rozhran´ı je lepˇs´ıch, neˇz jedno velk´e univerz´aln´ı.
Pokud m´ame jedno spoleˇcn´e rozhran´ı, ovˇsem jeho funkcionality spolu pˇr´ıliˇs nesouvis´ı, pak se rozr˚ust´a okruh tˇr´ıd, kter´e na dan´em rozhran´ı z´avis´ı a v pˇr´ıpadˇe ´upravy je pot´e n´aroˇcn´e kontrolovat zmˇeny, kter´e by mohly ovlivnit vˇsechny tˇr´ıdy, kter´e by mohly rozhran´ı pouˇz´ıvat. Pr´avˇe d´ıky tomu je lepˇs´ı rozhran´ı rozdˇelovat. Je vˇsak tˇreba d´avat pozor na vhodnou granularitu, jelikoˇz by striktn´ı dodrˇzov´an´ı tohoto principu mohlo vy´ustit v pˇr´ıliˇs mnoho drobn´ych rozhran´ı.
4.4.5 Princip obr´acen´ı z´avislost´ı
Jedn´a se o princip vyˇzaduj´ıc´ı aby z´avislosti byly vˇzdy na abstraktn´ım a ne na konkr´etn´ım. Tedy podle totoho principu je nutn´e, aby konkr´etnˇejˇs´ı implemen- tace z´avisela na abstraktnˇejˇs´ı, ne naopak. D´ıky tomuto principu v kombinaci s Liskovov´e principu zamˇenitelnosti je moˇzn´e jednoduˇse mˇenit implementace dan´e funkcionality bez vˇetˇs´ıho z´asahu do k´odu.
4.5 PHP-FIG PSR
4. N´avrh
pˇrenositeln´a mezi frameworky, pak je budu dodrˇzovat. V n´asleduj´ıc´ıch kapi- tol´ach pop´ıˇsi standardy, kter´e budu nejˇcastˇeji pouˇz´ıvat.
4.5.1 PSR-1
Jedn´a se o z´akladn´ı standard, kter´y je trouf´am si ˇr´ıct t´ım z´akladn´ım, co by mˇel v´yvoj´aˇr dodrˇzovat. Jedn´a se o popis vzhledu PHP souboru, kter´y by byo dobr´e dodrˇzovat kv˚uli ˇcitelnosti. V mnoha firm´ach je tento standard vyˇzadov´an a je podporov´an tak´e v mnoh´ych IDE. Nedodrˇzov´an´ı tohoto standardu vede k neˇciteln´emu, nebo tˇeˇzce ˇciteln´emu k´odu, kter´y je obt´ıˇzn´e udrˇzovat.
4.5.2 PSR-4
D´ıky tomuto standardu je moˇzn´e vyuˇz´ıvat knihovnu i mimo definovan´e prostˇred´ı.
Standard popisuje jak m´a vypadat adres´aˇrov´a struktura, aby bylo moˇzn´e tˇr´ıdy a rozhran´ı naˇc´ıtat dynamicky. Tento standard je uˇz´ıv´an ve spojistosti s n´astrojemComposer, kter´y byl pops´an v kapitole 4.3.
4.5.3 PSR-7
Tento standard je pro tuto pr´aci snad nejd˚uleˇzitˇejˇs´ım. Popisuje totiˇz pr´aci s HTTP poˇzadavky, jejich obsahem a obecnˇe popisuje, jak m´a dan´e rozˇs´ıˇren´ı zpracov´avat poˇzadavky a jak´e n´astroje m´a k dispozici. Pr´avˇe d´ıky tomuto standardu bude moˇzn´e vyuˇz´ıvat v´yslednou knihovnu v r˚uzn´ych frameworc´ıch (kter´e poskytuj´ı implementaciPSR-7 standardu).
4.5.4 PSR-11
Standard poskytuj´ıc´ırozhran´ıpro kontejner z´avislost´ı. D´ıky tomuto standardu nemus´ım v knihovnˇe specifikovat a popisovat vkl´ad´an´ı z´avislost´ı a vyhled´av´an´ı sluˇzeb, ale m˚uˇzu si pohodlnˇe vyˇz´adat kontejner, kter´y mi dan´e sluˇzby poskytne i se z´avislostmi.
4.6 Implementaˇ cn´ı n´ avrh j´ adra knihovny
D´ıky princip˚um popsan´ych v kapitole 4.4 a d´ıky znalosti poˇzadavk˚u z kapitoly 3.3 m˚uˇzeme nyn´ı navrhnout knihovnu tak, aby bylo moˇzn´e knihovnu d´ale pouˇz´ıvat v r˚uzn´ych frameworc´ıch.
Bˇehem n´avrhu je nutn´e br´at v ´uvahu pˇr´ıpadnou moˇznost implementaˇcn´ı zmˇeny dan´ych sluˇzeb. D´ıky tomu by se mˇel n´avrh pohybovat v maxim´aln´ı moˇzn´e m´ıˇre na ´urovni rozhran´ı. Konkr´etn´ı implementace bude dod´ana posl´eze kontejnerem c´ılov´e aplikaci.
26
4.6. Implementaˇcn´ı n´avrh j´adra knihovny Jednotliv´e d´ılˇc´ıimplementace knihovny pro pouˇzit´ıv r˚uzn´ych frameworc´ıch se d´ıky tomu m˚uˇze liˇsit a dod´avat sv´e vlastn´ı specifick´e ´upravy pro danou sluˇzbu.
4.6.1 J´adro knihovny
Aby bylo moˇzn´e pouˇz´ıvat knihovnu efektivnˇe v r˚uzn´ych prostˇred´ıch, byla zvo- lena jak implementace jako koncov´e rozhran´ı, tak jako middleware. To zna- men´a, ˇze program´ator pouˇz´ıvaj´ıc´ı tuto knihovnu se m˚uˇze rozhodnout, jak ji zaˇclen´ı do sv´eho k´odu.
Samotn´e j´adro je nutn´e rozdˇelit na d´ılˇc´ı sluˇzby, kter´e zajiˇst’uj´ı podporu pro r˚uzn´e funkˇcn´ı celky. Toto ˇclenˇen´ı bylo zvoleno zejm´ena kv˚uli udrˇzitelnosti v´yvoje do budoucna. Sluˇzby, na kter´e se j´adro dˇel´ı jsou:
RestCore
Tato sluˇzba by mˇela b´yt vstupn´ım bodem do knihovny. Poskytuje dvˇe mˇetody, kdy jedna slouˇz´ı jako middleware - tedy pˇrij´ım´a poˇzadavek a odpovˇed’, po- tencion´alnˇe pˇredszpracovanou jinou sluˇzbou, a vrac´ı odpovˇed’ obohacenou o vlastn´ı data. Poˇzadavek i odpovˇed’ jsou vyˇzadov´any dle doporuˇcen´ı PSR- 7, tedy jak´ykoli framework dodrˇzuj´ıc´ı nebo poskytuj´ıc´ı PSR-7 implementaci HTTP poˇzadavku a odpovˇedi bude moci vyuˇz´ıt tuto knihovnu.
Router
Tato sluˇzba slouˇz´ı k vyhled´an´ı vhodn´eho koncov´eho bodu (rzv. endpoint) pro pˇr´ıchoz´ı poˇzadavek a pokud nalzne vhodn´y endpoint, pak vr´at´ı jeho meta informace. O tom, jak´a je pouˇziteln´a HTTP metoda a jak´y m´a b´yt vzor pro URL (regex URL patter) rozhoduje samodn´y endpoint.
Vzhledem k odliˇsnosti pˇr´ıstupu ke konfiguraˇcn´ım soubor˚um v r˚uzn´ych fra- meworc´ıch a r˚uzn´ym moˇznostem parsov´an´ı jak soubor˚u, tak k´odu, je navrˇzeno ˇreˇsen´ıkdy knihovna vyˇzaduje objekt, kter´y v sobˇe drˇz´ıinformace o dostupn´ych
4. N´avrh
Dispatcher
Tato sluˇzba by mˇela b´yt vol´ana ve chv´ıli, kdy je zn´am´e, kter´y endpoint bude obsluhov´an. ´Ukolem Dispatcher sluˇzby je zajistit spr´avn´e zjiˇstˇen´ı vstupn´ıch parametr˚u pro poˇzadovanou cestu, spr´avn´e namapov´an´ı zjiˇstˇen´ych parametr˚u a v neposledn´ı ˇradˇe tak´e zpracov´an´ı v´ystupu z obluhovan´e metody.
Dispatcher spol´eh´a na pˇr´ıtomnost poˇzadovan´e metody v PSR-11 kontej- neru, tedy kontejneru, kter´y m´a zajistit spr´avn´e poskytnut´ı sluˇzeb dle dan´eho typu. D´ıky pouˇzit´ı PSR-11 kontejneru je moˇzn´e vyˇzadovat i sloˇzitˇejˇs´ı objekty, kter´e pˇr´ıpadnˇe vyˇzaduj´ı dalˇs´ı z´avislosti.
Ve chv´ıli, kdy z nˇejak´eho d˚uvodu nen´ı moˇzn´e obslouˇzit poˇzadavek, coˇz m˚uˇze b´yt zp˚usobeno napˇr´ıklad chybˇej´ıc´ım parametrem, nebo poskytnut´ı pa- rametru jin´eho neˇz oˇcek´avan´eho typu, je vytvoˇrena v´yjimka a tato je d´ale zachycena a zpracov´ana sluˇzbouExceptionMapper.
ExceptionMapper
Tato sluˇzba m´a za ´ukol mapovat v´yjimku na vstupu do odpov´ıdaj´ıc´ı struktury na v´ystupu. Za t´ımto ´uˇcelem je vytvoˇren pomocn´y objekt, viz kapitola 4.6.6.
Sluˇzba je zde zˇr´ızena pˇredevˇs´ım za ´uˇcelem budouc´ı rozˇsiˇritelnosti dle pˇr´an´ı program´atora, kter´y bude knihovnu vyuˇz´ıvat, protoˇze poskytuje moˇznost ma- povat r˚uzn´e typy v´yjimek do r˚uzn´ych sturktur.
Vyuˇzit´ı m˚uˇze b´yt napˇr´ıklad, pokud v aplikaci pouˇz´ıv´am v´yjimky NoSu- chEntityException a DuplicateEntryException, m˚uˇzu kaˇzdou z nich namapo- vat do jin´e stuktury, kterou posled´eze knihovna vyrenderuje do v´ysledn´eho form´atu tak, aby bylo moˇzn´e ji zobrazit klientovi.
4.6.2 Form´aty
Jak bylo deklarov´ano v kapitole 3.3.2, ne nutn´e zajistit podporu v´ıce form´at˚u pro danou knihovnu a ne se jen spol´ehat na pˇredem definovan´e vstupn´ı/v´ystupn´ı form´aty. Za t´ımto ´uˇcelem je navrˇzeno rozhran´ıFormatInterface, kter´e obsa- huje metodu, kter´a definuje metodu, d´ıky kter´e je moˇzn´e zjistit, zda dan´y form´at (na z´akladˇe mime-type) je moˇzn´e vyuˇz´ıt.
Z´aroveˇn poskytuje gettery pro tzv. Reader a Writer, tedy objekty, kter´e se d´ale staraj´ı o konverzi dat ze vstupu na intern´ı reprezentaci a obr´acenˇe.
Form´at bude moˇzn´e nadefinovat pouze jako vstupn´ı, pˇr´ıpadnˇe v´ystupn´ı na z´akladˇe dostupn´ychReader˚u aWriter˚u.
Zp˚usob udrˇzov´an´ı seznamu dostupn´ych form´at˚u bude realizov´an podobnˇe, jako seznam dostupn´ych endpoint˚u a to s ohledem na vyˇsˇs´ı m´ıru konfigurova- telnosti. D´ıky tomuto zp˚usobu je moˇzn´e prov´est napojen´ı na v´ysledn´e ˇreˇsen´ı.
28
4.6. Implementaˇcn´ı n´avrh j´adra knihovny
4.6.3 Reflexe
Jelikoˇz v knihovnˇe budeme ˇcasto pracovat s reflex´ı[16], a to zejm´ena pˇri ma- pov´an´ı obejkt˚u a jejich n´asledn´e dekompozici zpˇet do asociativn´ıho pole, je zde navrˇzeno vyuˇz´ıt zastˇreˇsuj´ıc´ı sluˇzby nazvan´eReflectionHolder. Tato sluˇzba bude m´ıt na starosti spr´avn´e zjiˇst’ov´an´ı vstupn´ıch parametr˚u pro settery a v´ystupn´ıch parametr˚u pro gettery.
Pro pr´aci s reflex´ıje vhodn´e pouˇz´ıt nˇejakou z jiˇz existuj´ıc´ıch knihovnen. Pro realizaci t´eto knihovny bylo zvoleno pouˇzit´ı knihovny laminas-code[17] (dˇr´ıve zn´am´a tak´e jako zend-code). Knihovna bylo zvolena pro svou jednoduchost pouˇzit´ı.
4.6.4 Mapov´an´ı vstupn´ıch dat
´Ukolem knihovny je mimo jin´e zajiˇstˇen´ı mapov´an´ı vstupn´ıch dat pro obluˇznou metodu, kdy pro zajiˇstˇen´ı spr´avn´eho mapov´an´ı a rozˇsiˇritelnosti je vyuˇzito podobn´eho principu jako u form´at˚u – tedy ˇze existuje jedna sluˇzba drˇz´ıc´ı vˇsechny dostupn´e mapovac´ı strategie. Mapovac´ı strategie budou realizov´any pomoc´ı tzv.:Mapper˚u a je pro to vyhrazeno rozhran´ıMapperInterface.
V z´akladn´ım stavu poskytuje knihovna mapov´an´ı pro vˇsechny primitivn´ı datov´e typy, objektov´e mapov´an´ı a tak´e mapov´an´ı pro objektovˇe relaˇcn´ı fra- mework Doctrine 2, resp. jeho entity.
Mapov´an´ı do objekt˚u je prov´adˇeno pomoc´ı setter˚u, coˇz pro ´uˇcely knihovny jsou vˇsechny metody zaˇc´ınaj´ıc´ıkl´ıˇcovou pˇredponouset. Seznam tˇechto metod, vˇcetnˇe jejich typ˚u bude z´ısk´an za pomoc´ı reflexe z ReflectionHolder kontej- neru. Struktura mapov´an´ı by mˇela b´yt takov´a, aby podporovala i vnoˇren´e datov´e struktury.
D´ıky mapov´an´ı pomoc´ı setter˚u bude moˇzn´e zav´est sloˇzitˇejˇs´ı validace spo- jen´e s business logikou pˇr´ımo v dan´e entitˇe. D´ıky prov´az´an´ı r˚uzn´ych va- lidaˇcn´ıch framework˚u a technik na dan´e c´ılov´e ˇreˇsen´ı, bylo zvoleno z´akladn´ı typov´e validov´an´ı v knihovnˇe, ale pokroˇcilejˇs´ı validaˇcn´ı pravidla souvisej´ıc´ı s business logikou aplikace necht’ jsou prov´adˇeny v pˇr´ısluˇsn´ych setterech.
U jednotliv´ych mapper˚u mus´ı b´yt moˇzn´e urˇcit, kter´eho typu vstupu se
4. N´avrh
4.6.5 Mapov´an´ı v´ystupn´ıch dat
Podobnˇe jako u vstupu, kdy je moˇzno mapovat vstupn´ı data do objektov´e reprezentace, knihovna by mˇela poskytovat tak´e zp˚usob jak mapovat objekty na v´ystupu do form´atu poˇzadovan´eho klientem.
Sluˇzba, kter´a toto bude zajiˇst’ovat se bude jmenovat ServiceOutputPro- cessor a bude prov´adˇet mapov´an´ı objekt˚u do asociativn´ıho pole na z´akladˇe getter˚u, tedy metody zaˇc´ınaj´ıc´ı na kl´ıˇcovou pˇredponu geta poskytuj´ıc´ı hod- noty pro dan´y atribut. Zde je opˇet hojnˇe vyuˇzitReflectionHolder k z´ısk´av´an´ı pˇr´ısluˇsn´ych informac´ı.
Mapov´an´ıv´ystupn´ıch dat, stejnˇe jako mapov´an´ıvstupn´ıch dat, je navrˇzeno tak, aby bylo moˇzn´e zpracov´avat i sloˇzitˇejˇs´ı datov´e struktury.
4.6.6 Zpracov´an´ı poˇzadavku
Zpracov´an´ı poˇzadavku provede, jak bylo pops´ano v kapitole 4.6.1, sluˇzba Dispatcher. Tato sluˇzba jist´ı z pˇr´ıchoz´ıho poˇzadavku v jak´ych form´atech ko- munikovat s klientem a v jak´em form´atu komunikuje klient samotn´y (je tedy moˇzn´e pouˇz´ıt r˚uzn´e form´aty pro vstup a pro v´ystup).
V n´asleduj´ıc´ım kroku by si mˇel Dispatcher zjistit dostupn´e a poˇzadovan´e hodnoty na vstupu. Pro zjiˇstˇen´ı poˇzadovan´ych hodnot servisn´ı metody je nutn´e pouˇz´ıt reflexi[16], kterou budeme ˇcasto vyuˇz´ıvat a proto je pro ni zˇr´ızena speci´aln´ı sluˇzba, tzv. ReflectionHolder. V´ıce o reflexi v kapitole 4.6.3
Po zjiˇstˇen´ıdostupn´eho form´atu je provedena konverze vstupn´ıch hodnot do poˇzadovan´ych parametr˚u servisn´ı metody. D´ıky tomuto se uˇzivatel pouˇz´ıvaj´ıc´ı tuto knihovnu nemus´ı starat o konverze, ani to, kde vz´ıt dan´e hodnoty. Jen- doduˇse uvede poˇzadovan´y typ a ten n´aslednˇe dostane.
N´aslednˇe je obluˇzn´a metoda poˇzadavku zavol´ana a jej´ı v´ystup je pot´e mapov´an jako odpovˇed’ klientovi. Odpovˇed’ m˚uˇze b´yt r˚uzn´ych typ˚u, pˇriˇcemˇz existuj´ı r˚uzn´a pravidla pro mapov´an´ı r˚uzn´ych typ˚u.
MinimalisticResponse
Pokud je vr´acena tato odpovˇed’, pak je jako v´ystup zpracov´an ne cel´y objekt, ale jeho data, ktr´a vloˇzil pˇred vytvoˇren´ım tohoto objektu uˇzivatel. V´yhodou pouˇzit´ıtohoto objektu pro v´ystup je moˇznost definovat si n´avratov´y k´od, kter´y bude navr´acen klientovi.
30
4.6. Implementaˇcn´ı n´avrh j´adra knihovny
ResponseInterface
Pokud je z obluˇzn´e metody navr´acen objekt implementuj´ıc´ıResponseInterface, pak je z Dispatcheru vr´acen pˇr´ımo tento objekt, jelikoˇz je zde pˇredpoklad, ˇze uˇzivatel v´ı co dˇel´a a odpovˇed’ n´aleˇzitˇe zpracoval jiˇz dˇr´ıve.
Ostatn´ı typy
Jak´ykoli jin´y typ je mapov´an pomoc´ı tzv. ServiceOutputProcessoru, kter´y se star´a o pˇreveden´ı pˇr´ıpadn´e objektov´e reprezentace do asociativn´ıho pole, kter´e je d´ale konvertov´ano do pˇr´ısluˇsn´eho form´atu, jak bylo pops´ano v kapitole 4.6.5 a 4.6.2.
4.6.7 Pˇr´ıklady budouc´ıho uˇzit´ı
Tato kapitola je urˇcen´a pro bliˇzˇs´ıilustraci v´ysledn´eho pouˇzit´ıknihovny, spoleˇcnˇe s bliˇzˇs´ım popisem tak, aby ˇcten´aˇr z´ıskal pˇredstavu o v´ysledn´em produktu.
Z´akladn´ı uˇzit´ı knihovny
Z´akladn´ı uˇzit´ı knihovny by mˇelo b´yt velice jednoduch´e. Staˇc´ı spr´avnˇe uv´adˇet typy, kter´e oˇcek´av´am na vstupu a kter´e poskytuji na v´ystupu dan´e obluˇzn´e metody. N´aslednˇe staˇc´ı zaregistrovat URI, kter´e povede k dan´e obluˇzn´e me- todˇe a to je vˇse. Pro koncov´eho program´atora by to mˇelo znamenat minimum konfigurace.
<?php
namespace App\Api\Controller;
class SomeService { /**
* @param string $string
*
* @return string
*/
public function get(string $string): string {
4. N´avrh
Pokud je Library entita spravovan´a pomoc´ı Doctrine 2 a j´a m´am definova- nou cestu ke zdroji jakoapi/v1/library/:lib/booksAvailable, kde m´ısto parametru :lib dosad´ım konkr´etn´ı ID knihovny, pak se mapov´an´ı postar´a o naˇcten´ı dan´e entity a j´a ji m´am jako program´ator k dispozici v obluˇzn´e metodˇe.
V pˇr´ıpadˇe, ˇze dan´a entita neexistuje, je vyhozena v´yjimka, kterou m˚uˇzu pohodlnˇe namapovat d´ıky ExceptionMapper sluˇzbˇe, kter´a je pops´ana v kapi- tole 4.6.1.
<?php
namespace App\Api\Controller;
use App\Entity\Library;
use App\Entity\Book;
class SomeService { /**
* @param Library $lib
*
* @return Book[]
*/
public function get(Library $lib): array { return $lib->getBooksAvailable();
} }
Jak si tak´e m˚uˇzete vˇsimnout, n´avratov´y typ uveden´y v PHP jearray, ale re´alnˇe se jedn´a o pole objekt˚u typuBook. Knihovna si tuto informaci spr´avnˇe zpracuje z anotace a provede pˇr´ısluˇsn´e mapov´an´ı odpov´ıdaj´ıc´ı dan´emu typu.
32
Kapitola 5
Realizace
V t´eto kapitole se budu vˇenovat v´ystup˚um praktick´e ˇc´asti t´eto pr´ace a po- stup˚um, kter´e vedly k jejich dokonˇcen´ı.
5.1 Postup realizace
V t´eto kapitole pojedn´av´am o postupu relalizace dan´e knihovny v kontextu cel´e pr´ace. Pro spr´avnou implementaci bylo zapotˇreb´ınejprve pˇren´est n´avrh do definovan´ych rozhran´ı v jazyce PHP. Rovnˇeˇz bylo zapotˇreb´ı vytvoˇren´ı bal´ıˇcku pro danou knihovnu.
Uvodn´ı f´´ aze
Po zapracov´an´ı rozhran´ı v jazyce PHP zaˇcala implementace hlavn´ıch kom- ponent, kter´e se staraj´ı o ˇzivotn´ı cyklus dan´eho poˇzadavku. Pro snadnˇejˇs´ı a rychlejˇs´ı testov´an´ı bylo jiˇz v prvotn´ı f´azi implementace rozhodnuto o paraleln´ı implementaci referenˇcn´ıho pouˇzit´ı ve frameworku Nette (v´ıce o referenˇcn´ı im- plementaci v kapitole 7).
Paraleln´ı implementace umoˇzˇnila vyzkouˇset si aktu´aln´ı rozpracovanou kni- hovnu, ale vyˇzadovalo to tak´e striktn´ı dodrˇzov´an´ı rozhran´ı, kter´e knihovna obsahuje a mˇela by obsahovat z d˚uvodu rozˇsiˇritelnosti a pˇrenositelnosti.
5. Realizace
testov´an´ıv kapitole 6). Bˇehem v´yvoje knihovny jsem se nepot´ykal se z´avaˇznˇejˇs´ımi probl´emy a knihovna vznikla bez nutnosti v´yraznˇe modifikovat n´avrh.
Bˇehem t´eto f´aze vˇsak doˇslo k situaci, kdy pr´ace s reflex´ı byla ˇcasto se opakuj´ıc´ı a bylo tedy nutn´e ji v´ıce uhladit. Kv˚uli t´eto skuteˇcnosti jsem se rozhodl k dalˇs´ı f´azi.
Refaktoring
Po dokonˇcen´ı intenzivn´ıho v´yvoje bylo nutn´e uhladit pr´aci tak, aby zbyteˇcnˇe neobsahovala opakuj´ıc´ıc se k´od a byla co nejv´ıce minim´aln´ı (a d´ıky tomu udrˇziteln´a do budoucna). Kv˚uli t´eto skuteˇcnosti n´asledoval refaktoring k´odu, tedy pˇreskupen´ı urˇcit´ych ˇc´ast´ı k´odu do logick´ych celk˚u.
Tuto f´azi povaˇzuji za velmi d˚uleˇzitou, aˇc se nejedn´a o refaktoring v prav´em slova smyslu. Je d˚uleˇzit´a pr´avˇe d´ıky skuteˇcnosti, ˇze dˇel´a k´od pˇrehlednˇejˇs´ı a mnohem v´ıce udrˇziteln´y.
Oprava chyb
Na z´avˇer byly doplnˇeny vznikl´e testovac´ı sc´en´aˇre o jeˇstˇe v´ıce pˇr´ıpad˚u a byly odhaleny chyby v r˚uzn´ych ˇc´astech knihovny. Zejm´ena se jednalo o chyby v renderov´an´ı a konverze obsahu z a do form´atu XML. V z´avˇereˇcn´e f´azi byly tyto chyby zapracov´any a bylo doc´ıleno funkˇcn´ıho stavu knihovny.
5.2 Instalaˇ cn´ı pˇ r´ıruˇ cka
Knihovna je psan´a pro verzi PHP 7.2 a vyˇsˇs´ı. Instalace knihovny vyˇzaduje pouˇzit´ı n´astroje Composer[18]. Jelikoˇz se v dobˇe zveˇrejnˇen´ı t´eto pr´ace ne- jedn´a o veˇrejnˇe pˇr´ıstupnou knihovnu, je nutn´e si st´ahnout pˇr´ılohu t´eto pr´ace a postupovat dle n´avodu v dokumentaci n´astroje Composer – konkr´etnˇe se jedn´a o instalaci pomoc´ı artefaktu[19].
Pro r˚uzn´e frameworky je pot´e nutn´e instalovat a nebo vytvoˇrit mezivrstvu mezi c´ılovou aplikac´ı a knihovnou. V´ıce informac´ı naleznete v kapitole 7 o referenˇcn´ı implementaci.
5.3 Program´ atorsk´ a dokumentace
Dokumentaci pro v´yvoj´aˇre, vˇcetnˇe uk´azkov´eho pouˇzit´ı lze nal´ezt v pˇr´ıloze ve sloˇzce /lib/core/doc ve form´atu Markdown[20]. V pˇriloˇzen´e dokumentaci lze nal´ezt detailnˇejˇs´ı uk´azky pouˇzit´ı, vˇcetnˇe detailnˇejˇs´ıho popisu vnitˇrn´ı ar- chitektury. Pokud by to bylo nutn´e, je moˇzn´e vygenerovat tak´e dokumentaci z PHPDoc[21] anotac´ı.
34
5.4. Zhodnocen´ı v´ysledn´e knihovny Aby bylo moˇzn´e generovat dokumentaci pomoc´ı n´astroje phpDocumen- tor[22], bylo nutn´e dodrˇzovat z´asadu, ˇze veˇsker´y k´od je zdokumentov´an. To tak´e umoˇzˇnujˇe dalˇs´ım v´yvoj´aˇr˚um, kteˇr´ı by se chtˇeli do projektu zapojit ve snadnˇejˇs´ı orientaci v k´odu.
5.4 Zhodnocen´ı v´ ysledn´ e knihovny
V´ysledkem realizace je praktick´a, minimalistick´a knihovna, kter´y je velice snadno pˇrenositeln´a mezi frameworky a splˇnuje m´a oˇcek´av´an´ı. Je moˇzn´e ji vyuˇz´ıt pro mapov´an´ı sloˇzit´ych struktur, stejnˇe jak jako i jednoduˇsˇs´ıch apli- kac´ı.
Knihovna jako takov´a poskytuje tak´e moˇznost navrhnout API na z´akladˇe interfacu – tedy je moˇzn´e vyuˇz´ıt vyˇsˇs´ı m´ıru abstrakce jak u entit, tak u ser- visn´ıch metod, coˇz je velice uˇziteˇcn´a vlastnost pr´avˇe z d˚uvodu pˇrenositelnosti a udrˇzitelnosti.
