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

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

[line 250]

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:

usedby:  ActiveRecord::__call()
access:  protected

Type:   string[]


[ Top ]

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

[line 213]

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



Tags:

access:  public
todo:  Document this variable

Type:   mixed


[ Top ]

$auto_save_associations =  true

[line 178]



Tags:

usedby:  ActiveRecord::update_attributes()
usedby:  ActiveRecord::save_associations()
usedby:  ActiveRecord::__set()
access:  public
todo:  Document this property

Type:   boolean


[ Top ]

$auto_save_habtm =  true

[line 309]



Tags:

usedby:  ActiveRecord::add_record()
access:  public
todo:  Document this variable

Type:   mixed


[ Top ]

$auto_timestamps =  true

[line 304]

Whether to automatically update timestamps in certain columns



Tags:


Type:   boolean


[ Top ]

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

[line 201]

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 ]

$begin_executed =  false

[line 320]

Transactions (only use if your db supports it)

FIXME: static should be after private




Tags:

access:  private
static:  

Type:   mixed


[ Top ]

$belongs_to =  null

[line 161]



Tags:

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

Type:   string[]


[ Top ]

$content_columns =  null

[line 99]

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

Database name override

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




Tags:

usedby:  ActiveRecord::establish_connection()
access:  public

Type:   string


[ Top ]

$date_format =  "Y-m-d"

[line 222]

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:  protected

Type:   string


[ Top ]

$db =  null

[line 73]

Reference to the database object

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




Tags:


Type:   object DB


[ Top ]

$display =  10

[line 278]



Tags:

usedby:  ActiveRecord::page_list()
access:  public
todo:  Document this variable

Type:   mixed


[ Top ]

$errors = array()

[line 295]

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 =  DB_FETCHMODE_ASSOC

[line 128]

Mode to use when fetching data from database

See the relevant PEAR DB class documentation




Tags:

access:  public

Type:   integer


[ Top ]

$force_reconnect =  false

[line 135]

Force reconnect to database



Tags:

usedby:  ActiveRecord::establish_connection()
access:  public

Type:   boolean


[ Top ]

$habtm_attributes =  null

[line 167]



Tags:

access:  protected
todo:  Document this variable

Type:   string[]


[ Top ]

$has_and_belongs_to_many =  null

[line 155]



Tags:

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

Type:   string[]


[ Top ]

$has_many =  null

[line 143]



Tags:

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

Type:   string[]


[ Top ]

$has_one =  null

[line 149]



Tags:

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

Type:   string[]


[ Top ]

$index_on =  "id"

[line 136]



Tags:

access:  public

Type:   mixed


[ Top ]

$new_record =  true

[line 189]

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 ]

$preserve_null_dates =  true

[line 240]

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

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

Default for how many rows to return from find_all()



Tags:

usedby:  ActiveRecord::find_all()
access:  public

Type:   integer


[ Top ]

$save_associations = array()

[line 172]



Tags:

access:  protected
todo:  Document this property

Type:   mixed


[ Top ]

$table_name =  null

[line 109]

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:

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

Type:   string


[ Top ]

$time_format =  "H:i:s"

[line 231]

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:  protected

Type:   string


[ Top ]

$use_transactions =  false

[line 325]

FIXME: static should be after public



Tags:

access:  public
static:  

Type:   mixed


[ Top ]



Class Methods


constructor __construct [line 343]

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

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

void add_habtm_records( mixed $this_foreign_value)



Tags:

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


[ Top ]

method add_record [line 1341]

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. FIXME: Shouldn't we be saving the insert ID value as an object variable $this->id?




Tags:

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


[ Top ]

method add_record_or_update_record [line 1300]

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
uses:  ActiveRecord::update_record()
access:  private
usedby:  ActiveRecord::save()
uses:  ActiveRecord::$new_record
uses:  ActiveRecord::before_save()
uses:  ActiveRecord::after_create()
uses:  ActiveRecord::after_update()
uses:  ActiveRecord::before_create()
uses:  ActiveRecord::add_record()


[ Top ]

method after_create [line 2294]

void after_create( )

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



Tags:

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


[ Top ]

method after_delete [line 2318]

void after_delete( )

Is called after delete().



Tags:

todo:  Document this API


[ Top ]

method after_save [line 2282]

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

void after_update( )

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



Tags:

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


[ Top ]

method after_validation [line 2246]

void after_validation( )

Is called after validate().



Tags:

todo:  Document this API


[ Top ]

method after_validation_on_create [line 2258]

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

void after_validation_on_update( )

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



Tags:

todo:  Document this API


[ Top ]

method aggregrate_all [line 720]

void aggregrate_all( mixed $aggregrate_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:

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


Parameters:

string   $agrregrate_type   SQL aggregate function to apply, suffixed '_all'. The aggregate function is one of the strings in $aggregrations.
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

[ Top ]

method before_create [line 2288]

void before_create( )

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



Tags:

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


[ Top ]

method before_delete [line 2312]

void before_delete( )

Is called before delete().



Tags:

todo:  Document this API


[ Top ]

method before_save [line 2276]

void before_save( )

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



Tags:

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


[ Top ]

method before_update [line 2300]

void before_update( )

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



Tags:

todo:  Document this API


[ Top ]

method before_validation [line 2240]

void before_validation( )

Is called before validate().



Tags:

todo:  Document this API


[ Top ]

method before_validation_on_create [line 2252]

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

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

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 check_datetime [line 1692]

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
uses:  ActiveRecord::$auto_update_timestamps
access:  private
uses:  ActiveRecord::$auto_create_timestamps
uses:  ActiveRecord::$auto_timestamps
uses:  ActiveRecord::$content_columns
uses:  ActiveRecord::$new_record


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

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

void column_for_attribute( mixed $attribute)

get the attributes for a specific column.



Tags:

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


[ Top ]

method commit [line 831]

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

void create( mixed $attributes, [mixed $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. FIXME: resolve calling sequence 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.


[ Top ]

method delete [line 1512]

void delete( [mixed $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


[ Top ]

method delete_all [line 1558]

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::$errors
uses:  ActiveRecord::$new_record
uses:  ActiveRecord::is_error()


Parameters:

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

[ Top ]

method delete_all_habtm_records [line 1659]

void delete_all_habtm_records( mixed $other_table_name, mixed $this_foreign_value)



Tags:

access:  private


[ Top ]

method delete_habtm_records [line 1649]

void delete_habtm_records( mixed $this_foreign_value)



Tags:

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


[ Top ]

method establish_connection [line 2006]

void establish_connection( )

Open a database connection if one is not currently open

The name of the database normally comes from $GLOBALS['TRAX_DB_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 DB object in $GLOBALS['ACTIVE_RECORD_DB'], 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 $GLOBALS['ACTIVE_RECORD_DB'].




Tags:



[ Top ]

method find [line 1104]

mixed find( mixed[] $id, [string $orderings = 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.

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


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   $orderings   Argument to "ORDER BY" in query. If specified, the query will include "ORDER BY $orderings". If omitted, no ordering will be applied.
integer[]   $limit   Page, rows per page???
string   $joins   ???

[ Top ]

method find_all [line 961]

object[] find_all( [string $conditions = null], [string $orderings = 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.
throws:  ActiveRecordError
uses:  ActiveRecord::query()
usedby:  ActiveRecord::find_by()
usedby:  ActiveRecord::find()
usedby:  ActiveRecord::find_first()
uses:  ActiveRecord::$new_record
uses:  ActiveRecord::is_error()
uses:  ActiveRecord::$rows_per_page_default
uses:  $rows_per_page
uses:  $offset
uses:  $page
todo:  Document the $limit and $joins parameters


Parameters:

string   $conditions   SQL to use in the query. If $conditions contains "SELECT", then $orderings, $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   $orderings   Argument to "ORDER BY" in query. If specified, the query will include "ORDER BY $orderings". If omitted, no ordering will be applied.
integer[]   $limit   Page, rows per page???
string   $joins   ???

[ Top ]

method find_all_habtm [line 529]

void find_all_habtm( mixed $other_table_name, [mixed $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:

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


[ Top ]

method find_all_has_many [line 584]

void find_all_has_many( mixed $other_table_name, [mixed $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:

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


[ Top ]

method find_by [line 889]

void find_by( mixed $method_name, mixed $parameters, [mixed $find_all = false])

Implement find_by_*() and find_all_by_* 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:

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


[ Top ]

method find_by_sql [line 1156]

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

mixed find_first( string $conditions, [string $orderings = null], [integer[] $limit = null], [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.
usedby:  ActiveRecord::find()
usedby:  ActiveRecord::find_by()
throws:  ActiveRecordError
uses:  ActiveRecord::find_all()


Parameters:

string   $conditions   SQL to use in the query. If $conditions contains "SELECT", then $orderings, $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   $orderings   Argument to "ORDER BY" in query. If specified, the query will include "ORDER BY $orderings". 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 673]

void find_one_belongs_to( mixed $other_object_name, [mixed $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:

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


[ Top ]

method find_one_has_one [line 641]

void find_one_has_one( mixed $other_object_name, [mixed $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:

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


[ Top ]

method get_association_type [line 1421]

mixed get_association_type( mixed $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
usedby:  ActiveRecord::__get()
usedby:  ActiveRecord::__set()
usedby:  ActiveRecord::__call()
uses:  ActiveRecord::$has_one
uses:  ActiveRecord::$has_many
todo:  Document this API
uses:  ActiveRecord::$belongs_to
uses:  ActiveRecord::$has_and_belongs_to_many
todo:  FIXME: does the match algorithm match a substring of what we want to match?


[ Top ]

method get_attributes [line 1817]

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_errors [line 2093]

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

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

string get_errors_as_string( [string $seperator = "
"])

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_insert_id [line 1975]

void get_insert_id( )

Returns the autogenerated id from the last insert query



Tags:



[ Top ]

method get_join_table_name [line 507]

void get_join_table_name( mixed $first_table, mixed $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:

access:  private
todo:  Document this API


[ Top ]

method get_primary_key_conditions [line 1883]

string get_primary_key_conditions( )

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


[ Top ]

method get_updates_sql [line 1913]

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_error [line 2042]

boolean is_error( object $obj)

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



Tags:



Parameters:

object   $obj   Object to test

[ Top ]

method is_new_record [line 749]

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 limit_select [line 2336]

void limit_select( [mixed $controller = null], [mixed $additional_query = null])

Paging html functions



Tags:

todo:  Document this API


[ Top ]

method load [line 1182]

void load( [mixed $conditions = null])

Loads into current object values from the database.



[ Top ]

method log_query [line 2326]

void log_query( string $sql)

Log SQL query in development mode

If running in development mode, log the query to $GLOBAL




Tags:



Parameters:

string   $sql   SQL to be logged

[ Top ]

method page_list [line 2362]

string page_list( )



Tags:

return:  HTML to link to previous and next pages
uses:  $paging_extra_params
uses:  rows_per_page
uses:  $pages
uses:  $page
uses:  ActiveRecord::$display
todo:  Document this API


[ Top ]

method query [line 857]

DB_result 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 1846]

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 raise [line 2055]

void raise( mixed $message)

Throw an exception describing an error in this object



Tags:



[ Top ]

method reload [line 1165]

void reload( [mixed $conditions = null])

Reloads the attributes of this object from the database.



Tags:

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


[ Top ]

method rollback [line 842]

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

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

void save_association( mixed $object, mixed $type)

save the association to the database



Tags:

access:  private
todo:  Document this API


[ Top ]

method save_associations [line 1467]

void save_associations( )

Saves any associations objects assigned to this instance



Tags:

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


[ Top ]

method save_without_validation [line 1247]

void save_without_validation( [mixed $attributes = null])

Save without valdiating anything.



Tags:

todo:  Document this API


[ Top ]

method send [line 801]

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

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. FIXME: should throw an exception if tableInfo() fails




Tags:



Parameters:

string   $table_name   Name of table to get information about

[ Top ]

method set_habtm_attributes [line 1580]

void set_habtm_attributes( mixed $attributes)



Tags:

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


[ Top ]

method set_table_name_using_class_name [line 1936]

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

void update( mixed $id, mixed $attributes, [mixed $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


[ Top ]

method update_all [line 1233]

void update_all( mixed $updates, [mixed $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()


[ Top ]

method update_attributes [line 1730]

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:

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


Parameters:

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

[ Top ]

method update_habtm_records [line 1603]

void update_habtm_records( mixed $this_foreign_value)



Tags:

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


[ Top ]

method update_record [line 1383]

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
uses:  ActiveRecord::update_habtm_records()
throws:  ActiveRecordError
access:  private
usedby:  ActiveRecord::add_record_or_update_record()
uses:  ActiveRecord::raise()
uses:  ActiveRecord::query()
uses:  ActiveRecord::is_error()
uses:  ActiveRecord::get_updates_sql()
uses:  ActiveRecord::get_primary_key_conditions()
todo:  Describe habtm automatic update


[ Top ]

method valid [line 2135]

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();
uses:  ActiveRecord::$new_record
uses:  validate_model_attributes();
uses:  validate_on_create();
usedby:  ActiveRecord::save()
uses:  ActiveRecord::$errors
uses:  before_validation_on_update();
uses:  after_validation_on_create();
uses:  after_validation_on_update();
uses:  before_validation();
uses:  before_validation_on_create();
uses:  after_validation();


[ Top ]

method validate [line 2222]

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 validate_model_attributes [line 2182]

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

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

void validate_on_update( )

Override this method for validation checks used only on updates.



Tags:

todo:  Document this API


[ Top ]

method __call [line 454]

void __call( mixed $method_name, mixed $parameters)

Override call() to dynamically call the database associations



Tags:



[ Top ]

method __get [line 377]

void __get( mixed $key)

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



Tags:



[ Top ]

method __set [line 417]

void __set( mixed $key, mixed $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:



[ Top ]


Documentation generated on Thu, 04 May 2006 19:47:11 -0600 by phpDocumentor 1.3.0RC4