Understanding and Troubleshooting User Access
User access is a critical piece of the process of accepting donations on your GiveWP site. From allowing donors access to their own (and only their own) donation history to giving recurring donors the ability to cancel their subscriptions from the site, there are many moving parts to user access. This article will walk you through what features GiveWP has for user access, and how you can troubleshoot issues related to user access on your GiveWP site.
What is a Session and why do we need them?
A critical component of donor access to donation data in GiveWP is what is called a session. Sessions are server-side collections of data which enable web applications to keep a record of what data a certain user has access to.
There are two types of sessions that are important to understand in the context of WordPress and GiveWP: Database sessions and PHP sessions. The distinction between them is where the data is stored.
In database sessions, the session data is stored in the database. So each time a user needs to be validated, there’s a hit on the database to confirm the session. As you might imagine, on high-traffic sites that’s not ideal. For this reason, GiveWP defaults to PHP sessions.
PHP sessions store the session data directly in the PHP files on the server.
By default, WordPress does not use sessions (database or PHP). This is known as being “stateless” because there is nothing on the server side to remember the state of a given user across multiple page loads.
WordPress instead uses only cookies to validate users. Cookies are bits of data stored in the browser, which validate who a user is. When a user logs into a default WordPress install, WordPress sets a cookie in the user’s browser. They are only validated if they are logged into WordPress.
This creates an interesting problem for situations like donations or other transactions where you need to be able to verify a donor who is _not_ a WordPress user. One such example would be to show them the Donation Confirmation page. Without a mechanism to tell the server “this is the correct person to see the donation history for ____ donor” it is impossible to restrict access to that data.
This is why GiveWP uses sessions. When a donor clicks “Donate Now” and GiveWP processes the donation, it also initiates a session.
How does Give handle Sessions?
GiveWP starts a session on a new donation. It saves a cookie in the browser to validate that session. This allows for securely displaying donation data (regarding only this donation) to this browser, regardless of whether they are a WordPress user, or are logged in.
By default, a GiveWP PHP session lasts one week. This timespan can be modified on the Settings page at Donations > Settings > General (tab) > Access Control (section).
That means that regardless of login, a donor initiates a PHP session for that browser on that device that will last one week. So if they check the donation confirmation page 4 days later, it will still show them the correct donation receipt.
How do Sessions get broken?
Sessions can be broken in variety of ways. The most common is caching, since by its very nature caching is meant to prevent code on the server from being executed, and instead delivering a cached version of the code’s output to subsequent users. This is obviously problematic for sessions.
Sessions can also be broken by load balancers, which are used by high-end hosting companies as a way to serve website assets from multiple servers simultaneously. For very high traffic sites, this means that the session data would need to be maintained on both servers simultaneously.
Finally, in addition to high-end hosts—on the other end there are some hosts which simply don’t support sessions. That can cause issues for GiveWP.
GiveWP has a roadmap for moving to a more cache-proof solution than straight PHP sessions, and if you want to follow along on that development, it all happens in the open at our GitHub repository.
Common Session Problems
The most common issue reported by broken sessions is donors who can’t access the Donation History page. This is the page in your GiveWP site with the [donation_history] shortcode. When a session is broken due to one of the problems listed above, the donor is not able to see their donation history.
In addition to the donation history page, any page that requires access to specific donor data can be affected by session problems. If a session is broken in the midst of a donation for example, the donation will still go through but the donation confirmation page (which should display the [[give_receipt]] shortcode output) will show a confusing message about “not having the payment key.” If email access is enabled (see below for a more full explanation) that page will display a form asking for an email.
How to Resolve Session Problems
The best way to diagnose and repair session issues with GiveWP is first to understand how they work (which this document has hopefully cleared up). Anecdotally, caching is the culprit 90% of the time.
Pro tip: it’s almost always caching that’s causing your problem.
— Ben Meredith (@benUNC) August 29, 2017
But if caching has been disabled, and you are still experiencing problems, here are some troubleshooting steps you can take:
There’s two main ways to set your site to have more reliable sessions with GiveWP:
First, Try using this free plugin which switches your site to use native PHP Sessions (in the event that your host does not use native PHP session for some reason)
If that plugin doesn’t resolve your issues, next you can force your GiveWP install to use Database sessions instead of PHP sessions. This can result in slowdowns and additional server load, especially for higher traffic sites, so it’s a last resort. To force GiveWP to use database sessions, set this in your wp-config.php file: `define( ‘GIVE_USE_PHP_SESSIONS’ , false);`
What is Email Access and why does GiveWP use it?
Email Access is a feature added as of GiveWP version 1.4 to give donors access to their donation history, without being logged in, or a part of a GiveWP PHP session. This is handled via a special link sent to their email. Here’s how that works on the back end:
GiveWP Site creates a form (for users who aren’t logged in or in a current PHP session) in place of the normal output of the Donation History or Donation Confirmation shortcodes.
That form asks the donor for an email address.
If the email address is validated as having a donation history, an email is sent containing a token (random string of characters) in a URL, and the token is saved in the database.
Back at the site, the token is verified to have been the same token sent from the site to the email.
If everything checks out, the donor is given access to their donation history, and a cookie is set in the donor’s browser. The cookie validates the token, and the token expires after the same amount of time as a GiveWP PHP session. Token expiration happens regardless of whether the donor clicks the link back to the site within the email.
So, if a donor submits the email access form at 7 PM today, and in the settings at Donations > Settings > General (tab) > Access Control (section) the session length is 7 days (the default), they have until 7 PM 1 week from today to click the link in their email, before they’ll need to re-enter their email address at the GiveWP site.
Tools and Resources for Understanding how Your Site uses Sessions and how to fix it.
- This discussion of Sessions and cookies on Stack Overflow was helpful in writing this article
- This W3Schools article is also helpful in getting a deeper understanding of sessions.
- Tom McFarlin with a high-level overview of PHP session in WordPress
- GiveWP’s Access Control documentation
