Releases: SMCoThrift/donation-manager
Release list
Improved Session Management, Redirect Handling, and Debugging Capabilities
Version 5.6.0 of Donation Manager is a major update focused on backend stability, session management, and debugging capabilities. This release represents a significant architectural improvement to the multi-step donation flow, with enhanced session persistence, smarter redirect handling, and modernized API integrations. These updates provide a more reliable and maintainable foundation for processing donor submissions while improving the developer experience with better debugging tools.
Complete Session Flow Handler Rewrite
The donation form submission handler has undergone a comprehensive rewrite to improve reliability and reduce edge cases. Form processing has been moved from the init hook to template_redirect, ensuring that only front-end template loads trigger donation flow processing. This change eliminates duplicate triggers caused by asset preloading and admin requests, resulting in more predictable behavior throughout the donation process.
The routing logic has been significantly enhanced with better step detection and validation. Each step of the donation flow—from ZIP code validation through organization selection, donation description, screening questions, contact details, and pickup scheduling—now has more robust detection patterns that properly distinguish between GET and POST requests. Additionally, a new redirect bounce protection mechanism prevents the system from re-processing form submissions immediately after redirecting, eliminating a class of duplicate processing bugs.
Enhanced Session Management & Persistence
Two new utility functions provide centralized, secure session handling throughout the application. The donman_start_session() function standardizes session initialization with secure configuration including httponly cookies, SSL support when available, and strict mode enabled. This function uses a static guard to prevent multiple initialization attempts and ensures the donor session array is properly initialized with unique request IDs for tracking.
The new donman_safe_redirect() function serves as a centralized redirect helper that preserves donor session state during navigation through the multi-step flow. This function marks the session as redirecting, adds tracking references, generates unique request IDs per navigation event, and guarantees session persistence before redirecting. It also includes comprehensive debug logging with caller file and line number tracking for easier troubleshooting.
Session reset logic has been hardened to prevent accidental data loss during active donation flows. The system now tracks whether a donor is actively in the donation process using an _in_flow flag, and only resets session data when landing on a start page (homepage, donate-now, or city pages) while NOT in an active flow. A new reset attribute has been added to the donation form shortcode for manual session clearing when needed. This prevents the frustrating scenario where a user's donation data would be lost if they momentarily navigated to the homepage during their submission.
CHHJ API Integration Updates
The integration with CHHJ has been updated to post to their new API endpoint. The system now dynamically determines the account type based on whether a company name is present in the donation—commercial accounts (type 3) are used when a company name is provided, while residential accounts (type 5) are used for individual donors. This automatic detection ensures proper categorization in the CHHJ system without requiring manual intervention.
The API posting logic now uses configurable CHHJ_API_EP and CHHJ_API_TOKEN constants for better environment management and includes improved error logging when these credentials are missing or misconfigured.
Debugging System Enhancements
The debugging system has been upgraded with flow-based tracking using unique request IDs. Each navigation through the donation process now receives a UUID that's tracked throughout the session, making it significantly easier to trace a specific donor's path through server logs. Debug headers are now printed only once per PHP execution and once per flow, preventing log clutter while maintaining visibility.
The uber_log() function now includes session-aware header printing with color-coded output (green start banners) and improved timestamp formatting. The debug system creates and tracks flow IDs automatically, ensuring continuity across redirects and page loads. This makes it substantially easier to diagnose issues in production environments where multiple donors may be active simultaneously.
Security & Stability Improvements
All redirect calls throughout the application have been updated to use WordPress's wp_safe_redirect() function instead of direct header() calls. This improves WordPress compliance, provides better security validation of redirect URLs, and ensures consistent behavior across the application.
Variable protection has been strengthened across the codebase with isset() checks added before accessing potentially undefined variables. This includes protection for company name field checking, pickup location variables, and session variables. These defensive programming practices reduce PHP notices and prevent potential errors in edge cases.
Next page URL handling in the donation form shortcode has been improved with better validation. The system now properly handles empty or null nextpage attributes, validates external URLs, and consistently formats internal URLs for more predictable redirect behavior.
User Interface Refinements
The contact details form has been updated to more accurately reflect modern communication preferences. The phone number field label has been changed from "Phone" to "Mobile Phone," setting clearer expectations for donors about the type of phone number being requested. This small change improves data quality by encouraging donors to provide the most appropriate contact number for pickup coordination.
Technical Details
- 26 files modified with 431 additions and 106 deletions (net +325 lines)
- Compatible with existing installations—no database migrations required
- Recommended to clear PHP session cache after deployment
- Developers should review custom callback implementations for compatibility with the new template_redirect timing