WooCommerce Code Reference

WC_Install
in package
Uses AccessiblePrivateMethods

WC_Install Class.

Table of Contents

NEWLY_INSTALLED_OPTION  = 'woocommerce_newly_installed'
Option name used to track new installations of WooCommerce.
$db_updates  : array<string|int, mixed>
DB updates and callbacks that need to be run per version.
add_admin_note_after_page_created()  : void
Adds an admin inbox note after a page has been created to notify user. For example to take action to edit the page such as the Refund and returns page.
background_installer()  : mixed
Install a plugin from .org in the background via a cron job (used by installer - opt in).
check_version()  : mixed
Check WooCommerce version and run the updater is required.
create_pages()  : mixed
Create pages that the plugin relies on, storing page IDs in variables.
create_roles()  : mixed
Create roles and capabilities.
create_tables()  : array<string|int, mixed>
Set up the database tables which the plugin needs to function.
create_terms()  : mixed
Add the default terms for WC taxonomies - product types and order statuses. Modify this at your own risk.
cron_schedules()  : array<string|int, mixed>
Add more cron schedules.
delete_obsolete_notes()  : mixed
Delete obsolete notes.
drop_tables()  : void
Drop WooCommerce tables.
get_core_capabilities()  : array<string|int, mixed>
Get capabilities for WooCommerce - these are assigned to admin/shop manager during installation or reset.
get_db_update_callbacks()  : array<string|int, mixed>
Get list of DB update callbacks.
get_tables()  : array<string|int, mixed>
Return a list of WooCommerce tables. Used to make sure all WC tables are dropped when uninstalling the plugin in a single site or multi site environment.
init()  : mixed
Hook in tabs.
install()  : mixed
Install WC.
install_actions()  : mixed
Install actions when a update button is clicked within the admin area.
is_new_install()  : bool
Is this a brand new WC install?
manual_database_update()  : mixed
Performan manual database update when triggered by WooCommerce System Tools.
maybe_create_pages()  : mixed
Create pages on installation.
migrate_options()  : mixed
Migrate option values to their new keys/names.
needs_db_update()  : bool
Is a DB update needed?
page_created()  : void
When pages are created, we might want to take some action.
plugin_action_links()  : array<string|int, mixed>
Show action links on the plugin screen.
plugin_row_meta()  : array<string|int, mixed>
Show row meta on the plugin screen.
remove_mailchimps_redirect()  : mixed
Removes redirect added during MailChimp plugin's activation.
remove_roles()  : mixed
Remove WooCommerce roles.
run_manual_database_update()  : mixed
Run manual database update.
run_update_callback()  : mixed
Run an update callback when triggered by ActionScheduler.
theme_background_installer()  : mixed
Install a theme from .org in the background via a cron job (used by installer - opt in).
update_db_version()  : mixed
Update DB version to current.
verify_base_tables()  : array<string|int, mixed>
Check if all the base tables are present.
wc_admin_db_update_notice()  : mixed
Add WC Admin based db update notice.
wpmu_drop_tables()  : array<string|int, string>
Uninstall tables when MU blog is deleted.
run_update_callback_end()  : mixed
Triggered when a callback has ran.
run_update_callback_start()  : mixed
Triggered when a callback will run.
associate_plugin_file()  : mixed
Get slug from path and associate it with the path.
create_cron_jobs()  : mixed
Create cron jobs (clear them first).
create_files()  : mixed
Create files/directories.
create_options()  : mixed
Default options.
create_placeholder_image()  : mixed
Create a placeholder image in the media library.
get_refunds_return_policy_page_content()  : string
Gets the content of the sample refunds and return policy page.
get_schema()  : string
Get Table schema.
is_installing()  : bool
Returns true if we're installing.
maybe_set_activation_transients()  : mixed
See if we need to set redirect transients for activation or not.
maybe_update_db_version()  : mixed
See if we need to show or run database updates during install.
newly_installed()  : mixed
Trigger `woocommerce_newly_installed` action for new installations.
remove_admin_notices()  : mixed
Reset any notices added to admin.
set_paypal_standard_load_eligibility()  : mixed
Sets whether PayPal Standard will be loaded on install.
setup_environment()  : mixed
Setup WC environment - post types, taxonomies, endpoints.
update()  : mixed
Push all needed DB updates to the queue for processing.
update_wc_version()  : mixed
Update WC version to current.

Constants

NEWLY_INSTALLED_OPTION

Option name used to track new installations of WooCommerce.

public string NEWLY_INSTALLED_OPTION = 'woocommerce_newly_installed'

Properties

$db_updates

DB updates and callbacks that need to be run per version.

private static array<string|int, mixed> $db_updates = array('2.0.0' => array('wc_update_200_file_paths', 'wc_update_200_permalinks', 'wc_update_200_subcat_display', 'wc_update_200_taxrates', 'wc_update_200_line_items', 'wc_update_200_images', 'wc_update_200_db_version'), '2.0.9' => array('wc_update_209_brazillian_state', 'wc_update_209_db_version'), '2.1.0' => array('wc_update_210_remove_pages', 'wc_update_210_file_paths', 'wc_update_210_db_version'), '2.2.0' => array('wc_update_220_shipping', 'wc_update_220_order_status', 'wc_update_220_variations', 'wc_update_220_attributes', 'wc_update_220_db_version'), '2.3.0' => array('wc_update_230_options', 'wc_update_230_db_version'), '2.4.0' => array('wc_update_240_options', 'wc_update_240_shipping_methods', 'wc_update_240_api_keys', 'wc_update_240_refunds', 'wc_update_240_db_version'), '2.4.1' => array('wc_update_241_variations', 'wc_update_241_db_version'), '2.5.0' => array('wc_update_250_currency', 'wc_update_250_db_version'), '2.6.0' => array('wc_update_260_options', 'wc_update_260_termmeta', 'wc_update_260_zones', 'wc_update_260_zone_methods', 'wc_update_260_refunds', 'wc_update_260_db_version'), '3.0.0' => array('wc_update_300_grouped_products', 'wc_update_300_settings', 'wc_update_300_product_visibility', 'wc_update_300_db_version'), '3.1.0' => array('wc_update_310_downloadable_products', 'wc_update_310_old_comments', 'wc_update_310_db_version'), '3.1.2' => array('wc_update_312_shop_manager_capabilities', 'wc_update_312_db_version'), '3.2.0' => array('wc_update_320_mexican_states', 'wc_update_320_db_version'), '3.3.0' => array('wc_update_330_image_options', 'wc_update_330_webhooks', 'wc_update_330_product_stock_status', 'wc_update_330_set_default_product_cat', 'wc_update_330_clear_transients', 'wc_update_330_set_paypal_sandbox_credentials', 'wc_update_330_db_version'), '3.4.0' => array('wc_update_340_states', 'wc_update_340_state', 'wc_update_340_last_active', 'wc_update_340_db_version'), '3.4.3' => array('wc_update_343_cleanup_foreign_keys', 'wc_update_343_db_version'), '3.4.4' => array('wc_update_344_recreate_roles', 'wc_update_344_db_version'), '3.5.0' => array('wc_update_350_reviews_comment_type', 'wc_update_350_db_version'), '3.5.2' => array('wc_update_352_drop_download_log_fk'), '3.5.4' => array('wc_update_354_modify_shop_manager_caps', 'wc_update_354_db_version'), '3.6.0' => array('wc_update_360_product_lookup_tables', 'wc_update_360_term_meta', 'wc_update_360_downloadable_product_permissions_index', 'wc_update_360_db_version'), '3.7.0' => array('wc_update_370_tax_rate_classes', 'wc_update_370_mro_std_currency', 'wc_update_370_db_version'), '3.9.0' => array('wc_update_390_move_maxmind_database', 'wc_update_390_change_geolocation_database_update_cron', 'wc_update_390_db_version'), '4.0.0' => array('wc_update_product_lookup_tables', 'wc_update_400_increase_size_of_column', 'wc_update_400_reset_action_scheduler_migration_status', 'wc_admin_update_0201_order_status_index', 'wc_admin_update_0230_rename_gross_total', 'wc_admin_update_0251_remove_unsnooze_action', 'wc_update_400_db_version'), '4.4.0' => array('wc_update_440_insert_attribute_terms_for_variable_products', 'wc_admin_update_110_remove_facebook_note', 'wc_admin_update_130_remove_dismiss_action_from_tracking_opt_in_note', 'wc_update_440_db_version'), '4.5.0' => array('wc_update_450_sanitize_coupons_code', 'wc_update_450_db_version'), '5.0.0' => array('wc_update_500_fix_product_review_count', 'wc_admin_update_160_remove_facebook_note', 'wc_admin_update_170_homescreen_layout', 'wc_update_500_db_version'), '5.6.0' => array('wc_update_560_create_refund_returns_page', 'wc_update_560_db_version'), '6.0.0' => array('wc_update_600_migrate_rate_limit_options', 'wc_admin_update_270_delete_report_downloads', 'wc_admin_update_271_update_task_list_options', 'wc_admin_update_280_order_status', 'wc_admin_update_290_update_apperance_task_option', 'wc_admin_update_290_delete_default_homepage_layout_option', 'wc_update_600_db_version'), '6.3.0' => array('wc_update_630_create_product_attributes_lookup_table', 'wc_admin_update_300_update_is_read_from_last_read', 'wc_update_630_db_version'), '6.4.0' => array('wc_update_640_add_primary_key_to_product_attributes_lookup_table', 'wc_admin_update_340_remove_is_primary_from_note_action', 'wc_update_640_db_version'), '6.5.0' => array('wc_update_650_approved_download_directories'), '6.5.1' => array('wc_update_651_approved_download_directories'), '6.7.0' => array('wc_update_670_purge_comments_count_cache', 'wc_update_670_delete_deprecated_remote_inbox_notifications_option'), '7.0.0' => array('wc_update_700_remove_download_log_fk', 'wc_update_700_remove_recommended_marketing_plugins_transient'), '7.2.1' => array('wc_update_721_adjust_new_zealand_states', 'wc_update_721_adjust_ukraine_states'), '7.2.2' => array('wc_update_722_adjust_new_zealand_states', 'wc_update_722_adjust_ukraine_states'), '7.5.0' => array('wc_update_750_add_columns_to_order_stats_table', 'wc_update_750_disable_new_product_management_experience'), '7.7.0' => array('wc_update_770_remove_multichannel_marketing_feature_options'))

Please note that these functions are invoked when WooCommerce is updated from a previous version, but NOT when WooCommerce is newly installed.

Database schema changes must be incorporated to the SQL returned by get_schema, which is applied via dbDelta at both install and update time. If any other kind of database change is required at install time (e.g. populating tables), use the 'woocommerce_installed' hook.

Methods

add_admin_note_after_page_created()

Adds an admin inbox note after a page has been created to notify user. For example to take action to edit the page such as the Refund and returns page.

public static add_admin_note_after_page_created() : void
Tags
since
5.6.0
Return values
void

background_installer()

Install a plugin from .org in the background via a cron job (used by installer - opt in).

public static background_installer(string $plugin_to_install_id, array<string|int, mixed> $plugin_to_install) : mixed
Parameters
$plugin_to_install_id : string

Plugin ID.

$plugin_to_install : array<string|int, mixed>

Plugin information.

Tags
throws
Exception

If unable to proceed with plugin installation.

since
2.6.0
Return values
mixed

check_version()

Check WooCommerce version and run the updater is required.

public static check_version() : mixed

This check is done on all requests and runs if the versions do not match.

Return values
mixed

create_pages()

Create pages that the plugin relies on, storing page IDs in variables.

public static create_pages() : mixed
Return values
mixed

create_roles()

Create roles and capabilities.

public static create_roles() : mixed
Return values
mixed

create_tables()

Set up the database tables which the plugin needs to function.

public static create_tables() : array<string|int, mixed>

WARNING: If you are modifying this method, make sure that its safe to call regardless of the state of database.

This is called from install method and is executed in-sync when WC is installed or updated. This can also be called optionally from verify_base_tables.

TODO: Add all crucial tables that we have created from workers in the past.

Tables: woocommerce_attribute_taxonomies - Table for storing attribute taxonomies - these are user defined woocommerce_downloadable_product_permissions - Table for storing user and guest download permissions. KEY(order_id, product_id, download_id) used for organizing downloads on the My Account page woocommerce_order_items - Order line items are stored in a table to make them easily queryable for reports woocommerce_order_itemmeta - Order line item meta is stored in a table for storing extra data. woocommerce_tax_rates - Tax Rates are stored inside 2 tables making tax queries simple and efficient. woocommerce_tax_rate_locations - Each rate can be applied to more than one postcode/city hence the second table.

Return values
array<string|int, mixed>Strings containing the results of the various update queries as returned by dbDelta.

create_terms()

Add the default terms for WC taxonomies - product types and order statuses. Modify this at your own risk.

public static create_terms() : mixed
Return values
mixed

cron_schedules()

Add more cron schedules.

public static cron_schedules(array<string|int, mixed> $schedules) : array<string|int, mixed>
Parameters
$schedules : array<string|int, mixed>

List of WP scheduled cron jobs.

Return values
array<string|int, mixed>

delete_obsolete_notes()

Delete obsolete notes.

public static delete_obsolete_notes() : mixed
Return values
mixed

get_core_capabilities()

Get capabilities for WooCommerce - these are assigned to admin/shop manager during installation or reset.

public static get_core_capabilities() : array<string|int, mixed>
Return values
array<string|int, mixed>

get_db_update_callbacks()

Get list of DB update callbacks.

public static get_db_update_callbacks() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed>

get_tables()

Return a list of WooCommerce tables. Used to make sure all WC tables are dropped when uninstalling the plugin in a single site or multi site environment.

public static get_tables() : array<string|int, mixed>
Return values
array<string|int, mixed>WC tables.

install_actions()

Install actions when a update button is clicked within the admin area.

public static install_actions() : mixed

This function is hooked into admin_init to affect admin only.

Return values
mixed

is_new_install()

Is this a brand new WC install?

public static is_new_install() : bool

A brand new install has no version yet. Also treat empty installs as 'new'.

Tags
since
3.2.0
Return values
bool

manual_database_update()

Performan manual database update when triggered by WooCommerce System Tools.

public static manual_database_update() : mixed
Tags
since
3.6.5
Return values
mixed

maybe_create_pages()

Create pages on installation.

public static maybe_create_pages() : mixed
Return values
mixed

migrate_options()

Migrate option values to their new keys/names.

public static migrate_options() : mixed
Return values
mixed

needs_db_update()

Is a DB update needed?

public static needs_db_update() : bool
Tags
since
3.2.0
Return values
bool

page_created()

When pages are created, we might want to take some action.

public static page_created(int $page_id, array<string|int, mixed> $page_data) : void

In this case we want to set an option when refund and returns page is created.

Parameters
$page_id : int

ID of the page.

$page_data : array<string|int, mixed>

The data of the page created.

Tags
since
5.6.0
Return values
void

Show action links on the plugin screen.

public static plugin_action_links(mixed $links) : array<string|int, mixed>
Parameters
$links : mixed

Plugin Action links.

Return values
array<string|int, mixed>

plugin_row_meta()

Show row meta on the plugin screen.

public static plugin_row_meta(mixed $links, mixed $file) : array<string|int, mixed>
Parameters
$links : mixed

Plugin Row Meta.

$file : mixed

Plugin Base file.

Return values
array<string|int, mixed>

remove_mailchimps_redirect()

Removes redirect added during MailChimp plugin's activation.

public static remove_mailchimps_redirect(string $option, string $value) : mixed
Parameters
$option : string

Option name.

$value : string

Option value.

Return values
mixed

run_manual_database_update()

Run manual database update.

public static run_manual_database_update() : mixed
Return values
mixed

run_update_callback()

Run an update callback when triggered by ActionScheduler.

public static run_update_callback(string $update_callback) : mixed
Parameters
$update_callback : string

Callback name.

Tags
since
3.6.0
Return values
mixed

theme_background_installer()

Install a theme from .org in the background via a cron job (used by installer - opt in).

public static theme_background_installer(string $theme_slug) : mixed
Parameters
$theme_slug : string

Theme slug.

Tags
throws
Exception

If unable to proceed with theme installation.

since
3.1.0
Return values
mixed

update_db_version()

Update DB version to current.

public static update_db_version([string|null $version = null ]) : mixed
Parameters
$version : string|null = null

New WooCommerce DB version or null.

Return values
mixed

verify_base_tables()

Check if all the base tables are present.

public static verify_base_tables([bool $modify_notice = true ][, bool $execute = false ]) : array<string|int, mixed>
Parameters
$modify_notice : bool = true

Whether to modify notice based on if all tables are present.

$execute : bool = false

Whether to execute get_schema queries as well.

Return values
array<string|int, mixed>List of queries.

wc_admin_db_update_notice()

Add WC Admin based db update notice.

public static wc_admin_db_update_notice() : mixed
Tags
since
4.0.0
Return values
mixed

wpmu_drop_tables()

Uninstall tables when MU blog is deleted.

public static wpmu_drop_tables(array<string|int, mixed> $tables) : array<string|int, string>
Parameters
$tables : array<string|int, mixed>

List of tables that will be deleted by WP.

Return values
array<string|int, string>

run_update_callback_end()

Triggered when a callback has ran.

protected static run_update_callback_end(string $callback, bool $result) : mixed
Parameters
$callback : string

Callback name.

$result : bool

Return value from callback. Non-false need to run again.

Tags
since
3.6.0
Return values
mixed

run_update_callback_start()

Triggered when a callback will run.

protected static run_update_callback_start(string $callback) : mixed
Parameters
$callback : string

Callback name.

Tags
since
3.6.0
Return values
mixed

associate_plugin_file()

Get slug from path and associate it with the path.

private static associate_plugin_file(array<string|int, mixed> $plugins, string $key) : mixed
Parameters
$plugins : array<string|int, mixed>

Associative array of plugin files to paths.

$key : string

Plugin relative path. Example: woocommerce/woocommerce.php.

Return values
mixed

create_cron_jobs()

Create cron jobs (clear them first).

private static create_cron_jobs() : mixed
Return values
mixed

create_options()

Default options.

private static create_options() : mixed

Sets up the default options used on the settings page.

Return values
mixed

create_placeholder_image()

Create a placeholder image in the media library.

private static create_placeholder_image() : mixed
Tags
since
3.5.0
Return values
mixed

get_refunds_return_policy_page_content()

Gets the content of the sample refunds and return policy page.

private static get_refunds_return_policy_page_content() : string
Tags
since
5.6.0
Return values
stringThe content for the page

get_schema()

Get Table schema.

private static get_schema() : string

See https://github.com/woocommerce/woocommerce/wiki/Database-Description/

A note on indexes; Indexes have a maximum size of 767 bytes. Historically, we haven't need to be concerned about that. As of WordPress 4.2, however, we moved to utf8mb4, which uses 4 bytes per character. This means that an index which used to have room for floor(767/3) = 255 characters, now only has room for floor(767/4) = 191 characters.

Changing indexes may cause duplicate index notices in logs due to https://core.trac.wordpress.org/ticket/34870 but dropping indexes first causes too much load on some servers/larger DB.

When adding or removing a table, make sure to update the list of tables in WC_Install::get_tables().

Return values
string

is_installing()

Returns true if we're installing.

private static is_installing() : bool
Return values
bool

maybe_set_activation_transients()

See if we need to set redirect transients for activation or not.

private static maybe_set_activation_transients() : mixed
Tags
since
4.6.0
Return values
mixed

maybe_update_db_version()

See if we need to show or run database updates during install.

private static maybe_update_db_version() : mixed
Tags
since
3.2.0
Return values
mixed

newly_installed()

Trigger `woocommerce_newly_installed` action for new installations.

private static newly_installed() : mixed
Tags
since
8.0.0
Return values
mixed

remove_admin_notices()

Reset any notices added to admin.

private static remove_admin_notices() : mixed
Tags
since
3.2.0
Return values
mixed

set_paypal_standard_load_eligibility()

Sets whether PayPal Standard will be loaded on install.

private static set_paypal_standard_load_eligibility() : mixed
Tags
since
5.5.0
Return values
mixed

setup_environment()

Setup WC environment - post types, taxonomies, endpoints.

private static setup_environment() : mixed
Tags
since
3.2.0
Return values
mixed

update()

Push all needed DB updates to the queue for processing.

private static update() : mixed
Return values
mixed

update_wc_version()

Update WC version to current.

private static update_wc_version() : mixed
Return values
mixed