donorFirstGave: tests and initial implementation.

Supporters/lib/Supporters.pm

@@ -1173,6 +1173,49 @@ sub donorLastGave($$) {
 }
 ######################################################################
 
+=begin donorFirstGave
+
+Arguments:
+
+=over
+
+=item $self
+
+Current object.
+
+=item $donorId
+
+   Valid donor id number currently in the database.  die() will occur if
+   the id number is not in the database already as a donor id.
+
+=back
+
+Returns an ISO 8601 formatted date of their first donation.  undef will be
+returned if the donor has never given (which should rarely be the case, but
+it could happen).
+
+=cut
+
+sub donorFirstGave($$) {
+  my($self, $donorId) = @_;
+
+  confess "donorFirstGave: donorId, \"$donorId\" not found in supporter database"
+    unless $self->_verifyId($donorId);
+
+  $self->_readLedgerData() if not defined $self->{ledgerData};
+
+  my $ledgerEntityId = $self->getLedgerEntityId($donorId);
+
+  if (not defined $self->{ledgerData}{$ledgerEntityId} or
+      not defined $self->{ledgerData}{$ledgerEntityId}{__FIRST_GAVE__} or
+      $self->{ledgerData}{$ledgerEntityId}{__FIRST_GAVE__} eq '9999-12-31') {
+    return undef;
+  } else {
+    return $self->{ledgerData}{$ledgerEntityId}{__FIRST_GAVE__};
+  }
+}
+######################################################################
+
 =back
 
 =head1 Non-Public Methods

Supporters/t/Supporters.t

@@ -8,7 +8,7 @@
 use strict;
 use warnings;
 
-use Test::More tests => 241;
+use Test::More tests => 248;
 use Test::Exception;
 use Sub::Override;
 use File::Temp qw/tempfile/;
@@ -757,6 +757,24 @@ lives_ok { $date = $sp->donorLastGave($olsonId) } "donorLastGave(): check for kn
 
 is($date, '2015-06-30', "donorLastGave(): ...and returned value is correct. ");
 
+=item donorFirstGave
+
+=cut
+
+dies_ok { $sp->donorFirstGave(undef); } "donorFirstGave(): dies with undefined donorId";
+dies_ok { $sp->donorFirstGave("str"); } "donorFirstGave(): dies with non-numeric donorId";
+dies_ok { $sp->donorFirstGave(0);     } "donorFirstGave(): dies with non-existent id";
+
+lives_ok { $date = $sp->donorFirstGave($drapperId) } "donorFirstGave(): check for known annual donor success...";
+
+is($date, '2015-02-26',  "donorFirstGave(): ...and returned value is correct. ");
+
+lives_ok { $date = $sp->donorFirstGave($olsonId) } "donorFirstGave(): check for known monthly donor success...";
+
+is($date, '2015-01-15', "donorFirstGave(): ...and returned value is correct. ");
+
+=back
+
 =item Internal methods used only by the module itself.
 
 =over