PHPonTrax
[ class tree: PHPonTrax ] [ index: PHPonTrax ] [ all elements ]

Class: ActiveRecord

Source Location: /vendor/trax/active_record.php

Class Overview


Base class for the ActiveRecord design pattern


Author(s):

Variables

Methods



Class Details

[line 64]
Base class for the ActiveRecord design pattern

Each subclass of this class is associated with a database table in the Model section of the Model-View-Controller architecture. By convention, the name of each subclass is the CamelCase singular form of the table name, which is in the lower_case_underscore plural notation. For example, a table named "order_details" would be associated with a subclass of ActiveRecord named "OrderDetail", and a table named "people" would be associated with subclass "Person". See the tutorial The Trax Naming Convention

For a discussion of the ActiveRecord design pattern, see "Patterns of Enterprise Application Architecture" by Martin Fowler, pp. 160-164.

Unit tester: ActiveRecordTest




Tags:

tutorial:  ActiveRecord


[ Top ]


Class Variables

static $active_connections = array()

[line 166]

Stores the active connections. Indexed on $connection_name.



Tags:

access:  public
usedby:  ActiveRecord::establish_connection()

Type:   mixed


[ Top ]

static $begin_executed =  false

[line 427]

Transactions (only use if your db supports it)

This is for transactions only to let query() know that a 'BEGIN' has been executed




Tags:

access:  private

Type:   mixed


[ Top ]

static $database_settings = array()

[line 161]

Stores the database settings



Tags:

access:  public

Type:   mixed


[ Top ]

static $db =  null

[line 75]

Reference to the database object

Reference to the database object returned by PEAR MDB2::Connect()




Tags:


Type:   object DB


[ Top ]

static $query_log = array()

[line 438]

Keep a log of queries executed if in development env



Tags:

access:  public

Type:   mixed


[ Top ]

static $table_info = array()

[line 109]

Table Info

Array to hold all the info about table columns. Indexed on $table_name.




Tags:

access:  public

Type:   array


[ Top ]

static $use_transactions =  false

[line 433]

Transactions (only use if your db supports it) This will issue a rollback command if any sql fails.



Tags:

access:  public

Type:   mixed


[ Top ]

$aggregations = array("count","sum","avg","max","min")

[line 318]

SQL aggregate functions that may be applied to the associated table.

SQL defines aggregate functions AVG, COUNT, MAX, MIN and SUM. Not all of these functions are implemented by all DBMS's




Tags:

access:  protected
usedby:  ActiveRecord::__call()

Type:   string[]


[ Top ]

$auto_create_timestamps = array("created_at","created_on")

[line 281]

Names of automatic create timestamp columns

When a row containing one of these columns is created and $auto_timestamps is true, store the current date and time in the timestamp columns.




Tags:


Type:   string[]


[ Top ]

$auto_delete_habtm =  true

[line 421]

Auto delete $has_and_belongs_to_many associations



Tags:

access:  public

Type:   mixed


[ Top ]

$auto_save_associations =  true

[line 246]

Whether or not to auto save defined associations if set



Tags:


Type:   boolean


[ Top ]

$auto_save_habtm =  true

[line 416]

Auto insert / update $has_and_belongs_to_many tables



Tags:

access:  public
usedby:  ActiveRecord::add_record()

Type:   mixed


[ Top ]

$auto_timestamps =  true

[line 411]

Whether to automatically update timestamps in certain columns



Tags:


Type:   boolean


[ Top ]

$auto_update_timestamps = array("updated_at","updated_on")

[line 269]

Names of automatic update timestamp columns

When a row containing one of these columns is updated and $auto_timestamps is true, update the contents of the timestamp columns with the current date and time.




Tags:


Type:   string[]


[ Top ]

$belongs_to =  null

[line 229]



Tags:

todo:  Document this variable
access:  protected
usedby:  ActiveRecord::get_association_type()
usedby:  ActiveRecord::__get()
usedby:  ActiveRecord::__call()

Type:   string[]


[ Top ]

$builtin_validation_functions = array(
        'validates_acceptance_of',
        'validates_confirmation_of',
        'validates_exclusion_of',        
        'validates_format_of',
        'validates_inclusion_of',        
        'validates_length_of',
        'validates_numericality_of',        
        'validates_presence_of',        
        'validates_uniqueness_of'
    )

[line 392]

An array of all the builtin validation function calls.



Tags:

access:  protected
usedby:  ActiveRecord::validate_builtin()

Type:   mixed


[ Top ]

$class_name =  null

[line 119]

Class name

Name of the child class. (this is optional and will automatically be determined) Normally set to the singular camel case form of the table name. May be overridden.




Tags:

access:  public

Type:   string


[ Top ]

$composed_of =  null

[line 204]

Composite custom user created objects



Tags:

access:  public
usedby:  ActiveRecord::is_composite()

Type:   mixed


[ Top ]

$connection_name =  TRAX_ENV

[line 156]

Index into the $active_connections array

Name of the index to use to return or set the current db connection Mainly used if you want to connect to different databases between different models.




Tags:

access:  public

Type:   string


[ Top ]

$content_columns =  null

[line 101]

Description of a row in the associated table in the database

Retrieved from the RDBMS by set_content_columns(). See DB_common::tableInfo() for the format. NOTE: Some RDBMS's don't return all values.

An additional element 'human_name' is added to each column by set_content_columns(). The actual value contained in each column is stored in an object variable with the name given by the 'name' element of the column description for each column.

NOTE:The information from the database about which columns are primary keys is not used. Instead, the primary keys in the table are listed in $primary_keys, which is maintained independently.




Tags:


Type:   string[]


[ Top ]

$database_name =  null

[line 146]

Database name override

Name of the database to use, if you are not using the value read from file config/database.ini




Tags:

access:  public
usedby:  ActiveRecord::establish_connection()

Type:   string


[ Top ]

$date_format =  "Y-m-d"

[line 290]

Date format for use with auto timestamping

The format for this should be compatiable with the php date() function. http://www.php.net/date




Tags:

access:  public

Type:   string


[ Top ]

$default_error_messages = array(
       'inclusion' => "is not included in the list",
       'exclusion' => "is reserved",
        'invalid' => "is invalid",
        'confirmation' => "doesn't match confirmation",
        'accepted ' => "must be accepted",
        'empty' => "can't be empty",
        'blank' => "can't be blank",
        'too_long' => "is too long (max is %d characters)",
        'too_short' => "is too short (min is %d characters)",
        'wrong_length' => "is the wrong length (should be %d characters)",
        'taken' => "has already been taken",
        'not_a_number' => "is not a number",
        'not_an_integer' => "is not an integer"
    )

[line 373]

An array with all the default error messages.



Tags:

access:  public

Type:   mixed


[ Top ]

$display =  10

[line 346]

Pagination how many numbers in the list < 1 2 3 4 > >>



Tags:

access:  public

Type:   mixed


[ Top ]

$errors = array()

[line 368]

Description of non-fatal errors found

For every non-fatal error found, an element describing the error is added to $errors. Initialized to an empty array in valid() before validating object. When an error message is associated with a particular attribute, the message should be stored with the attribute name as its key. If the message is independent of attributes, store it with a numeric key beginning with 0.




Tags:


Type:   string[]


[ Top ]

$fetch_mode =  MDB2_FETCHMODE_ASSOC

[line 176]

Mode to use when fetching data from database

See the relevant PEAR MDB2 class documentation




Tags:

access:  public

Type:   integer


[ Top ]

$force_reconnect =  false

[line 183]

Force reconnect to database every page load



Tags:

access:  public
usedby:  ActiveRecord::establish_connection()

Type:   boolean


[ Top ]

$habtm_attributes =  null

[line 235]



Tags:

todo:  Document this variable
access:  protected

Type:   string[]


[ Top ]

$has_and_belongs_to_many =  null

[line 223]



Tags:

todo:  Document this variable
access:  protected
usedby:  ActiveRecord::set_habtm_attributes()
usedby:  ActiveRecord::get_association_type()
usedby:  ActiveRecord::__get()
usedby:  ActiveRecord::__call()

Type:   string[]


[ Top ]

$has_many =  null

[line 211]



Tags:

todo:  Document this variable
access:  protected
usedby:  ActiveRecord::get_association_type()
usedby:  ActiveRecord::__get()
usedby:  ActiveRecord::__call()

Type:   string[]


[ Top ]

$has_one =  null

[line 217]



Tags:

todo:  Document this variable
access:  protected
usedby:  ActiveRecord::get_association_type()
usedby:  ActiveRecord::__get()
usedby:  ActiveRecord::__call()

Type:   string[]


[ Top ]

$index_on =  "id"

[line 191]

find_all() returns an array of objects, each object index is off of this field



Tags:

access:  public

Type:   string


[ Top ]

$lock_optimistically =  true

[line 198]

Not yet implemented (page 222 Rails books)



Tags:

access:  public

Type:   boolean


[ Top ]

$new_record =  true

[line 257]

Whether this object represents a new record

true => This object was created without reading a row from the database, so use SQL 'INSERT' to put it in the database. false => This object was a row read from the database, so use SQL 'UPDATE' to update database with new values.




Tags:


Type:   boolean


[ Top ]

$pagination_count =  0

[line 351]



Tags:

todo:  Document this variable
access:  public

Type:   mixed


[ Top ]

$preserve_null_dates =  true

[line 308]

Whether to keep date/datetime fields NULL if not set

true => If date field is not set it try to preserve NULL false => Don't try to preserve NULL if field is already NULL




Tags:

access:  protected

Type:   boolean


[ Top ]

$primary_keys = array("id")

[line 335]

Primary key of the associated table

Array element(s) name the primary key column(s), as used to specify the row to be updated or deleted. To be a primary key a column must be listed both here and in $content_columns. NOTE:This field is maintained by hand. It is not derived from the table description read from the database.




Tags:


Type:   string[]


[ Top ]

$rows_per_page_default =  20

[line 341]

Default for how many rows to return from find_all()



Tags:

access:  public
usedby:  ActiveRecord::build_sql()

Type:   integer


[ Top ]

$save_associations = array()

[line 240]



Tags:

todo:  Document this property
access:  protected

Type:   mixed


[ Top ]

$table_name =  null

[line 129]

Table name

Name of the table in the database associated with the subclass. Normally set to the pluralized lower case underscore form of the class name by the constructor. May be overridden.




Tags:

access:  public
usedby:  ActiveRecord::add_record()
usedby:  ActiveRecord::__construct()

Type:   string


[ Top ]

$table_prefix =  null

[line 137]

Table prefix

Name to prefix to the $table_name. May be overridden.




Tags:

access:  public

Type:   string


[ Top ]

$time_format =  "H:i:s"

[line 299]

Time format for use with auto timestamping

The format for this should be compatiable with the php date() function. http://www.php.net/date




Tags:

access:  public

Type:   string


[ Top ]



Class Methods


constructor __construct [line 456]

ActiveRecord __construct( [string[] $attributes = null])

Construct an ActiveRecord object

  1. Establish a connection to the database
  2. Find the name of the table associated with this object
  3. Read description of this table from the database
  4. Optionally apply update information to column attributes




Tags:



Parameters:

string[]   $attributes   Updates to column attributes

[ Top ]

method add_error [line 3173]

void add_error( string $error, [string $key = null])

Add or overwrite description of an error to the list of errors



Tags:



Parameters:

string   $error   Error message text
string   $key   Key to associate with the error (in the simple case, column name). If omitted, numeric keys will be assigned starting with 0. If specified and the key already exists in $errors, the old error message will be overwritten with the value of $error.

[ Top ]

method add_habtm_records [line 2034]

void add_habtm_records( $this_foreign_value)



Tags:

todo:  Document this API
throws:  ActiveRecordError
access:  private
usedby:  ActiveRecord::add_record()
uses:  ActiveRecord::query()
uses:  ActiveRecord::is_error()


Parameters:

   $this_foreign_value  

[ Top ]

method add_record [line 1686]

boolean add_record( )

Insert a new row in the table associated with this object

Build an SQL INSERT statement getting the table name from $table_name, the column names from $content_columns and the values from object variables. Send the insert to the RDBMS.




Tags:

return:  
  • true => row was inserted successfully
  • false => insert failed
throws:  ActiveRecordError
access:  private
uses:  ActiveRecord::query()
uses:  ActiveRecord::raise()
usedby:  ActiveRecord::add_record_or_update_record()
uses:  ActiveRecord::is_error()
uses:  ActiveRecord::get_insert_id()
uses:  ActiveRecord::$table_name
uses:  ActiveRecord::add_habtm_records()
uses:  ActiveRecord::before_create()
uses:  ActiveRecord::get_inserts()
uses:  ActiveRecord::$auto_save_habtm


[ Top ]

method add_record_or_update_record [line 1647]

boolean add_record_or_update_record( )

Create or update a row in the table

If this object represents a new row in the table, insert it. Otherwise, update the exiting row. before_?() and after_?() routines will be called depending on whether the row is new.




Tags:

return:  
  • true => row was updated or inserted successfully
  • false => insert failed
access:  private
uses:  ActiveRecord::update_record()
usedby:  ActiveRecord::save()
uses:  ActiveRecord::before_save()
uses:  ActiveRecord::before_create()
uses:  ActiveRecord::add_record()
uses:  ActiveRecord::after_create()
uses:  ActiveRecord::after_update()
uses:  ActiveRecord::$new_record


[ Top ]

method after_create [line 2770]

void after_create( )

Is called after save() on new objects that havent been saved yet (no record exists).



Tags:

todo:  Document this API
usedby:  ActiveRecord::add_record_or_update_record()


[ Top ]

method after_delete [line 2794]

void after_delete( )

Is called after delete().



Tags:

todo:  Document this API


[ Top ]

method after_save [line 2758]

void after_save( )

Is called after save (regardless of whether its a create or update save).



Tags:

todo:  Document this API


[ Top ]

method after_update [line 2782]

void after_update( )

Is called after save() on existing objects that has a record.



Tags:

todo:  Document this API
usedby:  ActiveRecord::add_record_or_update_record()


[ Top ]

method after_validation [line 2722]

void after_validation( )

Is called after validate().



Tags:

todo:  Document this API


[ Top ]

method after_validation_on_create [line 2734]

void after_validation_on_create( )

Is called after validate() on new objects that haven't been saved yet (no record exists).



Tags:

todo:  Document this API


[ Top ]

method after_validation_on_update [line 2746]

void after_validation_on_update( )

Is called after validate() on existing objects that has a record.



Tags:

todo:  Document this API


[ Top ]

method aggregate_all [line 956]

void aggregate_all( $aggregate_type, [string[] $parameters = null], string $agrregrate_type)

Implement *_all() functions (SQL aggregate functions)

Apply one of the SQL aggregate functions to a column of the table associated with this object. The SQL aggregate functions are AVG, COUNT, MAX, MIN and SUM. Not all DBMS's implement all of these functions.




Tags:

throws:  ActiveRecordError
access:  private
usedby:  ActiveRecord::__call()
uses:  ActiveRecord::query()
uses:  ActiveRecord::is_error()


Parameters:

string   $agrregrate_type   SQL aggregate function to apply, suffixed '_all'. The aggregate function is one of the strings in $aggregations.
string[]   $parameters   Conditions to apply to the aggregate function. If present, must be an array of three strings:
  1. $parameters[0]: If present, expression to apply the aggregate function to. Otherwise, '*' will be used. NOTE:SQL uses '*' only for the COUNT() function, where it means "including rows with NULL in this column".
  2. $parameters[1]: argument to WHERE clause
  3. $parameters[2]: joins??? @todo Document this parameter
   $aggregate_type  

[ Top ]

method attribute_is_string [line 2558]

void attribute_is_string( string $attribute, [ $column = null])

Determine if passed in attribute (table column) is a string



Tags:



Parameters:

string   $attribute   Name of the table column
   $column  

[ Top ]

method before_create [line 2764]

void before_create( )

Is called before save() on new objects that havent been saved yet (no record exists).



Tags:

todo:  Document this API
usedby:  ActiveRecord::add_record()
usedby:  ActiveRecord::add_record_or_update_record()


[ Top ]

method before_delete [line 2788]

void before_delete( )

Is called before delete().



Tags:

todo:  Document this API


[ Top ]

method before_save [line 2752]

void before_save( )

Is called before save() (regardless of whether its a create or update save)



Tags:

todo:  Document this API
usedby:  ActiveRecord::add_record_or_update_record()


[ Top ]

method before_update [line 2776]

void before_update( )

Is called before save() on existing objects that has a record.



Tags:

todo:  Document this API


[ Top ]

method before_validation [line 2716]

void before_validation( )

Is called before validate().



Tags:

todo:  Document this API


[ Top ]

method before_validation_on_create [line 2728]

void before_validation_on_create( )

Is called before validate() on new objects that haven't been saved yet (no record exists).



Tags:

todo:  Document this API


[ Top ]

method before_validation_on_update [line 2740]

void before_validation_on_update( )

Is called before validate() on existing objects that has a record.



Tags:

todo:  Document this API


[ Top ]

method begin [line 1090]

void begin( )

Only used if you want to do transactions and your db supports transactions



Tags:

todo:  Document this API
uses:  ActiveRecord::$db


[ Top ]

method build_sql [line 1234]

void build_sql( [ $conditions = null], [ $order = null], [ $limit = null], [ $joins = null])

Builds a sql statement.



Tags:

uses:  ActiveRecord::$rows_per_page_default
uses:  $rows_per_page
uses:  $page
uses:  $offset


Parameters:

   $conditions  
   $order  
   $limit  
   $joins  

[ Top ]

method check_datetime [line 2112]

mixed check_datetime( string $field, mixed $value)

Apply automatic timestamp updates

If automatic timestamps are in effect (as indicated by $auto_timestamps == true) and the column named in the $field argument is of type "timestamp" and matches one of the names in auto_create_timestamps or auto_update_timestamps(as selected by $new_record), then return the current date and time as a string formatted to insert in the database. Otherwise return $value.




Tags:

return:  Current date and time or $value
access:  private
uses:  ActiveRecord::$new_record
uses:  ActiveRecord::$content_columns
uses:  ActiveRecord::$auto_update_timestamps
uses:  ActiveRecord::$auto_timestamps
uses:  ActiveRecord::$auto_create_timestamps


Parameters:

string   $field   Name of a column in the table
mixed   $value   Value to return if $field is not an automatic timestamp column

[ Top ]

method column_attribute_exists [line 1048]

boolean column_attribute_exists( string $attribute)

Check whether a column exists in the associated table

When called, $content_columns lists the columns in the table described by this object.




Tags:

return:  true=>the column exists; false=>it doesn't
usedby:  ActiveRecord::send()
uses:  ActiveRecord::$content_columns


Parameters:

string   $attribute   Name of the column

[ Top ]

method column_for_attribute [line 1015]

void column_for_attribute( $attribute)

get the attributes for a specific column.



Tags:

todo:  Document this API
usedby:  ActiveRecord::attribute_is_string()
usedby:  ActiveRecord::column_type()
uses:  ActiveRecord::$content_columns


Parameters:

   $attribute  

[ Top ]

method column_type [line 1031]

void column_type( $attribute)

get the columns data type.



Tags:

todo:  Document this API
usedby:  ActiveRecordHelper::column_type()
uses:  ActiveRecord::column_for_attribute()


Parameters:

   $attribute  

[ Top ]

method commit [line 1101]

void commit( )

Only used if you want to do transactions and your db supports transactions



Tags:

todo:  Document this API
uses:  ActiveRecord::$db


[ Top ]

method create [line 1548]

void create( $attributes, [ $dont_validate = false])



Tags:

todo:  Document this API. What's going on here? It appears to either create a row with all empty values, or it tries to recurse once for each attribute in $attributes. Creates an object, instantly saves it as a record (if the validation permits it). If the save fails under validations it returns false and $errors array gets set.


Parameters:

   $attributes  
   $dont_validate  

[ Top ]

method delete [line 1917]

void delete( [ $id = null])

Deletes the record with the given $id or if you have done a $model = $model->find($id), then $model->delete() it will delete the record it just loaded from the find() without passing anything to delete(). If an array of ids is provided, all ids in array are deleted.



Tags:

todo:  Document this API
uses:  ActiveRecord::$errors


Parameters:

   $id  

[ Top ]

method delete_all [line 1981]

boolean delete_all( [string $conditions = null])

Delete from table all rows that match argument

Delete the row(s), if any, matching the argument.




Tags:

return:  
  • true => One or more rows were deleted
  • false => $conditions was omitted
throws:  ActiveRecordError
uses:  ActiveRecord::query()
uses:  ActiveRecord::is_error()
uses:  ActiveRecord::$new_record
uses:  ActiveRecord::$errors


Parameters:

string   $conditions   SQL argument to "WHERE" describing the rows to delete

[ Top ]

method delete_all_habtm_records [line 2079]

void delete_all_habtm_records( $other_table_name, $this_foreign_value)



Tags:

access:  private


Parameters:

   $other_table_name  
   $this_foreign_value  

[ Top ]

method delete_habtm_records [line 2069]

void delete_habtm_records( $this_foreign_value)



Tags:

todo:  Document this API
throws:  ActiveRecordError
access:  private
uses:  ActiveRecord::query()
uses:  ActiveRecord::is_error()


Parameters:

   $this_foreign_value  

[ Top ]

method escape [line