The Magic Link feature allows donors to access their donor dashboard without requiring a WordPress user account or login. Donors can request a secure, time-limited link via email that grants them access to view their donation history and account information.

---

Table of Contents

---

Hooks and Filters

The following PHP hooks and filters are available for extending and customizing the magic link functionality:

Magic Link Filters

• charitable_magic_link_logout_redirect – Filter the redirect URL after magic link logout
  • Parameters: $redirect_url (string)
  • Returns: Modified redirect URL string
  • Note: The filter result is validated to prevent redirecting back to donor dashboard
• charitable_is_magic_link_on_page – Determine if magic link functionality should be active on the current page
  • Parameters: $is_magic_link_on_page (bool)
  • Returns: Boolean
  • Default: True if on donor dashboard page, has donor_dashboard action, or has magic_link_token
• charitable_magic_link_verify_throttle – Filter the throttle period for verify key requests (in seconds)
  • Parameters: None
  • Returns: Integer (default: 300 seconds / 5 minutes)
• charitable_magic_link_limit_throttle – Filter the maximum number of magic link requests allowed per throttle period
  • Parameters: None
  • Returns: Integer (default: 3 requests)
• charitable_magic_link_token_expiration – Filter the token expiration time (in seconds)
  • Parameters: None
  • Returns: Integer (default: 7200 seconds / 2 hours)
• charitable_magic_link_token_expired_message – Filter the error message shown when token expires
  • Parameters: $message (string)
  • Returns: Modified message string

Email Filters

• charitable_email_magic_link_name – Filter the email name/title
  • Parameters: $name (string)
  • Returns: Modified email name string
• charitable_email_magic_link_default_subject – Filter the default email subject line
  • Parameters: $subject (string), $email (Charitable_Email_Magic_Link instance)
  • Returns: Modified subject string
• charitable_email_magic_link_default_headline – Filter the default email headline
  • Parameters: $headline (string), $email (Charitable_Email_Magic_Link instance)
  • Returns: Modified headline string
• charitable_email_magic_link_default_body – Filter the default email body content
  • Parameters: $body (string), $email (Charitable_Email_Magic_Link instance)
  • Returns: Modified body string

Dashboard Template Filters

• charitable_magic_link_dashboard_access_heading – Filter the heading text for the magic link access form
  • Parameters: $heading (string)
  • Returns: Modified heading string
• charitable_magic_link_dashboard_access_description – Filter the description text for the magic link access form
  • Parameters: $description (string)
  • Returns: Modified description string
• charitable_magic_link_form_shortcode – Filter the output of the magic link form shortcode
  • Parameters: $output (string)
  • Returns: Modified shortcode output

---

Authentication Flow

1. Logged-in Users: If a WordPress user is logged in, magic link is bypassed and standard user authentication is used
2. Magic Link Users: If not logged in, system checks for valid magic link token
3. No Authentication: If neither exists, magic link form is displayed (if enabled)

---

Settings and Configuration

Magic link functionality can be configured in Charitable → Settings → Donors → Magic Link.

Settings

• Enable Magic Link – Toggle to enable/disable magic link functionality
  • Default: Enabled
  • Note: Requires donor dashboard to be enabled and database upgrade completed
• Magic Link Expiration (Hours) – How long magic links remain valid
  • Default: 2 hours
  • Range: Configurable via charitable_magic_link_token_expiration filter
  • Note: Expiration is calculated from when the token is created (not from when email is sent)

Requirements

• Donor dashboard must be enabled
• Database upgrade for magic link columns must be completed
• Magic link email cannot be disabled while magic link is enabled

---

Security Features

The magic link system includes multiple security measures:

Rate Limiting

• Request Throttle: Maximum 3 magic link requests per 5-minute window per donor
• Throttle Window: 5 minutes (configurable via charitable_magic_link_verify_throttle)
• Request Limit: 3 requests (configurable via charitable_magic_link_limit_throttle)
• Implementation: Uses WordPress object cache and donor meta to track request counts

Token Security

• Unique Tokens: Only one active token per donor at a time
• Token Invalidation: When a new magic link is requested, all existing tokens for that donor are invalidated
• Expiration: Tokens automatically expire after the configured time period
• Secure Cookies: Tokens stored in cookies use HttpOnly and Secure flags (when SSL is available)

Session Validation

• Donor ID Matching: Session donor ID must match token donor ID
• Request Validation: AJAX requests validate that the token donor ID matches the requested donor ID
• Session Mismatch Protection: If session and token donor IDs don’t match, session is cleared and re-authentication is required

Logout Security

• Nonce Protection: Logout requires a valid nonce to prevent CSRF attacks
• Token Invalidation: Logout invalidates all tokens for the donor in the database
• Cookie Clearing: All magic link cookies are cleared on logout
• Session Clearing: All magic link session data is cleared

---

Database Structure

Magic link functionality uses the following database columns in the wp_charitable_donors table:

Columns

• magic_link_token – Stores the persistent access token (32-character string)
  • Set when verify key is first used
  • Cleared when token expires or is invalidated
  • Used for ongoing authentication
• magic_link_verify_key – Stores the initial verification key (32-character string)
  • Set when magic link email is sent
  • Converted to token on first use
  • Cleared after conversion or expiration
• magic_link_verify_throttle – Stores timestamp for rate limiting and token expiration
  • Used to track when verify key was created (for rate limiting)
  • Used to track when token was created (for expiration checking)
  • Format: MySQL datetime (Y-m-d H:i:s)

Donor Meta

• _charitable_magic_link_throttle_count – Tracks number of magic link requests in current throttle window
  • Incremented on each request
  • Reset when throttle window expires
  • Used with object cache to enforce rate limiting

---

Email System

The magic link email is a required email type that cannot be disabled while magic link is enabled.

Email Class

• Class: Charitable_Email_Magic_Link
• Email ID: magic_link
• Required: Yes (cannot be disabled while magic link is enabled)

Email Fields

The magic link email includes the following custom fields:

• {magic_link} – The secure URL to access the donor dashboard
  • Contains the verify key as magic_link_token parameter
  • Points to the donor dashboard page URL
• {donor_name} – The donor’s first name (or “Valued Donor” if not available)
• {expiration_time} – Human-readable expiration time (e.g., “2 hours from now”)

Email Template Tags

Standard Charitable email template tags are available, plus the custom fields listed above.

Email Filters

All standard Charitable email filters apply, plus magic link-specific filters listed in the Hooks and Filters section.

---

Shortcode

The magic link form can be displayed using a shortcode.

Shortcode

• Shortcode: [charitable_magic_link_form]
• Attributes: None currently supported
• Output: Displays the magic link request form

Form Process

1. User enters email address
2. Form validates email format
3. System checks if donor exists with that email
4. Rate limiting is checked
5. If allowed, magic link email is sent
6. Success or error message is displayed

Form Validation

• Email Required: Must be a valid email address
• Donor Must Exist: Email must be associated with at least one donation
• Rate Limiting: Must not exceed request limits

---

Helper Functions

The following helper functions are available for developers:

Check Functions

• charitable_is_magic_link_enabled() – Check if magic link is enabled
  • Returns: bool
  • Checks: Donor dashboard enabled, database upgrade completed, setting enabled
• charitable_is_authenticated_via_magic_link() – Check if current user is authenticated via magic link
  • Returns: bool
  • Checks session and token validity
• charitable_get_donor_id_from_magic_link() – Get donor ID from magic link authentication
  • Returns: int|false
  • Returns donor ID if valid magic link token exists, false otherwise

Class Methods

The Charitable_Magic_Link class provides the following public methods:

• get_instance() – Get singleton instance of the class
• get_token() – Get token from cookie or GET parameter
• is_valid_token($token) – Check if a token is valid and not expired
• is_valid_verify_key($token) – Check if a verify key is valid
• get_donor_by_token($token) – Get donor object by token
• get_donor_by_verify_key($verify_key) – Get donor object by verify key
• can_send_email($donor_id) – Check if magic link email can be sent (rate limiting)
• send_email($donor_id, $email) – Send magic link email to donor
• generate_verify_key() – Generate a new verify key (32-character random string)

---

Token Lifecycle

Token Creation

1. User Requests Magic Link:
   • Donor enters email on form
   • System generates verify key
   • Verify key stored in magic_link_verify_key
   • Email sent with verify key in URL
2. User Clicks Email Link:
   • Verify key validated
   • Verify key converted to token
   • Token stored in magic_link_token
   • Verify key cleared from database
   • Cookie set with token
   • Session created

Token Usage

1. Page Load:
   • System checks for token in cookie or GET parameter
   • Token validated (not expired, exists in database)
   • Session validated (donor ID matches)
   • Access granted if all checks pass
2. AJAX Requests:
   • Token validated on each request
   • Donor ID from token must match requested donor ID
   • Session donor ID must match token donor ID

Token Expiration

• Expiration Time: Configurable (default: 2 hours)
• Expiration Check: Based on magic_link_verify_throttle timestamp
• Expired Token Behavior:
  • Token is no longer valid
  • User must request a new magic link
  • Error message displayed

Token Invalidation

Tokens are invalidated in the following scenarios:

1. New Magic Link Requested: All existing tokens for the donor are invalidated when a new magic link is requested
2. User Logout: All tokens for the donor are invalidated on logout
3. Token Expiration: Expired tokens are automatically invalid
4. Session Mismatch: If session and token donor IDs don’t match, session is cleared

Logout Process

1. Logout Request:
   • User clicks logout link (requires nonce)
   • Nonce verified
   • Donor ID retrieved from session
2. Token Invalidation:
   • All tokens for donor cleared from database
   • Session data cleared
   • Cookies cleared
3. Redirect:
   • User redirected to homepage (clean URL, no query parameters)
   • Redirect URL can be filtered via charitable_magic_link_logout_redirect

---

Additional Notes

Compatibility

• Magic link works alongside standard WordPress user authentication
• If a user is logged in, magic link is bypassed
• Magic link only activates for non-logged-in users

Logging

The system logs magic link activities to the donor log:

• magic_link_sent – When a magic link email is sent
• magic_link_used – When a magic link is successfully used to access dashboard
• magic_link_failed – When a magic link attempt fails (invalid/expired token)

Debug Mode

When WP_DEBUG is enabled, detailed logging is available for:

• Token validation
• Session management
• Rate limiting
• Logout processing

---

Additional Resources

For more information about extending the magic link functionality:

• Charitable Developer Documentation
• WordPress Hooks and Filters Documentation
• Charitable GitHub Repository

---

Document Version: 1.0
Last Updated: Nov 2025