The Update Process

As people become more and more reliant on UserSpice, the goal is to make updating your code as painless as possible. Part of this involves not changing files unnecessarily. Whenever possible we will release patches that only overwrite the files which were changed.  We’ve also taken the version number out of each file.  The version number will only be changed in the file /users/includes/user_spice_ver.php and will be included in the admin panel by default.

When you download a patch the files will be in the same folders as they are in your site.  In other words, every patch will have the /user folder as we will always update the version number.  Some patches will be cumulative and some will be a single fix.  We’ll make that clear in the release below.

If you are upgrading from version 3.x, the only upgrade path is to go from 3.x straight to 4.0.0c.  From there you can apply any patches you want.  Please don’t try to go straight from 3.x to a different future version. The migration tool will not work for that.  You can get the 3 to 4 upgrade here.

Although updates are tested, you’re always encouraged to backup your files before patching. 

UserSpice 4.2 Patches

4.2.6 (From 4.2.3 or 4.2.4 or 4.2.5) –  April 18, 2017 – Lots of little patches. Thanks to all the users who submitted this stuff (Brandin, Trioxin).  Here’s a quick rundown.

Note: April – August is the busiest time of year for me in Alaska so I’m going to be concentrating on bug fixes rather than adding new features for the most part.
Note2: 4.2.4 was a botched release. Sorry about that.  Just apply this patch and you SHOULD be good to go.
Note3: 4.2.6 fixes a bug in user_settings.php  in 4.2.4 & 4.2.5.  If you already have 4.2.5 you, you can just update that one file along with users/includes/user_spice_ver.php

-Front end users are now forced to abide by your min/max password rules when editing passwords AFTER their account has been created.
-Admins can now edit passwords in admin_user.php
-A bug has been fixed in the “recent users” section of the admin panel if a user showed up in the list whose account has been deleted.
-A bug has been fixed for users who were redirected to the login page after being denied access
-A bug has been fixed regarding validation errors
-The bug for users who fail to check the terms and conditions box has finally been fixed. Sorry about that.

4.2.3 (From 4.2.2) – March 10, 2017 – SECURITY UPDATE – As part of our release update, our software is audited by a 3rd party looking for vulnerabilities.  Last full review was 4.1.8.  This one found some very minor bugs, but still worth fixing.  1 clickjacking vector was fixed in the header.  Also, now that js/css are being called from various CDNs, it is important to have integrity checks in those calls to make sure the code is not being modified by a man in the middle. This was fixed for all 3rd party CDN calls.  Additionally, I decided to change input fields from “text” to “password” for sensitive information in the admin dashboard and email settings to prevent people from seeing passwords. Note that out of necessity, these passwords/keys are stored in the clear in the database itself.  AND FINALLY – I think I found a universal fix for content sliding up under the header when resizing the screen.  Just in case it breaks stuff for you, this code is called in usersc/includes/bootstrap_corrections.php.  You can put whatever you want in there and it will be injected into the header.

4.2.2 (From 4.2.1d,e,f, or g) – March 6, 2017 – Rollup of previous bugfixes as well as new features.   Most of these changes primarily affect new installations by default but with a few changes in your init.php file, you should be up to speed.

Note: If you are upgrading and want to take advantage of the “Master Account” feature, you must add the line…
$master_account = [1];
to your users/init.php file.

New features:

New Check For Updates feature is built into the admin dashboard. This feature will be more automated over time. Because of this, version numbers will no longer have letters.

Master Account lets you mark the sign offline to everyone except the users whose ids are in the $master_account array in the init. Those users just see a warning message that the site is offline. login.php is always online.

Timezone is now set during installation.  Existing users should consider changing their timezone in  users/init.php unless you happen to live in Toronto.

Recaptcha is now fully disabled by default on installation (as opposed to only on join as it was before).


4.2.1g (From 4.2.1d OR 4.2.1e or 4.2.1f) – March 2, 2017 – Rollup of bugfixes for version d,e, and f.  Fixes header/footer bugs. Fixes a messaging bug in some browser versions.  Hopefully will fix some issues some users were having on some servers with jQuery. Removed double jQuery call in join form.  Just overwrite the files and you’re good to go. Please give feedback in the forums.
New Feature: There are 2 new scripts in usersc/scripts. They allow you to take control over what happens if a user bumps into our “not logged in” or “doesn’t have permission” checks.  You can do anything from database updates to redirecting them somewhere else. The sky’s the limit.

4.2.1d (From 4.2.0 any version) – February 20, 2017 – New experimental message system. Ability to alter echouser function. Ability to allow username changes. Ability to have recaptcha for join form only.  This is a BIG update with a very complicated patch. PLEASE backup your files and database just in case.  Note, users of 4.2.0 final or 4.2.0b should run patchme420.php.  Users who were on a previous version of 4.2.1(rare) should run patchme421.php to fix a minor bug.

4.2.0b (From 4.2.0 Final) – February 18, 2017 – Bug fixes found by users after installing 4.2.0. Primarily around Facebook Oauth and showing the words UserSpice instead of your site_name as defined in the database.
4.2.0 Final (From 4.1.8c OR 4.2.0 Beta) – February 13, 2017 – Significant improvements from the “Release Candidate” below. See for documentation.   Expect to spend about 10-20 minutes getting the credentials for the social logins setup.  They’re all disabled by default.

1. Backup your files and database and anything that’s important to you.
2. If you have not upgraded to at least version 4.1.8c, do that before running this patch.
3. Copy all the files to your server, overwriting existing files.
4. Patch your database
a. If you’re running version 4.1.8c run patchme418.php (ignore all errors)
b. If you’re running version 4.2.0 beta, run patchme42beta.php (ignore all errors)
5. Delete both patchme files for security reasons.
6. Enjoy

4.2.0 Beta (From 4.1.8c) – November 27, 2016 – Beta but Stable – This is the release candidate for version 4.2.  It includes Facebook and Google social logins. See for documentation.   Expect to spend about 10-20 minutes getting the credentials for the social logins setup.  They’re all disabled by default.

Note: YOU MUST PATCH YOUR DATABASE by running the patchme.php file in the root folder. This will give your database the default spaces to store all the new settings.

Note2: Because no data is migrated (i.e. changed) in this update, you can replace the changed files with ones from 4.1.8c to roll back your install even after patching the database. No harm no foul if you don’t like it.

Also added in 4.2…

  • Password rules are now stored in the database with a new strength meter from user gtilflm (Note that symbol rule is suggested, not enforced).
  • Hooks have been put in for version comparision and automatic update detection.
  • Force SSL/HTTPS is no longer considered experimental
  • Admin pages is now a little clearer (red and green colors) if a page is private or public…thanks to picassoo for this.

UserSpice 4.1 Patches

4.1.8c (From 4.1.8b) – November 6, 2016 – Recommended Several bug fixes. Just unzip over your current install and replace files. Backup your stuff first. WARNING: if you are using the analytics.php file, this update will overwrite your customizations.  The main problem was bad commenting in the file.  You should probably just fix it manually. It’s a new feature, so I’m sure it’s not widely used yet.

install/install/includes/sql.sql – Not for upgraders, but new installers get cleaned up default sql with all the ids starting down low where they belong. Several useless things removed and proper auto-increments.
users/join.php – Got rid of ‘company’, reduced min username to 2.
users/views/_join.php – Got rid of ‘company’, reduced min username to 2.
usersc/includes/analytics.php – Fixed a bug that showed up in various annyoing ways on different systems. Caused AJAX and Headers Already Sent Errors.
users/includes/user_spice_ver.php – Obligatory


4.1.8b (From 4.1.7b) – October 31, 2016 – Super Strongly Recommended – I have had various people try to pound on UserSpice 4.0 and 4.1 and try to break things over the past 9 months, but I decided to do a full on pentest/secturity audit from several different automated firms.  There’s good news.  There isn’t a ton of “the sky is falling” stuff in the old code, but I’ve cleaned up a lot of stuff (with PLB’s help) that will make your code more secure.  NOTE: I will be posting the full methodology and report and outstanding issues in a separate post.  For now…just update.

What you need to know:  Various new .htaccess files have been added. Bootstrap and FontAwesome have been updated to the latest versions.  If you use the custom scripts in the usersc folder, don’t go overwriting your scripts willy-nilly. They were, however, what was causing the extra /’s in the urls.  I’ve fixed that. More details to come, but this is a BIG update with lots of files.

What’s optional: The /usersc stuff and the css/js/fonts files are all optional, but adding the .htaccess files are strongly recommended if your server has directory listings turned on by default

4.1.7b – (From any version 4.1.3,4.1.4,4.1.4b,4.1.5,4.1.6,4.1.6b, or 4.1.7 )October 22, 2016 – Strongly Recommended – This patch includes everything in the one below, but also includes these bug fixes.

users/user_settings.php – A missing = sign was causing email addresses to become not verified even if email verification was turned off. This was a problem because if this happened, the user had no way to verify. Many thanks to Kighlander for finding this bug.
users/admin_users.php – Admins can now create usernames as short as two characters.  I also added back the automatically generated profile for new users.
users/includes/user_spice_ver.php – Gives you peace of mind that your UserSpice is up to date.

4.1.7 – (From any version 4.1.3,4.1.4,4.1.4b,4.1.5,4.1.6,or 4.1.6b)October 19, 2016 – Strongly Recommended – Let’s just pretend that version 4.1.6 never happened, mmmkay?   This is a complete rollup release of all updates to take ANY userspice version 4.1.3 or later all the way up to 4.1.7.  The individual issues below are listed. This release in particular finally addresses encoding issues and has been thoroughly tested for email verification, password resetting, and all things email. If there is a use case I’ve missed, please let me know. It also fixes an unlikely but possible edit_profile.php bug. Much thanks to Nikolai, Sebastian, PLB, and Brian for pointing me in the right direction on this stuff.

4.1.6b – (From 4.1.5) – October 16, 2016 – NOT Recommended – Fixes a bunch of bugs found in the forums.   NOTE: To install this patch, unzip the patch over your current install, it will overwrite the following files.

Many thanks to everyone in the forums who submitted bugs and often bug fixes. You make patching this project MUCH easier.

Note: If you downloaded the “original 4.1.6 and you are missing some navigation links, just steal the navigation.php from this package”

This is a substantial bugfix, usability fix, and new feature release.  A post in the forums will give a little more info behind some of this stuff.

userc/includes/analytics.php – Added a place to put your custom Google or other Analytics code.
usersc/includes/custom_functions.php – Added a place to put your custom helpers/functions.
users/admin_users.php – When creating users in the backend, users who were created with a permission level other than “user” (such as admin), were not given “user” permission by default. This is fixed.
users/classes/Redirect.php – Added support for PLB’s redirect with a message feature and custom redirects.  More on this in the forum at the post listed at the top of this bugfix.
users/classes/User.php – session_unset and session_destroy are now part of the class on logout.
users/edit_profile.php – It is possible that some users who upgraded may not have received this fix, so I’m re-pushing it out.
users/forgot_password.php – Fixed overzealous use of rawurlencode. Changed rawurlencode to urlencode.
users/helpers/language.php – Added an error message that was missing for manual account creation.
users/helpers/us_helpers.php – Added PLB’s redirect, custom functions, and custom analytics.
users/includes/header.php – Test feature  – if an err get message is found in the url, it is sanitized and displayed.
users/includes/navigation.php – Capitalized the first letter of the username in the navigation bar – WARNING, if you’ve modified your navigation php, do not install this file or it will overwrite your changes.
users/includes/users_spice_ver.php – If you’re rocking 4.1.6, you should see it in the admin panel. Major upgrade over the previous version of this file.
users/join.php – Lowered required username length to 2 for people who like to keep things simple or have names like Bo or Jo.
users/login.php – Put in the groundwork for AfterLoginGoto feature
users/user_settings.php – Corrected minimum password length to 6 as pointed out by user Angel.
users/views/_email_template_forgot_password.php -Fixed underzealous use of rawurlencode. Changed regular to raw.
users/views/_join.php – Starred currently required fields.

4.1.5 – (From 4.1.4b)September 11, 2016 – Recommended – Fixes a bunch of bugs found in the forums.   NOTE: To install this patch, unzip the patch over your current install, it will overwrite the following files.

Many thanks to PLB, Brian, and Anphung for the bug reports and patches.

users/_blank_pages/project_root.php – Fixes a bug where the securePage function was commented out by default
users/classes/Config.php – Adds a return false if no configuration data is found
users/classes/Input.php – Allows the input::get function to process arrays.
users/includes/user_spice_ver.php – Lets you know that you’re now rocking 4.1.5
users/admin_users.php – Fixes yet another bug when you delete a user. This bug only showed up on certain configurations.
users/email_test.php – Better formatted email test and notes on debugging email configuration courtesy of PLB
users/forgot_password.php – We are now properly encoding email addresses to deal with people who have non-traditional addresses.
users/join.php – We are now properly encoding email addresses to deal with people who have non-traditional addresses.
users/user_settings.php – Added an explanation of how to change your profile pic.
users/verify.php – Changed line 27 to Redirect::to($us_url_root.’users/verify.php’); for people who were having verify redirect issues. Feel free to hard code this with something else if you need to.
users/verify_resend.php – We are now properly encoding email addresses to deal with people who have non-traditional addresses.

4.1.4b – (From 4.1.3)August 29, 2016 – Recommended – Fixes a bunch of bugs found in the forums.   NOTE: To install this patch, unzip the patch over your current install, it will overwrite the following files.

users/email_settings.php (your settings are safe in the database)
users/user_settings.php (again, your settings are safe)

Many of these patches are documented at  <a href=”″>Debugging With Dan</a>.

Bugs Fixed
-User was required to verify email even after resetting password (which requires proof of email).  Forum Discussion here. Credit: user plb
-Verify.php link was wrong – Forum Discussion here.  Credit: user plb.  Video here.
-Bio was not being created when a user was manually created.  Sorry, I can’t find the original post to give credit 🙁  Video here.
-Email settings not being saved before testing. Forum Discussion here.  Credit: user plb.  Video here.
-User was able to (after verifying once) change their email address to anything.  Forum Discussion here. Credit: user plb. Video here.
-User could change username even if it was supposedly disallowed. Forum Discussion here. Credit: users plb and firestorm.  Video here.
-Error messages popped up when deleting a user since the manual user creation feature was added.   Forum Discussion Here. Credit: user firestorm. Video here.

PLEASE NOTE: There are a few more usability features coming soon.  I decided to break these bugs out so we could fix errors in this release and add features in the next one.

4.1.3 – (From 4.1.2)July 24, 2016 – Recommended – Fixes a few random database and usability bugs found in the forums. Gives better (working) guest tracking.  Also allows admins to create new users in the admin_users panel without having to walk through the join process.  NOTE: To install this patch, unzip the patch over your current install, it will overwrite the following files.

IN ADDITION: you also need to run the patchme.php file to make a quick update to your database. It is strongly recommended that you backup your files and your database first.

4.1.2 – (From 4.1.0 and/or 4.1.1) May 22, 2016 – Recommended – Fixes the initial bugs found on release of version 4.1. Updates the user class, various email functions and some built in helper functions. View 4.1.1 changelog here and the 4.1.2 changelog here.

UserSpice 4.0 Patches

(Current version is located in /users/includes/userspice/user_spice_ver.php)
4.0.0f – Note – If your server is blocking your css files after upgrading to 4.0.0f, the fastest fix is to delete the .htaccess files in all the subfolders.  Sorry about that. The same issue could be going on in the beta as well.  We will release a new version ASAP.

4.0.0e to 4.0.0f – April 11, 2016 – Strongly Recommended – This patch adds .htaccess files to folders that probably should have had them.  Your php files were always safe, but it’s nice to shut down people who are playing around with urls.  Also included in this patch is a the ability to block a user.  Simply go to manage users, click a user’s name, select block and update. They will be presented with a banned message.  It’s something we were toying around with on the UserSpice 4.1 alpha and decided to roll out with the security update. This is an in-place update that adds a lot of .htaccess files and then replaces your existing us_helpers.php file, your admin_user file and your admin_user view.  It shouldn’t break anything.  If you get strange errors of people being banned who shouldn’t be, let us know in the forums, but everything has been tested and seems to work fine.  Best of all…no need to update your database. This structure was baked in all along in the users table as “permissions.”  1 is not blocked, 0 (as in zero permissions) is blocked.

4.0.0d to 4.0.0e March 28, 2016 – Recommended – These are relatively simple bug fixes in 4.0 that I wanted to get out of the way before beginning on 4.1.  Thanks to everyone in the forums who is pointing this stuff out.  What’s new? I rolled in that fix to the profile system that has been available for about a month into 4.0.0e.  Also fixed were some ugly errors if someone didn’t enter a username or password or if you created a new page but never added it to the database.  Now UserSpice is much more clear about what’s going on.  Also, “remember me” is no longer checked by default on the login form for security reasons.  There are 2 patches.

OR – This one will take you from ANY 4.0 release up to 4.0.0e.


4.0.0 to 4.0.0d – February 22, 2016Recommended – Apparently menus are hard. Especially conditional ones.  It’s not a security vulnerability, but administrator links were coming up in regular users’ menus. This patch fixes that.  There will be a completely new navigation overhaul in version 4.1, but this is a temporary solution to the problem. It can be unzipped and will work by dropping it right on top of any version of 4.0 from beta through 4.0.0c.

4.0.0 to 4.0.0cFebruary 17, 2016Recommended – This cumulative patch fixes a bug where the user was given a 404 when trying to reset their password from certain pages.  It also removes the version number from the header and puts it in a separate file. This allows us to change the version number without constantly modifying your header files.   You can install this patch on 4.0.0 or 4.0.0b (formerly referred to as 4.0.1). Because this bug could cause a bad user experience, it is recommended.

3.2.0 to 4.0.0 February 1, 2016.  Watch this video for more info…