AbstractJoinDao 

namespace	bhenk\msdata\abc
predicates	Abstract
extends	AbstractDao
hierarchy	AbstractJoinDao -> AbstractDao
known subclasses	JoinDao

Abstract Dao for a join table

The corresponding Data Object is envisaged to extend Join.

The relationship is symmetric.

A Join with the field $deleted set to true will be deleted on any call to AbstractJoinDao::updateLeftJoin or AbstractJoinDao::updateRightJoin.

Methods 

AbstractJoinDao::selectLeft 

predicates

public

Select on left hand foreign key

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

param int $fk_left - left hand foreign key
return array  - with right hand IDs as key
throws Exception

AbstractJoinDao::selectRight 

predicates

public

Select on right hand foreign key

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

param int $fk_right - right hand foreign key
return array  - with left hand IDs as key
throws Exception

AbstractJoinDao::updateLeftJoin 

predicates

public

Update Joins with a common FK_LEFT

This method deletes deleted Joins; updates existing Joins and inserts new Joins.

Side effect: the common param $fk_left will be set on all Joins.

public function updateLeftJoin(
      Parameter #0 [ <required> int $fk_left ]
      Parameter #1 [ <required> array $joins ]
 ): array

param int $fk_left - common left hand foreign key
param array $joins - Joins to update
return array  - Updated Joins, array key is FK_RIGHT
throws Exception

AbstractJoinDao::updateRightJoin 

predicates

public

Update Joins with a common FK_RIGHT

This method deletes deleted Joins; updates existing Joins and inserts new Joins.

Side effect: the common param $fk_right will be set on all Joins.

public function updateRightJoin(
      Parameter #0 [ <required> int $fk_right ]
      Parameter #1 [ <required> array $joins ]
 ): array

param int $fk_right - common right hand foreign key
param array $joins - Joins to update
return array  - Updated Joins, array key is FK_LEFT
throws Exception

AbstractJoinDao::dropTable 

predicates	public
inherited from	AbstractDao::dropTable

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

AbstractJoinDao::createTable 

predicates	public
inherited from	AbstractDao::createTable

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

AbstractJoinDao::getTableName 

predicates	public \| abstract
inherited from	AbstractDao::getTableName

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

AbstractJoinDao::getCreateTableStatement 

predicates	public
inherited from	AbstractDao::getCreateTableStatement

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

AbstractJoinDao::getDataObjectName 

predicates	public \| abstract
inherited from	AbstractDao::getDataObjectName

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

public abstract function getDataObjectName(): string

return string - fully qualified classname

AbstractJoinDao::insert 

predicates	public
inherited from	AbstractDao::insert

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

AbstractJoinDao::insertBatch 

predicates	public
inherited from	AbstractDao::insertBatch

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

AbstractJoinDao::update 

predicates	public
inherited from	AbstractDao::update

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

AbstractJoinDao::updateBatch 

predicates	public
inherited from	AbstractDao::updateBatch

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

AbstractJoinDao::delete 

predicates	public
inherited from	AbstractDao::delete

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

AbstractJoinDao::deleteBatch 

predicates	public
inherited from	AbstractDao::deleteBatch

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

AbstractJoinDao::select 

predicates	public
inherited from	AbstractDao::select

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

AbstractJoinDao::selectBatch 

predicates	public
inherited from	AbstractDao::selectBatch

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

AbstractJoinDao::deleteWhere 

predicates	public
inherited from	AbstractDao::deleteWhere

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

AbstractJoinDao::selectWhere 

predicates	public
inherited from	AbstractDao::selectWhere

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

AbstractJoinDao::selectSql 

predicates	public
inherited from	AbstractDao::selectSql

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

AbstractJoinDao::execute 

predicates	public
inherited from	AbstractDao::execute

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:23 +0000