The Charitable_Donor class allows you to get access to information about a particular donor.

Getting an instance of Charitable_Donor

A Charitable_Donor instance can be retrieved in different ways depending on the context in which you need to use it.

With a donor ID

$donor_id = 123;
$donor    = new Charitable_Donor( $donor_id );

With a donor ID and a donation ID

$donor_id    = 123;
$donation_id = 456;
$donor       = new Charitable_Donor( $donor_id, $donation_id );

With a donation object or ID

// If you have a donation ID, first get the Charitable_Donation object.
$donation_id = 123;
$donation    = charitable_get_donation( $donation_id );

// Get the Charitable_Donor object.
$donor = $donation->get_donor();

With a Charitable_User object

// If you have a user ID, first get the Charitable_User object.
$user_id = 123;
$user    = charitable_get_user( $user_id );

// Now get the donor ID.
$donor_id = $user->get_donor_id();

// Instantiate the Charitable_Donor object with the donor ID.
$donor = new Charitable_Donor( $donor_id );

Properties

user_id
The user ID for the donor. For unregistered donors, this will return 0.

first_name
The donor’s first name.

last_name
The donor’s last name.

email
The donor’s email address.

date_joined
The date the donor first became a donor. This will be returned as a MySQL date time string.

date_erased
The date in MySQL date time that the donor’s information was erased. This is only populated if there was a data erasure request for the donor’s email address.

contact_consent
Whether the donor has opted to give their consent to be contacted.

Methods

get_user()

This returns the Charitable_User object associated with this donor.

get_donation()

If you instantiated Charitable_Donor with a donation ID or with the get_donor() method of Charitable_Donation, get_donation() will return the instance of Charitable_Donation.

Otherwise, this will return false.

get_donations()

This will return an array of all donations made by the donor.

get_donor_meta( $key = '' )

Return the donor meta stored for the particular donation.

Params
$key
If set, this will return the meta value for the given key, or false if no such meta value exists. If left empty, this will return an array of all the donor meta.

get_last_donation()

Returns the donor’s most recent donation as a Charitable_Donation instance, or null if they have not made a donation.

get_name()

Returns the donor’s name stored for the particular donation.

get_email()

Returns the donor’s email address.

has_valid_email()

Returns whether the donor’s supplied email address is valid.

get_address()

Returns the donor’s printable address.

This is a wrapper for Charitable_User::get_address().

get_avatar( $size = 100 )

Returns the HTML to display the donor’s avatar. By default, this will return the Gravatar associated with the donor’s email address.

This is a wrapper for Charitable_User::get_avatar().

Params
$size
Optional. Sets the width & height of the avatar to return. By default, the avatar is returned with a width and height of 100px.

get_location()

Returns the donor’s location.

If the Charitable_Donor object was not called with a $donation_id set, this returns the result of Charitable_User::get_location(). Otherwise, this will return the location provided for the donation, based on the city, state and/or country.

get_amount( $campaign_id = false )

Return the donation amount.

If a donation ID was passed when the Charitable_Donor was instantiated, this will return the total donated with this particular donation. Otherwise, this will return the total amount ever donated by the donor.

Params
$campaign_id
Optional. If set, this will only return the amount donated to the given campaign.