FS::Record - Database record objects
use FS::Record;
use FS::Record qw(dbh fields qsearch qsearchs dbdef);
$record = new FS::Record 'table', \%hash;
$record = new FS::Record 'table', { 'column' => 'value', ... };
$record = qsearchs FS::Record 'table', \%hash;
$record = qsearchs FS::Record 'table', { 'column' => 'value', ... };
@records = qsearch FS::Record 'table', \%hash;
@records = qsearch FS::Record 'table', { 'column' => 'value', ... };
$table = $record->table;
$dbdef_table = $record->dbdef_table;
$value = $record->get('column');
$value = $record->getfield('column');
$value = $record->column;
$record->set( 'column' => 'value' );
$record->setfield( 'column' => 'value' );
$record->column('value');
%hash = $record->hash;
$hashref = $record->hashref;
$error = $record->insert;
#$error = $record->add; #depriciated
$error = $record->delete;
#$error = $record->del; #depriciated
$error = $new_record->replace($old_record);
#$error = $new_record->rep($old_record); #depriciated
$value = $record->unique('column');
$error = $record->ut_float('column');
$error = $record->ut_number('column');
$error = $record->ut_numbern('column');
$error = $record->ut_money('column');
$error = $record->ut_text('column');
$error = $record->ut_textn('column');
$error = $record->ut_alpha('column');
$error = $record->ut_alphan('column');
$error = $record->ut_phonen('column');
$error = $record->ut_anything('column');
$error = $record->ut_name('column');
$dbdef = reload_dbdef;
$dbdef = reload_dbdef "/non/standard/filename";
$dbdef = dbdef;
$quoted_value = _quote($value,'table','field');
#depriciated
$fields = hfields('table');
if ( $fields->{Field} ) { # etc.
@fields = fields 'table'; #as a subroutine
@fields = $record->fields; #as a method call
(Mostly) object-oriented interface to database records. Records are currently
implemented on top of DBI. FS::Record is intended as a base class for
table-specific classes to inherit from, i.e. FS::cust_main.
- new [ TABLE, ] HASHREF
-
Creates a new record. It doesn't store it in the database, though. See
insert for that.
Note that the object stores this hash reference, not a distinct copy of the
hash it points to. You can ask the object for a copy with the hash
method.
TABLE can only be omitted when a dervived class overrides the table method.
- qsearch TABLE, HASHREF, SELECT, EXTRA_SQL
-
Searches the database for all records matching (at least) the key/value pairs
in HASHREF. Returns all the records found as `FS::TABLE' objects if that
module is loaded (i.e. via `use FS::cust_main;'), otherwise returns FS::Record
objects.
###oops, argh, FS::Record::new only lets us create database fields.
#Normal behaviour if SELECT is not specified is `*', as in
#SELECT * FROM table WHERE ...
. However, there is an experimental new
#feature where you can specify SELECT - remember, the objects returned,
#although blessed into the appropriate `FS::TABLE' package, will only have the
#fields you specify. This might have unwanted results if you then go calling
#regular FS::TABLE methods
#on it.
- jsearch TABLE, HASHREF, SELECT, EXTRA_SQL, PRIMARY_TABLE, PRIMARY_KEY
-
Experimental JOINed search method. Using this method, you can execute a
single SELECT spanning multiple tables, and cache the results for subsequent
method calls. Interface will almost definately change in an incompatible
fashion.
Arguments:
- qsearchs TABLE, HASHREF
-
Same as qsearch, except that if more than one record matches, it carps but
returns the first. If this happens, you either made a logic error in asking
for a single item, or your data is corrupted.
- table
-
Returns the table name.
- dbdef_table
-
Returns the FS::dbdef_table object for the table.
- get, getfield COLUMN
-
Returns the value of the column/field/key COLUMN.
- set, setfield COLUMN, VALUE
-
Sets the value of the column/field/key COLUMN to VALUE. Returns VALUE.
- AUTLOADED METHODS
-
$record->column is a synonym for $record->get('column');
$record->column('value')
is a synonym for $record->set('column','value');
- hash
-
Returns a list of the column/value pairs, usually for assigning to a new hash.
To make a distinct duplicate of an FS::Record object, you can do:
$new = new FS::Record ( $old->table, { $old->hash } );
- hashref
-
Returns a reference to the column/value hash.
- insert
-
Inserts this record to the database. If there is an error, returns the error,
otherwise returns false.
- add
-
Depriciated (use insert instead).
- delete
-
Delete this record from the database. If there is an error, returns the error,
otherwise returns false.
- del
-
Depriciated (use delete instead).
- replace OLD_RECORD
-
Replace the OLD_RECORD with this one in the database. If there is an error,
returns the error, otherwise returns false.
- rep
-
Depriciated (use replace instead).
- check
-
Not yet implemented, croaks. Derived classes should provide a check method.
- unique COLUMN
-
Replaces COLUMN in record with a unique number. Called by the add method
on primary keys and single-field unique columns (see the DBIx::DBSchema::Table manpage).
Returns the new value.
- ut_float COLUMN
-
Check/untaint floating point numeric data: 1.1, 1, 1.1e10, 1e10. May not be
null. If there is an error, returns the error, otherwise returns false.
- ut_number COLUMN
-
Check/untaint simple numeric data (whole numbers). May not be null. If there
is an error, returns the error, otherwise returns false.
- ut_numbern COLUMN
-
Check/untaint simple numeric data (whole numbers). May be null. If there is
an error, returns the error, otherwise returns false.
- ut_money COLUMN
-
Check/untaint monetary numbers. May be negative. Set to 0 if null. If there
is an error, returns the error, otherwise returns false.
- ut_text COLUMN
-
Check/untaint text. Alphanumerics, spaces, and the following punctuation
symbols are currently permitted: ! @ # $ % & ( ) - + ; : ' `` , . ? /
May not be null. If there is an error, returns the error, otherwise returns
false.
- ut_textn COLUMN
-
Check/untaint text. Alphanumerics, spaces, and the following punctuation
symbols are currently permitted: ! @ # $ % & ( ) - + ; : ' `` , . ? /
May be null. If there is an error, returns the error, otherwise returns false.
- ut_alpha COLUMN
-
Check/untaint alphanumeric strings (no spaces). May not be null. If there is
an error, returns the error, otherwise returns false.
- ut_alpha COLUMN
-
Check/untaint alphanumeric strings (no spaces). May be null. If there is an
error, returns the error, otherwise returns false.
- ut_phonen COLUMN [ COUNTRY ]
-
Check/untaint phone numbers. May be null. If there is an error, returns
the error, otherwise returns false.
Takes an optional two-letter ISO country code; without it or with unsupported
countries, ut_phonen simply calls ut_alphan.
- ut_ip COLUMN
-
Check/untaint ip addresses. IPv4 only for now.
- ut_ipn COLUMN
-
Check/untaint ip addresses. IPv4 only for now. May be null.
- ut_domain COLUMN
-
Check/untaint host and domain names.
- ut_name COLUMN
-
Check/untaint proper names; allows alphanumerics, spaces and the following
punctuation: , . - '
May not be null.
- ut_zip COLUMN
-
Check/untaint zip codes.
- ut_country COLUMN
-
Check/untaint country codes. Country names are changed to codes, if possible -
see the Locale::Country manpage.
- ut_anything COLUMN
-
Untaints arbitrary data. Be careful.
- ut_enum COLUMN CHOICES_ARRAYREF
-
Check/untaint a column, supplying all possible choices, like the ``enum'' type.
- fields [ TABLE ]
-
This can be used as both a subroutine and a method call. It returns a list
of the columns in this record's table, or an explicitly specified table.
(See the DBIx::DBSchema::Table manpage).
reload_dbdef([FILENAME])
-
Load a database definition (see the DBIx::DBSchema manpage), optionally from a
non-default filename. This command is executed at startup unless
$FS::Record::setup_hack is true. Returns a DBIx::DBSchema object.
- dbdef
-
Returns the current database definition. See the FS::dbdef manpage.
- _quote VALUE, TABLE, COLUMN
-
This is an internal function used to construct SQL statements. It returns
VALUE DBI-quoted (see DBI/``quote'') unless VALUE is a number and the column
type (see the FS::dbdef_column manpage) does not end in `char' or `binary'.
- hfields TABLE
-
This is depriciated. Don't use it.
It returns a hash-type list with the fields of this record's table set true.
This module should probably be renamed, since much of the functionality is
of general use. It is not completely unlike Adapter::DBI (see below).
Exported qsearch and qsearchs should be depriciated in favor of method calls
(against an FS::Record object like the old search and searchs that qsearch
and qsearchs were on top of.)
The whole fields / hfields mess should be removed.
The various WHERE clauses should be subroutined.
table string should be depriciated in favor of FS::dbdef_table.
No doubt we could benefit from a Tied hash. Documenting how exists / defined
true maps to the database (and WHERE clauses) would also help.
The ut_ methods should ask the dbdef for a default length.
ut_sqltype (like ut_varchar) should all be defined
A fallback check method should be provided which uses the dbdef.
The ut_money method assumes money has two decimal digits.
The Pg money kludge in the new method only strips `$'.
The ut_phonen method only checks US-style phone numbers.
The _quote function should probably use ut_float instead of a regex.
All the subroutines probably should be methods, here or elsewhere.
Probably should borrow/use some dbdef methods where appropriate (like sub
fields)
As of 1.14, DBI fetchall_hashref( {} ) doesn't set fetchrow_hashref NAME_lc,
or allow it to be set. Working around it is ugly any way around - DBI should
be fixed. (only affects RDBMS which return uppercase column names)
ut_zip should take an optional country like ut_phone.
the DBIx::DBSchema manpage, the FS::UID manpage, DBI
Adapter::DBI from Ch. 11 of Advanced Perl Programming by Sriram Srinivasan.