The auto_increment problem and its symptoms

When you export the WordPress database and then import it again, either via phpmyadmin or via mysqldump and the mysql CLI, all sorts of things can (and often will) go wrong. This can be understandably very stressful, especially on a live system. Please take a deep breath and read on.

I did a dump of my (fortunately development) environment and then imported it again. At first glance, all was working perfectly.

Then, all of a sudden I noticed that the Administrator user had no rights to create posts or pages. The usual Publish button was replaced with Submit for review.

Naïvely my first thought was to install a plugin to fix roles and capabilities. Sure enough, the admin user had no right to create posts or pages. When I tried to give those rights, I saw the following in my logs:

PHP message: WordPress database error Duplicate entry '0' for key 'PRIMARY' for query INSERT INTO `wp_usermeta` (`user_id`, `meta_key`, `meta_value`) VALUES (1, 'wp_capabilities', 'a:1:{s:13:\"administrator\";b:1;}') made by require_once('wp-admin/admin.php'), do_action('users_page_users-user-role-editor'), User_Role_Editor->edit_roles, Ure_Lib->editor, Ure_Lib->process_user_request, Ure_Lib->permissions_object_update, Ure_Lib->update_user, WP_User->add_role, update_user_meta, update_metadata, add_metadata

(I have debug logs enabled in my development environment. If you’re in a production environment you might not see this.)

Why would a primary key be set to 0 you ask? A quick glance at the structure of the wp_usermeta table via phpmyadmin reveals that the primary key column had no auto_increment flag.

SQL INSERT statements from various plugins were inserting rows in various tables with the primary key being undefined (and therefore set to a default of 0). Since primary keys have a unique constraint, attempting to do a second insert to the same table fails, causing all sorts of havoc.

For some reason the auto_increment flag had not been preserved when I re-imported the SQL dump. Everything else seemed to be in order though. I did not investigate why this happened but decided to simply fix this.

Coding is the solution

By now I could see the front-end but was not able to login to the admin interface any more. Any INSERT query to the database, including those that store session information upon login, were failing. As I had quite a lot of tables, I decided not to do this manually, but to write a generic script.

As a side-note, the script needs to connect with the NO_ZERO_DATE SQL mode. WordPress uses a lot of DATETIME fields with a default value of 0000-00-00 00:00:00 and this script will be very unhappy if this mode is not set.

Pseudocode

for all tables in database
    get the primary key column's name and type
    get the next available primary key value
    change the row with zero primary key so it has the next available primary key
    set the auto_increment flag to the primary key column

Note: The above assumes that all the primary keys are numeric. YMMV.

What to do:

Next is a PHP listing of the above solution. Here’s what to do:

1. Check to see that your issue is actually one of missing auto_increment flags. This script will only repair this particular error.
2. Check to see that all your primary keys are numeric. There shouldn’t be an issue if some aren’t but you might have to hack the code manually or go update the structure of those tables via phpmyadmin.
3. Change the host, dbname, username and password in the code to those that match your system.
4. Backup your database (I guess you already have a backup and that’s what caused the issue, but still, you want to be able to go back if something goes wrong when running this.) You are solely responsible for any damages including data loss from running this script. Don’t blame me for corrupting your data please. Read and understand the code first!

The PHP script

Save this in a file, take another deep breath, and run it via the PHP CLI. I hope it solves your MySQL woes. Good luck buddy.

<?php

// change these settings
$servername = 'localhost';
$username = 'dbuser';
$password = 'password';
$db = 'database';

// connect
$conn = new mysqli($servername, $username, $password);
try {
    $conn = new PDO("mysql:host=$servername;dbname=$db", $username, $password, array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET sql_mode="NO_ZERO_DATE"') );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION );
    echo "Connected successfully";
} catch(PDOException $e) {
    exit( "Connection failed: " . $e->getMessage() );
}

// get all table names
$stm = $conn->prepare('SHOW TABLES');
$stm->execute();
$table_names = array();
foreach ( $stm->fetchAll() as $row ) {
    $table_names[] = $row[0];
}

// for all tables
foreach ( $table_names as $table_name ) {
    echo "\nRepairing table $table_name...\n";

    // get the primary key name
    $stm = $conn->prepare( "show keys from $table_name where Key_name = 'PRIMARY'" );
    $stm->execute();
    $key_name = $stm->fetch()['Column_name'];

    // get the primary key type
    $stm = $conn->prepare( "show fields from $table_name where Field = '$key_name'" );
    $stm->execute();
    $key_type = $stm->fetch()['Type'];

    // if there is a primary key
    if ($key_name) {
        echo "Primary key is $key_name\n";

        try {
            // if auto_increment was missing there might be a row with key=0 . compute the next available primary key
            $sql = "select (ifnull( max($key_name), 0)+1) as next_id from $table_name";
            $stm = $conn->prepare( $sql );
            echo "$sql\n";
            $stm->execute();
            $next_id = $stm->fetch()['next_id'];

            // give a sane primary key to a row that has key = 0 if it exists
            $sql = "update $table_name set $key_name = $next_id where $key_name = 0";
            echo "$sql\n";
            $stm = $conn->prepare( $sql );
            $stm->execute();

            // set auto_increment to the primary key
            $sql = "alter table $table_name modify column $key_name $key_type auto_increment";
            echo "$sql\n";
            $stm = $conn->prepare( $sql );
            $stm->execute();

        } catch (PDOException $e) {
            echo "\n\nQuery: $sql\nError:" . $e->getMessage() . "\n\n";
        }
    } else {
        echo "No primary key found for table $table_name.\n";
    }
}
echo "\n\nFinished\n";
$conn = null;

If I have helped you get your site up and running, you can donate a few Satoshis at: bc1qjkgp8u2jwy2n9k20avjweuy7etsjfpfplvf99q

The post auto_increment flag repair on primary keys of a WordPress MySQL database appeared first on Alexandros Georgiou.

Some things to note about dismissible notices

Don’t you just hate how this functionality has still not made it into core? Legend has it that dismissible notices were introduced back in WordPress 4.2, but that only means that when you click the little “x” at the top right, the notice box becomes hidden. The way to enable this is that you add a .is-dismissible class into your notice’s markup:

<div class="notice notice-warn is-dismissible">your message here</div>

And that hides the box. Until the next page refresh. This is not only annoying, it also goes against the WordPress.org guidelines:

Upgrade prompts, notices, and alerts should be limited in scope and used sparingly or only on the plugin’s setting page. Any site wide notices or embedded dashboard widgets must be dismissible. Error messages and alerts should include information on how to resolve the situation, and remove themselves when completed.

So for those of us aspiring to be hosted on WordPress.org it’s a necessity, rather than a luxury feature, to be able to let the user dismiss notices persistently.

Requirements analysis

WordPress tradition has it that you store an option in the database. That way you know not to show the same notice again. But this is something that you have to do over and over again, so it’s exactly the kind of thing that you want to include in all your code as a library. You want something that can be easily called from wherever, so the tried and true singleton pattern will do. You need the ability to be able to assign a slug to your notice, so you know how to store it in the options table. But you also want to be able to show the occasional non-dismissible notice. Finally, let’s be nice and clean up after ourselves. The options will be deleted when our plugin is uninstalled.

Let’s do this!

Writing code with class

We need something that can be included from our plugin (or theme). Let’s make a singleton class that can hold arrays of different types of notices (success, info, warn, error):

<?php

// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( 'MyPlugin_Admin_Notices' ) ) {

    class MyPlugin_Admin_Notices {

        private static $_instance;
        private $admin_notices;
        const TYPES = 'error,warning,info,success';

        private function __construct() {
            $this->admin_notices = new stdClass();
            foreach ( explode( ',', self::TYPES ) as $type ) {
                $this->admin_notices->{$type} = array();
            }
        }

        public static function get_instance() {
            if ( ! ( self::$_instance instanceof self ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }
    }
}

MyPlugin_Admin_Notices::get_instance();

Nice. This is a useful bucket where we can throw in notices. They will be retrieved for rendering only later, when we will add code to the admin_notices action.

An API for entering notices from our code

For now, let’s add in some methods to our class for populating our notice arrays:

public function error( $message, $dismiss_option = false ) {
    $this->notice( 'error', $message, $dismiss_option );
}

public function warning( $message, $dismiss_option = false ) {
    $this->notice( 'warning', $message, $dismiss_option );
}

public function success( $message, $dismiss_option = false ) {
    $this->notice( 'success', $message, $dismiss_option );
}

public function info( $message, $dismiss_option = false ) {
    $this->notice( 'info', $message, $dismiss_option );
}

private function notice( $type, $message, $dismiss_option ) {
    $notice = new stdClass();
    $notice->message = $message;
    $notice->dismiss_option = $dismiss_option;

    $this->admin_notices->{$type}[] = $notice;
}

Notice the visibility of the functions. The four public functions that comprise our API all defer to the private function that does the data collection. We’ll let the user enter a message string, and optionally give a slug with the dismiss_option parameter. If set, this will be part of the database option’s slug.

Writing the markup

We have a mechanism for adding notices into our memory, now let’s dump them to the admin area as markup. This will happen on the admin_notices action, so first add this to the constructor:

add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );

and then let’s actually write the markup. I’ve chosen to show notices in decreasing levels of severity, hence the nested loops:

public function action_admin_notices() {
    foreach ( explode( ',', self::TYPES ) as $type ) {
        foreach ( $this->admin_notices->{$type} as $admin_notice ) {

            $dismiss_url = add_query_arg( array(
                'myplugin_dismiss' => $admin_notice->dismiss_option
            ), admin_url() );

            if ( ! get_option( "myplugin_dismissed_{$admin_notice->dismiss_option}" ) ) {
                ?><div
                    class="notice myplugin-notice notice-<?php echo $type;

                    if ( $admin_notice->dismiss_option ) {
                        echo ' is-dismissible" data-dismiss-url="' . esc_url( $dismiss_url );
                    } ?>">

                    <h2><?php echo "My Plugin $type"; ?></h2>
                    <p><?php echo $admin_notice->message; ?></p>

                </div><?php
            }
        }
    }
}

Note how we show a notice only if the DB does not have a corresponding option named myplugin_dismissed_$dismiss_option. We’ll need a mechanism to set that DB option when the user clicks to dismiss the notice. We will do this from JavaScript, making a call with that option name as a GET parameter, so that we know to set the correct database option.

Notifying the backend from the admin front

When a notice is dismissible, we output a data-dismiss-url attribute in the HTML. We’ll use that from JavaScript to make a call to that URL:

/**
 * Admin code for dismissing notifications.
 *
 */
(function( $ ) {
    'use strict';
    $( function() {
        $( '.myplugin-notice' ).on( 'click', '.notice-dismiss', function( event, el ) {
            var $notice = $(this).parent('.notice.is-dismissible');
            var dismiss_url = $notice.attr('data-dismiss-url');
            if ( dismiss_url ) {
                $.get( dismiss_url );
            }
        });
    } );
})( jQuery );

Pretty standard stuff. When a dismissible notice from our plugin is clicked on its .notice-dismiss, get the dismiss_url and call it. I guess I could have used a fancy framework like VanillaJS for this, but I chose plain old jQuery instead :-p

Don’t forget the usual enqueue script shenanigans:

public function action_admin_enqueue_scripts() {
    wp_enqueue_script( 'jquery' );
    wp_enqueue_script(
        'myplugin-notify',
        plugins_url( 'assets/scripts/myplugin-notify.js', __FILE__ ),
        array( 'jquery' )
    );
}

and add this to our constructor so the enqueuing will actually happen:

add_action( 'admin_enqueue_scripts', array( &$this, 'action_admin_enqueue_scripts' ) );

Perfect. Our little piece of JavaScript code now lives in the WordPress admin screens.

Setting the DB option

Now we’ll just need to catch the request on the PHP side and set a database option. Let’s do this on the admin_init action:

add_action( 'admin_init', array( &$this, 'action_admin_init' ) );

…and this is the code that will set an option in the database. Note how the name is constructed from the GET parameter in the request URL.

public function action_admin_init() {
    $dismiss_option = filter_input( INPUT_GET, 'myplugin_dismiss', FILTER_SANITIZE_STRING );
    if ( is_string( $dismiss_option ) ) {
        update_option( "myplugin_dismissed_$dismiss_option", true );
        wp_die();
    }
}

Once the option is set, we can just let WordPress die. No need to return the admin interface to the browser, this is just a background AJAX call.

Cleaning up after ourselves

Unfortunately, even in this day and age, many developers don’t think it’s important to clean up the trash they leave in the poor user’s database. This is even more infuriating when you consider that it rarely takes more than a couple of lines of code. Don’t be that guy. Create an uninstall.php file with the following content.

<?php
if ( defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    global $wpdb;
    $wpdb->query( 'DELETE FROM wp_options WHERE option_name LIKE "myplugin_dismissed_%";' );
}

We can exploit the fact that we know the common prefix of all the dismissal DB options, and thus we can delete them all in one go, circumventing the delete_option() function altogether:

Expecting the unexpected

If you put together all of the above you already have a nice way to show persistent dismissible admin notices. But why stop there? We can hack away some more and make sure that any runtime errors in our code show up as notices too.

Imagine a clueless user sees your theme not working. Which do you prefer? To have to explain to them how to enable debugging and how to find and send you the logs from the wordpress unix directory on the host? Or do you simply ask them to copy the error on the screen and send it to you via email?

Observe this little hack that takes advantage of the PHP error reporting mechanism:

public static function error_handler( $errno, $errstr, $errfile, $errline, $errcontext ) {
    if ( ! ( error_reporting() & $errno ) ) {
        // This error code is not included in error_reporting
        return;
    }

    $message = "errstr: $errstr, errfile: $errfile, errline: $errline, PHP: " . PHP_VERSION . " OS: " . PHP_OS;

    $self = self::get_instance();
    switch ($errno) {
        case E_USER_ERROR:
            $self->error( $message );
            break;

        case E_USER_WARNING:
            $self->warning( $message );
            break;

        case E_USER_NOTICE:
        default:
            $self->notice( $message );
            break;
    }

    // write to wp-content/debug.log if logging enabled
    error_log( $message );

    // Don't execute PHP internal error handler
    return true;
}

Notice how this method is static, since we’d like to be able to call it from both dynamic and static contexts. We can now hook it up to PHP’s error reporting like so:

set_error_handler( array( 'MyPlugin_Admin_Notices', 'error_handler' ) );

and after your code ends, unhook it so as not to interfere with the WordPress core or other components:

restore_error_handler();

This will pop your error handler from a stack and return to whatever error handling mechanism was there before. Make a habit of surrounding your function bodies with these two lines, and you will know that whatever happens, you’ll at least get a visible user-friendly and developer-friendly error message on the admin screens.

Putting it all together

JS

/**
 * Admin code for dismissing notifications.
 *
 */
(function( $ ) {
    'use strict';
    $( function() {
        $( '.myplugin-notice' ).on( 'click', '.notice-dismiss', function( event, el ) {

            var $notice = $(this).parent('.notice.is-dismissible');
            var dismiss_url = $notice.attr('data-dismiss-url');
            if ( dismiss_url ) {
                $.get( dismiss_url );
            }
        });
    } );
})( jQuery );

PHP

<?php
if ( defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    global $wpdb;
    $wpdb->query( 'DELETE FROM wp_options WHERE option_name LIKE "/* @echo slugus */_dismissed_%";' );
}

<?php
// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( 'MyPlugin_Admin_Notices' ) ) {

    class MyPlugin_Admin_Notices {

        private static $_instance;
        private $admin_notices;
        const TYPES = 'error,warning,info,success';

        private function __construct() {
            $this->admin_notices = new stdClass();
            foreach ( explode( ',', self::TYPES ) as $type ) {
                $this->admin_notices->{$type} = array();
            }
            add_action( 'admin_init', array( &$this, 'action_admin_init' ) );
            add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );
            add_action( 'admin_enqueue_scripts', array( &$this, 'action_admin_enqueue_scripts' ) );
        }

        public static function get_instance() {
            if ( ! ( self::$_instance instanceof self ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }

        public function action_admin_init() {
            $dismiss_option = filter_input( INPUT_GET, 'myplugin_dismiss', FILTER_SANITIZE_STRING );
            if ( is_string( $dismiss_option ) ) {
                update_option( "myplugin_dismissed_$dismiss_option", true );
                wp_die();
            }
        }

        public function action_admin_enqueue_scripts() {
            wp_enqueue_script( 'jquery' );
            wp_enqueue_script(
                'myplugin-notify',
                plugins_url( 'assets/scripts/myplugin-notify.js', __FILE__ ),
                array( 'jquery' )
            );
        }

        public function action_admin_notices() {
            foreach ( explode( ',', self::TYPES ) as $type ) {
                foreach ( $this->admin_notices->{$type} as $admin_notice ) {

                    $dismiss_url = add_query_arg( array(
                        'myplugin_dismiss' => $admin_notice->dismiss_option
                    ), admin_url() );

                    if ( ! get_option( "myplugin_dismissed_{$admin_notice->dismiss_option}" ) ) {
                        ?><div
                            class="notice myplugin-notice notice-<?php echo $type;

                            if ( $admin_notice->dismiss_option ) {
                                echo ' is-dismissible" data-dismiss-url="' . esc_url( $dismiss_url );
                            } ?>">

                            <h2><?php echo "My Plugin $type"; ?></h2>
                            <p><?php echo $admin_notice->message; ?></p>

                        </div><?php
                    }
                }
            }
        }

        public function error( $message, $dismiss_option = false ) {
            $this->notice( 'error', $message, $dismiss_option );
        }

        public function warning( $message, $dismiss_option = false ) {
            $this->notice( 'warning', $message, $dismiss_option );
        }

        public function success( $message, $dismiss_option = false ) {
            $this->notice( 'success', $message, $dismiss_option );
        }

        public function info( $message, $dismiss_option = false ) {
            $this->notice( 'info', $message, $dismiss_option );
        }

        private function notice( $type, $message, $dismiss_option ) {
            $notice = new stdClass();
            $notice->message = $message;
            $notice->dismiss_option = $dismiss_option;

            $this->admin_notices->{$type}[] = $notice;
        }

	public static function error_handler( $errno, $errstr, $errfile, $errline, $errcontext ) {
		if ( ! ( error_reporting() & $errno ) ) {
			// This error code is not included in error_reporting
			return;
		}

		$message = "errstr: $errstr, errfile: $errfile, errline: $errline, PHP: " . PHP_VERSION . " OS: " . PHP_OS;

		$self = self::get_instance();

		switch ($errno) {
			case E_USER_ERROR:
				$self->error( $message );
				break;

			case E_USER_WARNING:
				$self->warning( $message );
				break;

			case E_USER_NOTICE:
			default:
				$self->notice( $message );
				break;
		}

		// write to wp-content/debug.log if logging enabled
		error_log( $message );

		// Don't execute PHP internal error handler
		return true;
	}
    }
}

MyPlugin_Admin_Notices::get_instance();

Thanks for reading

Please comment on what you liked or didn’t like in my code. What would you have done differently? Can you spot any bugs?

Until next time. Dismissed!

The post 🗨 Dismissible notices that persist when refreshing the WordPress admin screens appeared first on Alexandros Georgiou.