Sgss_Collection_Pdo_Table
Represents a table in database

Description

This is an implementation of the Sgss_Collection_Table_Interface using database.

The database schema to be used with this class requires at least two columns of text datatype. One column represents the row identifiers in this table, and another represents the values associated with those identifiers. The row identifier column must have either primary key or unique constraint to avoid duplication.

Row identifiers and values will be serialized when stored into database, so that those retain its datatype or class when retrieved. Therefore, any elements (identifiers and values) must be serializable, in other words, not contain any resource object. The columns must have enough length to store serialized elements.

A simple query to create such table follows:

 CREATE TABLE table_name (
     row_column_name   TEXT PRIMARY KEY
     column_name_1     TEXT
     column_name_2     TEXT
     ...
     column_name_N     TEXT
 );

The first parameter of the constructor specifies the database to be used with this table. This can be either config array or PDO object. The second parameter specifies table name, the third specifies name of the columns to store row identifiers, and the fourth specifies an array of value column names.

  1.  <?php
  2.  require_once 'Sgss/Collection/Pdo/Table.php';
  3.  
  4.  $table = new Sgss_Collection_Pdo_Table(
  5.      array('dns'      => 'mysql:dbname=testdb;host=127.0.0.1',
  6.            'username' => 'dbuser',
  7.            'password' => 'dbpass'),
  8.      'table_name', 'row_column_name',
  9.      array('column_name_1', 'column_name_2', ..., 'column_name_N')
  10.  );

is equivalent to:

  1.  <?php
  2.  require_once 'Sgss/Collection/Pdo/Table.php';
  3.  
  4.  $db = new PDO('mysql:dbname=testdb;host=127.0.0.1', 'dbuser', 'dbpass');
  5.  $table = new Sgss_Collection_Pdo_Table(
  6.      $db, 'table_name', 'key_column_name',
  7.      array('column_name_1', 'column_name_2', ..., 'column_name_N')
  8.  );

Do not specify quoted name in those parameters because all the names will be automatically quoted, otherwise it will indicate different table or column from what you intended.

The Sgss_Collection_Table_Interface defines three methods to retrieve table row: retrieveRow(), createRow(), and getRow(). The differences between those are in the existence of row. The retrieveRow() returns a row that already exists in the table, and the createRow() returns a non-existing row. For example:

  1.  <?php
  2.  // Assume this represents an empty table.
  3.  $table = new Sgss_Collection_Pdo_Table($config, $table, $row, array('foo', 'bar'));
  4.  
  5.  // This is not inserted into the table at this time.
  6.  $row = $table->createRow('row');
  7.  $row->foo = 'foo';
  8.  $row->bar = 'bar';
  9.  // Actually insert into the table.
  10.  $row->insert();
  11.  
  12.  $table->hasRow('row'); // true
  13.  $table->createRow('row'); // null
  14.  
  15.  // This already exists in the table.
  16.  $row = $table->retrieveRow('row');
  17.  // Not need to call insert().
  18.  $row->foo = 'foo';
  19.  $row->bar = 'bar';
  20.  
  21.  // Remove this row from the table.
  22.  $row->remove();
  23.  
  24.  $table->hasRow('row'); // false
  25.  $table->retrieveRow('row'); // null

The getRow() returns both of the aboves depending on whether the row to be retrieved exists in the table. Thus if the existence is undetermined, you should call insert() or remove() of the returned row every time applying changes or removing it.

  1.  <?php
  2.  $row = $table->getRow($someRow);
  3.  $row->foo = 'foo';
  4.  $row->bar = 'bar';
  5.  // Make sure to call this.
  6.  $row->insert();

Class diagram:
Sgss_Collection_Table_Abstract
 + Sgss_Collection_Pdo_Table
Author:
Matsuda Shota
Copyright:
(c) 2007-2008 Matsuda Shota
License:
http://creativecommons.org/licenses/GPL/2.0/
Located in:
/Collection/Pdo/Table.php (line 172)

Class overview

Variables

protected array $_columns

Column names defined in the database schema
protected array $_config

Config to connect to the database
protected PDO $_db

Database handle used with this table
protected string $_driver

Driver name of the database handle
protected boolean $_isPrepared

Represents whether the prepared statements were created
protected string $_row

Name of the column containing row identifiers that already exists in the database
protected string $_table

Name of the table that already exists in the database

Methods

__construct (array|PDO $config, string $table, string $row, array $columns)

The constructor
boolean clearRows ()

Removes all the rows in this table
Sgss_Collection_TableRow_Interface|null createRow (mixed $row)

Creates and returns the row object associated with the specified identifier, which is prepared to be inserted into this table
int getRowCount ()

Returns the number of rows in this table
boolean hasRow (mixed $row)

Determines this table contains the row associated with the specified identifier
boolean removeRow (mixed $row)

Removes the row associated with the specified identifier from this table
Sgss_Collection_TableRow_Interface|null retrieveRow (mixed $row)

Retrieves and returns the row object associated with the specified identifier in this table
array toArray ()

Converts this table to an associated array
array toColumnArray ()

Returns an array containing all the column names in this table
array toRowArray ()

Returns an array containing all the keys associated with the rows in this table
protected void _connect ()

Connects to the database
protected void _invalidateStatements ()

Marks the prepared statements as no longer working
protected void _prepareStatements ()

Creates the prepared statements used with the database handle
protected string|array _quoteName (string|array $name)

Quotes the specified table or column name
protected scalar _sopite (mixed $obj, [boolean $key = false])

Converts the specified object to the corresponding scalar value
protected mixed _waken (scalar $scalar, [boolean $key = false])

Converts the specified scalar value to the corresponding object
array __sleep ()
void __wakeup ()
Inherited from Sgss_Collection_Table_Abstract:
count(), getRow(), hasAllRows(), isRowEmpty(), offsetExists(), offsetGet(), offsetSet(), offsetUnset(), removeAllRows(), __get(), __isset(), __unset()

Variable detail

$_columns 

Column names defined in the database schema

Signature:
protected array $_columns

$_config 

Config to connect to the database

Signature:
protected array $_config = array(...)

$_db 

Database handle used with this table

Signature:
protected PDO $_db

$_driver 

Driver name of the database handle

Signature:
protected string $_driver = ''

$_isPrepared 

Represents whether the prepared statements were created

Signature:
protected boolean $_isPrepared = false

$_row 

Name of the column containing row identifiers that already exists in the database

Signature:
protected string $_row

$_table 

Name of the table that already exists in the database

Signature:
protected string $_table

Method detail

__construct

The constructor

Parameters:
  • array|PDO $config

    Config to connect to the database, or PDO object used with the table

  • string $table

    Name of the table that already exists in the database

  • string $row

    Name of the column containing row identifiers that already exists in the database

  • array $columns

    Column names defined in the database schema

Throws:
  • Sgss_Collection_Table_Exception

    When the $columns contains no element

Signature:
public __construct (array|PDO $config, string $table, string $row, array $columns)

clearRows

Removes all the rows in this table

Returns:
boolean -- True when the operation changed this table
Uses:
Sgss_Collection_Pdo_Table::getRowCount()
Related subject:
Sgss_Collection_Table_Interface::clearRows()
Signature:
public boolean clearRows ()

createRow

Creates and returns the row object associated with the specified identifier, which is prepared to be inserted into this table

Parameters:
  • mixed $row

    Identifier to be associated with the prepared row

Returns:
Sgss_Collection_TableRow_Interface|null -- Prepared row object associated with the identifier, or null if this table already contains the identifier
Uses:
Sgss_Collection_Pdo_Table::hasRow(), Sgss_Collection_Pdo_TableRow_Prepared
Related subject:
Sgss_Collection_Table_Interface::createRow()
Signature:
public Sgss_Collection_TableRow_Interface|null createRow (mixed $row)

getRowCount

Returns the number of rows in this table

Returns:
int -- The number of rows in this table
Used by:
Sgss_Collection_Pdo_Table::clearRows()
Related subject:
Sgss_Collection_Table_Interface::getRowCount()
Signature:
public int getRowCount ()

hasRow

Determines this table contains the row associated with the specified identifier

Parameters:
  • mixed $row

    Identifier with which the row to determine is associated

Returns:
boolean -- True when this table contains the row associated with the identifier
Uses:
Sgss_Collection_Pdo_Table::_sopite()
Used by:
Sgss_Collection_Pdo_Table::retrieveRow(), Sgss_Collection_Pdo_Table::createRow()
Related subject:
Sgss_Collection_Table_Interface::hasRow()
Signature:
public boolean hasRow (mixed $row)

removeRow

Removes the row associated with the specified identifier from this table

Parameters:
  • mixed $row

    Identifier with which the row to be removed is associated

Returns:
boolean -- True when the operation changed this table
Uses:
Sgss_Collection_Pdo_Table::_sopite()
Related subject:
Sgss_Collection_Table_Interface::removeRow()
Signature:
public boolean removeRow (mixed $row)

retrieveRow

Retrieves and returns the row object associated with the specified identifier in this table

Parameters:
  • mixed $row

    Identifier with which the row is associated

Returns:
Sgss_Collection_TableRow_Interface|null -- Row object associated with the identifier, or null if this table does not contain the identifier
Uses:
Sgss_Collection_Pdo_Table::hasRow(), Sgss_Collection_Pdo_TableRow
Related subject:
Sgss_Collection_Table_Interface::retrieveRow()
Signature:
public Sgss_Collection_TableRow_Interface|null retrieveRow (mixed $row)

toArray

Converts this table to an associated array

Returns:
array -- Associated array representing this table
Related subject:
Sgss_Collection_Table_Interface::toArray()
Signature:
public array toArray ()

toColumnArray

Returns an array containing all the column names in this table

Returns:
array -- Array containing all the column names in this table
Related subject:
Sgss_Collection_Table_Interface::toColumnArray()
Signature:
public array toColumnArray ()

toRowArray

Returns an array containing all the keys associated with the rows in this table

Returns:
array -- Array containing all the keys associated with the rows in this table
Related subject:
Sgss_Collection_Table_Interface::toRowArray()
Signature:
public array toRowArray ()

_connect 

Connects to the database

Throws:
  • Sgss_Collection_Table_Exception

    When unable to connect to the database

Used by:
Sgss_Collection_Pdo_Table::__wakeup()
Signature:
protected void _connect ()

_invalidateStatements 

Marks the prepared statements as no longer working

Signature:
protected void _invalidateStatements ()

_prepareStatements 

Creates the prepared statements used with the database handle

Throws:
  • Sgss_Collection_Table_Exception

    When unable to prepare statements

Signature:
protected void _prepareStatements ()

_quoteName 

Quotes the specified table or column name

Parameters:
  • string|array $name

    Column or table name or its array to be quoted

Returns:
string|array -- Quoted string or array
Signature:
protected string|array _quoteName (string|array $name)

_sopite 

Converts the specified object to the corresponding scalar value

Parameters:
  • mixed $obj

    Object to be converted to scalar

  • boolean $key

    Whether the object is used as the key

Returns:
scalar -- Scalar value corresponding to the object
Throws:
  • Sgss_Collection_Table_Exception

    When the object is or contains unconvertable to scalar (resource or internal class)

Uses:
serialize()
Used by:
Sgss_Collection_Pdo_Table::removeRow(), Sgss_Collection_Pdo_Table::hasRow()
Signature:
protected scalar _sopite (mixed $obj, [boolean $key = false])

_waken 

Converts the specified scalar value to the corresponding object

Parameters:
  • scalar $scalar

    Scalar value to be converted to object

  • boolean $key

    Whether the converted object is to be used as the key

Returns:
mixed -- Object corresponding to the scalar
Uses:
unserialize()
Signature:
protected mixed _waken (scalar $scalar, [boolean $key = false])

__sleep

Throws:
  • Sgss_Collection_Table_Exception

    When this table is unserializable

Signature:
public array __sleep ()

__wakeup

Uses:
Sgss_Collection_Pdo_Table::_connect()
Signature:
public void __wakeup ()