GravityKit\GravityMigrate\Util

Utility class.

Source: src/Util.php:22

Details

• Kind: class
• Namespace: GravityKit\GravityMigrate

Properties

Property	Type	Description
$wp_filesystem	WP_Filesystem_Base	WP Filesystem variable.

Methods

Method	Description
get_instance()	Returns class instance.
__construct()	Constructor.
filesystem()	A connected filesystem, or null.
set_time_limit()	Sets time limit.
log_debug()	Writes debug message to the Foundation log.
log_error()	Writes error message to the Foundation log.
db_insert_ignoring_duplicates()	Runs an INSERT IGNORE and says how many rows it skipped.
table_exists()	Reports whether a table exists.
db_count_rows()	Counts rows, telling a failed query apart from an empty table.
sanitize_id_list()	Builds a comma separated list of ids safe to drop into an IN() clause.
require_migration_capability()	Refuses a migration request from a user who cannot administer the site.
db_query()	Simple {@see wpdb} query function wrapper.
db_get_var()	Simple {@see wpdb} function wrapper for get_var.
db_get_results()	Simple {@see wpdb} function wrapper for get_results.
delete_directory()	Deletes files and folder recursively.
array_remove()	Removes an item from the array and returns its value.
get_imports_dir()	Returns the directory path for storing imports.
create_protected_directory()	Creates a directory that the web server will not serve out of.
create_unlisted_directory()	Creates a directory the web server will not list, but will still serve out of.
create_protected_directory_tree()	Creates every level of $sub_path below $base_dir, guarding each one.
get_current_import_dir()	Returns the directory path for the current import files.
get_current_import_file()	Returns an array containing file paths for the current import files.
staged_import_bundle_exists()	Whether the staged import bundle's dump and info files are both present and readable.
get_exports_dir()	Returns the directory path for storing exports.
get_local_upload_info()	Gets the local filesystem upload directory info without any plugin filters.
get_shortcodes_list()	Returns a list of shortcode names.
get_blocks_list()	Returns a list of block names.
is_same_site()	Whether two site URLs point at the same install.
site_identity()	The part of a URL that says which install it belongs to: host, port and path.
url_authority()	A URL's host and port, normalized. Empty when it has no host.
url_path()	A URL's path with any trailing slash removed. Empty for a URL with no host.
post_content_like_statement()	Generates a "WHERE statement" for querying posts based on shortcodes and blocks in post content.
get_form_meta_rows()	The display_meta of the named forms, straight from the form meta table.
get_upload_fields()	The fields in the named forms whose entry value names an uploaded file.
build_uploads_where()	A WHERE clause matching the entry meta rows written by the given upload fields.

Method Reference

get_instance()

public static function get_instance(): Util

Returns class instance.

Returns

• Util

Since: 1.0.0

Source: src/Util.php:72

__construct()

public function __construct()

Constructor.

Since: 1.0.0

Source: src/Util.php:85

filesystem()

public static function filesystem()

A connected filesystem, or null.

\self::$wp_filesystem() is captured once, in the constructor, so a connect that failed then stays failed for the life of the request while \self::delete_directory() goes on connecting fresh every call. This answers with the captured handle when there is one -- which is also the seam the tests inject at -- and connects when there is not.

Returns

• \WP_Filesystem_Base | null

Since: %ver%

Source: src/Util.php:116

set_time_limit()

public function set_time_limit()

Sets time limit.

Returns

• void

Since: 1.0.0

Source: src/Util.php:176

log_debug()

public function log_debug( $message )

Writes debug message to the Foundation log.

Parameters

Name	Type	Default	Description
$message

Since: 1.0.0

Source: src/Util.php:192

log_error()

public function log_error( $message )

Writes error message to the Foundation log.

Parameters

Name	Type	Default	Description
$message

Since: 1.0.0

Source: src/Util.php:201

db_insert_ignoring_duplicates()

public function db_insert_ignoring_duplicates( string $sql, string $label='', int $expected=-1 ): int

Runs an INSERT IGNORE and says how many rows it skipped.

The import's final step copies each temp table into the live one, and a replay after a partially completed finish meets rows that are already there. A plain INSERT aborts at the first duplicate key and loses every remaining row -- silently, since the run still reports success -- so the step uses IGNORE to stay resumable. IGNORE on its own would also swallow rows dropped for any other reason, which is why the count that went in is compared against the count that landed.

Parameters

Name	Type	Default	Description
$sql	string		INSERT IGNORE ... SELECT statement.
$label	string	''	What is being copied, for the log.
$expected	int	-1	Rows the source query holds, when known.

Returns

• int — Rows actually inserted.

Since: %ver%

Source: src/Util.php:223

table_exists()

public function table_exists( string $table ): bool

Reports whether a table exists.

The import's finalising steps rename a _final table into place and drop the temp one, so they are only safe to run once. On a replay — which the Resume button does by design — the _final table is already gone, and running them again would drop the table holding the data and rename nothing into its place. Asking first is how each step tells whether it has already happened.

Parameters

Name	Type	Default	Description
$table	string		Table name.

Returns

• bool

Since: %ver%

Source: src/Util.php:266

db_count_rows()

public function db_count_rows( string $table, string $where='' ): ?int

Counts rows, telling a failed query apart from an empty table.

db_get_var() logs the error and returns anyway, so a caller casting the result with (int) cannot tell "this table has no rows" from "this query failed". That distinction decides whether the export offers a data type at all: a count of 0 hides the option, so a query that errors removes the user's entries from the export screen without a word.

Parameters

Name	Type	Default	Description
$table	string		Table name.
$where	string	''	Optional WHERE clause, with or without the leading keyword.

Returns

• int | null — Null when the table is absent or the query failed.

Since: %ver%

Source: src/Util.php:287

sanitize_id_list()

public function sanitize_id_list( $ids )

Builds a comma separated list of ids safe to drop into an IN() clause.

esc_sql() escapes quotes, which does nothing for a value that contains none and is interpolated straight into a clause. Ids are numbers, so they are cast as numbers, and anything that is not one is dropped rather than escaped: there is no legitimate non-numeric form id.

Returns '0' rather than '' when nothing survives, since IN() with an empty list is a syntax error and IN(0) simply matches nothing.

Parameters

Name	Type	Default	Description
$ids	array | string		Ids, as an array or an already-joined list.

Returns

• string

Since: %ver%

Source: src/Util.php:340

require_migration_capability()

public function require_migration_capability( $context='' )

Refuses a migration request from a user who cannot administer the site.

Foundation's AJAX router gates a route on wp_doing_ajax() plus the gk_foundation_do_ajax nonce. That nonce is shared by every Foundation AJAX call and is not bound to a capability, so it establishes that the request came from this site, not that its sender may run a migration.

manage_options is the capability the admin menu and the WP-CLI commands require, so this admits exactly the users who can reach the migration screens.

Parameters

Name	Type	Default	Description
$context	string	''	Route being refused, recorded in the log so a blocked request can be told apart from a failed one.

Returns

• void

Throws

• Exception — When the current user lacks manage_options and this is not an AJAX request. Under AJAX, {@see CoreHelpers::process_return()} sends the error response and exits instead of returning.

Since: %ver%

Source: src/Util.php:389

db_query()

public function db_query( $query, $type='IMPORT' )

Simple {@see wpdb} query function wrapper.

Logs error.

Parameters

Name	Type	Default	Description
$query	string
$type	string	'IMPORT'

Returns

• mixed

Since: 1.0.0

Source: src/Util.php:425

db_get_var()

public function db_get_var( $query, $type='IMPORT' )

Simple {@see wpdb} function wrapper for get_var.

Logs error if required.

Parameters

Name	Type	Default	Description
$query	string
$type	string	'IMPORT'

Returns

• mixed

Since: 1.0.0

Source: src/Util.php:452

db_get_results()

public function db_get_results( $query, $return_data_type='OBJECT', $type='IMPORT' )

Simple {@see wpdb} function wrapper for get_results.

Logs error if required.

Parameters

Name	Type	Default	Description
$query	string
$return_data_type	string	'OBJECT'
$type	string	'IMPORT'

Returns

• array | object | null — Database query results.

Since: 1.0.0

Source: src/Util.php:480

delete_directory()

public function delete_directory( $dir )

Deletes files and folder recursively.

Parameters

Name	Type	Default	Description
$dir	string		Directory path.

Returns

• bool — Returns true on success or false on failure.

Source: src/Util.php:503

array_remove()

public function array_remove( $original_array, $removal_array )

Removes an item from the array and returns its value.

Parameters

Name	Type	Default	Description
$original_array	array		Original array to remove from.
$removal_array	array		Array of items to remove.

Returns

• array

Since: 1.0.0

Source: src/Util.php:525

get_imports_dir()

public function get_imports_dir()

Returns the directory path for storing imports.

Returns

• string — The directory path for storing imports.

Since: 1.1.0

Source: src/Util.php:536

create_protected_directory()

public function create_protected_directory( $dir )

Creates a directory that the web server will not serve out of.

Everything staged for an import lands under the uploads tree, which is web-served, at a path derived only from constants -- so it is guessable by anyone. What sits there is the whole source database as a plain SQL dump, and now the uploaded files a bundle carried. Nothing in either is meant to be fetched over HTTP: the importer reads them off disk.

Two guards, because they fail in different places. The .htaccess denies the directory outright, which is the real protection but only on Apache. The index.php stops a server with directory indexing on from listing the contents, which is what turns a guessable directory into an enumerable one, and works everywhere.

Neither helps on nginx, which reads no .htaccess, so it is defence in depth rather than the only defence -- what may be written here is gated separately.

Parameters

Name	Type	Default	Description
$dir	string		Absolute path to create.

Returns

• bool — Whether the directory exists afterwards.

Since: %ver%

Source: src/Util.php:562

create_unlisted_directory()

public function create_unlisted_directory( $dir )

Creates a directory the web server will not list, but will still serve out of.

The exports tree cannot take the .htaccess its imports sibling gets. A finished export is delivered as a static file: package_up() hands the browser a URL into the uploads tree and the web server reads it off disk, so a deny rule refuses the operator's own download along with everyone else's. What is left is the index.php, which stops a server with directory indexing on from listing the contents -- the step that turns a guessable path into an enumerable one -- and works on every server rather than Apache alone.

That is weaker than denying the directory, and knowingly so: what remains fetchable is a bundle whose run directory is named from wp_hash() and whose filename carries eight random characters. Closing it properly means serving the download through PHP, where a capability can be asked for.

Parameters

Name	Type	Default	Description
$dir	string		Absolute path to create.

Returns

• bool — Whether the directory exists afterwards.

Since: %ver%

Source: src/Util.php:614

create_protected_directory_tree()

public function create_protected_directory_tree( $base_dir, $sub_path )

Creates every level of $sub_path below $base_dir, guarding each one.

\self::create_protected_directory() guards the directory it is given, and wp_mkdir_p() creates the parents above it silently -- so creating gk-media/2026/08 in one call leaves gk-media/2026 with no guards at all. The levels a bundle's own directory tree adds are exactly the ones nothing else was going to protect.

Parameters

Name	Type	Default	Description
$base_dir	string		Absolute path of the directory the tree hangs from.
$sub_path	string		Relative path below it. . or '' means $base_dir itself.

Returns

• bool — Whether every level exists afterwards.

Since: %ver%

Source: src/Util.php:666

get_current_import_dir()

public function get_current_import_dir()

Returns the directory path for the current import files.

Returns

• string — The directory path for the current import files.

Since: 1.1.0

Source: src/Util.php:701

get_current_import_file()

public function get_current_import_file()

Returns an array containing file paths for the current import files.

Returns

• array — An array with 'dump' and 'json' file paths for the current import.

Since: 1.1.0

Source: src/Util.php:712

staged_import_bundle_exists()

public function staged_import_bundle_exists(): bool

Whether the staged import bundle's dump and info files are both present and readable.

Returns

• bool

Since: %ver%

Source: src/Util.php:728

get_exports_dir()

public function get_exports_dir()

Returns the directory path for storing exports.

Returns

• string — The directory path for storing exports.

Since: 1.1.0

Source: src/Util.php:744

get_local_upload_info()

public function get_local_upload_info()

Gets the local filesystem upload directory info without any plugin filters.

Works with any cloud storage plugin by temporarily removing filters.

Returns

• array — The local upload directory info (basedir, baseurl, etc).

Since: 1.1.4

Source: src/Util.php:756

get_shortcodes_list()

public function get_shortcodes_list()

Returns a list of shortcode names.

Returns

• array — List of shortcode names.

Since: 1.1.0

Source: src/Util.php:779

get_blocks_list()

public function get_blocks_list()

Returns a list of block names.

Returns

• array — List of block names.

Since: 1.0.0

Source: src/Util.php:844

is_same_site()

public static function is_same_site( string $a, string $b ): bool

Whether two site URLs point at the same install.

Identity is \self::site_identity(): host, port and path, normalized. An empty identity (no host) never matches, including against itself.

Parameters

Name	Type	Default	Description
$a	string		First URL.
$b	string		Second URL.

Returns

• bool

Since: %ver%

Source: src/Util.php:925

site_identity()

public static function site_identity( string $url ): string

The part of a URL that says which install it belongs to: host, port and path.

Scheme, www., trailing slashes and case are dropped, because they differ routinely between what a site records about itself and what it reports now. The port is kept, unless it is the default for its scheme -- two installs on one host at different ports are two sites, while http://example.com and http://example.com:80 are one site written twice.

Parameters

Name	Type	Default	Description
$url	string		URL to reduce.

Returns

• string — Empty when the URL has no host, which no real URL matches.

Since: %ver%

Source: src/Util.php:945

url_authority()

public static function url_authority( string $url ): string

A URL's host and port, normalized. Empty when it has no host.

Parameters

Name	Type	Default	Description
$url	string		URL to read.

Returns

• string

Since: %ver%

Source: src/Util.php:958

url_path()

public static function url_path( string $url ): string

A URL's path with any trailing slash removed. Empty for a URL with no host.

Parameters

Name	Type	Default	Description
$url	string		URL to read.

Returns

• string

Since: %ver%

Source: src/Util.php:983

post_content_like_statement()

public function post_content_like_statement( $column='post_content' )

Generates a "WHERE statement" for querying posts based on shortcodes and blocks in post content.

Parameters

Name	Type	Default	Description
$column	string	'post_content'	The column name for where statement.

Returns

• string — The generated WHERE statement for database queries.

Since: 1.1.0

Source: src/Util.php:1024

get_form_meta_rows()

public function get_form_meta_rows( array $form_ids, ?string $table=null ): array

The display_meta of the named forms, straight from the form meta table.

Reads the table rather than GFAPI::get_form() because both callers need the JSON a form was stored with, and one of them is reading a temp table full of another site's forms that Gravity Forms has never been told about.

Parameters

Name	Type	Default	Description
$form_ids	int[]		Form ids.
$table	string | null	null	Form meta table to read. Defaults to this site's own.

Returns

• array<int,array{form_id:mixed,display_meta:mixed}>

Since: %ver%

Source: src/Util.php:1055

get_upload_fields()

public function get_upload_fields( array $form_ids, ?string $table=null ): array

The fields in the named forms whose entry value names an uploaded file.

A field records the form it belongs to twice -- on the field as formId, and on the row carrying it -- and the two disagree on a form imported from another site before the remap finishes. The field's own value wins where it has one, because it is what the entry meta was written against.

Parameters

Name	Type	Default	Description
$form_ids	int[]		Form ids.
$table	string | null	null	Form meta table to read. Defaults to this site's own.

Returns

• array<int,array{form_id:int,field_id:int,type:string}>

Since: %ver%

Source: src/Util.php:1088

build_uploads_where()

public function build_uploads_where( array $upload_fields ): string

A WHERE clause matching the entry meta rows written by the given upload fields.

Returns a clause matching nothing when there are no fields. An empty string would be concatenated into WHERE AND ... by every caller, and 1=1 would match the whole table -- which for a caller about to package every matching file is the difference between a bundle with no attachments and a bundle with the site's entire uploads folder.

Parameters

Name	Type	Default	Description
$upload_fields	array		Rows from \self::get_upload_fields().

Returns

• string

Since: %ver%

Source: src/Util.php:1140