WebToDate/Příručka vývojáře/Tipy a návody

Vývoj a ladění rozšíření WebToDate

Vývoj těchto rozšíření v praxi není možné provádět na produkčním serveru, zejména extenze mají okamžitý vliv na funkčnost celého řešení a jakákoliv chyba může způsobit vážné potíže v chodu serveru.

Proto je doporučeno provádět vývoj na testovací kopii systému, kde je možné ladit extenze, moduly apod. To ovšem vyžaduje dbát na přenositelnost výsledného řešení na jiný stroj, jde tedy zejména o

• Vytvoření prvotní instalace databázových struktur a dat modulu – je velmi vhodné vytvořit např. instalační SQL skript, který dávkově provádí potřebné zápisy do databáze systému.
• Udržování seznamu souborů, které je třeba instalovat a cílových adresářů.

Všechny SQL dotazy spouštěné zejména ve veřejné části modulů je třeba testovat nejen na funkčnost ale zejména na rychlost provedení, pomalé SQL dotazy mohou mít vliv na běh celého serveru. Optimalizace dotazů je vhodné provádět v SQL konzoli příslušné databáze nebo s využitím specializovaných vývojových nástrojů, v prostředí PHP, toto provádět nelze.

Souborová knihovna

Pomocí Souborové knihovny by se měly provádět veškeré operace se soubory/adresáři spojené. Jejím cílem je jednak zachycení a zpracování chyb, které mohou při práci s filesystémem vznikat, jednak umožnit definovat a pro filesystémové funkce "uzavřít" adresáře se skripty (mimo určené). Souborová knihovna je přístupná přes objekt $fa. Fyzicky je uložena v souboru /classes/FileAccess.php.

Ošetřování chyb probíhá neustále při práci se Souborovou knihovnou. Po vykonání požadované operace je možné pomocí funkce "getErrorMessage" zjistit, zda proběhla operace bez chyb (fce vrací FALSE, příp. vrací text chybové zprávy). Pro "vyčištění" statutu je k dispozici fce "clsErrorMessage". Pokud dojde k chybě při vykonávání operace, Knihovna vrací poslední uloženou, zpravidla nejobecnější, chybovou zprávu (např. "Nepodařilo se uložit text do souboru." místo "Soubor neexistuje." nebo "Není možné do souboru zapisovat z důvodu..."). Historie chybových je proto dostupná, a to v poli "arrErrorLog".

Výchozím nastavením je určeno několik adresářů, do nichž má Souborová knihovna přístup. Jde rekurzivně o adresáře /wwwroot, /texts, /offlinedata a /rdata, navíc pak o adresáře virtuálních serverů. Knihovna potom při požadovaných operacích ověřuje, zda se soubor či adresář, ke kterému je přistupováno, nachází v některém z těchto "povolených umístění". Globálně je tato ochrana vypnutelná pomocí nastavení konstanty "CHECK_FILEACCESS_GLOBAL" v konfiguračním souboru systému (global.php; toto by mělo smysl např. při instalaci apod.), případně při běhu skriptu nastavením vlastnosti "blnAllowManual" Souborové knihovny na hodnotu TRUE (po vykonání operace se však nesmí zapomenout "zamknout" hodnotu zpět na FALSE !). Knihovna pak veškeré operace uznává jako prováděné v povolením umístění.

Nejběžnější způsob použití demonstruje následující příklad (načtení obsahu souboru):

// urcime relativni cestu k souboru
  $filename_relative = "/rdata/resources/webtodate/soubor.php";
// sestavime absolutni cestu
  $filename = '''$fa->pathBuild(''' getWTDPath(), $filename_relative ''');'''
// nacteme soubor do textu
  $obsah = "";
// - overime existenci souboru
    if ( '''$fa->fileExists'''($'''filename''')''' ):
// - - otevreme soubor pro cteni
      $fres = '''$fa->fileOpen(''' $filename, FILEACCESS_MODE_READ ''');'''
// - - nacteme obsah do retezce
      $obsah = '''$fa->fileRead(''' $fres, FILEACCESS_READ_STRING ''');'''
// - - uzavreme soubor
      '''$fa->fileClose(''' $fres ''');'''
    endif;

/* alternativni zpusob ziskani obsahu souboru do retezce:
  $obsah = '''$fa->fileContentRead(''' $filename ''');'''
*/

// osetreni chyb
    if ( $err = '''$fa->getErrorMessage()''' ):
// - kod osetreni chyby; $err obsahuje lokalizovane chybove hlaseni
    endif;
...

Reference Souborové knihovny

KONSTANTY:

• FILEACCESS_MODE_READ

konstanta obsahuje hodnotu "r"; určuje způsob otevření souboru (pro čtení)

• FILEACCESS_MODE_WRITE

konstanta obsahuje hodnotu "w"; určuje způsob otevření souboru (pro zápis)

• FILEACCESS_MODE_APPEND

konstanta obsahuje hodnotu "a"; určuje způsob otevření souboru (pro přidávání)

• FILEACCESS_READ_STRING

konstanta obsahuje hodnotu "string"; určuje způsob načítání obsahu souboru (do řetězce)

• FILEACCESS_READ_ARRAY

konstanta obsahuje hodnotu "array"; určuje způsob načítání obsahu souboru (do pole)

VLASTNOSTI:

• arrAllowedDir

- pole s cestami k adresářům, ze kterých je možné číst, příp. kam je povolen zápis

• blnErrorOccurred

- indikátor výskytu chyby

• strErrorMessage

- text chybového hlášení

• arrFileHandle

- pole informací a deskriptorů otevíraných souborů

• arrDirHandle

- pole informací a deskriptorů otevíraných adresářů

• strFileSeparator

- oddělovač souborů podle údaje v konfiguračním souboru

• arrErrorLog

- pole se všemi vyskytnutými chybovými zprávami

• arrDevLog

- pole pro ukládání vývojového logu

• dev

- proměnná pro vývojové zprávy

• blnAllowManual

- indikátor, zda se má vypnout kontrola povolených umístění

METODY:

• FileAccess ()

- konstruktor objektu načítá seznam povolených umístění pomocí metody loadAllowedDir (pokud to není omezeno v konfiguračním souboru – volba CHECK_FILEACCESS_GLOBAL

• loadAllowedDir ()

- načítá seznam povolených umístění

• fileOpen ( strPath, chrMode=, blnCreateByOpen=false )

- otevírá soubor strPath v módu určeném parametrem chrMode. Třetí parametr, blnCreateByOpen, určuje, zda se má vytvářet případně neexistující soubor při otevírání pro čtení. Metoda vrací deskriptor otevřeného souboru.

• fileClose ( intHandle )

- uzavírá otevřený soubor podle předaného deskriptoru intHandle

• fileWrite ( intHandle, strString )

- zapisuje řetězec strString do souboru určeného předaným deskriptorem intHandle

• fileRead ( intHandle, strMode='string', intLenght=0 )

- načítá určeným způsobem (strMode) obsah souboru určeného deskriptorem intHandle. Pokud je parametr intLenght větší, než 0 a soubor se načítá do řetězce, určuje intLenght počet znaků, které se mají načíst.

• fileCreate ( strPath, blnRecursive )

- vytváří soubor v zadané cestě strPath. Pokud cesta neexistuje celá, blnRecursive určuje, zda se má chybějící část cesty dovytvořit.

• fileCopy ( strSource, strTarget, blnRecursive=FALSE, intRewriteFiles=2 )

- kopíruje soubor určený zdrojovou cestou strSource na cílovou cestu strTarget. Pokud cílová cesta není kompletní, parametr blnRecursive určuje, zda se má dovytvořit. Pokud cílový soubor již existuje, parametr intRewriteFiles určuje další chování skriptu (0 = ukončit s chybou, 1 = přepsat původní soubor, 2 = ponechat původní soubor)

• fileMove ( strSource, strTarget, blnRecursive=FALSE )

- přesouvá soubor ze zdrojového umístění strSource do cílového strTarget. Pokud cílová cesta není kompletní, parametr blnRecursive určuje, zda se má dovytvořit.

• fileDelete ( strPath, blnAllowFileNotExists=true )

- odstraňuje soubor na zadané cestě strPath. Parametr blnAllowFileNotExists určuje, zda je přípustné, když požadovaný soubor neexistuje (funkčnost je pak "odstranit pokud existuje")

• fileIsWriteable ( strPath )

- zjišťuje, zda je soubor na zadané cestě strPath povolený k zápisu

• fileIsReadable ( strPath )

- zjišťuje, zda je soubor na zadané cestě strPath povolený ke čtení

• fileExists ( strPath, blnOnlyAllowedDir=TRUE)

- zjišťuje, zda se na zadané cestě strPath nachází

• fileHandleCreate ( &intHandle, strPath, chrMode )

- interní metoda; vytváří zápis o novém otevřeném deskriptoru intHandle, ukládá cestu strPath k souboru a mód otevření (chrMode)

• fileHandleDelete ( intHandle )

- interní metoda; deaktivuje zápis o předaném deskriptoru souboru intHandle

• fileHandleIsActive ( intHandle )

- interní metoda; zjišťuje, zda má předaný deskriptor intHandle aktivní zápis, tzn. je použitelný

• fileStringAppend ( strPath, strString, blnCreate=FALSE, blnRecursive=FALSE )

- do souboru strPath zapíše řetězec strString tak, že jej přidá na konec již existujícího textu. Další parametry určují, zda se má soubor vytvořit v případě, že neexistuje (blnCreate) a zda se má dotvořit i případně neexistující cesta k němu (blnRecursive).

• fileStringWrite ( strPath, strString, blnCreate=FALSE, blnRecursive=FALSE )

- do souboru strPath zapíše řetězec strString tak, že smaže původní obsah souboru a nahradí jej novým. Další parametry určují, zda se má soubor vytvořit v případě, že neexistuje (blnCreate) a zda se má dotvořit i případně neexistující cesta k němu (blnRecursive).

• fileContentRead ( strPath )

- načte obsah souboru strPath do řetězce

• dirOpen ( strPath )

- otevírá adresář strPath

• dirClose ( &intHandle )

- uzavírá adresář podle předaného deskriptoru intHandle

• dirCreate ( strPath, blnRecursive=TRUE )

- vytváří adresář na zadané cestě strPath, příp. i chybějící cestu k němu, pokud to dovoluje parametr blnRecursive

• dirDelete ( strPath, blnRecursive=FALSE )

- odstraňuje adresář strPath, parametr blnRecursive určuje, zda i s případným obsahem.

• dirCopy ( strSource, strTarget, intRewriteFiles=2 )

- kopíruje adresář strPath na nové umístění strTarget. Pokud soubory v cílovém adresáři již existují, parametr intRewriteFiles určuje další chování skriptu (0 = ukončit s chybou, 1 = přepsat původní soubory, 2 = ponechat původní soubory).

• dirMove ( strSource, strTarget, intRewriteFiles=2 )

- přesouvá adresář strPath na nové umístění strTarget. Pokud soubory v cílovém adresáři již existují, parametr intRewriteFiles určuje další chování skriptu (0 = ukončit s chybou, 1 = přepsat původní soubory, 2 = ponechat původní soubory).

• dirIsWriteable ( strPath )

- zjišťuje, zda je možné do adresáře strPath zapisovat

• dirIsReadable ( strPath )

- zjišťuje, zda je možné z adresáře strPath číst

• dirExists ( strPath, blnOnlyAllowedDir=TRUE )

- zjišťuje, zda adresář strPath existuje. Parametr blnOnlyAllowedDir určuje, zda se má soubor "hledat" pouze v povoleném umístění.

• dirHandleCreate ( intHandle, strPath )

- interní metoda; vytváří zápis o novém otevřeném deskriptoru intHandle a ukládá cestu strPath k adresáři

• dirHandleDelete ( intHandle )

- interní metoda; deaktivuje zápis o předaném deskriptoru adresáře (intHandle)

• dirHandleIsActive ( intHandle )

- interní metoda; zjišťuje, zda má předaný deskriptor intHandle aktivní zápis, tzn. je použitelný

• dirContentList ( strPath )

- načítá obsah určeného adresáře strPath do 3D pole rozděleně na adresáře, soubory a ostatní

• pathSplit ( strPath, blnPathToArray=FALSE )

- rozděluje předanou cestu strPath na samotnou cestu a název souboru. Pokud to určí parametr blnPathToArray, rozděluje se i cesta po jednotlivých adresářích do pole.

• pathAdjust ( strPath, blnReplaceChars=FALSE)

- spíše interní metoda; upravuje předanou cestu strPath pro další použití v ostatních metodách. Pokud je to vyžádáno parametrem blnReplaceChars, metoda nahrazuje všechny nepovolené znaky v názvech adresářů a souboru (vše krom písmen anglické abecedy, čísel, znaků + (plus), :- (mínus) a tečky) podtržítkem.

• pathRemoveOddSeparators ( strPath )

- odstraňuje zdvojené oddělovače adresářů (lomítka) a nahrazuje je jedním lomítkem

• pathIsIncluded ( strParent, strChild, blnAllowRoot=FALSE )

- zjišťuje, zda je jedna cesta (strChild) vnořena do jiné (strParent). Parametr blnAllowRoot určuje, zda lze za "vnoření" cest považovat, pokud se strParent a strChild shodují.

• pathExtend ( strPath, strAdditionalPath, blnActionCut=TRUE )

- odnímá řetězec strAdditionalPath ze začátku cesty strPath (při nastavení parametru blnActionCut na TRUE), příp. jej na začátek přidává (blnActionCut = FALSE)

• pathBuild ( parametry )

- spojuje jednotlivé fragmenty cesty (jednotlivé předané parametry) do jednoho řetězce se správným proložením oddělovači adresářů

• checkAllowedDir ( strPath, blnAllowRoot=TRUE )

- interní metoda; ověřuje, zda se udaná cesta strPath nachází v povoleném umístění. Pokud je kontrola vypnuta globálně v konfiguračním souboru nebo ručně vlastností blnAllowManual, vrací metoda vždy TRUE.

• setErrorMessage ( strMessage, blnRewriteErrorOccurrence=FALSE )

- interní metoda; nastavuje chybový stav a text chyby, zapisuje text chybového hlášení do pole arrErrorLog. Parametr blnRewriteErrorOccurrence určuje, zda se má případná již existující chybová zpráva přepsat touto aktuální novou.

• getErrorMessage ( )

- ověřuje, zda se vyskytla chyba, příp. vrací její lokalizovaný text.

• clsErrorMessage ( )

- resetuje výskyt chyb

• log_zapis ( strString= )

- zapisuje řetězec strString do pole vývojového logu

• log_vypis ( )

- vypisuje vývojový log

• checkStructure ( blnRecursive=FALSE )

- ověřuje, zda by měla být spuštěna kontrola přístupnosti povolených umístění, případně tuto kontrolu spouští (metoda runCheckStructure). Parametr blnRecursive určuje, zda se kontrola provádí také na vnořených adresářích, nebo jen na hlavních adresářích povolených umístění.

• runCheckStructure ( blnRecursive=FALSE )

- prochází povolená umístění a spouští nad nimi kontrolu jejich přístupnosti (metoda runCheckDirectory). Parametr blnRecursive určuje, zda se kontrola provádí také na vnořených adresářích, nebo jen na hlavních adresářích povolených umístění.

• runCheckDirectory ( strDirectory )

- provádí kontrolu, zda je adresář strDirectory přístupný pro čtení a zápis.

• getFileList ( strPath, blnGetAbsolutePath=FALSE )

- vytváří pole se seznamem souborů v adresáři strPath. Parametr blnGetAbsolutePath určuje, zda je uváděna absolutní cesta k souboru.

• getParentDir ( strDirPath )

- zjišťuje cestu k nadřazenému, rodičovskému adresáři adresáře strDirPath

Databázová knihovna

S databázemi se nepracuje přímo příslušnými funkcemi, ale pomocí objektu $db. Fyzicky je uložena v adresáři /classes/ v souboru podle typu databáze. Jeho metody zprostředkovávají všechny potřebné databázové funkce, není nutné tedy řešit typ databáze (to je určeno na jednom místě – konfiguračním souboru global.php). Objekt je vytvářen v inicializačním skriptu (init.php) po výběru a načtení databázové knihovny. Jeho pomocí je pak uskutečněno i připojení se k určenému databázovému serveru a výběr databáze.

Nejběžnější způsob použití demonstruje následující příklad (výpis ID uložených zpráv):

   $sql = 'select * from NEWSDB';
            // vykoname dotaz
               $res = '''$db->query(''' $sql ''');'''
            // zjistime pocet navracenych radku
               $count = '''$db->num_rows(''' $res''');'''
            // vypiseme ID vybranych zaznamu
               while ( $row = '''$db->fetch_array(''' $rec ''')''' ):
                  print ( $row['ID'] . "<br>\n");
               endwhile;
               ...

Reference Databázové knihovny

METODY:

• MysqlDB ( DB_HOST, DB_USER, DB_PASS, DB_LANGUAGE, DB_NAME )

- konstruktor; volá metody na připojení k databázovému serveru (connect) a na připojení k databázi (select_db)

• connect ( DB_HOST, DB_USER, DB_PASS, DB_LANGUAGE )

- interní metoda; provádí připojení k serveru DB_HOST pomocí uživatelského jména DB_USER a hesla DB_PASS jazykem DB_LANGUAGE

• select_db ( db, DB_NAME )

- interní metoda; provádí výběr databáze v rámci připojení určeného předaným deskriptorem db

• query ( sql )

- vykonává příkaz sql

• limit ( sql, count, start=0 )

- mění předaný sql dotaz tak, aby vybíral jen limitovaný počet (count) řádků, přičemž určitý počet řádků (start) bude ignorováno

• fetch_row ( result )

- vrací pole s výsledkem provedeného dotazu, tento výsledek je určen deskriptorem result

• fetch_array ( result )

- vrací asociativní pole s výsledkem provedeného dotazu, tento výsledek je určen deskriptorem result

• num_rows ( result )

- zjišťuje počet vrácených řádků z dotazu určeného deskriptorem result

• error ( )

- vrací text chybové zprávy předchozího příkazu

• fetch_all_data ( result, id = 'ID' )

- sestavuje 3D pole s výsledkem SELECT dotazu result. Klíčem jednotlivých záznamů je hodnota ze získaného pole (sloupce) podle parametru id, hodnotou záznamů je pak asociativní pole s vybranými hodnotami, kde klíčem jsou názvy polí (sloupců)

• query_for_id_column ( query )

- provádí dotaz a hodnoty v prvním vráceném sloupci uloží do pole, vrátí i duplikované hodnoty

• print_debug ( )

- vypisuje dubug log

• seek ( result, row )

- vyhledává a vrací konkrétní řádek (row) z výsledku dotazu result. Řádky jsou číslovány od nuly.

• dropProcedure ( $inProcedureName )

- jen pro Sybase; ruší uloženou proceduru

• get_rowcount_query ( inRowCount )

- jen pro MSSQL a pro Sybase

- interní metoda; vytváří SQL příkaz na změnu počtu vracených řádků

• set_rowcount ( inRowCount )

- jen pro MSSQL a pro Sybase

- vykonává příkaz na změnu počtu vracených řádků ( SET ROWCOUNT... )

• createProcedure ( inName, inParameters, inContent )

- jen pro MSSQL a pro Sybase

- vytváří uloženou proceduru databáze. Předané parametry určují její název (inName), parametry (inParameters) a obsah vytvářecího kódu (inContent).

• result ( result, row, field )

- získává konkrétní řádek (row) a pole (field) z předaného výsledku (result)

• check_quotes ( value )

- přidává zpětné lomítko před jednoduché i dvojité uvozovky v řetězci value

• check_apostrophes ( value )

- přidává zpětné lomítko před jednoduchou uvozovku (apostrof) v řetězci value

• check_slashes ( value )

- zdvojuje zpětná lomítka existující v řetězci value

• trigger ( table, event, id = 0 )

- jen pro MySql

- simuluje práci triggerů ostatních databází, název triggeru je složen z názvu tabulky (table) a události (event), parametr id identifikuje záznam, na který se "trigger" aplikuje.

• createTime ( year, month, day, hour = 0, min=0, sec=0 )

- generuje datum a čas pro databázi podle předaných parametrů

• createDatabaseTime ( unixTime=null )

- vrací naformátované datum pro vložení do databáze

• createTimeFromUnix ( time )

- interní metoda; generuje datum a čas v databázovém tvaru z předaného timestampu time

• createTimeFromUnixNull ( time )

- vrací datum a čas v databázovém tvaru nebo NULL, pokud má parametr time tuto hodnotu

• createUnixTime ( datetime )

- generuje timestamp z údaje datetime v databázovém tvaru

• fetch_field ( qId )

- vrací objekt s parametry následujícího, ještě nenačteného sloupce výsledku qId

• free_result ( qId )

- uvolňuje zdroje po výsledku qId

• runDynamicList ( inListId, inNewsId=0 )

- liší se podle typu databáze: MySql spouští dynamický seznam, MSSQL a Sybase spouští databázovou uloženou proceduru Parametry určují číslo seznamu (inListId) a ID zprávy, které se vztahuje (inNewsId)

• make_date_time_query ( columnName )

- jen pro MSSQL a Sybase

- upravuje část dotazu (název sloupce columnName s datem a časem), aby vracel formátovaný čas

• make_is_null_query ( columnName, defaultValue )

- upravuje část dotazu (název sloupce columnName) tak, aby případně místo hodnoty NULL vracel hodnotu defaultValue

• execute_and_get_result ( query )

- provádí dotaz query a vrací hodnotu v prvním poli prvního vráceného záznamu

• check_if_result_exists ( resultIndex )

- ověřuje platnost deskriptoru výsledku resultIndex

• affected_rows ( resultId )

- zjišťuje, kolik řádků ovlivnil naposledy vykonaný příkaz identifikovaný deskriptorem výsledku resultId

• make_date_time_condition ( inDate )

- připravuje předané datum inDate pro použití v podmínce dotazu

• sql_getdate ( )

- vrací název SQL funkce, kterou server nahrazuje aktuálním datem

• get_tables ( inGetUserTablesOnly=true )

- vrací pole s názvy všech databázových tabulek; parametr inGetUserTablesOnly určuje, zda se mají načítat jen uživatelské tabulky a systémové se mají ignorovat

• dropTableIfExists ( tabName )

- jen pro MySql

- odstraní tabulku tabName, pokud existuje

• dropTable ( tabName )

- odstraní tabulku tabName

• getColumnType ( table, column )

- zjišťuje datový typ sloupce column v tabulce table

• getColumnsNames ( table )

- vrací seznam názvů polí tabulky

• getTables ( database )

- vrací seznam tabulek v databázi database

• getNullSql ( value )

- vrací část podmínky dotazu pro data typu String nebo NULL

• getPKName ( aTable )

- vrací název primárního klíče tabulky aTable; pokud je nalezen, jinak prázdný řetězec