# final class \SmartDbaDb
{ } ->

Class: SmartDbaDb - provides a Client for DBA Databases.
By default this class will just log the errors.
It supports the following handlers: gdbm, qdbm, db4 which do not have limits on the record size.
The handler will be locked using LockFile as it is supported on all platforms and all handlers.
The DBA file path should be starting with '#db/' or 'tmp/', which are protected via HtAccess files or by config.
Do not use other dir prefixes unless you know what you are doing ...

- Language: PHP
- Located at: lib/core/plugins/lib_db_dba.php
- Package: Application:Plugins:Database:Dba
- Namespace: \
- Class Name: SmartDbaDb
- Version: v.20241216
- Depends: extensions: PHP DBA Extension ; classes: Smart, SmartEnvironment, SmartHashCrypto, SmartComponents, SmartFileSysUtils, SmartFileSystem
- Hints: This class is mainly written to be used with DBA Key/Value store
- Usage: dynamic object: (new Class())->method() - This class provides only DYNAMIC methods

## class Methods

public function __construct ( STRING $file, STRING $y_description = "DEFAULT", BOOLEAN $y_fatal_err = false, FLOAT $y_debug_exch_slowtime = 0 ) {} @
@param: {STRING} $file: The DBA DB Path ; If does not exists will be created, but will be re-suffixed (see getDbRealPath() in this class ...)
@param: {STRING} $y_description: *OPTIONAL* The description of the DBA instance to make easy debug and log errors
@param: {BOOLEAN} $y_fatal_err: *OPTIONAL* If Errors are Fatal or Not ... ; Set this parameter to TRUE if you want to Raise a fatal error on DBA errors ; otherwise default is FALSE and will ignore DBA errors but just log them as warnings (this is the wanted behaviour on a production server ...)
@param: {FLOAT} $y_debug_exch_slowtime: *OPTIONAL* The Debug Slow Time in microseconds to Record slow Queries ; if > 0 will use this, otherwise will use the value from configs
Class Constructor :: It try to initiate the DB connection or FAIL
public function __destruct ( ) {} @
Class Destructor :: It try to close the DB connection if any
Will randomly optimize the DB prior to close connection
public function isAvailable ( ) {} -> BOOLEAN
@return: {BOOLEAN} Will return TRUE if available and FALSE if not
Check if the PHP DBA Extension is available and also have the handler set in config
public function getDbRealPath ( ) {} -> STRING
@return: {STRING} The Real Path to the current DB File OR Empty string if there is no connection on this instance
Get the Real Path to the DB File. If the DB instance failed will return empty string.
The DB File Path will be re-suffixed with the handler's name in the file extension to avoid operate a handler on another handler's DB
Ex: tmp/my-db.dba will be actually be: tmp/my-db.gdbm.dba (for the gdbm hanlder), tmp/my-db.qdbm.dba (for the qdbm hanlder), tmp/my-db.db4.dba (for the db4 hanlder)
public function getTtl ( STRING $key ) {} -> INTEGER
@return: {INTEGER} number of seconds the key will expire ; -1 if the key does not expire (is persistent) ; -2 if the key does not exists ; -3 if N/A or ERR
@param: {STRING} $key: The Key
Get the TTL in seconds for a key from DB
If will try to get the TTL for an expired key will automatically unset it and will return a result like the key does not exists
public function getKey ( STRING $key ) {} -> MIXED
@return: {MIXED} Returns FALSE if the Key is expired or Invalid ; NULL if the Key does not exists ; STRING as the value of the given Key as set in DB
@param: {STRING} $key: The Key
Get a Key from DB and return it's value
If will try to get an expired key will automatically unset it and will return a result like the key does not exists
public function setKey ( STRING $key, STRING $value, INTEGER+ $expire = 0 ) {} -> BOOLEAN
@return: {BOOLEAN} Returns TRUE if the key was set or FALSE if not (that might be an error)
@param: {STRING} $key: The Key
@param: {STRING} $value: The value to be stored (if non-string must be sent as json-encoded string)
@param: {INTEGER+} $expire: Key Expiration in seconds (zero if key does not expire)
Set a Key in the DB with a given VALUE
If Key Exists will replace it's value with new one
public function keyExists ( STRING $key ) {} -> BOOLEAN
@return: {BOOLEAN} TRUE if Key Exists or FALSE if not
@param: {STRING} $key: The Key
Check if a Key exists in the DB
If will check an expired key will automatically unset it and will return a result like the key does not exists
public function unsetKey ( STRING $key ) {} -> BOOLEAN
@return: {BOOLEAN} Returns TRUE if the key was unset or FALSE if not
@param: {STRING} $key: The Key
Unset a Key from DB
Will randomly optimize the DB
public function optimizeDb ( BOOLEAN $randomly = false ) {} -> BOOLEAN
@return: {BOOLEAN} Returns TRUE if was running or FALSE if not
@param: {BOOLEAN} $randomly: If set to TRUE will only randomly run it with a probability as of 1 in 1000
Optimize the DB
public function getKeysList ( ) {} -> ARRAY
@return: {ARRAY} A non-associative array with all, non-expired keys in DB or empty array if no key available ; Ex: [ key1, key2, ..., keyN ]
Get the list with all available keys in the DB
Will clear al expired key while iterating on all DB records to get the list
Will optimize the DB
public function clearExpiredKeys ( INTEGER+ $limit = 0 ) {} -> BOOLEAN
@return: {BOOLEAN} Will return TRUE if success or FALSE if not
@param: {INTEGER+} $limit: How many Keys to iterate ; If zero will iterate over all ; If non zero and positive will stop after reaching this limit
Clear all expired keys from the DB
Will have to iterate on all keys in DB
Will optimize the DB
public function truncateDb ( $testFirstKey = false ) {} -> BOOLEAN
@return: {BOOLEAN} Will return TRUE on success and FALSE if FAIL
TRUNCATE The Database by clearing (erasing) all data
This may break current transactions if called

## class Properties

## class Constants

## Sample code: PHP

`

    <?php

    // Example (must be set in etc/config.php)
     $configs['dba']['handler'] = 'gdbm';

    // #end php code

`

documentation generated on: 2024-12-16 16:53:45 +0000

Smart.Framework © 2009-2024 unix-world.org