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.
STORE_ID_OPTION  = 'woocommerce_store_id'
Option name used to uniquely identify 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.
maybe_enable_hpos()  : mixed
Enable HPOS by default for new shops.
maybe_set_store_id()  : mixed
Set the Store ID if not already present.
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.
get_cart_block_content()  : string
Get the Cart block content.
get_checkout_block_content()  : string
Get the Checkout block content.
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.
install_core()  : mixed
Core function that performs the WooCommerce install.
is_installing()  : bool
Returns true if we're installing.
maybe_activate_legacy_api_enabled_option()  : mixed
If in a previous version of WooCommerce the Legacy REST API plugin was installed manually but the core Legacy REST API was kept disabled, now the Legacy API is still disabled and can't be manually enabled from settings UI (the plugin, which is now in control, won't allow that), which is weird and confusing. So we detect this case and explicitly enable it.
maybe_install_legacy_api_plugin()  : mixed
Install and activate the WooCommerce Legacy REST API plugin from the WordPress.org directory if all the following is true:
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.
should_enable_hpos_for_new_shop()  : bool
Checks whether HPOS should be enabled for new shops.
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'

STORE_ID_OPTION

Option name used to uniquely identify installations of WooCommerce.

public string STORE_ID_OPTION = 'woocommerce_store_id'

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'), '8.1.0' => array('wc_update_810_migrate_transactional_metadata_for_hpos'), '8.6.0' => array('wc_update_860_remove_recommended_marketing_plugins_transient'), '8.7.0' => array('wc_update_870_prevent_listing_of_transient_files_directory'), '8.9.0' => array('wc_update_890_update_connect_to_woocommerce_note', 'wc_update_890_update_paypal_standard_load_eligibility'), '8.9.1' => array('wc_update_891_create_plugin_autoinstall_history_option'), '9.1.0' => array('wc_update_910_add_launch_your_store_tour_option', 'wc_update_910_remove_obsolete_user_meta'))

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 —

maybe_enable_hpos()

Enable HPOS by default for new shops.

public static maybe_enable_hpos() : mixed
Tags
since
8.2.0
Return values
mixed —

maybe_set_store_id()

Set the Store ID if not already present.

public static maybe_set_store_id() : mixed
Tags
since
8.4.0
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 —

plugin_action_links()

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> —

get_cart_block_content()

Get the Cart block content.

protected static get_cart_block_content() : string
Tags
since
8.3.0
Return values
string —

get_checkout_block_content()

Get the Checkout block content.

protected static get_checkout_block_content() : string
Tags
since
8.3.0
Return values
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
string — The 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 —

install_core()

Core function that performs the WooCommerce install.

private static install_core() : mixed
Return values
mixed —

is_installing()

Returns true if we're installing.

private static is_installing() : bool
Return values
bool —

maybe_activate_legacy_api_enabled_option()

If in a previous version of WooCommerce the Legacy REST API plugin was installed manually but the core Legacy REST API was kept disabled, now the Legacy API is still disabled and can't be manually enabled from settings UI (the plugin, which is now in control, won't allow that), which is weird and confusing. So we detect this case and explicitly enable it.

private static maybe_activate_legacy_api_enabled_option() : mixed
Return values
mixed —

maybe_install_legacy_api_plugin()

Install and activate the WooCommerce Legacy REST API plugin from the WordPress.org directory if all the following is true:

private static maybe_install_legacy_api_plugin() : mixed
  1. We are in a WooCommerce upgrade process (not a new install).
  2. The 'woocommerce_skip_legacy_rest_api_plugin_auto_install' filter returns false (which is the default).
  3. The plugin is not installed and active already (but see note about multisite below).
  4. The Legacy REST API is enabled in the site OR the site has at least one webhook defined that uses the Legacy REST API payload format (disabled webhooks also count).

In multisite setups it could happen that the plugin was installed by an installation process performed in another site. In this case we check if the plugin was autoinstalled in such a way, and if so we activate it if the conditions are fulfilled.

Return values
mixed —

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 —

should_enable_hpos_for_new_shop()

Checks whether HPOS should be enabled for new shops.

private static should_enable_hpos_for_new_shop() : bool
Return values
bool —

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 —