1<?php
  2/**
  3 * Plugins may load this file to gain access to special helper functions
  4 * for plugin installation. This file is not included by WordPress and it is
  5 * recommended, to prevent fatal errors, that this file is included using
  6 * require_once.
  7 *
  8 * These functions are not optimized for speed, but they should only be used
  9 * once in a while, so speed shouldn't be a concern. If it is and you are
 10 * needing to use these functions a lot, you might experience timeouts.
 11 * If you do, then it is advised to just write the SQL code yourself.
 12 *
 13 *     check_column( 'wp_links', 'link_description', 'mediumtext' );
 14 *
 15 *     if ( check_column( $wpdb->comments, 'comment_author', 'tinytext' ) ) {
 16 *         echo "ok\n";
 17 *     }
 18 *
 19 *     // Check the column.
 20 *     if ( ! check_column( $wpdb->links, 'link_description', 'varchar( 255 )' ) ) {
 21 *         $ddl = "ALTER TABLE $wpdb->links MODIFY COLUMN link_description varchar(255) NOT NULL DEFAULT '' ";
 22 *         $q = $wpdb->query( $ddl );
 23 *     }
 24 *
 25 *     $error_count = 0;
 26 *     $tablename   = $wpdb->links;
 27 *
 28 *     if ( check_column( $wpdb->links, 'link_description', 'varchar( 255 )' ) ) {
 29 *         $res .= $tablename . ' - ok <br />';
 30 *     } else {
 31 *         $res .= 'There was a problem with ' . $tablename . '<br />';
 32 *         ++$error_count;
 33 *     }
 34 *
 35 * @package WordPress
 36 * @subpackage Plugin
 37 */
 38
 39/** Load WordPress Bootstrap */
 40require_once dirname( __DIR__ ) . '/wp-load.php';
 41
 42if ( ! function_exists( 'maybe_create_table' ) ) :
 43	/**
 44	 * Creates a table in the database if it doesn't already exist.
 45	 *
 46	 * @since 1.0.0
 47	 *
 48	 * @global wpdb $wpdb WordPress database abstraction object.
 49	 *
 50	 * @param string $table_name Database table name.
 51	 * @param string $create_ddl SQL statement to create table.
 52	 * @return bool True on success or if the table already exists. False on failure.
 53	 */
 54	function maybe_create_table( $table_name, $create_ddl ) {
 55		global $wpdb;
 56
 57		foreach ( $wpdb->get_col( 'SHOW TABLES', 0 ) as $table ) {
 58			if ( $table === $table_name ) {
 59				return true;
 60			}
 61		}
 62
 63		// Didn't find it, so try to create it.
 64		// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- No applicable variables for this query.
 65		$wpdb->query( $create_ddl );
 66
 67		// We cannot directly tell whether this succeeded!
 68		foreach ( $wpdb->get_col( 'SHOW TABLES', 0 ) as $table ) {
 69			if ( $table === $table_name ) {
 70				return true;
 71			}
 72		}
 73
 74		return false;
 75	}
 76endif;
 77
 78if ( ! function_exists( 'maybe_add_column' ) ) :
 79	/**
 80	 * Adds column to database table, if it doesn't already exist.
 81	 *
 82	 * @since 1.0.0
 83	 *
 84	 * @global wpdb $wpdb WordPress database abstraction object.
 85	 *
 86	 * @param string $table_name  Database table name.
 87	 * @param string $column_name Table column name.
 88	 * @param string $create_ddl  SQL statement to add column.
 89	 * @return bool True on success or if the column already exists. False on failure.
 90	 */
 91	function maybe_add_column( $table_name, $column_name, $create_ddl ) {
 92		global $wpdb;
 93
 94		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Cannot be prepared. Fetches columns for table names.
 95		foreach ( $wpdb->get_col( "DESC $table_name", 0 ) as $column ) {
 96			if ( $column === $column_name ) {
 97				return true;
 98			}
 99		}
100
101		// Didn't find it, so try to create it.
102		// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- No applicable variables for this query.
103		$wpdb->query( $create_ddl );
104
105		// We cannot directly tell whether this succeeded!
106		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Cannot be prepared. Fetches columns for table names.
107		foreach ( $wpdb->get_col( "DESC $table_name", 0 ) as $column ) {
108			if ( $column === $column_name ) {
109				return true;
110			}
111		}
112
113		return false;
114	}
115endif;
116
117/**
118 * Drops column from database table, if it exists.
119 *
120 * @since 1.0.0
121 *
122 * @global wpdb $wpdb WordPress database abstraction object.
123 *
124 * @param string $table_name  Database table name.
125 * @param string $column_name Table column name.
126 * @param string $drop_ddl    SQL statement to drop column.
127 * @return bool True on success or if the column doesn't exist. False on failure.
128 */
129function maybe_drop_column( $table_name, $column_name, $drop_ddl ) {
130	global $wpdb;
131
132	// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Cannot be prepared. Fetches columns for table names.
133	foreach ( $wpdb->get_col( "DESC $table_name", 0 ) as $column ) {
134		if ( $column === $column_name ) {
135
136			// Found it, so try to drop it.
137			// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- No applicable variables for this query.
138			$wpdb->query( $drop_ddl );
139
140			// We cannot directly tell whether this succeeded!
141			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Cannot be prepared. Fetches columns for table names.
142			foreach ( $wpdb->get_col( "DESC $table_name", 0 ) as $column ) {
143				if ( $column === $column_name ) {
144					return false;
145				}
146			}
147		}
148	}
149
150	// Else didn't find it.
151	return true;
152}
153
154/**
155 * Checks that database table column matches the criteria.
156 *
157 * Uses the SQL DESC for retrieving the table info for the column. It will help
158 * understand the parameters, if you do more research on what column information
159 * is returned by the SQL statement. Pass in null to skip checking that criteria.
160 *
161 * Column names returned from DESC table are case sensitive and are as listed:
162 *
163 *  - Field
164 *  - Type
165 *  - Null
166 *  - Key
167 *  - Default
168 *  - Extra
169 *
170 * @since 1.0.0
171 *
172 * @global wpdb $wpdb WordPress database abstraction object.
173 *
174 * @param string $table_name    Database table name.
175 * @param string $col_name      Table column name.
176 * @param string $col_type      Table column type.
177 * @param bool   $is_null       Optional. Check is null.
178 * @param mixed  $key           Optional. Key info.
179 * @param mixed  $default_value Optional. Default value.
180 * @param mixed  $extra         Optional. Extra value.
181 * @return bool True, if matches. False, if not matching.
182 */
183function check_column( $table_name, $col_name, $col_type, $is_null = null, $key = null, $default_value = null, $extra = null ) {
184	global $wpdb;
185
186	$diffs = 0;
187
188	// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Cannot be prepared. Fetches columns for table names.
189	$results = $wpdb->get_results( "DESC $table_name" );
190
191	foreach ( $results as $row ) {
192
193		if ( $row->Field === $col_name ) {
194
195			// Got our column, check the params.
196			if ( ( null !== $col_type ) && ( $row->Type !== $col_type ) ) {
197				++$diffs;
198			}
199			if ( ( null !== $is_null ) && ( $row->Null !== $is_null ) ) {
200				++$diffs;
201			}
202			if ( ( null !== $key ) && ( $row->Key !== $key ) ) {
203				++$diffs;
204			}
205			if ( ( null !== $default_value ) && ( $row->Default !== $default_value ) ) {
206				++$diffs;
207			}
208			if ( ( null !== $extra ) && ( $row->Extra !== $extra ) ) {
209				++$diffs;
210			}
211
212			if ( $diffs > 0 ) {
213				return false;
214			}
215
216			return true;
217		} // End if found our column.
218	}
219
220	return false;
221}
222