FS/FS/Record.pm

   1 package FS::Record;
   2
   3 use strict;
   4 use vars qw( $AUTOLOAD @ISA @EXPORT_OK $DEBUG
   5              $conf $conf_encryption $me
   6              %virtual_fields_cache
   7              $nowarn_identical $nowarn_classload
   8              $no_update_diff $no_check_foreign
   9            );
  10 use Exporter;
  11 use Carp qw(carp cluck croak confess);
  12 use Scalar::Util qw( blessed );
  13 use File::CounterFile;
  14 use Locale::Country;
  15 use Text::CSV_XS;
  16 use File::Slurp qw( slurp );
  17 use DBI qw(:sql_types);
  18 use DBIx::DBSchema 0.38;
  19 use FS::UID qw(dbh getotaker datasrc driver_name);
  20 use FS::CurrentUser;
  21 use FS::Schema qw(dbdef);
  22 use FS::SearchCache;
  23 use FS::Msgcat qw(gettext);
  24 #use FS::Conf; #dependency loop bs, in install_callback below instead
  25
  26 use FS::part_virtual_field;
  27
  28 use Tie::IxHash;
  29
  30 @ISA = qw(Exporter);
  31
  32 #export dbdef for now... everything else expects to find it here
  33 @EXPORT_OK = qw(dbh fields hfields qsearch qsearchs dbdef jsearch
  34                 str2time_sql str2time_sql_closing regexp_sql not_regexp_sql );
  35
  36 $DEBUG = 0;
  37 $me = '[FS::Record]';
  38
  39 $nowarn_identical = 0;
  40 $nowarn_classload = 0;
  41 $no_update_diff = 0;
  42 $no_check_foreign = 0;
  43
  44 my $rsa_module;
  45 my $rsa_loaded;
  46 my $rsa_encrypt;
  47 my $rsa_decrypt;
  48
  49 $conf = '';
  50 $conf_encryption = '';
  51 FS::UID->install_callback( sub {
  52   eval "use FS::Conf;";
  53   die $@ if $@;
  54   $conf = FS::Conf->new;
  55   $conf_encryption = $conf->exists('encryption');
  56   $File::CounterFile::DEFAULT_DIR = $conf->base_dir . "/counters.". datasrc;
  57   if ( driver_name eq 'Pg' ) {
  58     eval "use DBD::Pg ':pg_types'";
  59     die $@ if $@;
  60   } else {
  61     eval "sub PG_BYTEA { die 'guru meditation #9: calling PG_BYTEA when not running Pg?'; }";
  62   }
  63 } );
  64
  65 =head1 NAME
  66
  67 FS::Record - Database record objects
  68
  69 =head1 SYNOPSIS
  70
  71     use FS::Record;
  72     use FS::Record qw(dbh fields qsearch qsearchs);
  73
  74     $record = new FS::Record 'table', \%hash;
  75     $record = new FS::Record 'table', { 'column' => 'value', ... };
  76
  77     $record  = qsearchs FS::Record 'table', \%hash;
  78     $record  = qsearchs FS::Record 'table', { 'column' => 'value', ... };
  79     @records = qsearch  FS::Record 'table', \%hash;
  80     @records = qsearch  FS::Record 'table', { 'column' => 'value', ... };
  81
  82     $table = $record->table;
  83     $dbdef_table = $record->dbdef_table;
  84
  85     $value = $record->get('column');
  86     $value = $record->getfield('column');
  87     $value = $record->column;
  88
  89     $record->set( 'column' => 'value' );
  90     $record->setfield( 'column' => 'value' );
  91     $record->column('value');
  92
  93     %hash = $record->hash;
  94
  95     $hashref = $record->hashref;
  96
  97     $error = $record->insert;
  98
  99     $error = $record->delete;
 100
 101     $error = $new_record->replace($old_record);
 102
 103     # external use deprecated - handled by the database (at least for Pg, mysql)
 104     $value = $record->unique('column');
 105
 106     $error = $record->ut_float('column');
 107     $error = $record->ut_floatn('column');
 108     $error = $record->ut_number('column');
 109     $error = $record->ut_numbern('column');
 110     $error = $record->ut_snumber('column');
 111     $error = $record->ut_snumbern('column');
 112     $error = $record->ut_money('column');
 113     $error = $record->ut_text('column');
 114     $error = $record->ut_textn('column');
 115     $error = $record->ut_alpha('column');
 116     $error = $record->ut_alphan('column');
 117     $error = $record->ut_phonen('column');
 118     $error = $record->ut_anything('column');
 119     $error = $record->ut_name('column');
 120
 121     $quoted_value = _quote($value,'table','field');
 122
 123     #deprecated
 124     $fields = hfields('table');
 125     if ( $fields->{Field} ) { # etc.
 126
 127     @fields = fields 'table'; #as a subroutine
 128     @fields = $record->fields; #as a method call
 129
 130
 131 =head1 DESCRIPTION
 132
 133 (Mostly) object-oriented interface to database records.  Records are currently
 134 implemented on top of DBI.  FS::Record is intended as a base class for
 135 table-specific classes to inherit from, i.e. FS::cust_main.
 136
 137 =head1 CONSTRUCTORS
 138
 139 =over 4
 140
 141 =item new [ TABLE, ] HASHREF
 142
 143 Creates a new record.  It doesn't store it in the database, though.  See
 144 L<"insert"> for that.
 145
 146 Note that the object stores this hash reference, not a distinct copy of the
 147 hash it points to.  You can ask the object for a copy with the I<hash>
 148 method.
 149
 150 TABLE can only be omitted when a dervived class overrides the table method.
 151
 152 =cut
 153
 154 sub new {
 155   my $proto = shift;
 156   my $class = ref($proto) || $proto;
 157   my $self = {};
 158   bless ($self, $class);
 159
 160   unless ( defined ( $self->table ) ) {
 161     $self->{'Table'} = shift;
 162     carp "warning: FS::Record::new called with table name ". $self->{'Table'}
 163       unless $nowarn_classload;
 164   }
 165
 166   $self->{'Hash'} = shift;
 167
 168   foreach my $field ( grep !defined($self->{'Hash'}{$_}), $self->fields ) {
 169     $self->{'Hash'}{$field}='';
 170   }
 171
 172   $self->_rebless if $self->can('_rebless');
 173
 174   $self->{'modified'} = 0;
 175
 176   $self->_cache($self->{'Hash'}, shift) if $self->can('_cache') && @_;
 177
 178   $self;
 179 }
 180
 181 sub new_or_cached {
 182   my $proto = shift;
 183   my $class = ref($proto) || $proto;
 184   my $self = {};
 185   bless ($self, $class);
 186
 187   $self->{'Table'} = shift unless defined ( $self->table );
 188
 189   my $hashref = $self->{'Hash'} = shift;
 190   my $cache = shift;
 191   if ( defined( $cache->cache->{$hashref->{$cache->key}} ) ) {
 192     my $obj = $cache->cache->{$hashref->{$cache->key}};
 193     $obj->_cache($hashref, $cache) if $obj->can('_cache');
 194     $obj;
 195   } else {
 196     $cache->cache->{$hashref->{$cache->key}} = $self->new($hashref, $cache);
 197   }
 198
 199 }
 200
 201 sub create {
 202   my $proto = shift;
 203   my $class = ref($proto) || $proto;
 204   my $self = {};
 205   bless ($self, $class);
 206   if ( defined $self->table ) {
 207     cluck "create constructor is deprecated, use new!";
 208     $self->new(@_);
 209   } else {
 210     croak "FS::Record::create called (not from a subclass)!";
 211   }
 212 }
 213
 214 =item qsearch PARAMS_HASHREF | TABLE, HASHREF, SELECT, EXTRA_SQL, CACHE_OBJ, ADDL_FROM
 215
 216 Searches the database for all records matching (at least) the key/value pairs
 217 in HASHREF.  Returns all the records found as `FS::TABLE' objects if that
 218 module is loaded (i.e. via `use FS::cust_main;'), otherwise returns FS::Record
 219 objects.
 220
 221 The preferred usage is to pass a hash reference of named parameters:
 222
 223   @records = qsearch( {
 224                         'table'       => 'table_name',
 225                         'hashref'     => { 'field' => 'value'
 226                                            'field' => { 'op'    => '<',
 227                                                         'value' => '420',
 228                                                       },
 229                                          },
 230
 231                         #these are optional...
 232                         'select'      => '*',
 233                         'extra_sql'   => 'AND field = ? AND intfield = ?',
 234                         'extra_param' => [ 'value', [ 5, 'int' ] ],
 235                         'order_by'    => 'ORDER BY something',
 236                         #'cache_obj'   => '', #optional
 237                         'addl_from'   => 'LEFT JOIN othtable USING ( field )',
 238                         'debug'       => 1,
 239                       }
 240                     );
 241
 242 Much code still uses old-style positional parameters, this is also probably
 243 fine in the common case where there are only two parameters:
 244
 245   my @records = qsearch( 'table', { 'field' => 'value' } );
 246
 247 Also possible is an experimental LISTREF of PARAMS_HASHREFs for a UNION of
 248 the individual PARAMS_HASHREF queries
 249
 250 ###oops, argh, FS::Record::new only lets us create database fields.
 251 #Normal behaviour if SELECT is not specified is `*', as in
 252 #C<SELECT * FROM table WHERE ...>.  However, there is an experimental new
 253 #feature where you can specify SELECT - remember, the objects returned,
 254 #although blessed into the appropriate `FS::TABLE' package, will only have the
 255 #fields you specify.  This might have unwanted results if you then go calling
 256 #regular FS::TABLE methods
 257 #on it.
 258
 259 =cut
 260
 261 my %TYPE = (); #for debugging
 262
 263 sub _bind_type {
 264   my($type, $value) = @_;
 265
 266   my $bind_type = { TYPE => SQL_VARCHAR };
 267
 268   if ( $type =~ /(big)?(int|serial)/i && $value =~ /^\d+(\.\d+)?$/ ) {
 269
 270     $bind_type = { TYPE => SQL_INTEGER };
 271
 272   } elsif ( $type =~ /^bytea$/i || $type =~ /(blob|varbinary)/i ) {
 273
 274     if ( driver_name eq 'Pg' ) {
 275       no strict 'subs';
 276       $bind_type = { pg_type => PG_BYTEA };
 277     #} else {
 278     #  $bind_type = ? #SQL_VARCHAR could be fine?
 279     }
 280
 281   #DBD::Pg 1.49: Cannot bind ... unknown sql_type 6 with SQL_FLOAT
 282   #fixed by DBD::Pg 2.11.8
 283   #can change back to SQL_FLOAT in early-mid 2010, once everyone's upgraded
 284   #(make a Tron test first)
 285   } elsif ( _is_fs_float( $type, $value ) ) {
 286
 287     $bind_type = { TYPE => SQL_DECIMAL };
 288
 289   }
 290
 291   $bind_type;
 292
 293 }
 294
 295 sub _is_fs_float {
 296   my($type, $value) = @_;
 297   if ( ( $type =~ /(numeric)/i && $value =~ /^[+-]?\d+(\.\d+)?$/ ) ||
 298        ( $type =~ /(real|float4)/i && $value =~ /[-+]?\d*\.?\d+([eE][-+]?\d+)?/)
 299      ) {
 300     return 1;
 301   }
 302   '';
 303 }
 304
 305 sub qsearch {
 306   my( @stable, @record, @cache );
 307   my( @select, @extra_sql, @extra_param, @order_by, @addl_from );
 308   my @debug = ();
 309   my %union_options = ();
 310   if ( ref($_[0]) eq 'ARRAY' ) {
 311     my $optlist = shift;
 312     %union_options = @_;
 313     foreach my $href ( @$optlist ) {
 314       push @stable,      ( $href->{'table'} or die "table name is required" );
 315       push @record,      ( $href->{'hashref'}     || {} );
 316       push @select,      ( $href->{'select'}      || '*' );
 317       push @extra_sql,   ( $href->{'extra_sql'}   || '' );
 318       push @extra_param, ( $href->{'extra_param'} || [] );
 319       push @order_by,    ( $href->{'order_by'}    || '' );
 320       push @cache,       ( $href->{'cache_obj'}   || '' );
 321       push @addl_from,   ( $href->{'addl_from'}   || '' );
 322       push @debug,       ( $href->{'debug'}       || '' );
 323     }
 324     die "at least one hashref is required" unless scalar(@stable);
 325   } elsif ( ref($_[0]) eq 'HASH' ) {
 326     my $opt = shift;
 327     $stable[0]      = $opt->{'table'}       or die "table name is required";
 328     $record[0]      = $opt->{'hashref'}     || {};
 329     $select[0]      = $opt->{'select'}      || '*';
 330     $extra_sql[0]   = $opt->{'extra_sql'}   || '';
 331     $extra_param[0] = $opt->{'extra_param'} || [];
 332     $order_by[0]    = $opt->{'order_by'}    || '';
 333     $cache[0]       = $opt->{'cache_obj'}   || '';
 334     $addl_from[0]   = $opt->{'addl_from'}   || '';
 335     $debug[0]       = $opt->{'debug'}       || '';
 336   } else {
 337     ( $stable[0],
 338       $record[0],
 339       $select[0],
 340       $extra_sql[0],
 341       $cache[0],
 342       $addl_from[0]
 343     ) = @_;
 344     $select[0] ||= '*';
 345   }
 346   my $cache = $cache[0];
 347
 348   my @statement = ();
 349   my @value = ();
 350   my @bind_type = ();
 351   my $dbh = dbh;
 352   foreach my $stable ( @stable ) {
 353     #stop altering the caller's hashref
 354     my $record      = { %{ shift(@record) || {} } };#and be liberal in receipt
 355     my $select      = shift @select;
 356     my $extra_sql   = shift @extra_sql;
 357     my $extra_param = shift @extra_param;
 358     my $order_by    = shift @order_by;
 359     my $cache       = shift @cache;
 360     my $addl_from   = shift @addl_from;
 361     my $debug       = shift @debug;
 362
 363     #$stable =~ /^([\w\_]+)$/ or die "Illegal table: $table";
 364     #for jsearch
 365     $stable =~ /^([\w\s\(\)\.\,\=]+)$/ or die "Illegal table: $stable";
 366     $stable = $1;
 367
 368     my $table = $cache ? $cache->table : $stable;
 369     my $dbdef_table = dbdef->table($table)
 370       or die "No schema for table $table found - ".
 371              "do you need to run freeside-upgrade?";
 372     my $pkey = $dbdef_table->primary_key;
 373
 374     my @real_fields = grep exists($record->{$_}), real_fields($table);
 375     my @virtual_fields;
 376     if ( eval 'scalar(@FS::'. $table. '::ISA);' ) {
 377       @virtual_fields = grep exists($record->{$_}), "FS::$table"->virtual_fields;
 378     } else {
 379       cluck "warning: FS::$table not loaded; virtual fields not searchable"
 380         unless $nowarn_classload;
 381       @virtual_fields = ();
 382     }
 383
 384     my $statement .= "SELECT $select FROM $stable";
 385     $statement .= " $addl_from" if $addl_from;
 386     if ( @real_fields or @virtual_fields ) {
 387       $statement .= ' WHERE '. join(' AND ',
 388         get_real_fields($table, $record, \@real_fields) ,
 389         get_virtual_fields($table, $pkey, $record, \@virtual_fields),
 390         );
 391     }
 392
 393     $statement .= " $extra_sql" if defined($extra_sql);
 394     $statement .= " $order_by"  if defined($order_by);
 395
 396     push @statement, $statement;
 397
 398     warn "[debug]$me $statement\n" if $DEBUG > 1 || $debug;
 399
 400
 401     foreach my $field (
 402       grep defined( $record->{$_} ) && $record->{$_} ne '', @real_fields
 403     ) {
 404
 405       my $value = $record->{$field};
 406       my $op = (ref($value) && $value->{op}) ? $value->{op} : '=';
 407       $value = $value->{'value'} if ref($value);
 408       my $type = dbdef->table($table)->column($field)->type;
 409
 410       my $bind_type = _bind_type($type, $value);
 411
 412       #if ( $DEBUG > 2 ) {
 413       #  no strict 'refs';
 414       #  %TYPE = map { &{"DBI::$_"}() => $_ } @{ $DBI::EXPORT_TAGS{sql_types} }
 415       #    unless keys %TYPE;
 416       #  warn "  bind_param $bind (for field $field), $value, TYPE $TYPE{$TYPE}\n";
 417       #}
 418
 419       push @value, $value;
 420       push @bind_type, $bind_type;
 421
 422     }
 423
 424     foreach my $param ( @$extra_param ) {
 425       my $bind_type = { TYPE => SQL_VARCHAR };
 426       my $value = $param;
 427       if ( ref($param) ) {
 428         $value = $param->[0];
 429         my $type = $param->[1];
 430         $bind_type = _bind_type($type, $value);
 431       }
 432       push @value, $value;
 433       push @bind_type, $bind_type;
 434     }
 435   }
 436
 437   my $statement = join( ' ) UNION ( ', @statement );
 438   $statement = "( $statement )" if scalar(@statement) > 1;
 439   $statement .= " $union_options{order_by}" if $union_options{order_by};
 440
 441   my $sth = $dbh->prepare($statement)
 442     or croak "$dbh->errstr doing $statement";
 443
 444   my $bind = 1;
 445   foreach my $value ( @value ) {
 446     my $bind_type = shift @bind_type;
 447     $sth->bind_param($bind++, $value, $bind_type );
 448   }
 449
 450 #  $sth->execute( map $record->{$_},
 451 #    grep defined( $record->{$_} ) && $record->{$_} ne '', @fields
 452 #  ) or croak "Error executing \"$statement\": ". $sth->errstr;
 453
 454   $sth->execute or croak "Error executing \"$statement\": ". $sth->errstr;
 455
 456   # virtual fields and blessings are nonsense in a heterogeneous UNION, right?
 457   my $table = $stable[0];
 458   my $pkey = '';
 459   $table = '' if grep { $_ ne $table } @stable;
 460   $pkey = dbdef->table($table)->primary_key if $table;
 461
 462   my @virtual_fields = ();
 463   if ( eval 'scalar(@FS::'. $table. '::ISA);' ) {
 464     @virtual_fields = "FS::$table"->virtual_fields;
 465   } else {
 466     cluck "warning: FS::$table not loaded; virtual fields not returned either"
 467       unless $nowarn_classload;
 468     @virtual_fields = ();
 469   }
 470
 471   my %result;
 472   tie %result, "Tie::IxHash";
 473   my @stuff = @{ $sth->fetchall_arrayref( {} ) };
 474   if ( $pkey && scalar(@stuff) && $stuff[0]->{$pkey} ) {
 475     %result = map { $_->{$pkey}, $_ } @stuff;
 476   } else {
 477     @result{@stuff} = @stuff;
 478   }
 479
 480   $sth->finish;
 481
 482   if ( keys(%result) and @virtual_fields ) {
 483     $statement =
 484       "SELECT virtual_field.recnum, part_virtual_field.name, ".
 485              "virtual_field.value ".
 486       "FROM part_virtual_field JOIN virtual_field USING (vfieldpart) ".
 487       "WHERE part_virtual_field.dbtable = '$table' AND ".
 488       "virtual_field.recnum IN (".
 489       join(',', keys(%result)). ") AND part_virtual_field.name IN ('".
 490       join(q!', '!, @virtual_fields) . "')";
 491     warn "[debug]$me $statement\n" if $DEBUG > 1;
 492     $sth = $dbh->prepare($statement) or croak "$dbh->errstr doing $statement";
 493     $sth->execute or croak "Error executing \"$statement\": ". $sth->errstr;
 494
 495     foreach (@{ $sth->fetchall_arrayref({}) }) {
 496       my $recnum = $_->{recnum};
 497       my $name = $_->{name};
 498       my $value = $_->{value};
 499       if (exists($result{$recnum})) {
 500         $result{$recnum}->{$name} = $value;
 501       }
 502     }
 503   }
 504   my @return;
 505   if ( eval 'scalar(@FS::'. $table. '::ISA);' ) {
 506     if ( eval 'FS::'. $table. '->can(\'new\')' eq \&new ) {
 507       #derivied class didn't override new method, so this optimization is safe
 508       if ( $cache ) {
 509         @return = map {
 510           new_or_cached( "FS::$table", { %{$_} }, $cache )
 511         } values(%result);
 512       } else {
 513         @return = map {
 514           new( "FS::$table", { %{$_} } )
 515         } values(%result);
 516       }
 517     } else {
 518       #okay, its been tested
 519       # warn "untested code (class FS::$table uses custom new method)";
 520       @return = map {
 521         eval 'FS::'. $table. '->new( { %{$_} } )';
 522       } values(%result);
 523     }
 524
 525     # Check for encrypted fields and decrypt them.
 526    ## only in the local copy, not the cached object
 527     if ( $conf_encryption
 528          && eval 'defined(@FS::'. $table . '::encrypted_fields)' ) {
 529       foreach my $record (@return) {
 530         foreach my $field (eval '@FS::'. $table . '::encrypted_fields') {
 531           # Set it directly... This may cause a problem in the future...
 532           $record->setfield($field, $record->decrypt($record->getfield($field)));
 533         }
 534       }
 535     }
 536   } else {
 537     cluck "warning: FS::$table not loaded; returning FS::Record objects"
 538       unless $nowarn_classload;
 539     @return = map {
 540       FS::Record->new( $table, { %{$_} } );
 541     } values(%result);
 542   }
 543   return @return;
 544 }
 545
 546 ## makes this easier to read
 547
 548 sub get_virtual_fields {
 549    my $table = shift;
 550    my $pkey = shift;
 551    my $record = shift;
 552    my $virtual_fields = shift;
 553
 554    return
 555     ( map {
 556       my $op = '=';
 557       my $column = $_;
 558       if ( ref($record->{$_}) ) {
 559         $op = $record->{$_}{'op'} if $record->{$_}{'op'};
 560         if ( uc($op) eq 'ILIKE' ) {
 561           $op = 'LIKE';
 562           $record->{$_}{'value'} = lc($record->{$_}{'value'});
 563           $column = "LOWER($_)";
 564         }
 565         $record->{$_} = $record->{$_}{'value'};
 566       }
 567
 568       # ... EXISTS ( SELECT name, value FROM part_virtual_field
 569       #              JOIN virtual_field
 570       #              ON part_virtual_field.vfieldpart = virtual_field.vfieldpart
 571       #              WHERE recnum = svc_acct.svcnum
 572       #              AND (name, value) = ('egad', 'brain') )
 573
 574       my $value = $record->{$_};
 575
 576       my $subq;
 577
 578       $subq = ($value ? 'EXISTS ' : 'NOT EXISTS ') .
 579       "( SELECT part_virtual_field.name, virtual_field.value ".
 580       "FROM part_virtual_field JOIN virtual_field ".
 581       "ON part_virtual_field.vfieldpart = virtual_field.vfieldpart ".
 582       "WHERE virtual_field.recnum = ${table}.${pkey} ".
 583       "AND part_virtual_field.name = '${column}'".
 584       ($value ?
 585         " AND virtual_field.value ${op} '${value}'"
 586       : "") . ")";
 587       $subq;
 588
 589     } @{ $virtual_fields } ) ;
 590 }
 591
 592 sub get_real_fields {
 593   my $table = shift;
 594   my $record = shift;
 595   my $real_fields = shift;
 596
 597    ## this huge map was previously inline, just broke it out to help read the qsearch method, should be optimized for readability
 598       return (
 599       map {
 600
 601       my $op = '=';
 602       my $column = $_;
 603       my $type = dbdef->table($table)->column($column)->type;
 604       my $value = $record->{$column};
 605       $value = $value->{'value'} if ref($value);
 606       if ( ref($record->{$_}) ) {
 607         $op = $record->{$_}{'op'} if $record->{$_}{'op'};
 608         #$op = 'LIKE' if $op =~ /^ILIKE$/i && driver_name ne 'Pg';
 609         if ( uc($op) eq 'ILIKE' ) {
 610           $op = 'LIKE';
 611           $record->{$_}{'value'} = lc($record->{$_}{'value'});
 612           $column = "LOWER($_)";
 613         }
 614         $record->{$_} = $record->{$_}{'value'}
 615       }
 616
 617       if ( ! defined( $record->{$_} ) || $record->{$_} eq '' ) {
 618         if ( $op eq '=' ) {
 619           if ( driver_name eq 'Pg' ) {
 620             if ( $type =~ /(int|numeric|real|float4|(big)?serial)/i ) {
 621               qq-( $column IS NULL )-;
 622             } else {
 623               qq-( $column IS NULL OR $column = '' )-;
 624             }
 625           } else {
 626             qq-( $column IS NULL OR $column = "" )-;
 627           }
 628         } elsif ( $op eq '!=' ) {
 629           if ( driver_name eq 'Pg' ) {
 630             if ( $type =~ /(int|numeric|real|float4|(big)?serial)/i ) {
 631               qq-( $column IS NOT NULL )-;
 632             } else {
 633               qq-( $column IS NOT NULL AND $column != '' )-;
 634             }
 635           } else {
 636             qq-( $column IS NOT NULL AND $column != "" )-;
 637           }
 638         } else {
 639           if ( driver_name eq 'Pg' ) {
 640             qq-( $column $op '' )-;
 641           } else {
 642             qq-( $column $op "" )-;
 643           }
 644         }
 645       #if this needs to be re-enabled, it needs to use a custom op like
 646       #"APPROX=" or something (better name?, not '=', to avoid affecting other
 647       # searches
 648       #} elsif ( $op eq 'APPROX=' && _is_fs_float( $type, $value ) ) {
 649       #  ( "$column <= ?", "$column >= ?" );
 650       } else {
 651         "$column $op ?";
 652       }
 653     } @{ $real_fields } );
 654 }
 655
 656 =item by_key PRIMARY_KEY_VALUE
 657
 658 This is a class method that returns the record with the given primary key
 659 value.  This method is only useful in FS::Record subclasses.  For example:
 660
 661   my $cust_main = FS::cust_main->by_key(1); # retrieve customer with custnum 1
 662
 663 is equivalent to:
 664
 665   my $cust_main = qsearchs('cust_main', { 'custnum' => 1 } );
 666
 667 =cut
 668
 669 sub by_key {
 670   my ($class, $pkey_value) = @_;
 671
 672   my $table = $class->table
 673     or croak "No table for $class found";
 674
 675   my $dbdef_table = dbdef->table($table)
 676     or die "No schema for table $table found - ".
 677            "do you need to create it or run dbdef-create?";
 678   my $pkey = $dbdef_table->primary_key
 679     or die "No primary key for table $table";
 680
 681   return qsearchs($table, { $pkey => $pkey_value });
 682 }
 683
 684 =item jsearch TABLE, HASHREF, SELECT, EXTRA_SQL, PRIMARY_TABLE, PRIMARY_KEY
 685
 686 Experimental JOINed search method.  Using this method, you can execute a
 687 single SELECT spanning multiple tables, and cache the results for subsequent
 688 method calls.  Interface will almost definately change in an incompatible
 689 fashion.
 690
 691 Arguments:
 692
 693 =cut
 694
 695 sub jsearch {
 696   my($table, $record, $select, $extra_sql, $ptable, $pkey ) = @_;
 697   my $cache = FS::SearchCache->new( $ptable, $pkey );
 698   my %saw;
 699   ( $cache,
 700     grep { !$saw{$_->getfield($pkey)}++ }
 701       qsearch($table, $record, $select, $extra_sql, $cache )
 702   );
 703 }
 704
 705 =item qsearchs PARAMS_HASHREF | TABLE, HASHREF, SELECT, EXTRA_SQL, CACHE_OBJ, ADDL_FROM
 706
 707 Same as qsearch, except that if more than one record matches, it B<carp>s but
 708 returns the first.  If this happens, you either made a logic error in asking
 709 for a single item, or your data is corrupted.
 710
 711 =cut
 712
 713 sub qsearchs { # $result_record = &FS::Record:qsearchs('table',\%hash);
 714   my $table = $_[0];
 715   my(@result) = qsearch(@_);
 716   cluck "warning: Multiple records in scalar search ($table)"
 717     if scalar(@result) > 1;
 718   #should warn more vehemently if the search was on a primary key?
 719   scalar(@result) ? ($result[0]) : ();
 720 }
 721
 722 =back
 723
 724 =head1 METHODS
 725
 726 =over 4
 727
 728 =item table
 729
 730 Returns the table name.
 731
 732 =cut
 733
 734 sub table {
 735 #  cluck "warning: FS::Record::table deprecated; supply one in subclass!";
 736   my $self = shift;
 737   $self -> {'Table'};
 738 }
 739
 740 =item dbdef_table
 741
 742 Returns the DBIx::DBSchema::Table object for the table.
 743
 744 =cut
 745
 746 sub dbdef_table {
 747   my($self)=@_;
 748   my($table)=$self->table;
 749   dbdef->table($table);
 750 }
 751
 752 =item primary_key
 753
 754 Returns the primary key for the table.
 755
 756 =cut
 757
 758 sub primary_key {
 759   my $self = shift;
 760   my $pkey = $self->dbdef_table->primary_key;
 761 }
 762
 763 =item get, getfield COLUMN
 764
 765 Returns the value of the column/field/key COLUMN.
 766
 767 =cut
 768
 769 sub get {
 770   my($self,$field) = @_;
 771   # to avoid "Use of unitialized value" errors
 772   if ( defined ( $self->{Hash}->{$field} ) ) {
 773     $self->{Hash}->{$field};
 774   } else {
 775     '';
 776   }
 777 }
 778 sub getfield {
 779   my $self = shift;
 780   $self->get(@_);
 781 }
 782
 783 =item set, setfield COLUMN, VALUE
 784
 785 Sets the value of the column/field/key COLUMN to VALUE.  Returns VALUE.
 786
 787 =cut
 788
 789 sub set {
 790   my($self,$field,$value) = @_;
 791   $self->{'modified'} = 1;
 792   $self->{'Hash'}->{$field} = $value;
 793 }
 794 sub setfield {
 795   my $self = shift;
 796   $self->set(@_);
 797 }
 798
 799 =item exists COLUMN
 800
 801 Returns true if the column/field/key COLUMN exists.
 802
 803 =cut
 804
 805 sub exists {
 806   my($self,$field) = @_;
 807   exists($self->{Hash}->{$field});
 808 }
 809
 810 =item AUTLOADED METHODS
 811
 812 $record->column is a synonym for $record->get('column');
 813
 814 $record->column('value') is a synonym for $record->set('column','value');
 815
 816 =cut
 817
 818 # readable/safe
 819 sub AUTOLOAD {
 820   my($self,$value)=@_;
 821   my($field)=$AUTOLOAD;
 822   $field =~ s/.*://;
 823   if ( defined($value) ) {
 824     confess "errant AUTOLOAD $field for $self (arg $value)"
 825       unless blessed($self) && $self->can('setfield');
 826     $self->setfield($field,$value);
 827   } else {
 828     confess "errant AUTOLOAD $field for $self (no args)"
 829       unless blessed($self) && $self->can('getfield');
 830     $self->getfield($field);
 831   }
 832 }
 833
 834 # efficient
 835 #sub AUTOLOAD {
 836 #  my $field = $AUTOLOAD;
 837 #  $field =~ s/.*://;
 838 #  if ( defined($_[1]) ) {
 839 #    $_[0]->setfield($field, $_[1]);
 840 #  } else {
 841 #    $_[0]->getfield($field);
 842 #  }
 843 #}
 844
 845 =item hash
 846
 847 Returns a list of the column/value pairs, usually for assigning to a new hash.
 848
 849 To make a distinct duplicate of an FS::Record object, you can do:
 850
 851     $new = new FS::Record ( $old->table, { $old->hash } );
 852
 853 =cut
 854
 855 sub hash {
 856   my($self) = @_;
 857   confess $self. ' -> hash: Hash attribute is undefined'
 858     unless defined($self->{'Hash'});
 859   %{ $self->{'Hash'} };
 860 }
 861
 862 =item hashref
 863
 864 Returns a reference to the column/value hash.  This may be deprecated in the
 865 future; if there's a reason you can't just use the autoloaded or get/set
 866 methods, speak up.
 867
 868 =cut
 869
 870 sub hashref {
 871   my($self) = @_;
 872   $self->{'Hash'};
 873 }
 874
 875 =item modified
 876
 877 Returns true if any of this object's values have been modified with set (or via
 878 an autoloaded method).  Doesn't yet recognize when you retreive a hashref and
 879 modify that.
 880
 881 =cut
 882
 883 sub modified {
 884   my $self = shift;
 885   $self->{'modified'};
 886 }
 887
 888 =item select_for_update
 889
 890 Selects this record with the SQL "FOR UPDATE" command.  This can be useful as
 891 a mutex.
 892
 893 =cut
 894
 895 sub select_for_update {
 896   my $self = shift;
 897   my $primary_key = $self->primary_key;
 898   qsearchs( {
 899     'select'    => '*',
 900     'table'     => $self->table,
 901     'hashref'   => { $primary_key => $self->$primary_key() },
 902     'extra_sql' => 'FOR UPDATE',
 903   } );
 904 }
 905
 906 =item lock_table
 907
 908 Locks this table with a database-driver specific lock method.  This is used
 909 as a mutex in order to do a duplicate search.
 910
 911 For PostgreSQL, does "LOCK TABLE tablename IN SHARE ROW EXCLUSIVE MODE".
 912
 913 For MySQL, does a SELECT FOR UPDATE on the duplicate_lock table.
 914
 915 Errors are fatal; no useful return value.
 916
 917 Note: To use this method for new tables other than svc_acct and svc_phone,
 918 edit freeside-upgrade and add those tables to the duplicate_lock list.
 919
 920 =cut
 921
 922 sub lock_table {
 923   my $self = shift;
 924   my $table = $self->table;
 925
 926   warn "$me locking $table table\n" if $DEBUG;
 927
 928   if ( driver_name =~ /^Pg/i ) {
 929
 930     dbh->do("LOCK TABLE $table IN SHARE ROW EXCLUSIVE MODE")
 931       or die dbh->errstr;
 932
 933   } elsif ( driver_name =~ /^mysql/i ) {
 934
 935     dbh->do("SELECT * FROM duplicate_lock
 936                WHERE lockname = '$table'
 937                FOR UPDATE"
 938            ) or die dbh->errstr;
 939
 940   } else {
 941
 942     die "unknown database ". driver_name. "; don't know how to lock table";
 943
 944   }
 945
 946   warn "$me acquired $table table lock\n" if $DEBUG;
 947
 948 }
 949
 950 =item insert
 951
 952 Inserts this record to the database.  If there is an error, returns the error,
 953 otherwise returns false.
 954
 955 =cut
 956
 957 sub insert {
 958   my $self = shift;
 959   my $saved = {};
 960
 961   warn "$self -> insert" if $DEBUG;
 962
 963   my $error = $self->check;
 964   return $error if $error;
 965
 966   #single-field unique keys are given a value if false
 967   #(like MySQL's AUTO_INCREMENT or Pg SERIAL)
 968   foreach ( $self->dbdef_table->unique_singles) {
 969     $self->unique($_) unless $self->getfield($_);
 970   }
 971
 972   #and also the primary key, if the database isn't going to
 973   my $primary_key = $self->dbdef_table->primary_key;
 974   my $db_seq = 0;
 975   if ( $primary_key ) {
 976     my $col = $self->dbdef_table->column($primary_key);
 977
 978     $db_seq =
 979       uc($col->type) =~ /^(BIG)?SERIAL\d?/
 980       || ( driver_name eq 'Pg'
 981              && defined($col->default)
 982              && $col->quoted_default =~ /^nextval\(/i
 983          )
 984       || ( driver_name eq 'mysql'
 985              && defined($col->local)
 986              && $col->local =~ /AUTO_INCREMENT/i
 987          );
 988     $self->unique($primary_key) unless $self->getfield($primary_key) || $db_seq;
 989   }
 990
 991   my $table = $self->table;
 992
 993   # Encrypt before the database
 994   if (    defined(eval '@FS::'. $table . '::encrypted_fields')
 995        && scalar( eval '@FS::'. $table . '::encrypted_fields')
 996        && $conf->exists('encryption')
 997   ) {
 998     foreach my $field (eval '@FS::'. $table . '::encrypted_fields') {
 999       $self->{'saved'} = $self->getfield($field);
1000       $self->setfield($field, $self->encrypt($self->getfield($field)));
1001     }
1002   }
1003
1004   #false laziness w/delete
1005   my @real_fields =
1006     grep { defined($self->getfield($_)) && $self->getfield($_) ne "" }
1007     real_fields($table)
1008   ;
1009   my @values = map { _quote( $self->getfield($_), $table, $_) } @real_fields;
1010   #eslaf
1011
1012   my $statement = "INSERT INTO $table ";
1013   if ( @real_fields ) {
1014     $statement .=
1015       "( ".
1016         join( ', ', @real_fields ).
1017       ") VALUES (".
1018         join( ', ', @values ).
1019        ")"
1020     ;
1021   } else {
1022     $statement .= 'DEFAULT VALUES';
1023   }
1024   warn "[debug]$me $statement\n" if $DEBUG > 1;
1025   my $sth = dbh->prepare($statement) or return dbh->errstr;
1026
1027   local $SIG{HUP} = 'IGNORE';
1028   local $SIG{INT} = 'IGNORE';
1029   local $SIG{QUIT} = 'IGNORE';
1030   local $SIG{TERM} = 'IGNORE';
1031   local $SIG{TSTP} = 'IGNORE';
1032   local $SIG{PIPE} = 'IGNORE';
1033
1034   $sth->execute or return $sth->errstr;
1035
1036   # get inserted id from the database, if applicable & needed
1037   if ( $db_seq && ! $self->getfield($primary_key) ) {
1038     warn "[debug]$me retreiving sequence from database\n" if $DEBUG;
1039
1040     my $insertid = '';
1041
1042     if ( driver_name eq 'Pg' ) {
1043
1044       #my $oid = $sth->{'pg_oid_status'};
1045       #my $i_sql = "SELECT $primary_key FROM $table WHERE oid = ?";
1046
1047       my $default = $self->dbdef_table->column($primary_key)->quoted_default;
1048       unless ( $default =~ /^nextval\(\(?'"?([\w\.]+)"?'/i ) {
1049         dbh->rollback if $FS::UID::AutoCommit;
1050         return "can't parse $table.$primary_key default value".
1051                " for sequence name: $default";
1052       }
1053       my $sequence = $1;
1054
1055       my $i_sql = "SELECT currval('$sequence')";
1056       my $i_sth = dbh->prepare($i_sql) or do {
1057         dbh->rollback if $FS::UID::AutoCommit;
1058         return dbh->errstr;
1059       };
1060       $i_sth->execute() or do { #$i_sth->execute($oid)
1061         dbh->rollback if $FS::UID::AutoCommit;
1062         return $i_sth->errstr;
1063       };
1064       $insertid = $i_sth->fetchrow_arrayref->[0];
1065
1066     } elsif ( driver_name eq 'mysql' ) {
1067
1068       $insertid = dbh->{'mysql_insertid'};
1069       # work around mysql_insertid being null some of the time, ala RT :/
1070       unless ( $insertid ) {
1071         warn "WARNING: DBD::mysql didn't return mysql_insertid; ".
1072              "using SELECT LAST_INSERT_ID();";
1073         my $i_sql = "SELECT LAST_INSERT_ID()";
1074         my $i_sth = dbh->prepare($i_sql) or do {
1075           dbh->rollback if $FS::UID::AutoCommit;
1076           return dbh->errstr;
1077         };
1078         $i_sth->execute or do {
1079           dbh->rollback if $FS::UID::AutoCommit;
1080           return $i_sth->errstr;
1081         };
1082         $insertid = $i_sth->fetchrow_arrayref->[0];
1083       }
1084
1085     } else {
1086
1087       dbh->rollback if $FS::UID::AutoCommit;
1088       return "don't know how to retreive inserted ids from ". driver_name.
1089              ", try using counterfiles (maybe run dbdef-create?)";
1090
1091     }
1092
1093     $self->setfield($primary_key, $insertid);
1094
1095   }
1096
1097   my @virtual_fields =
1098       grep defined($self->getfield($_)) && $self->getfield($_) ne "",
1099           $self->virtual_fields;
1100   if (@virtual_fields) {
1101     my %v_values = map { $_, $self->getfield($_) } @virtual_fields;
1102
1103     my $vfieldpart = $self->vfieldpart_hashref;
1104
1105     my $v_statement = "INSERT INTO virtual_field(recnum, vfieldpart, value) ".
1106                     "VALUES (?, ?, ?)";
1107
1108     my $v_sth = dbh->prepare($v_statement) or do {
1109       dbh->rollback if $FS::UID::AutoCommit;
1110       return dbh->errstr;
1111     };
1112
1113     foreach (keys(%v_values)) {
1114       $v_sth->execute($self->getfield($primary_key),
1115                       $vfieldpart->{$_},
1116                       $v_values{$_})
1117       or do {
1118         dbh->rollback if $FS::UID::AutoCommit;
1119         return $v_sth->errstr;
1120       };
1121     }
1122   }
1123
1124
1125   my $h_sth;
1126   if ( defined dbdef->table('h_'. $table) ) {
1127     my $h_statement = $self->_h_statement('insert');
1128     warn "[debug]$me $h_statement\n" if $DEBUG > 2;
1129     $h_sth = dbh->prepare($h_statement) or do {
1130       dbh->rollback if $FS::UID::AutoCommit;
1131       return dbh->errstr;
1132     };
1133   } else {
1134     $h_sth = '';
1135   }
1136   $h_sth->execute or return $h_sth->errstr if $h_sth;
1137
1138   dbh->commit or croak dbh->errstr if $FS::UID::AutoCommit;
1139
1140   # Now that it has been saved, reset the encrypted fields so that $new
1141   # can still be used.
1142   foreach my $field (keys %{$saved}) {
1143     $self->setfield($field, $saved->{$field});
1144   }
1145
1146   '';
1147 }
1148
1149 =item add
1150
1151 Depriciated (use insert instead).
1152
1153 =cut
1154
1155 sub add {
1156   cluck "warning: FS::Record::add deprecated!";
1157   insert @_; #call method in this scope
1158 }
1159
1160 =item delete
1161
1162 Delete this record from the database.  If there is an error, returns the error,
1163 otherwise returns false.
1164
1165 =cut
1166
1167 sub delete {
1168   my $self = shift;
1169
1170   my $statement = "DELETE FROM ". $self->table. " WHERE ". join(' AND ',
1171     map {
1172       $self->getfield($_) eq ''
1173         #? "( $_ IS NULL OR $_ = \"\" )"
1174         ? ( driver_name eq 'Pg'
1175               ? "$_ IS NULL"
1176               : "( $_ IS NULL OR $_ = \"\" )"
1177           )
1178         : "$_ = ". _quote($self->getfield($_),$self->table,$_)
1179     } ( $self->dbdef_table->primary_key )
1180           ? ( $self->dbdef_table->primary_key)
1181           : real_fields($self->table)
1182   );
1183   warn "[debug]$me $statement\n" if $DEBUG > 1;
1184   my $sth = dbh->prepare($statement) or return dbh->errstr;
1185
1186   my $h_sth;
1187   if ( defined dbdef->table('h_'. $self->table) ) {
1188     my $h_statement = $self->_h_statement('delete');
1189     warn "[debug]$me $h_statement\n" if $DEBUG > 2;
1190     $h_sth = dbh->prepare($h_statement) or return dbh->errstr;
1191   } else {
1192     $h_sth = '';
1193   }
1194
1195   my $primary_key = $self->dbdef_table->primary_key;
1196   my $v_sth;
1197   my @del_vfields;
1198   my $vfp = $self->vfieldpart_hashref;
1199   foreach($self->virtual_fields) {
1200     next if $self->getfield($_) eq '';
1201     unless(@del_vfields) {
1202       my $st = "DELETE FROM virtual_field WHERE recnum = ? AND vfieldpart = ?";
1203       $v_sth = dbh->prepare($st) or return dbh->errstr;
1204     }
1205     push @del_vfields, $_;
1206   }
1207
1208   local $SIG{HUP} = 'IGNORE';
1209   local $SIG{INT} = 'IGNORE';
1210   local $SIG{QUIT} = 'IGNORE';
1211   local $SIG{TERM} = 'IGNORE';
1212   local $SIG{TSTP} = 'IGNORE';
1213   local $SIG{PIPE} = 'IGNORE';
1214
1215   my $rc = $sth->execute or return $sth->errstr;
1216   #not portable #return "Record not found, statement:\n$statement" if $rc eq "0E0";
1217   $h_sth->execute or return $h_sth->errstr if $h_sth;
1218   $v_sth->execute($self->getfield($primary_key), $vfp->{$_})
1219     or return $v_sth->errstr
1220         foreach (@del_vfields);
1221
1222   dbh->commit or croak dbh->errstr if $FS::UID::AutoCommit;
1223
1224   #no need to needlessly destoy the data either (causes problems actually)
1225   #undef $self; #no need to keep object!
1226
1227   '';
1228 }
1229
1230 =item del
1231
1232 Depriciated (use delete instead).
1233
1234 =cut
1235
1236 sub del {
1237   cluck "warning: FS::Record::del deprecated!";
1238   &delete(@_); #call method in this scope
1239 }
1240
1241 =item replace OLD_RECORD
1242
1243 Replace the OLD_RECORD with this one in the database.  If there is an error,
1244 returns the error, otherwise returns false.
1245
1246 =cut
1247
1248 sub replace {
1249   my ($new, $old) = (shift, shift);
1250
1251   $old = $new->replace_old unless defined($old);
1252
1253   warn "[debug]$me $new ->replace $old\n" if $DEBUG;
1254
1255   if ( $new->can('replace_check') ) {
1256     my $error = $new->replace_check($old);
1257     return $error if $error;
1258   }
1259
1260   return "Records not in same table!" unless $new->table eq $old->table;
1261
1262   my $primary_key = $old->dbdef_table->primary_key;
1263   return "Can't change primary key $primary_key ".
1264          'from '. $old->getfield($primary_key).
1265          ' to ' . $new->getfield($primary_key)
1266     if $primary_key
1267        && ( $old->getfield($primary_key) ne $new->getfield($primary_key) );
1268
1269   my $error = $new->check;
1270   return $error if $error;
1271
1272   # Encrypt for replace
1273   my $saved = {};
1274   if (    $conf->exists('encryption')
1275        && defined(eval '@FS::'. $new->table . '::encrypted_fields')
1276        && scalar( eval '@FS::'. $new->table . '::encrypted_fields')
1277   ) {
1278     foreach my $field (eval '@FS::'. $new->table . '::encrypted_fields') {
1279       $saved->{$field} = $new->getfield($field);
1280       $new->setfield($field, $new->encrypt($new->getfield($field)));
1281     }
1282   }
1283
1284   #my @diff = grep $new->getfield($_) ne $old->getfield($_), $old->fields;
1285   my %diff = map { ($new->getfield($_) ne $old->getfield($_))
1286                    ? ($_, $new->getfield($_)) : () } $old->fields;
1287
1288   unless (keys(%diff) || $no_update_diff ) {
1289     carp "[warning]$me $new -> replace $old: records identical"
1290       unless $nowarn_identical;
1291     return '';
1292   }
1293
1294   my $statement = "UPDATE ". $old->table. " SET ". join(', ',
1295     map {
1296       "$_ = ". _quote($new->getfield($_),$old->table,$_)
1297     } real_fields($old->table)
1298   ). ' WHERE '.
1299     join(' AND ',
1300       map {
1301
1302         if ( $old->getfield($_) eq '' ) {
1303
1304          #false laziness w/qsearch
1305          if ( driver_name eq 'Pg' ) {
1306             my $type = $old->dbdef_table->column($_)->type;
1307             if ( $type =~ /(int|(big)?serial)/i ) {
1308               qq-( $_ IS NULL )-;
1309             } else {
1310               qq-( $_ IS NULL OR $_ = '' )-;
1311             }
1312           } else {
1313             qq-( $_ IS NULL OR $_ = "" )-;
1314           }
1315
1316         } else {
1317           "$_ = ". _quote($old->getfield($_),$old->table,$_);
1318         }
1319
1320       } ( $primary_key ? ( $primary_key ) : real_fields($old->table) )
1321     )
1322   ;
1323   warn "[debug]$me $statement\n" if $DEBUG > 1;
1324   my $sth = dbh->prepare($statement) or return dbh->errstr;
1325
1326   my $h_old_sth;
1327   if ( defined dbdef->table('h_'. $old->table) ) {
1328     my $h_old_statement = $old->_h_statement('replace_old');
1329     warn "[debug]$me $h_old_statement\n" if $DEBUG > 2;
1330     $h_old_sth = dbh->prepare($h_old_statement) or return dbh->errstr;
1331   } else {
1332     $h_old_sth = '';
1333   }
1334
1335   my $h_new_sth;
1336   if ( defined dbdef->table('h_'. $new->table) ) {
1337     my $h_new_statement = $new->_h_statement('replace_new');
1338     warn "[debug]$me $h_new_statement\n" if $DEBUG > 2;
1339     $h_new_sth = dbh->prepare($h_new_statement) or return dbh->errstr;
1340   } else {
1341     $h_new_sth = '';
1342   }
1343
1344   # For virtual fields we have three cases with different SQL
1345   # statements: add, replace, delete
1346   my $v_add_sth;
1347   my $v_rep_sth;
1348   my $v_del_sth;
1349   my (@add_vfields, @rep_vfields, @del_vfields);
1350   my $vfp = $old->vfieldpart_hashref;
1351   foreach(grep { exists($diff{$_}) } $new->virtual_fields) {
1352     if($diff{$_} eq '') {
1353       # Delete
1354       unless(@del_vfields) {
1355         my $st = "DELETE FROM virtual_field WHERE recnum = ? ".
1356                  "AND vfieldpart = ?";
1357         warn "[debug]$me $st\n" if $DEBUG > 2;
1358         $v_del_sth = dbh->prepare($st) or return dbh->errstr;
1359       }
1360       push @del_vfields, $_;
1361     } elsif($old->getfield($_) eq '') {
1362       # Add
1363       unless(@add_vfields) {
1364         my $st = "INSERT INTO virtual_field (value, recnum, vfieldpart) ".
1365                  "VALUES (?, ?, ?)";
1366         warn "[debug]$me $st\n" if $DEBUG > 2;
1367         $v_add_sth = dbh->prepare($st) or return dbh->errstr;
1368       }
1369       push @add_vfields, $_;
1370     } else {
1371       # Replace
1372       unless(@rep_vfields) {
1373         my $st = "UPDATE virtual_field SET value = ? ".
1374                  "WHERE recnum = ? AND vfieldpart = ?";
1375         warn "[debug]$me $st\n" if $DEBUG > 2;
1376         $v_rep_sth = dbh->prepare($st) or return dbh->errstr;
1377       }
1378       push @rep_vfields, $_;
1379     }
1380   }
1381
1382   local $SIG{HUP} = 'IGNORE';
1383   local $SIG{INT} = 'IGNORE';
1384   local $SIG{QUIT} = 'IGNORE';
1385   local $SIG{TERM} = 'IGNORE';
1386   local $SIG{TSTP} = 'IGNORE';
1387   local $SIG{PIPE} = 'IGNORE';
1388
1389   my $rc = $sth->execute or return $sth->errstr;
1390   #not portable #return "Record not found (or records identical)." if $rc eq "0E0";
1391   $h_old_sth->execute or return $h_old_sth->errstr if $h_old_sth;
1392   $h_new_sth->execute or return $h_new_sth->errstr if $h_new_sth;
1393
1394   $v_del_sth->execute($old->getfield($primary_key),
1395                       $vfp->{$_})
1396         or return $v_del_sth->errstr
1397       foreach(@del_vfields);
1398
1399   $v_add_sth->execute($new->getfield($_),
1400                       $old->getfield($primary_key),
1401                       $vfp->{$_})
1402         or return $v_add_sth->errstr
1403       foreach(@add_vfields);
1404
1405   $v_rep_sth->execute($new->getfield($_),
1406                       $old->getfield($primary_key),
1407                       $vfp->{$_})
1408         or return $v_rep_sth->errstr
1409       foreach(@rep_vfields);
1410
1411   dbh->commit or croak dbh->errstr if $FS::UID::AutoCommit;
1412
1413   # Now that it has been saved, reset the encrypted fields so that $new
1414   # can still be used.
1415   foreach my $field (keys %{$saved}) {
1416     $new->setfield($field, $saved->{$field});
1417   }
1418
1419   '';
1420
1421 }
1422
1423 sub replace_old {
1424   my( $self ) = shift;
1425   warn "[$me] replace called with no arguments; autoloading old record\n"
1426     if $DEBUG;
1427
1428   my $primary_key = $self->dbdef_table->primary_key;
1429   if ( $primary_key ) {
1430     $self->by_key( $self->$primary_key() ) #this is what's returned
1431       or croak "can't find ". $self->table. ".$primary_key ".
1432         $self->$primary_key();
1433   } else {
1434     croak $self->table. " has no primary key; pass old record as argument";
1435   }
1436
1437 }
1438
1439 =item rep
1440
1441 Depriciated (use replace instead).
1442
1443 =cut
1444
1445 sub rep {
1446   cluck "warning: FS::Record::rep deprecated!";
1447   replace @_; #call method in this scope
1448 }
1449
1450 =item check
1451
1452 Checks virtual fields (using check_blocks).  Subclasses should still provide
1453 a check method to validate real fields, foreign keys, etc., and call this
1454 method via $self->SUPER::check.
1455
1456 (FIXME: Should this method try to make sure that it I<is> being called from
1457 a subclass's check method, to keep the current semantics as far as possible?)
1458
1459 =cut
1460
1461 sub check {
1462   #confess "FS::Record::check not implemented; supply one in subclass!";
1463   my $self = shift;
1464
1465   foreach my $field ($self->virtual_fields) {
1466     for ($self->getfield($field)) {
1467       # See notes on check_block in FS::part_virtual_field.
1468       eval $self->pvf($field)->check_block;
1469       if ( $@ ) {
1470         #this is bad, probably want to follow the stack backtrace up and see
1471         #wtf happened
1472         my $err = "Fatal error checking $field for $self";
1473         cluck "$err: $@";
1474         return "$err (see log for backtrace): $@";
1475
1476       }
1477       $self->setfield($field, $_);
1478     }
1479   }
1480   '';
1481 }
1482
1483 =item process_batch_import JOB OPTIONS_HASHREF PARAMS
1484
1485 Processes a batch import as a queued JSRPC job
1486
1487 JOB is an FS::queue entry.
1488
1489 OPTIONS_HASHREF can have the following keys:
1490
1491 =over 4
1492
1493 =item table
1494
1495 Table name (required).
1496
1497 =item params
1498
1499 Listref of field names for static fields.  They will be given values from the
1500 PARAMS hashref and passed as a "params" hashref to batch_import.
1501
1502 =item formats
1503
1504 Formats hashref.  Keys are field names, values are listrefs that define the
1505 format.
1506
1507 Each listref value can be a column name or a code reference.  Coderefs are run
1508 with the row object, data and a FS::Conf object as the three parameters.
1509 For example, this coderef does the same thing as using the "columnname" string:
1510
1511   sub {
1512     my( $record, $data, $conf ) = @_;
1513     $record->columnname( $data );
1514   },
1515
1516 Coderefs are run after all "column name" fields are assigned.
1517
1518 =item format_types
1519
1520 Optional format hashref of types.  Keys are field names, values are "csv",
1521 "xls" or "fixedlength".  Overrides automatic determination of file type
1522 from extension.
1523
1524 =item format_headers
1525
1526 Optional format hashref of header lines.  Keys are field names, values are 0
1527 for no header, 1 to ignore the first line, or to higher numbers to ignore that
1528 number of lines.
1529
1530 =item format_sep_chars
1531
1532 Optional format hashref of CSV sep_chars.  Keys are field names, values are the
1533 CSV separation character.
1534
1535 =item format_fixedlenth_formats
1536
1537 Optional format hashref of fixed length format defintiions.  Keys are field
1538 names, values Parse::FixedLength listrefs of field definitions.
1539
1540 =item default_csv
1541
1542 Set true to default to CSV file type if the filename does not contain a
1543 recognizable ".csv" or ".xls" extension (and type is not pre-specified by
1544 format_types).
1545
1546 =back
1547
1548 PARAMS is a base64-encoded Storable string containing the POSTed data as
1549 a hash ref.  It normally contains at least one field, "uploaded files",
1550 generated by /elements/file-upload.html and containing the list of uploaded
1551 files.  Currently only supports a single file named "file".
1552
1553 =cut
1554
1555 use Storable qw(thaw);
1556 use Data::Dumper;
1557 use MIME::Base64;
1558 sub process_batch_import {
1559   my($job, $opt) = ( shift, shift );
1560
1561   my $table = $opt->{table};
1562   my @pass_params = $opt->{params} ? @{ $opt->{params} } : ();
1563   my %formats = %{ $opt->{formats} };
1564
1565   my $param = thaw(decode_base64(shift));
1566   warn Dumper($param) if $DEBUG;
1567
1568   my $files = $param->{'uploaded_files'}
1569     or die "No files provided.\n";
1570
1571   my (%files) = map { /^(\w+):([\.\w]+)$/ ? ($1,$2):() } split /,/, $files;
1572
1573   my $dir = '%%%FREESIDE_CACHE%%%/cache.'. $FS::UID::datasrc. '/';
1574   my $file = $dir. $files{'file'};
1575
1576   my %iopt = (
1577     #class-static
1578     table                      => $table,
1579     formats                    => \%formats,
1580     format_types               => $opt->{format_types},
1581     format_headers             => $opt->{format_headers},
1582     format_sep_chars           => $opt->{format_sep_chars},
1583     format_fixedlength_formats => $opt->{format_fixedlength_formats},
1584     format_xml_formats         => $opt->{format_xml_formats},
1585     format_row_callbacks       => $opt->{format_row_callbacks},
1586     #per-import
1587     job                        => $job,
1588     file                       => $file,
1589     #type                       => $type,
1590     format                     => $param->{format},
1591     params                     => { map { $_ => $param->{$_} } @pass_params },
1592     #?
1593     default_csv                => $opt->{default_csv},
1594   );
1595
1596   if ( $opt->{'batch_namecol'} ) {
1597     $iopt{'batch_namevalue'} = $param->{ $opt->{'batch_namecol'} };
1598     $iopt{$_} = $opt->{$_} foreach qw( batch_keycol batch_table batch_namecol );
1599   }
1600
1601   my $error = FS::Record::batch_import( \%iopt );
1602
1603   unlink $file;
1604
1605   die "$error\n" if $error;
1606 }
1607
1608 =item batch_import PARAM_HASHREF
1609
1610 Class method for batch imports.  Available params:
1611
1612 =over 4
1613
1614 =item table
1615
1616 =item format - usual way to specify import, with this format string selecting data from the formats and format_* info hashes
1617
1618 =item formats
1619
1620 =item format_types
1621
1622 =item format_headers
1623
1624 =item format_sep_chars
1625
1626 =item format_fixedlength_formats
1627
1628 =item format_row_callbacks
1629
1630 =item fields - Alternate way to specify import, specifying import fields directly as a listref
1631
1632 =item postinsert_callback
1633
1634 =item params
1635
1636 =item job
1637
1638 FS::queue object, will be updated with progress
1639
1640 =item file
1641
1642 =item type
1643
1644 csv, xls, fixedlength, xml
1645
1646 =item empty_ok
1647
1648 =back
1649
1650 =cut
1651
1652 sub batch_import {
1653   my $param = shift;
1654
1655   warn "$me batch_import call with params: \n". Dumper($param)
1656     if $DEBUG;
1657
1658   my $table   = $param->{table};
1659
1660   my $job     = $param->{job};
1661   my $file    = $param->{file};
1662   my $params  = $param->{params} || {};
1663
1664   my( $type, $header, $sep_char, $fixedlength_format,
1665       $xml_format, $row_callback, @fields );
1666   my $postinsert_callback = '';
1667   if ( $param->{'format'} ) {
1668
1669     my $format  = $param->{'format'};
1670     my $formats = $param->{formats};
1671     die "unknown format $format" unless exists $formats->{ $format };
1672
1673     $type = $param->{'format_types'}
1674             ? $param->{'format_types'}{ $format }
1675             : $param->{type} || 'csv';
1676
1677
1678     $header = $param->{'format_headers'}
1679                ? $param->{'format_headers'}{ $param->{'format'} }
1680                : 0;
1681
1682     $sep_char = $param->{'format_sep_chars'}
1683                   ? $param->{'format_sep_chars'}{ $param->{'format'} }
1684                   : ',';
1685
1686     $fixedlength_format =
1687       $param->{'format_fixedlength_formats'}
1688         ? $param->{'format_fixedlength_formats'}{ $param->{'format'} }
1689         : '';
1690
1691     $xml_format =
1692       $param->{'format_xml_formats'}
1693         ? $param->{'format_xml_formats'}{ $param->{'format'} }
1694         : '';
1695
1696     $row_callback =
1697       $param->{'format_row_callbacks'}
1698         ? $param->{'format_row_callbacks'}{ $param->{'format'} }
1699         : '';
1700
1701     @fields = @{ $formats->{ $format } };
1702
1703   } elsif ( $param->{'fields'} ) {
1704
1705     $type = ''; #infer from filename
1706     $header = 0;
1707     $sep_char = ',';
1708     $fixedlength_format = '';
1709     $row_callback = '';
1710     @fields = @{ $param->{'fields'} };
1711
1712     $postinsert_callback = $param->{'postinsert_callback'}
1713       if $param->{'postinsert_callback'}
1714
1715   } else {
1716     die "neither format nor fields specified";
1717   }
1718
1719   #my $file    = $param->{file};
1720
1721   unless ( $type ) {
1722     if ( $file =~ /\.(\w+)$/i ) {
1723       $type = lc($1);
1724     } else {
1725       #or error out???
1726       warn "can't parse file type from filename $file; defaulting to CSV";
1727       $type = 'csv';
1728     }
1729     $type = 'csv'
1730       if $param->{'default_csv'} && $type ne 'xls';
1731   }
1732
1733
1734   my $row = 0;
1735   my $count;
1736   my $parser;
1737   my @buffer = ();
1738   if ( $type eq 'csv' || $type eq 'fixedlength' ) {
1739
1740     if ( $type eq 'csv' ) {
1741
1742       my %attr = ();
1743       $attr{sep_char} = $sep_char if $sep_char;
1744       $parser = new Text::CSV_XS \%attr;
1745
1746     } elsif ( $type eq 'fixedlength' ) {
1747
1748       eval "use Parse::FixedLength;";
1749       die $@ if $@;
1750       $parser = new Parse::FixedLength $fixedlength_format;
1751
1752     }
1753     else {
1754       die "Unknown file type $type\n";
1755     }
1756
1757     @buffer = split(/\r?\n/, slurp($file) );
1758     splice(@buffer, 0, ($header || 0) );
1759     $count = scalar(@buffer);
1760
1761   } elsif ( $type eq 'xls' ) {
1762
1763     eval "use Spreadsheet::ParseExcel;";
1764     die $@ if $@;
1765
1766     eval "use DateTime::Format::Excel;";
1767     #for now, just let the error be thrown if it is used, since only CDR
1768     # formats bill_west and troop use it, not other excel-parsing things
1769     #die $@ if $@;
1770
1771     my $excel = Spreadsheet::ParseExcel::Workbook->new->Parse($file);
1772
1773     $parser = $excel->{Worksheet}[0]; #first sheet
1774
1775     $count = $parser->{MaxRow} || $parser->{MinRow};
1776     $count++;
1777
1778     $row = $header || 0;
1779   } elsif ( $type eq 'xml' ) {
1780     # FS::pay_batch
1781     eval "use XML::Simple;";
1782     die $@ if $@;
1783     my $xmlrow = $xml_format->{'xmlrow'};
1784     $parser = $xml_format->{'xmlkeys'};
1785     die 'no xmlkeys specified' unless ref $parser eq 'ARRAY';
1786     my $data = XML::Simple::XMLin(
1787       $file,
1788       'SuppressEmpty' => '', #sets empty values to ''
1789       'KeepRoot'      => 1,
1790     );
1791     my $rows = $data;
1792     $rows = $rows->{$_} foreach @$xmlrow;
1793     $rows = [ $rows ] if ref($rows) ne 'ARRAY';
1794     $count = @buffer = @$rows;
1795   } else {
1796     die "Unknown file type $type\n";
1797   }
1798
1799   #my $columns;
1800
1801   local $SIG{HUP} = 'IGNORE';
1802   local $SIG{INT} = 'IGNORE';
1803   local $SIG{QUIT} = 'IGNORE';
1804   local $SIG{TERM} = 'IGNORE';
1805   local $SIG{TSTP} = 'IGNORE';
1806   local $SIG{PIPE} = 'IGNORE';
1807
1808   my $oldAutoCommit = $FS::UID::AutoCommit;
1809   local $FS::UID::AutoCommit = 0;
1810   my $dbh = dbh;
1811
1812   #my $params  = $param->{params} || {};
1813   if ( $param->{'batch_namecol'} && $param->{'batch_namevalue'} ) {
1814     my $batch_col   = $param->{'batch_keycol'};
1815
1816     my $batch_class = 'FS::'. $param->{'batch_table'};
1817     my $batch = $batch_class->new({
1818       $param->{'batch_namecol'} => $param->{'batch_namevalue'}
1819     });
1820     my $error = $batch->insert;
1821     if ( $error ) {
1822       $dbh->rollback if $oldAutoCommit;
1823       return "can't insert batch record: $error";
1824     }
1825     #primary key via dbdef? (so the column names don't have to match)
1826     my $batch_value = $batch->get( $param->{'batch_keycol'} );
1827
1828     $params->{ $batch_col } = $batch_value;
1829   }
1830
1831   #my $job     = $param->{job};
1832   my $line;
1833   my $imported = 0;
1834   my( $last, $min_sec ) = ( time, 5 ); #progressbar foo
1835   while (1) {
1836
1837     my @columns = ();
1838     if ( $type eq 'csv' ) {
1839
1840       last unless scalar(@buffer);
1841       $line = shift(@buffer);
1842
1843       next if $line =~ /^\s*$/; #skip empty lines
1844
1845       $line = &{$row_callback}($line) if $row_callback;
1846
1847       $parser->parse($line) or do {
1848         $dbh->rollback if $oldAutoCommit;
1849         return "can't parse: ". $parser->error_input();
1850       };
1851       @columns = $parser->fields();
1852
1853     } elsif ( $type eq 'fixedlength' ) {
1854
1855       @columns = $parser->parse($line);
1856
1857     } elsif ( $type eq 'xls' ) {
1858
1859       last if $row > ($parser->{MaxRow} || $parser->{MinRow})
1860            || ! $parser->{Cells}[$row];
1861
1862       my @row = @{ $parser->{Cells}[$row] };
1863       @columns = map $_->{Val}, @row;
1864
1865       #my $z = 'A';
1866       #warn $z++. ": $_\n" for @columns;
1867
1868     } elsif ( $type eq 'xml' ) {
1869       # $parser = [ 'Column0Key', 'Column1Key' ... ]
1870       last unless scalar(@buffer);
1871       my $row = shift @buffer;
1872       @columns = @{ $row }{ @$parser };
1873     } else {
1874       die "Unknown file type $type\n";
1875     }
1876
1877     my @later = ();
1878     my %hash = %$params;
1879
1880     foreach my $field ( @fields ) {
1881
1882       my $value = shift @columns;
1883
1884       if ( ref($field) eq 'CODE' ) {
1885         #&{$field}(\%hash, $value);
1886         push @later, $field, $value;
1887       } else {
1888         #??? $hash{$field} = $value if length($value);
1889         $hash{$field} = $value if defined($value) && length($value);
1890       }
1891
1892     }
1893
1894     #my $table   = $param->{table};
1895     my $class = "FS::$table";
1896
1897     my $record = $class->new( \%hash );
1898
1899     my $param = {};
1900     while ( scalar(@later) ) {
1901       my $sub = shift @later;
1902       my $data = shift @later;
1903       eval {
1904         &{$sub}($record, $data, $conf, $param); # $record->&{$sub}($data, $conf)
1905       };
1906       if ( $@ ) {
1907         $dbh->rollback if $oldAutoCommit;
1908         return "can't insert record". ( $line ? " for $line" : '' ). ": $@";
1909       }
1910       last if exists( $param->{skiprow} );
1911     }
1912     next if exists( $param->{skiprow} );
1913
1914     my $error = $record->insert;
1915
1916     if ( $error ) {
1917       $dbh->rollback if $oldAutoCommit;
1918       return "can't insert record". ( $line ? " for $line" : '' ). ": $error";
1919     }
1920
1921     $row++;
1922     $imported++;
1923
1924     if ( $postinsert_callback ) {
1925       my $error = &{$postinsert_callback}($record, $param);
1926       if ( $error ) {
1927         $dbh->rollback if $oldAutoCommit;
1928         return "postinsert_callback error". ( $line ? " for $line" : '' ).
1929                ": $error";
1930       }
1931     }
1932
1933     if ( $job && time - $min_sec > $last ) { #progress bar
1934       $job->update_statustext( int(100 * $imported / $count) );
1935       $last = time;
1936     }
1937
1938   }
1939
1940   unless ( $imported || $param->{empty_ok} ) {
1941     $dbh->rollback if $oldAutoCommit;
1942     return "Empty file!";
1943   }
1944
1945   $dbh->commit or die $dbh->errstr if $oldAutoCommit;;
1946
1947   ''; #no error
1948
1949 }
1950
1951 sub _h_statement {
1952   my( $self, $action, $time ) = @_;
1953
1954   $time ||= time;
1955
1956   my %nohistory = map { $_=>1 } $self->nohistory_fields;
1957
1958   my @fields =
1959     grep { defined($self->get($_)) && $self->get($_) ne "" && ! $nohistory{$_} }
1960     real_fields($self->table);
1961   ;
1962
1963   # If we're encrypting then don't store the payinfo in the history
1964   if ( $conf && $conf->exists('encryption') ) {
1965     @fields = grep { $_ ne 'payinfo' } @fields;
1966   }
1967
1968   my @values = map { _quote( $self->getfield($_), $self->table, $_) } @fields;
1969
1970   "INSERT INTO h_". $self->table. " ( ".
1971       join(', ', qw(history_date history_user history_action), @fields ).
1972     ") VALUES (".
1973       join(', ', $time, dbh->quote(getotaker()), dbh->quote($action), @values).
1974     ")"
1975   ;
1976 }
1977
1978 =item unique COLUMN
1979
1980 B<Warning>: External use is B<deprecated>.
1981
1982 Replaces COLUMN in record with a unique number, using counters in the
1983 filesystem.  Used by the B<insert> method on single-field unique columns
1984 (see L<DBIx::DBSchema::Table>) and also as a fallback for primary keys
1985 that aren't SERIAL (Pg) or AUTO_INCREMENT (mysql).
1986
1987 Returns the new value.
1988
1989 =cut
1990
1991 sub unique {
1992   my($self,$field) = @_;
1993   my($table)=$self->table;
1994
1995   croak "Unique called on field $field, but it is ",
1996         $self->getfield($field),
1997         ", not null!"
1998     if $self->getfield($field);
1999
2000   #warn "table $table is tainted" if is_tainted($table);
2001   #warn "field $field is tainted" if is_tainted($field);
2002
2003   my($counter) = new File::CounterFile "$table.$field",0;
2004 # hack for web demo
2005 #  getotaker() =~ /^([\w\-]{1,16})$/ or die "Illegal CGI REMOTE_USER!";
2006 #  my($user)=$1;
2007 #  my($counter) = new File::CounterFile "$user/$table.$field",0;
2008 # endhack
2009
2010   my $index = $counter->inc;
2011   $index = $counter->inc while qsearchs($table, { $field=>$index } );
2012
2013   $index =~ /^(\d*)$/;
2014   $index=$1;
2015
2016   $self->setfield($field,$index);
2017
2018 }
2019
2020 =item ut_float COLUMN
2021
2022 Check/untaint floating point numeric data: 1.1, 1, 1.1e10, 1e10.  May not be
2023 null.  If there is an error, returns the error, otherwise returns false.
2024
2025 =cut
2026
2027 sub ut_float {
2028   my($self,$field)=@_ ;
2029   ($self->getfield($field) =~ /^\s*(\d+\.\d+)\s*$/ ||
2030    $self->getfield($field) =~ /^\s*(\d+)\s*$/ ||
2031    $self->getfield($field) =~ /^\s*(\d+\.\d+e\d+)\s*$/ ||
2032    $self->getfield($field) =~ /^\s*(\d+e\d+)\s*$/)
2033     or return "Illegal or empty (float) $field: ". $self->getfield($field);
2034   $self->setfield($field,$1);
2035   '';
2036 }
2037 =item ut_floatn COLUMN
2038
2039 Check/untaint floating point numeric data: 1.1, 1, 1.1e10, 1e10.  May be
2040 null.  If there is an error, returns the error, otherwise returns false.
2041
2042 =cut
2043
2044 #false laziness w/ut_ipn
2045 sub ut_floatn {
2046   my( $self, $field ) = @_;
2047   if ( $self->getfield($field) =~ /^()$/ ) {
2048     $self->setfield($field,'');
2049     '';
2050   } else {
2051     $self->ut_float($field);
2052   }
2053 }
2054
2055 =item ut_sfloat COLUMN
2056
2057 Check/untaint signed floating point numeric data: 1.1, 1, 1.1e10, 1e10.
2058 May not be null.  If there is an error, returns the error, otherwise returns
2059 false.
2060
2061 =cut
2062
2063 sub ut_sfloat {
2064   my($self,$field)=@_ ;
2065   ($self->getfield($field) =~ /^\s*(-?\d+\.\d+)\s*$/ ||
2066    $self->getfield($field) =~ /^\s*(-?\d+)\s*$/ ||
2067    $self->getfield($field) =~ /^\s*(-?\d+\.\d+[eE]-?\d+)\s*$/ ||
2068    $self->getfield($field) =~ /^\s*(-?\d+[eE]-?\d+)\s*$/)
2069     or return "Illegal or empty (float) $field: ". $self->getfield($field);
2070   $self->setfield($field,$1);
2071   '';
2072 }
2073 =item ut_sfloatn COLUMN
2074
2075 Check/untaint signed floating point numeric data: 1.1, 1, 1.1e10, 1e10.  May be
2076 null.  If there is an error, returns the error, otherwise returns false.
2077
2078 =cut
2079
2080 sub ut_sfloatn {
2081   my( $self, $field ) = @_;
2082   if ( $self->getfield($field) =~ /^()$/ ) {
2083     $self->setfield($field,'');
2084     '';
2085   } else {
2086     $self->ut_sfloat($field);
2087   }
2088 }
2089
2090 =item ut_snumber COLUMN
2091
2092 Check/untaint signed numeric data (whole numbers).  If there is an error,
2093 returns the error, otherwise returns false.
2094
2095 =cut
2096
2097 sub ut_snumber {
2098   my($self, $field) = @_;
2099   $self->getfield($field) =~ /^\s*(-?)\s*(\d+)\s*$/
2100     or return "Illegal or empty (numeric) $field: ". $self->getfield($field);
2101   $self->setfield($field, "$1$2");
2102   '';
2103 }
2104
2105 =item ut_snumbern COLUMN
2106
2107 Check/untaint signed numeric data (whole numbers).  If there is an error,
2108 returns the error, otherwise returns false.
2109
2110 =cut
2111
2112 sub ut_snumbern {
2113   my($self, $field) = @_;
2114   $self->getfield($field) =~ /^\s*(-?)\s*(\d*)\s*$/
2115     or return "Illegal (numeric) $field: ". $self->getfield($field);
2116   if ($1) {
2117     return "Illegal (numeric) $field: ". $self->getfield($field)
2118       unless $2;
2119   }
2120   $self->setfield($field, "$1$2");
2121   '';
2122 }
2123
2124 =item ut_number COLUMN
2125
2126 Check/untaint simple numeric data (whole numbers).  May not be null.  If there
2127 is an error, returns the error, otherwise returns false.
2128
2129 =cut
2130
2131 sub ut_number {
2132   my($self,$field)=@_;
2133   $self->getfield($field) =~ /^\s*(\d+)\s*$/
2134     or return "Illegal or empty (numeric) $field: ". $self->getfield($field);
2135   $self->setfield($field,$1);
2136   '';
2137 }
2138
2139 =item ut_numbern COLUMN
2140
2141 Check/untaint simple numeric data (whole numbers).  May be null.  If there is
2142 an error, returns the error, otherwise returns false.
2143
2144 =cut
2145
2146 sub ut_numbern {
2147   my($self,$field)=@_;
2148   $self->getfield($field) =~ /^\s*(\d*)\s*$/
2149     or return "Illegal (numeric) $field: ". $self->getfield($field);
2150   $self->setfield($field,$1);
2151   '';
2152 }
2153
2154 =item ut_money COLUMN
2155
2156 Check/untaint monetary numbers.  May be negative.  Set to 0 if null.  If there
2157 is an error, returns the error, otherwise returns false.
2158
2159 =cut
2160
2161 sub ut_money {
2162   my($self,$field)=@_;
2163   $self->setfield($field, 0) if $self->getfield($field) eq '';
2164   $self->getfield($field) =~ /^\s*(\-)?\s*(\d*)(\.\d{2})?\s*$/
2165     or return "Illegal (money) $field: ". $self->getfield($field);
2166   #$self->setfield($field, "$1$2$3" || 0);
2167   $self->setfield($field, ( ($1||''). ($2||''). ($3||'') ) || 0);
2168   '';
2169 }
2170
2171 =item ut_moneyn COLUMN
2172
2173 Check/untaint monetary numbers.  May be negative.  If there
2174 is an error, returns the error, otherwise returns false.
2175
2176 =cut
2177
2178 sub ut_moneyn {
2179   my($self,$field)=@_;
2180   if ($self->getfield($field) eq '') {
2181     $self->setfield($field, '');
2182     return '';
2183   }
2184   $self->ut_money($field);
2185 }
2186
2187 =item ut_text COLUMN
2188
2189 Check/untaint text.  Alphanumerics, spaces, and the following punctuation
2190 symbols are currently permitted: ! @ # $ % & ( ) - + ; : ' " , . ? / = [ ] < >
2191 May not be null.  If there is an error, returns the error, otherwise returns
2192 false.
2193
2194 =cut
2195
2196 sub ut_text {
2197   my($self,$field)=@_;
2198   #warn "msgcat ". \&msgcat. "\n";
2199   #warn "notexist ". \&notexist. "\n";
2200   #warn "AUTOLOAD ". \&AUTOLOAD. "\n";
2201   $self->getfield($field)
2202     =~ /^([µ_0123456789aAáÁàÀâÂåÅäÄãÃªæÆbBcCçÇdDðÐeEéÉèÈêÊëËfFgGhHiIíÍìÌîÎïÏjJkKlLmMnNñÑoOóÓòÒôÔöÖõÕøØºpPqQrRsSßtTuUúÚùÙûÛüÜvVwWxXyYýÝÿzZþÞ \!\@\#\$\%\&\(\)\-\+\;\:\'\"\,\.\?\/\=\[\]\<\>]+)$/
2203       or return gettext('illegal_or_empty_text'). " $field: ".
2204                  $self->getfield($field);
2205   $self->setfield($field,$1);
2206   '';
2207 }
2208
2209 =item ut_textn COLUMN
2210
2211 Check/untaint text.  Alphanumerics, spaces, and the following punctuation
2212 symbols are currently permitted: ! @ # $ % & ( ) - + ; : ' " , . ? /
2213 May be null.  If there is an error, returns the error, otherwise returns false.
2214
2215 =cut
2216
2217 sub ut_textn {
2218   my($self,$field)=@_;
2219   return $self->setfield($field, '') if $self->getfield($field) =~ /^$/;
2220   $self->ut_text($field);
2221 }
2222
2223 =item ut_alpha COLUMN
2224
2225 Check/untaint alphanumeric strings (no spaces).  May not be null.  If there is
2226 an error, returns the error, otherwise returns false.
2227
2228 =cut
2229
2230 sub ut_alpha {
2231   my($self,$field)=@_;
2232   $self->getfield($field) =~ /^(\w+)$/
2233     or return "Illegal or empty (alphanumeric) $field: ".
2234               $self->getfield($field);
2235   $self->setfield($field,$1);
2236   '';
2237 }
2238
2239 =item ut_alphan COLUMN
2240
2241 Check/untaint alphanumeric strings (no spaces).  May be null.  If there is an
2242 error, returns the error, otherwise returns false.
2243
2244 =cut
2245
2246 sub ut_alphan {
2247   my($self,$field)=@_;
2248   $self->getfield($field) =~ /^(\w*)$/
2249     or return "Illegal (alphanumeric) $field: ". $self->getfield($field);
2250   $self->setfield($field,$1);
2251   '';
2252 }
2253
2254 =item ut_alphasn COLUMN
2255
2256 Check/untaint alphanumeric strings, spaces allowed.  May be null.  If there is
2257 an error, returns the error, otherwise returns false.
2258
2259 =cut
2260
2261 sub ut_alphasn {
2262   my($self,$field)=@_;
2263   $self->getfield($field) =~ /^([\w ]*)$/
2264     or return "Illegal (alphanumeric) $field: ". $self->getfield($field);
2265   $self->setfield($field,$1);
2266   '';
2267 }
2268
2269
2270 =item ut_alpha_lower COLUMN
2271
2272 Check/untaint lowercase alphanumeric strings (no spaces).  May not be null.  If
2273 there is an error, returns the error, otherwise returns false.
2274
2275 =cut
2276
2277 sub ut_alpha_lower {
2278   my($self,$field)=@_;
2279   $self->getfield($field) =~ /[[:upper:]]/
2280     and return "Uppercase characters are not permitted in $field";
2281   $self->ut_alpha($field);
2282 }
2283
2284 =item ut_phonen COLUMN [ COUNTRY ]
2285
2286 Check/untaint phone numbers.  May be null.  If there is an error, returns
2287 the error, otherwise returns false.
2288
2289 Takes an optional two-letter ISO country code; without it or with unsupported
2290 countries, ut_phonen simply calls ut_alphan.
2291
2292 =cut
2293
2294 sub ut_phonen {
2295   my( $self, $field, $country ) = @_;
2296   return $self->ut_alphan($field) unless defined $country;
2297   my $phonen = $self->getfield($field);
2298   if ( $phonen eq '' ) {
2299     $self->setfield($field,'');
2300   } elsif ( $country eq 'US' || $country eq 'CA' ) {
2301     $phonen =~ s/\D//g;
2302     $phonen = $conf->config('cust_main-default_areacode').$phonen
2303       if length($phonen)==7 && $conf->config('cust_main-default_areacode');
2304     $phonen =~ /^(\d{3})(\d{3})(\d{4})(\d*)$/
2305       or return gettext('illegal_phone'). " $field: ". $self->getfield($field);
2306     $phonen = "$1-$2-$3";
2307     $phonen .= " x$4" if $4;
2308     $self->setfield($field,$phonen);
2309   } else {
2310     warn "warning: don't know how to check phone numbers for country $country";
2311     return $self->ut_textn($field);
2312   }
2313   '';
2314 }
2315
2316 =item ut_hex COLUMN
2317
2318 Check/untaint hexadecimal values.
2319
2320 =cut
2321
2322 sub ut_hex {
2323   my($self, $field) = @_;
2324   $self->getfield($field) =~ /^([\da-fA-F]+)$/
2325     or return "Illegal (hex) $field: ". $self->getfield($field);
2326   $self->setfield($field, uc($1));
2327   '';
2328 }
2329
2330 =item ut_hexn COLUMN
2331
2332 Check/untaint hexadecimal values.  May be null.
2333
2334 =cut
2335
2336 sub ut_hexn {
2337   my($self, $field) = @_;
2338   $self->getfield($field) =~ /^([\da-fA-F]*)$/
2339     or return "Illegal (hex) $field: ". $self->getfield($field);
2340   $self->setfield($field, uc($1));
2341   '';
2342 }
2343 =item ut_ip COLUMN
2344
2345 Check/untaint ip addresses.  IPv4 only for now, though ::1 is auto-translated
2346 to 127.0.0.1.
2347
2348 =cut
2349
2350 sub ut_ip {
2351   my( $self, $field ) = @_;
2352   $self->setfield($field, '127.0.0.1') if $self->getfield($field) eq '::1';
2353   $self->getfield($field) =~ /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/
2354     or return "Illegal (IP address) $field: ". $self->getfield($field);
2355   for ( $1, $2, $3, $4 ) { return "Illegal (IP address) $field" if $_ > 255; }
2356   $self->setfield($field, "$1.$2.$3.$4");
2357   '';
2358 }
2359
2360 =item ut_ipn COLUMN
2361
2362 Check/untaint ip addresses.  IPv4 only for now, though ::1 is auto-translated
2363 to 127.0.0.1.  May be null.
2364
2365 =cut
2366
2367 sub ut_ipn {
2368   my( $self, $field ) = @_;
2369   if ( $self->getfield($field) =~ /^()$/ ) {
2370     $self->setfield($field,'');
2371     '';
2372   } else {
2373     $self->ut_ip($field);
2374   }
2375 }
2376
2377 =item ut_coord COLUMN [ LOWER [ UPPER ] ]
2378
2379 Check/untaint coordinates.
2380 Accepts the following forms:
2381 DDD.DDDDD
2382 -DDD.DDDDD
2383 DDD MM.MMM
2384 -DDD MM.MMM
2385 DDD MM SS
2386 -DDD MM SS
2387 DDD MM MMM
2388 -DDD MM MMM
2389
2390 The "DDD MM SS" and "DDD MM MMM" are potentially ambiguous.
2391 The latter form (that is, the MMM are thousands of minutes) is
2392 assumed if the "MMM" is exactly three digits or two digits > 59.
2393
2394 To be safe, just use the DDD.DDDDD form.
2395
2396 If LOWER or UPPER are specified, then the coordinate is checked
2397 for lower and upper bounds, respectively.
2398
2399 =cut
2400
2401 sub ut_coord {
2402
2403   my ($self, $field) = (shift, shift);
2404
2405   my $lower = shift if scalar(@_);
2406   my $upper = shift if scalar(@_);
2407   my $coord = $self->getfield($field);
2408   my $neg = $coord =~ s/^(-)//;
2409
2410   my ($d, $m, $s) = (0, 0, 0);
2411
2412   if (
2413     (($d) = ($coord =~ /^(\s*\d{1,3}(?:\.\d+)?)\s*$/)) ||
2414     (($d, $m) = ($coord =~ /^(\s*\d{1,3})\s+(\d{1,2}(?:\.\d+))\s*$/)) ||
2415     (($d, $m, $s) = ($coord =~ /^(\s*\d{1,3})\s+(\d{1,2})\s+(\d{1,3})\s*$/))
2416   ) {
2417     $s = (((($s =~ /^\d{3}$/) or $s > 59) ? ($s / 1000) : ($s / 60)) / 60);
2418     $m = $m / 60;
2419     if ($m > 59) {
2420       return "Invalid (coordinate with minutes > 59) $field: "
2421              . $self->getfield($field);
2422     }
2423
2424     $coord = ($neg ? -1 : 1) * sprintf('%.8f', $d + $m + $s);
2425
2426     if (defined($lower) and ($coord < $lower)) {
2427       return "Invalid (coordinate < $lower) $field: "
2428              . $self->getfield($field);;
2429     }
2430
2431     if (defined($upper) and ($coord > $upper)) {
2432       return "Invalid (coordinate > $upper) $field: "
2433              . $self->getfield($field);;
2434     }
2435
2436     $self->setfield($field, $coord);
2437     return '';
2438   }
2439
2440   return "Invalid (coordinate) $field: " . $self->getfield($field);
2441
2442 }
2443
2444 =item ut_coordn COLUMN [ LOWER [ UPPER ] ]
2445
2446 Same as ut_coord, except optionally null.
2447
2448 =cut
2449
2450 sub ut_coordn {
2451
2452   my ($self, $field) = (shift, shift);
2453
2454   if ($self->getfield($field) =~ /^$/) {
2455     return '';
2456   } else {
2457     return $self->ut_coord($field, @_);
2458   }
2459
2460 }
2461
2462
2463 =item ut_domain COLUMN
2464
2465 Check/untaint host and domain names.
2466
2467 =cut
2468
2469 sub ut_domain {
2470   my( $self, $field ) = @_;
2471   #$self->getfield($field) =~/^(\w+\.)*\w+$/
2472   $self->getfield($field) =~/^(([\w\-]+\.)*\w+)$/
2473     or return "Illegal (domain) $field: ". $self->getfield($field);
2474   $self->setfield($field,$1);
2475   '';
2476 }
2477
2478 =item ut_name COLUMN
2479
2480 Check/untaint proper names; allows alphanumerics, spaces and the following
2481 punctuation: , . - '
2482
2483 May not be null.
2484
2485 =cut
2486
2487 sub ut_name {
2488   my( $self, $field ) = @_;
2489 #  warn "ut_name allowed alphanumerics: +(sort grep /\w/, map { chr() } 0..255), "\n";
2490   #$self->getfield($field) =~ /^([\w \,\.\-\']+)$/
2491   $self->getfield($field) =~ /^([µ_0123456789aAáÁàÀâÂåÅäÄãÃªæÆbBcCçÇdDðÐeEéÉèÈêÊëËfFgGhHiIíÍìÌîÎïÏjJkKlLmMnNñÑoOóÓòÒôÔöÖõÕøØºpPqQrRsSßtTuUúÚùÙûÛüÜvVwWxXyYýÝÿzZþÞ \,\.\-\']+)$/
2492     or return gettext('illegal_name'). " $field: ". $self->getfield($field);
2493   $self->setfield($field,$1);
2494   '';
2495 }
2496
2497 =item ut_zip COLUMN
2498
2499 Check/untaint zip codes.
2500
2501 =cut
2502
2503 my @zip_reqd_countries = qw( AU CA US ); #CA, US implicit...
2504
2505 sub ut_zip {
2506   my( $self, $field, $country ) = @_;
2507
2508   if ( $country eq 'US' ) {
2509
2510     $self->getfield($field) =~ /^\s*(\d{5}(\-\d{4})?)\s*$/
2511       or return gettext('illegal_zip'). " $field for country $country: ".
2512                 $self->getfield($field);
2513     $self->setfield($field, $1);
2514
2515   } elsif ( $country eq 'CA' ) {
2516
2517     $self->getfield($field) =~ /^\s*([A-Z]\d[A-Z])\s*(\d[A-Z]\d)\s*$/i
2518       or return gettext('illegal_zip'). " $field for country $country: ".
2519                 $self->getfield($field);
2520     $self->setfield($field, "$1 $2");
2521
2522   } else {
2523
2524     if ( $self->getfield($field) =~ /^\s*$/
2525          && ( !$country || ! grep { $_ eq $country } @zip_reqd_countries )
2526        )
2527     {
2528       $self->setfield($field,'');
2529     } else {
2530       $self->getfield($field) =~ /^\s*(\w[\w\-\s]{2,8}\w)\s*$/
2531         or return gettext('illegal_zip'). " $field: ". $self->getfield($field);
2532       $self->setfield($field,$1);
2533     }
2534
2535   }
2536
2537   '';
2538 }
2539
2540 =item ut_country COLUMN
2541
2542 Check/untaint country codes.  Country names are changed to codes, if possible -
2543 see L<Locale::Country>.
2544
2545 =cut
2546
2547 sub ut_country {
2548   my( $self, $field ) = @_;
2549   unless ( $self->getfield($field) =~ /^(\w\w)$/ ) {
2550     if ( $self->getfield($field) =~ /^([\w \,\.\(\)\']+)$/
2551          && country2code($1) ) {
2552       $self->setfield($field,uc(country2code($1)));
2553     }
2554   }
2555   $self->getfield($field) =~ /^(\w\w)$/
2556     or return "Illegal (country) $field: ". $self->getfield($field);
2557   $self->setfield($field,uc($1));
2558   '';
2559 }
2560
2561 =item ut_anything COLUMN
2562
2563 Untaints arbitrary data.  Be careful.
2564
2565 =cut
2566
2567 sub ut_anything {
2568   my( $self, $field ) = @_;
2569   $self->getfield($field) =~ /^(.*)$/s
2570     or return "Illegal $field: ". $self->getfield($field);
2571   $self->setfield($field,$1);
2572   '';
2573 }
2574
2575 =item ut_enum COLUMN CHOICES_ARRAYREF
2576
2577 Check/untaint a column, supplying all possible choices, like the "enum" type.
2578
2579 =cut
2580
2581 sub ut_enum {
2582   my( $self, $field, $choices ) = @_;
2583   foreach my $choice ( @$choices ) {
2584     if ( $self->getfield($field) eq $choice ) {
2585       $self->setfield($field, $choice);
2586       return '';
2587     }
2588   }
2589   return "Illegal (enum) field $field: ". $self->getfield($field);
2590 }
2591
2592 =item ut_foreign_key COLUMN FOREIGN_TABLE FOREIGN_COLUMN
2593
2594 Check/untaint a foreign column key.  Call a regular ut_ method (like ut_number)
2595 on the column first.
2596
2597 =cut
2598
2599 sub ut_foreign_key {
2600   my( $self, $field, $table, $foreign ) = @_;
2601   return '' if $no_check_foreign;
2602   qsearchs($table, { $foreign => $self->getfield($field) })
2603     or return "Can't find ". $self->table. ".$field ". $self->getfield($field).
2604               " in $table.$foreign";
2605   '';
2606 }
2607
2608 =item ut_foreign_keyn COLUMN FOREIGN_TABLE FOREIGN_COLUMN
2609
2610 Like ut_foreign_key, except the null value is also allowed.
2611
2612 =cut
2613
2614 sub ut_foreign_keyn {
2615   my( $self, $field, $table, $foreign ) = @_;
2616   $self->getfield($field)
2617     ? $self->ut_foreign_key($field, $table, $foreign)
2618     : '';
2619 }
2620
2621 =item ut_agentnum_acl COLUMN [ NULL_RIGHT | NULL_RIGHT_LISTREF ]
2622
2623 Checks this column as an agentnum, taking into account the current users's
2624 ACLs.  NULL_RIGHT or NULL_RIGHT_LISTREF, if specified, indicates the access
2625 right or rights allowing no agentnum.
2626
2627 =cut
2628
2629 sub ut_agentnum_acl {
2630   my( $self, $field ) = (shift, shift);
2631   my $null_acl = scalar(@_) ? shift : [];
2632   $null_acl = [ $null_acl ] unless ref($null_acl);
2633
2634   my $error = $self->ut_foreign_keyn($field, 'agent', 'agentnum');
2635   return "Illegal agentnum: $error" if $error;
2636
2637   my $curuser = $FS::CurrentUser::CurrentUser;
2638
2639   if ( $self->$field() ) {
2640
2641     return "Access denied"
2642       unless $curuser->agentnum($self->$field());
2643
2644   } else {
2645
2646     return "Access denied"
2647       unless grep $curuser->access_right($_), @$null_acl;
2648
2649   }
2650
2651   '';
2652
2653 }
2654
2655 =item virtual_fields [ TABLE ]
2656
2657 Returns a list of virtual fields defined for the table.  This should not
2658 be exported, and should only be called as an instance or class method.
2659
2660 =cut
2661
2662 sub virtual_fields {
2663   my $self = shift;
2664   my $table;
2665   $table = $self->table or confess "virtual_fields called on non-table";
2666
2667   confess "Unknown table $table" unless dbdef->table($table);
2668
2669   return () unless dbdef->table('part_virtual_field');
2670
2671   unless ( $virtual_fields_cache{$table} ) {
2672     my $query = 'SELECT name from part_virtual_field ' .
2673                 "WHERE dbtable = '$table'";
2674     my $dbh = dbh;
2675     my $result = $dbh->selectcol_arrayref($query);
2676     confess "Error executing virtual fields query: $query: ". $dbh->errstr
2677       if $dbh->err;
2678     $virtual_fields_cache{$table} = $result;
2679   }
2680
2681   @{$virtual_fields_cache{$table}};
2682
2683 }
2684
2685
2686 =item fields [ TABLE ]
2687
2688 This is a wrapper for real_fields and virtual_fields.  Code that called
2689 fields before should probably continue to call fields.
2690
2691 =cut
2692
2693 sub fields {
2694   my $something = shift;
2695   my $table;
2696   if($something->isa('FS::Record')) {
2697     $table = $something->table;
2698   } else {
2699     $table = $something;
2700     $something = "FS::$table";
2701   }
2702   return (real_fields($table), $something->virtual_fields());
2703 }
2704
2705 =item pvf FIELD_NAME
2706
2707 Returns the FS::part_virtual_field object corresponding to a field in the
2708 record (specified by FIELD_NAME).
2709
2710 =cut
2711
2712 sub pvf {
2713   my ($self, $name) = (shift, shift);
2714
2715   if(grep /^$name$/, $self->virtual_fields) {
2716     return qsearchs('part_virtual_field', { dbtable => $self->table,
2717                                             name    => $name } );
2718   }
2719   ''
2720 }
2721
2722 =item vfieldpart_hashref TABLE
2723
2724 Returns a hashref of virtual field names and vfieldparts applicable to the given
2725 TABLE.
2726
2727 =cut
2728
2729 sub vfieldpart_hashref {
2730   my $self = shift;
2731   my $table = $self->table;
2732
2733   return {} unless dbdef->table('part_virtual_field');
2734
2735   my $dbh = dbh;
2736   my $statement = "SELECT vfieldpart, name FROM part_virtual_field WHERE ".
2737                   "dbtable = '$table'";
2738   my $sth = $dbh->prepare($statement);
2739   $sth->execute or croak "Execution of '$statement' failed: ".$dbh->errstr;
2740   return { map { $_->{name}, $_->{vfieldpart} }
2741     @{$sth->fetchall_arrayref({})} };
2742
2743 }
2744
2745 =item encrypt($value)
2746
2747 Encrypts the credit card using a combination of PK to encrypt and uuencode to armour.
2748
2749 Returns the encrypted string.
2750
2751 You should generally not have to worry about calling this, as the system handles this for you.
2752
2753 =cut
2754
2755 sub encrypt {
2756   my ($self, $value) = @_;
2757   my $encrypted;
2758
2759   if ($conf->exists('encryption')) {
2760     if ($self->is_encrypted($value)) {
2761       # Return the original value if it isn't plaintext.
2762       $encrypted = $value;
2763     } else {
2764       $self->loadRSA;
2765       if (ref($rsa_encrypt) =~ /::RSA/) { # We Can Encrypt
2766         # RSA doesn't like the empty string so let's pack it up
2767         # The database doesn't like the RSA data so uuencode it
2768         my $length = length($value)+1;
2769         $encrypted = pack("u*",$rsa_encrypt->encrypt(pack("Z$length",$value)));
2770       } else {
2771         die ("You can't encrypt w/o a valid RSA engine - Check your installation or disable encryption");
2772       }
2773     }
2774   }
2775   return $encrypted;
2776 }
2777
2778 =item is_encrypted($value)
2779
2780 Checks to see if the string is encrypted and returns true or false (1/0) to indicate it's status.
2781
2782 =cut
2783
2784
2785 sub is_encrypted {
2786   my ($self, $value) = @_;
2787   # Possible Bug - Some work may be required here....
2788
2789   if ($value =~ /^M/ && length($value) > 80) {
2790     return 1;
2791   } else {
2792     return 0;
2793   }
2794 }
2795
2796 =item decrypt($value)
2797
2798 Uses the private key to decrypt the string. Returns the decryoted string or undef on failure.
2799
2800 You should generally not have to worry about calling this, as the system handles this for you.
2801
2802 =cut
2803
2804 sub decrypt {
2805   my ($self,$value) = @_;
2806   my $decrypted = $value; # Will return the original value if it isn't encrypted or can't be decrypted.
2807   if ($conf->exists('encryption') && $self->is_encrypted($value)) {
2808     $self->loadRSA;
2809     if (ref($rsa_decrypt) =~ /::RSA/) {
2810       my $encrypted = unpack ("u*", $value);
2811       $decrypted =  unpack("Z*", eval{$rsa_decrypt->decrypt($encrypted)});
2812       if ($@) {warn "Decryption Failed"};
2813     }
2814   }
2815   return $decrypted;
2816 }
2817
2818 sub loadRSA {
2819     my $self = shift;
2820     #Initialize the Module
2821     $rsa_module = 'Crypt::OpenSSL::RSA'; # The Default
2822
2823     if ($conf->exists('encryptionmodule') && $conf->config('encryptionmodule') ne '') {
2824       $rsa_module = $conf->config('encryptionmodule');
2825     }
2826
2827     if (!$rsa_loaded) {
2828         eval ("require $rsa_module"); # No need to import the namespace
2829         $rsa_loaded++;
2830     }
2831     # Initialize Encryption
2832     if ($conf->exists('encryptionpublickey') && $conf->config('encryptionpublickey') ne '') {
2833       my $public_key = join("\n",$conf->config('encryptionpublickey'));
2834       $rsa_encrypt = $rsa_module->new_public_key($public_key);
2835     }
2836
2837     # Intitalize Decryption
2838     if ($conf->exists('encryptionprivatekey') && $conf->config('encryptionprivatekey') ne '') {
2839       my $private_key = join("\n",$conf->config('encryptionprivatekey'));
2840       $rsa_decrypt = $rsa_module->new_private_key($private_key);
2841     }
2842 }
2843
2844 =item h_search ACTION
2845
2846 Given an ACTION, either "insert", or "delete", returns the appropriate history
2847 record corresponding to this record, if any.
2848
2849 =cut
2850
2851 sub h_search {
2852   my( $self, $action ) = @_;
2853
2854   my $table = $self->table;
2855   $table =~ s/^h_//;
2856
2857   my $primary_key = dbdef->table($table)->primary_key;
2858
2859   qsearchs({
2860     'table'   => "h_$table",
2861     'hashref' => { $primary_key     => $self->$primary_key(),
2862                    'history_action' => $action,
2863                  },
2864   });
2865
2866 }
2867
2868 =item h_date ACTION
2869
2870 Given an ACTION, either "insert", or "delete", returns the timestamp of the
2871 appropriate history record corresponding to this record, if any.
2872
2873 =cut
2874
2875 sub h_date {
2876   my($self, $action) = @_;
2877   my $h = $self->h_search($action);
2878   $h ? $h->history_date : '';
2879 }
2880
2881 =item scalar_sql SQL [ PLACEHOLDER, ... ]
2882
2883 A class or object method.  Executes the sql statement represented by SQL and
2884 returns a scalar representing the result: the first column of the first row.
2885
2886 Dies on bogus SQL.  Returns an empty string if no row is returned.
2887
2888 Typically used for statments which return a single value such as "SELECT
2889 COUNT(*) FROM table WHERE something" OR "SELECT column FROM table WHERE key = ?"
2890
2891 =cut
2892
2893 sub scalar_sql {
2894   my($self, $sql) = (shift, shift);
2895   my $sth = dbh->prepare($sql) or die dbh->errstr;
2896   $sth->execute(@_)
2897     or die "Unexpected error executing statement $sql: ". $sth->errstr;
2898   my $scalar = $sth->fetchrow_arrayref->[0];
2899   defined($scalar) ? $scalar : '';
2900 }
2901
2902 =back
2903
2904 =head1 SUBROUTINES
2905
2906 =over 4
2907
2908 =item real_fields [ TABLE ]
2909
2910 Returns a list of the real columns in the specified table.  Called only by
2911 fields() and other subroutines elsewhere in FS::Record.
2912
2913 =cut
2914
2915 sub real_fields {
2916   my $table = shift;
2917
2918   my($table_obj) = dbdef->table($table);
2919   confess "Unknown table $table" unless $table_obj;
2920   $table_obj->columns;
2921 }
2922
2923 =item _quote VALUE, TABLE, COLUMN
2924
2925 This is an internal function used to construct SQL statements.  It returns
2926 VALUE DBI-quoted (see L<DBI/"quote">) unless VALUE is a number and the column
2927 type (see L<DBIx::DBSchema::Column>) does not end in `char' or `binary'.
2928
2929 =cut
2930
2931 sub _quote {
2932   my($value, $table, $column) = @_;
2933   my $column_obj = dbdef->table($table)->column($column);
2934   my $column_type = $column_obj->type;
2935   my $nullable = $column_obj->null;
2936
2937   warn "  $table.$column: $value ($column_type".
2938        ( $nullable ? ' NULL' : ' NOT NULL' ).
2939        ")\n" if $DEBUG > 2;
2940
2941   if ( $value eq '' && $nullable ) {
2942     'NULL';
2943   } elsif ( $value eq '' && $column_type =~ /^(int|numeric)/ ) {
2944     cluck "WARNING: Attempting to set non-null integer $table.$column null; ".
2945           "using 0 instead";
2946     0;
2947   } elsif ( $value =~ /^\d+(\.\d+)?$/ &&
2948             ! $column_type =~ /(char|binary|text)$/i ) {
2949     $value;
2950   } elsif (( $column_type =~ /^bytea$/i || $column_type =~ /(blob|varbinary)/i )
2951            && driver_name eq 'Pg'
2952           )
2953   {
2954     no strict 'subs';
2955 #    dbh->quote($value, { pg_type => PG_BYTEA() }); # doesn't work right
2956     # Pg binary string quoting: convert each character to 3-digit octal prefixed with \\,
2957     # single-quote the whole mess, and put an "E" in front.
2958     return ("E'" . join('', map { sprintf('\\\\%03o', ord($_)) } split(//, $value) ) . "'");
2959   } else {
2960     dbh->quote($value);
2961   }
2962 }
2963
2964 =item hfields TABLE
2965
2966 This is deprecated.  Don't use it.
2967
2968 It returns a hash-type list with the fields of this record's table set true.
2969
2970 =cut
2971
2972 sub hfields {
2973   carp "warning: hfields is deprecated";
2974   my($table)=@_;
2975   my(%hash);
2976   foreach (fields($table)) {
2977     $hash{$_}=1;
2978   }
2979   \%hash;
2980 }
2981
2982 sub _dump {
2983   my($self)=@_;
2984   join("\n", map {
2985     "$_: ". $self->getfield($_). "|"
2986   } (fields($self->table)) );
2987 }
2988
2989 sub DESTROY { return; }
2990
2991 #sub DESTROY {
2992 #  my $self = shift;
2993 #  #use Carp qw(cluck);
2994 #  #cluck "DESTROYING $self";
2995 #  warn "DESTROYING $self";
2996 #}
2997
2998 #sub is_tainted {
2999 #             return ! eval { join('',@_), kill 0; 1; };
3000 #         }
3001
3002 =item str2time_sql [ DRIVER_NAME ]
3003
3004 Returns a function to convert to unix time based on database type, such as
3005 "EXTRACT( EPOCH FROM" for Pg or "UNIX_TIMESTAMP(" for mysql.  See
3006 the str2time_sql_closing method to return a closing string rather than just
3007 using a closing parenthesis as previously suggested.
3008
3009 You can pass an optional driver name such as "Pg", "mysql" or
3010 $dbh->{Driver}->{Name} to return a function for that database instead of
3011 the current database.
3012
3013 =cut
3014
3015 sub str2time_sql {
3016   my $driver = shift || driver_name;
3017
3018   return 'UNIX_TIMESTAMP('      if $driver =~ /^mysql/i;
3019   return 'EXTRACT( EPOCH FROM ' if $driver =~ /^Pg/i;
3020
3021   warn "warning: unknown database type $driver; guessing how to convert ".
3022        "dates to UNIX timestamps";
3023   return 'EXTRACT(EPOCH FROM ';
3024
3025 }
3026
3027 =item str2time_sql_closing [ DRIVER_NAME ]
3028
3029 Returns the closing suffix of a function to convert to unix time based on
3030 database type, such as ")::integer" for Pg or ")" for mysql.
3031
3032 You can pass an optional driver name such as "Pg", "mysql" or
3033 $dbh->{Driver}->{Name} to return a function for that database instead of
3034 the current database.
3035
3036 =cut
3037
3038 sub str2time_sql_closing {
3039   my $driver = shift || driver_name;
3040
3041   return ' )::INTEGER ' if $driver =~ /^Pg/i;
3042   return ' ) ';
3043 }
3044
3045 =item regexp_sql [ DRIVER_NAME ]
3046
3047 Returns the operator to do a regular expression comparison based on database
3048 type, such as '~' for Pg or 'REGEXP' for mysql.
3049
3050 You can pass an optional driver name such as "Pg", "mysql" or
3051 $dbh->{Driver}->{Name} to return a function for that database instead of
3052 the current database.
3053
3054 =cut
3055
3056 sub regexp_sql {
3057   my $driver = shift || driver_name;
3058
3059   return '~'      if $driver =~ /^Pg/i;
3060   return 'REGEXP' if $driver =~ /^mysql/i;
3061
3062   die "don't know how to use regular expressions in ". driver_name." databases";
3063
3064 }
3065
3066 =item not_regexp_sql [ DRIVER_NAME ]
3067
3068 Returns the operator to do a regular expression negation based on database
3069 type, such as '!~' for Pg or 'NOT REGEXP' for mysql.
3070
3071 You can pass an optional driver name such as "Pg", "mysql" or
3072 $dbh->{Driver}->{Name} to return a function for that database instead of
3073 the current database.
3074
3075 =cut
3076
3077 sub not_regexp_sql {
3078   my $driver = shift || driver_name;
3079
3080   return '!~'         if $driver =~ /^Pg/i;
3081   return 'NOT REGEXP' if $driver =~ /^mysql/i;
3082
3083   die "don't know how to use regular expressions in ". driver_name." databases";
3084
3085 }
3086
3087 =back
3088
3089 =head1 BUGS
3090
3091 This module should probably be renamed, since much of the functionality is
3092 of general use.  It is not completely unlike Adapter::DBI (see below).
3093
3094 Exported qsearch and qsearchs should be deprecated in favor of method calls
3095 (against an FS::Record object like the old search and searchs that qsearch
3096 and qsearchs were on top of.)
3097
3098 The whole fields / hfields mess should be removed.
3099
3100 The various WHERE clauses should be subroutined.
3101
3102 table string should be deprecated in favor of DBIx::DBSchema::Table.
3103
3104 No doubt we could benefit from a Tied hash.  Documenting how exists / defined
3105 true maps to the database (and WHERE clauses) would also help.
3106
3107 The ut_ methods should ask the dbdef for a default length.
3108
3109 ut_sqltype (like ut_varchar) should all be defined
3110
3111 A fallback check method should be provided which uses the dbdef.
3112
3113 The ut_money method assumes money has two decimal digits.
3114
3115 The Pg money kludge in the new method only strips `$'.
3116
3117 The ut_phonen method only checks US-style phone numbers.
3118
3119 The _quote function should probably use ut_float instead of a regex.
3120
3121 All the subroutines probably should be methods, here or elsewhere.
3122
3123 Probably should borrow/use some dbdef methods where appropriate (like sub
3124 fields)
3125
3126 As of 1.14, DBI fetchall_hashref( {} ) doesn't set fetchrow_hashref NAME_lc,
3127 or allow it to be set.  Working around it is ugly any way around - DBI should
3128 be fixed.  (only affects RDBMS which return uppercase column names)
3129
3130 ut_zip should take an optional country like ut_phone.
3131
3132 =head1 SEE ALSO
3133
3134 L<DBIx::DBSchema>, L<FS::UID>, L<DBI>
3135
3136 Adapter::DBI from Ch. 11 of Advanced Perl Programming by Sriram Srinivasan.
3137
3138 http://poop.sf.net/
3139
3140 =cut
3141
3142 1;
3143