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 2315]

void escape( $string)

Escapes a string for use in an sql statement.



Parameters:

   $string  

[ Top ]

method establish_connection [line 2502]

void establish_connection( )

Open a database connection if one is not currently open

The name of the database normally comes from $database_settings which is set in environment.php by reading file config/database.ini. The database name may be overridden by assigning a different name to $database_name.

If there is a connection now open, as indicated by the saved value of a MDB2 object in $active_connections[$connection_name], and force_reconnect is not true, then set the database fetch mode and return.

If there is no connection, open one and save a reference to it in $active_connections[$connection_name].




Tags:



[ Top ]

method find [line 1430]

mixed find( mixed[] $id, [string $order = null], [integer[] $limit = null], [string $joins = null])

Find row(s) with specified value(s)

Find all the rows in the table which match the argument $id. Return zero or more objects of the same class as this class representing the rows that matched the argument.




Tags:

return:  

Results of query. If $id was a scalar then the result is an object of the same class as this class and matching $id conditions, or if no row matched the result is null.

If $id was an array then the result is an array containing objects of the same class as this class and matching the conditions set by $id. If no rows matched, the array is empty.

todo:  Document the $limit and $joins parameters
throws:  ActiveRecordError
uses:  ActiveRecord::find_all()
uses:  ActiveRecord::find_first()


Parameters:

mixed[]   $id   If $id is an array then a query will be generated selecting all of the array values in column "id". If $id is a string containing "=" then the string value of $id will be inserted in a WHERE clause in the query. If $id is a scalar not containing "=" then a query will be generated selecting the first row WHERE id = '$id'. NOTE The column name "id" is used regardless of the value of $primary_keys. Therefore if you need to select based on some column other than "id", you must pass a string argument ready to insert in the SQL SELECT.
string   $order   Argument to "ORDER BY" in query. If specified, the query will include "ORDER BY $order". If omitted, no ordering will be applied.
integer[]   $limit   Page, rows per page???
string   $joins   ???

[ Top ]

method find_all [line 1356]

object[] find_all( [string $conditions = null], [string $order = null], [integer[] $limit = null], [string $joins = null])

Return rows selected by $conditions

If no rows match, an empty array is returned.




Tags:

return:  Array of objects of the same class as this object, one object for each row returned by the query. If the column 'id' was in the results, it is used as the key for that object in the array.
todo:  Document the $limit and $joins parameters
throws:  ActiveRecordError
usedby:  ActiveRecord::find()
usedby:  ActiveRecord::find_first()
usedby:  ActiveRecord::find_by()
uses:  ActiveRecord::query()
uses:  ActiveRecord::$new_record
uses:  ActiveRecord::is_error()


Parameters:

string   $conditions   SQL to use in the query. If $conditions contains "SELECT", then $order, $limit and $joins are ignored and the query is completely specified by $conditions. If $conditions is omitted or does not contain "SELECT", "SELECT * FROM" will be used. If $conditions is specified and does not contain "SELECT", the query will include "WHERE $conditions". If $conditions is null, the entire table is returned.
string   $order   Argument to "ORDER BY" in query. If specified, the query will include "ORDER BY $order". If omitted, no ordering will be applied.
integer[]   $limit   Page, rows per page???
string   $joins   ???

[ Top ]

method find_all_habtm [line 643]

void find_all_habtm( $other_table_name, [ $parameters = null])

Find all records using a "has_and_belongs_to_many" relationship

(many-to-many with a join table in between). Note that you can also specify an optional "paging limit" by setting the corresponding "limit" instance variable. For example, if you want to return 10 movies from the 5th movie on, you could set $this->movies_limit = "10, 5"

Parameters: $this_table_name: The name of the database table that has the one row you are interested in. E.g. genres $other_table_name: The name of the database table that has the many rows you are interested in. E.g. movies Returns: An array of ActiveRecord objects. (e.g. Movie objects)




Tags:

todo:  Document this API
access:  private
usedby:  ActiveRecord::__get()


Parameters:

   $other_table_name  
   $parameters  

[ Top ]

method find_all_has_many [line 741]

void find_all_has_many( $other_table_name, [ $parameters = null])

Find all records using a "has_many" relationship (one-to-many)

Parameters: $other_table_name: The name of the other table that contains many rows relating to this object's id. Returns: An array of ActiveRecord objects. (e.g. Contact objects)




Tags:

todo:  Document this API
access:  private
usedby:  ActiveRecord::__get()


Parameters:

   $other_table_name  
   $parameters  

[ Top ]

method find_by [line 1159]

void find_by( $method_name, $parameters, [ $find_type = null])

Implement find_by_*() and =_* methods

Converts a method name beginning 'find_by_' or 'find_all_by_' into a query for rows matching the rest of the method name and the arguments to the function. The part of the method name after '_by' is parsed for columns and logical relationships (AND and OR) to match. For example, the call find_by_fname('Ben') is converted to SELECT * ... WHERE fname='Ben' and the call find_by_fname_and_lname('Ben','Dover') is converted to SELECT * ... WHERE fname='Ben' AND lname='Dover'




Tags:

access:  private
usedby:  ActiveRecord::__call()
uses:  ActiveRecord::find_first()
uses:  ActiveRecord::find_all()


Parameters:

   $method_name  
   $parameters  
   $find_type  

[ Top ]

method find_by_sql [line 1511]

void find_by_sql( string $sql)

Return all the rows selected by the SQL argument

If no rows match, an empty array is returned.




Parameters:

string   $sql   SQL to use in the query.

[ Top ]

method find_first [line 1491]

mixed find_first( [string $conditions = null], [string $order = null], [integer[] $limit = 1], [string $joins = null])

Return first row selected by $conditions

If no rows match, null is returned.




Tags:

return:  An object of the same class as this class and matching $conditions, or null if none did.
throws:  ActiveRecordError
usedby:  ActiveRecord::find()
usedby:  ActiveRecord::find_by()
uses:  ActiveRecord::find_all()


Parameters:

string   $conditions   SQL to use in the query. If $conditions contains "SELECT", then $order, $limit and $joins are ignored and the query is completely specified by $conditions. If $conditions is omitted or does not contain "SELECT", "SELECT * FROM" will be used. If $conditions is specified and does not contain "SELECT", the query will include "WHERE $conditions". If $conditions is null, the entire table is returned.
string   $order   Argument to "ORDER BY" in query. If specified, the query will include "ORDER BY $order". If omitted, no ordering will be applied. FIXME This parameter doesn't seem to make sense
integer[]   $limit   Page, rows per page??? @todo Document this parameter FIXME This parameter doesn't seem to make sense
string   $joins   ??? @todo Document this parameter

[ Top ]

method find_one_belongs_to [line 881]

void find_one_belongs_to( $other_object_name, [ $parameters = null])

Find all records using a "belongs_to" relationship (one-to-one) (the foreign key being in the table itself) Parameters: $other_object_name: The singularized version of a table name.

E.g. If the Contact class belongs_to the Customer class, then $other_object_name will be "customer".




Tags:

todo:  Document this API
access:  private
usedby:  ActiveRecord::__get()


Parameters:

   $other_object_name  
   $parameters  

[ Top ]

method find_one_has_one [line 821]

void find_one_has_one( $other_object_name, [ $parameters = null])

Find all records using a "has_one" relationship (one-to-one) (the foreign key being in the other table) Parameters: $other_table_name: The name of the other table that contains many rows relating to this object's id.

Returns: An array of ActiveRecord objects. (e.g. Contact objects)




Tags:

todo:  Document this API
access:  private
usedby:  ActiveRecord::__get()


Parameters:

   $other_object_name  
   $parameters  

[ Top ]

method get_association_type [line 1825]

mixed get_association_type( $association_name)

returns the association type if defined in child class or null



Tags:

return:  Association type, one of the following:
  • "belongs_to"
  • "has_and_belongs_to_many"
  • "has_many"
  • "has_one"
if an association exists, or null if no association
todo:  Document this API
usedby:  ActiveRecord::__set()
usedby:  ActiveRecord::__call()
usedby:  ActiveRecord::__get()
uses:  ActiveRecord::$has_many
uses:  ActiveRecord::$belongs_to
uses:  ActiveRecord::$has_and_belongs_to_many
uses:  ActiveRecord::$has_one


Parameters:

   $association_name  

[ Top ]

method get_attributes [line 2250]

void get_attributes( )

Return pairs of column-name:column-value

Return the contents of the object as an array of elements where the key is the column name and the value is the column value. Relies on a previous call to set_content_columns() for information about the format of a row in the table.




Tags:



[ Top ]

method get_class_name [line 2417]

string get_class_name( )

Get class name of child object

this will return the manually set name or get_class($this)




Tags:

return:  child class name
access:  private


[ Top ]

method get_composite_object [line 1773]

void get_composite_object( $name)

Loads the model values into composite object



Tags:

todo:  Document this API
access:  private


Parameters:

   $name  

[ Top ]

method get_errors [line 3196]

mixed get_errors( [boolean $return_string = false], [string $seperator = "<br>"])

Return description of non-fatal errors



Tags:

return:  Error description(s), if any
uses:  ActiveRecord::$errors


Parameters:

boolean   $return_string  
  • true => Concatenate all error descriptions into a string using $seperator between elements and return the string
  • false => Return the error descriptions as an array
string   $seperator   String to concatenate between error descriptions if $return_string == true

[ Top ]

method get_errors_as_string [line 3213]

string get_errors_as_string( [string $seperator = "<br>"])

Return errors as a string.

Concatenate all error descriptions into a stringusing $seperator between elements and return the string.




Tags:

return:  Concatenated error description(s), if any


Parameters:

string   $seperator   String to concatenate between error descriptions

[ Top ]

method get_error_message_for_validation [line 3128]

string get_error_message_for_validation( string $message, string $key, [string $value = null])

Return the error message for a validation function



Tags:

access:  private


Parameters:

string   $message  
string   $key  
string   $value  

[ Top ]

method get_inserts [line 2328]

void get_inserts( )

Return column values for SQL insert statement

Return an array containing the column names and values of this object, filtering out the primary keys, which are not set.




Tags:



[ Top ]

method get_insert_id [line 2465]

void get_insert_id( )

Returns the autogenerated id from the last insert query



Tags:



[ Top ]

method get_join_table_name [line 995]

void get_join_table_name( $first_table, $second_table)

Returns a the name of the join table that would be used for the two tables. The join table name is decided from the alphabetical order of the two tables. e.g. "genres_movies" because "g" comes before "m"

Parameters: $first_table, $second_table: the names of two database tables, e.g. "movies" and "genres"




Tags:

todo:  Document this API
access:  public


Parameters:

   $first_table  
   $second_table  

[ Top ]

method get_primary_key_conditions [line 2355]

string get_primary_key_conditions( [ $operator = "="])

Return argument for a "WHERE" clause specifying this row

Returns a string which specifies the column(s) and value(s) which describe the primary key of this row of the associated table. The primary key must be one or more attributes of the object and must be listed in $content_columns as columns in the row.

Example: if $primary_keys = array("id", "ssn") and column "id" has value "5" and column "ssn" has value "123-45-6789" then the string "id = 5 AND ssn = '123-45-6789'" would be returned.




Tags:

return:  Column name = 'value' [ AND name = 'value']...
usedby:  ActiveRecord::update_record()
usedby:  ActiveRecord::reload()
uses:  ActiveRecord::quoted_attributes()
uses:  ActiveRecord::$primary_keys


Parameters:

   $operator  

[ Top ]

method get_updates_sql [line 2381]

string get_updates_sql( )

Return column values of object formatted for SQL update statement

Return a string containing the column names and values of this object in a format ready to be inserted in a SQL UPDATE statement. Automatic update has been applied to timestamps if enabled and characters special to SQL have been quoted.




Tags:

return:  Column name = 'value', ... for all attributes
usedby:  ActiveRecord::update_record()
uses:  ActiveRecord::quoted_attributes()


[ Top ]

method is_composite [line 2577]

void is_composite( string $name)

Determine if passed in name is a composite class or not



Tags:

access:  private
uses:  ActiveRecord::$composed_of


Parameters:

string   $name   Name of the composed_of mapping

[ Top ]

method is_error [line 3144]

boolean is_error( object $obj)

Test whether argument is a PEAR Error object or a MDB2 Error object.



Tags:



Parameters:

object   $obj   Object to test

[ Top ]

method is_new_record [line 1006]

boolean is_new_record( )

Test whether this object represents a new record



Tags:

return:  Whether this object represents a new record
uses:  ActiveRecord::$new_record


[ Top ]

method load [line 1537]

void load( [ $conditions = null])

Loads into current object values from the database.



Parameters:

   $conditions  

[ Top ]

method log_query [line 3223]

void log_query( string $query)

Log SQL query in development mode

If running in development mode, log the query to self::$query_log




Tags:



Parameters:

string   $query   SQL to be logged

[ Top ]

method query [line 1127]

$mdb2->query query( string $sql)

Perform an SQL query and return the results



Tags:



Parameters:

string   $sql   SQL for the query command

[ Top ]

method quoted_attributes [line 2279]

string[] quoted_attributes( [string[] $attributes = null])

Return pairs of column-name:quoted-column-value

Return pairs of column-name:quoted-column-value where the key is the column name and the value is the column value with automatic timestamp updating applied and characters special to SQL quoted.

If $attributes is null or omitted, return all columns as currently stored in content_columns(). Otherwise, return the name:value pairs in $attributes.




Tags:



Parameters:

string[]   $attributes   Name:value pairs to return. If null or omitted, return the column names and values of the object as stored in $content_columns.

[ Top ]

method quote_attribute [line 2294]

void quote_attribute( $attribute, [ $value = null])

Quotes a single attribute for use in an sql statement.



Parameters:

   $attribute  
   $value  

[ Top ]

method raise [line 3157]

void raise( $message)

Throw an exception describing an error in this object



Tags:



Parameters:

   $message  

[ Top ]

method reload [line 1520]

void reload( [ $conditions = null])

Reloads the attributes of this object from the database.



Tags:

todo:  Document this API
uses:  ActiveRecord::get_primary_key_conditions()


Parameters:

   $conditions  

[ Top ]

method rollback [line 1112]

void rollback( )

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



Tags:

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


[ Top ]

method save [line 1617]

boolean save( [string[] $attributes = null], [boolean $dont_validate = false])

Create or update a row in the table with specified attributes



Tags:

return:  
  • true => row was updated or inserted successfully
  • false => insert failed
uses:  ActiveRecord::valid()
uses:  ActiveRecord::update_attributes()
uses:  ActiveRecord::add_record_or_update_record()


Parameters:

string[]   $attributes   List of name => value pairs giving name and value of attributes to set.
boolean   $dont_validate   true => Don't call validation routines before saving the row. If false or omitted, all applicable validation routines are called.

[ Top ]

method save_association [line 1893]

void save_association( $object, $type)

save the association to the database



Tags:

todo:  Document this API
access:  private


Parameters:

   $object  
   $type  

[ Top ]

method save_associations [line 1871]

void save_associations( )

Saves any associations objects assigned to this instance



Tags:

todo:  Document this API
access:  private
uses:  ActiveRecord::$auto_save_associations


[ Top ]

method save_without_validation [line 1596]

void save_without_validation( [ $attributes = null])

Save without valdiating anything.



Tags:

todo:  Document this API


Parameters:

   $attributes  

[ Top ]

method send [line 1071]

void send( string $column)

Get contents of one column of record selected by id and table

When called, $id identifies one record in the table identified by $table. Fetch from the database the contents of column $column of this record.




Tags:



Parameters:

string   $column   Name of column to retrieve

[ Top ]

method set_content_columns [line 2435]

void set_content_columns( string $table_name)

Populate object with information about the table it represents

Call DB_common::tableInfo() to get a description of the table and store it in $content_columns. Add a more human friendly name to the element for each column.




Tags:



Parameters:

string   $table_name   Name of table to get information about

[ Top ]

method set_habtm_attributes [line 2000]

void set_habtm_attributes( $attributes)



Tags:

todo:  Document this API
access:  private
uses:  ActiveRecord::$has_and_belongs_to_many


Parameters:

   $attributes  

[ Top ]

method set_table_name_using_class_name [line 2404]

void set_table_name_using_class_name( )

Set $table_name from the class name of this object

By convention, the name of the database table represented by this object is derived from the name of the class.




Tags:



[ Top ]

method update [line 1560]

void update( $id, $attributes, [ $dont_validate = false])

Finds the record from the passed id, instantly saves it with the passed attributes (if the validation permits it). Returns true on success and false on error.



Tags:

todo:  Document this API


Parameters:

   $id  
   $attributes  
   $dont_validate  

[ Top ]

method update_all [line 1582]

void update_all( $updates, [ $conditions = null])

Updates all records with the SET-part of an SQL update statement in updates and returns an integer with the number of rows updates. A subset of the records can be selected by specifying conditions.

Example: $model->update_all("category = 'cooldude', approved = 1", "author = 'John'");




Tags:

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


Parameters:

   $updates  
   $conditions  

[ Top ]

method update_attributes [line 2150]

void update_attributes( string[] $attributes)

Update object attributes from list in argument

The elements of $attributes are parsed and assigned to attributes of the ActiveRecord object. Date/time fields are treated according to the The Trax Naming Convention.




Tags:

todo:  Figure out and document how datetime fields work
usedby:  ActiveRecord::save()
usedby:  ActiveRecord::__construct()
uses:  ActiveRecord::$auto_save_associations


Parameters:

string[]   $attributes   List of name => value pairs giving name and value of attributes to set.

[ Top ]

method update_composite_attributes [line 2223]

void update_composite_attributes( )

If a composite object was specified via $composed_of, then its values mapped to the model will overwrite the models values.



[ Top ]

method update_habtm_records [line 2023]

void update_habtm_records( $this_foreign_value)



Tags:

todo:  Document this API
access:  private
usedby:  ActiveRecord::update_record()


Parameters:

   $this_foreign_value  

[ Top ]

method update_record [line 1744]

boolean update_record( )

Update the row in the table described by this object

The primary key attributes must exist and have appropriate non-null values. If a column is listed in $content_columns but no attribute of that name exists, the column will be set to the null string ''.




Tags:

return:  
  • true => row was updated successfully
  • false => update failed
todo:  Describe habtm automatic update
throws:  ActiveRecordError
access:  private
usedby:  ActiveRecord::add_record_or_update_record()
uses:  ActiveRecord::update_habtm_records()
uses:  ActiveRecord::query()
uses:  ActiveRecord::get_primary_key_conditions()
uses:  ActiveRecord::get_updates_sql()
uses:  ActiveRecord::is_error()
uses:  ActiveRecord::raise()


[ Top ]

method valid [line 2608]

boolean valid( )

Runs validation routines for update or create



Tags:

return:  
  • true => Valid, no errors found. $errors is empty
  • false => Not valid, errors in $errors
uses:  validate_builtin();
uses:  validate();
uses:  validate_model_attributes();
uses:  validate_on_create();
usedby:  ActiveRecord::save()
uses:  before_validation_on_update();
uses:  before_validation_on_create();
uses:  after_validation();
uses:  ActiveRecord::$new_record
uses:  after_validation_on_create();
uses:  after_validation_on_update();
uses:  before_validation();
uses:  ActiveRecord::$errors


[ Top ]

method validate [line 2698]

void validate( )

Overwrite this method for validation checks on all saves and

use $this->errors[] = "My error message."; or for invalid attributes $this->errors['attribute'] = "Attribute is invalid.";




Tags:

todo:  Document this API


[ Top ]

method validates_acceptance_of [line 2897]

void validates_acceptance_of( string|array $attribute_names, [string $message = null], [string $accept = 1])

Validates that a checkbox is clicked.

eg. validates_acceptance_of('eula')




Parameters:

string|array   $attribute_names  
string   $message  
string   $accept  

[ Top ]

method validates_confirmation_of [line 2914]

void validates_confirmation_of( string|array $attribute_names, [string $message = null])

Validates that a field has the same value as its corresponding confirmation field.

eg. validates_confirmation_of('password')




Parameters:

string|array   $attribute_names  
string   $message  

[ Top ]

method validates_exclusion_of [line 2933]

void validates_exclusion_of( string|array $attribute_names, [mixed $in = array()], [string $message = null])

Validates that specified attributes are NOT in an array of elements.

eg. validates_exclusion_of('age, 'in' => array(13, 19))




Parameters:

string|array   $attribute_names  
mixed   $in   array(1,2,3,4,5) or string 1..5
string   $message  

[ Top ]

method validates_format_of [line 2959]

void validates_format_of( string|array $attribute_names, string $regex, [string $message = null])

Validates that specified attributes matches a regular expression eg. validates_format_of('email', '/^(+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i')



Parameters:

string|array   $attribute_names  
string   $regex  
string   $message  

[ Top ]

method validates_inclusion_of [line 2979]

void validates_inclusion_of( string|array $attribute_names, [mixed $in = array()], [string $message = null])

Validates that specified attributes are in an array of elements.

eg. validates_inclusion_of('gender', array('m', 'f'))




Parameters:

string|array   $attribute_names  
mixed   $in   array(1,2,3,4,5) or string 1..5
string   $message  

[ Top ]

method validates_length_of [line 3004]

void validates_length_of( string|array $attribute_names, [array $options = array( 'too_short' => null, 'too_long' => null, 'wrong_length' => null, 'message' => null)])

Validates that specified attributes are of some length eg. validates_length_of('password', array('minimum' => 8))



Parameters:

string|array   $attribute_names  
array   $options  

[ Top ]

method validates_numericality_of [line 3055]

void validates_numericality_of( string|array $attribute_names, [string $message = null], [ $only_integer = false], [ $allow_null = false])

Validates that specified attributes are numbers eg. validates_numericality_of('value')



Parameters:

string|array   $attribute_names  
string   $message  
   $only_integer  
   $allow_null  

[ Top ]

method validates_presence_of [line 3085]

void validates_presence_of( string|array $attribute_names, [string $message = null])

Validates that specified attributes are not blank eg. validates_presence_of(array('firstname', 'lastname'))



Parameters:

string|array   $attribute_names  
string   $message  

[ Top ]

method validates_uniqueness_of [line 3102]

void validates_uniqueness_of( string|array $attribute_names, [string $message = null])

Validates that specified attributes are unique in the model database table eg. validates_uniqueness_of('username')



Parameters:

string|array   $attribute_names  
string   $message  

[ Top ]

method validate_builtin [line 2815]

void validate_builtin( )

Validates any builtin validates_* functions defined as class variables in child model class.

eg. public $validates_presence_of = array( 'first_name' => array( 'message' => "is not optional.", 'on' => 'update' ), 'last_name' => null, 'password' => array( 'on' => 'create' ) );




Tags:



[ Top ]

method validate_model_attributes [line 2658]

boolean validate_model_attributes( )

Call every method named "validate_*()" where * is a column name

Find and call every method named "validate_something()" where "something" is the name of a column. The "validate_something()" functions are expected to return an array whose first element is true or false (indicating whether or not the validation succeeded), and whose second element is the error message to display if the first element is false.




Tags:

return:  
  • true => Valid, no errors found. $errors is empty
  • false => Not valid, errors in $errors. $errors is an array whose keys are the names of columns, and the value of each key is the error message returned by the corresponding validate_*() method.
uses:  ActiveRecord::get_attributes()
uses:  ActiveRecord::$errors


[ Top ]

method validate_on_create [line 2704]

void validate_on_create( )

Override this method for validation checks used only on creation.



Tags:

todo:  Document this API


[ Top ]

method validate_on_update [line 2710]

void validate_on_update( )

Override this method for validation checks used only on updates.



Tags:

todo:  Document this API


[ Top ]

method __call [line 578]

void __call( $method_name, $parameters)

Override call() to dynamically call the database associations



Tags:



Parameters:

   $method_name  
   $parameters  

[ Top ]

method __get [line 496]

void __get( $key)

Override get() if they do $model->some_association->field_name dynamically load the requested contents from the database.



Tags:



Parameters:

   $key  

[ Top ]

method __set [line 540]

void __set( $key, $value)

Store column value or description of the table format

If called with key 'table_name', $value is stored as the description of the table format in $content_columns. Any other key causes an object variable with the same name to be created and stored into. If the value of $key matches the name of a column in content_columns, the corresponding object variable becomes the content of the column in this row.




Tags:



Parameters:

   $key  
   $value  

[ Top ]


Documentation generated on Mon, 21 May 2007 22:28:04 -0600 by phpDocumentor 1.3.2