AbstractDao 

namespace	bhenk\msdata\abc
predicates	Abstract
known subclasses	AbstractJoinDao \| NodeDao \| PersonDao \| UserDao

Data Access Object with basic functionality

In most cases subclasses only need to implement getDataObjectName and getTableName. If getCreateTableStatement is not sufficient override that method as well.

This class expects Entities that subclass other Entity implementations to have parent-first in their __construct() and toArray() functions, i.e.:

class A extends Entity

class B extends A

In their __construct() and toArray() functions, properties/parameters have the order:

ID, {props of A}, {props of B}

Methods 

AbstractDao::dropTable 

predicates

public

Drop table if it exists

Tries to drop the table with the name returned by AbstractDao::getTableName.

public function dropTable(): bool

return bool - true on success, even if table does not exist, false on failure

throws Exception

AbstractDao::createTable 

predicates

public

Create a table in the database

The statement used is the one from getCreateTableStatement.

public function createTable(
      Parameter #0 [ <optional> bool $drop = false ]
 ): int

param bool $drop - Drop (if exists) table with same name before create
return int  - count of executed statements
throws ReflectionException
throws Exception  - code 200

AbstractDao::getTableName 

predicates

public | abstract

Get the name of the table that will store the Entities this class provides access to

public abstract function getTableName(): string

return string - name of table reserved for DO

AbstractDao::getCreateTableStatement 

predicates

public

Produces a minimal CreateTableStatement

CREATE TABLE IF NOT EXISTS `%table_name%`
(
     `ID`                INT NOT NULL AUTO_INCREMENT,
     `%int_prop%`        INT,
     `%string_prop%`     VARCHAR(255),
     `%bool_prop%`       BOOLEAN,
     `%float_prop%`      FLOAT,
     PRIMARY KEY (`ID`)
);

In the above %xyz% is placeholder for table name or property name. Notice that string type parameters have a limited length of 255 characters.

Subclasses may override. The table MUST have the same name as the one returned by the method getTableName.

public function getCreateTableStatement(): string

return string - the CREATE TABLE sql

throws ReflectionException

AbstractDao::getDataObjectName 

predicates

public | abstract

Get the fully qualified classname of the Entity this class provides access to

public abstract function getDataObjectName(): string

return string - fully qualified classname

AbstractDao::insert 

predicates

public

Insert the given Entity

With param $insertID set to false (this is the default), the ID of the Entity (if any) will be ignored. Returns an Entity equal to the given Entity with the new ID.

In order to be able to reconstruct a table, the ID of the Entity can be inserted as well. Set param $insertID to true to achieve this.

public function insert(
      Parameter #0 [ <required> bhenk\msdata\abc\Entity $entity ]
      Parameter #1 [ <optional> bool $insertID = false ]
 ): Entity

param Entity $entity - Entity to insert
param bool $insertID - should the primary key ID also be inserted
return Entity  - new Entity, equal to given one, with new ID
throws Exception  - code 201

AbstractDao::insertBatch 

predicates

public

Insert the Entities from the given array

The ID of the Entities (if any) will be ignored. Returns an array of Entities equal to the given Entities with new IDs and ID as array key. This default behaviour can be altered by providing a closure that receives each inserted entity and decides what key will be returned:

$func = function(Entity $entity): int {
    return  $entity->getID();
};

In order to be able to reconstruct a table, the ID of the Entities can be inserted as well. Set param $insertID to true to achieve this.

public function insertBatch(
      Parameter #0 [ <required> array $entity_array ]
      Parameter #1 [ <optional> ?Closure $func = NULL ]
      Parameter #2 [ <optional> bool $insertID = false ]
 ): array

param array $entity_array - array of Entities to insert
param ?Closure $func - function to assign key in the returned array
param bool $insertID - should the primary key ID also be inserted
return array  - array of Entities with new IDs
throws Exception  - code 201

AbstractDao::update 

predicates

public

Update the given Entity

public function update(
      Parameter #0 [ <required> bhenk\msdata\abc\Entity $entity ]
 ): int

param Entity $entity - persisted Entity to update
return int  - rows affected: 1 for success, 0 for failure
throws Exception  - code 202

AbstractDao::updateBatch 

predicates

public

Update the Entities in the given array

public function updateBatch(
      Parameter #0 [ <required> array $entity_array ]
 ): int

param array $entity_array - array of persisted Entities to update
return int  - rows affected
throws Exception  - code 202

AbstractDao::delete 

predicates

public

Delete the row with the given ID

public function delete(
      Parameter #0 [ <required> int $ID ]
 ): int

param int $ID - the ID to delete
return int  - rows affected: 1 for success, 0 if ID was not present
throws Exception  - code 203

AbstractDao::deleteBatch 

predicates

public

Delete rows with the given IDs

public function deleteBatch(
      Parameter #0 [ <required> array $ids ]
 ): int

param array $ids - array with IDs of persisted entities
return int  - affected rows
throws Exception  - code 203

AbstractDao::select 

predicates

public

Fetch the Entity with the given ID

public function select(
      Parameter #0 [ <required> int $ID ]
 ): ?Entity

param int $ID - the ID to fetch
return ?Entity  - Entity with given ID or null if not present
throws Exception  - code 204

AbstractDao::selectBatch 

predicates

public

Select Entities with the given IDs

The returned Entity[] array has Entity IDs as keys.

public function selectBatch(
      Parameter #0 [ <required> array $ids ]
 ): array

param array $ids - array of IDs of persisted Entities
return array  - array of Entities or empty array if none found
throws Exception  - code 204

AbstractDao::deleteWhere 

predicates

public

Delete Entity rows with a where-clause

DELETE FROM %table_name% WHERE %expression%

public function deleteWhere(
      Parameter #0 [ <required> string $where_clause ]
 ): int

param string $where_clause - expression
return int  - rows affected
throws Exception  - code 203

AbstractDao::selectWhere 

predicates

public

Select Entities with a where-clause

SELECT FROM %table_name% WHERE %expression% LIMIT %offset%, %limit%;

The optional param $func receives selected Entities and can decide what key the Entity will have in the returned Entity[] array. Default: the returned Entity[] array has Entity IDs as keys.

$func = function(Entity $entity): int {
    return  $entity->getID();
};

public function selectWhere(
      Parameter #0 [ <required> string $where_clause ]
      Parameter #1 [ <optional> int $offset = 0 ]
      Parameter #2 [ <optional> int $limit = bhenk\msdata\abc\PHP_INT_MAX ]
      Parameter #3 [ <optional> ?Closure $func = NULL ]
 ): array

param string $where_clause - expression
param int $offset - offset of the first row to return
param int $limit - the maximum number of rows to return
param ?Closure $func - if given decides which keys the returned array will have
return array  - array of Entities or empty array if none found
throws Exception  - code 204

AbstractDao::selectSql 

predicates

public

Select Entities with a sql statement

The optional param $func receives selected Entities and can decide what key the Entity will have in the returned Entity[] array. Default: the returned Entity[] array has Entity IDs as keys.

$func = function(Entity $entity): int {
    return  $entity->getID();
};

If the param $sql selects not all fields from the designated table or selects from tables other than the designated, the result is unpredictable.

public function selectSql(
      Parameter #0 [ <required> string $sql ]
      Parameter #1 [ <optional> ?Closure $func = NULL ]
 ): array

param string $sql - sql selecting all fields from designated table
param ?Closure $func - if given decides which keys the returned array will have
return array  - array of Entities or empty array if none found
throws Exception

AbstractDao::execute 

predicates

public

Execute the given query

public function execute(
      Parameter #0 [ <required> string $sql ]
 ): array|bool

param string $sql
return array | bool  - result rows in array; bool if result is boolean
throws Exception

Sat, 01 Jul 2023 13:02:22 +0000