# add_query_arg()

URL: https://chugunov.pro/api-wordpress/functions/add_query_arg/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 1.5.0.

## Сигнатура

```php
add_query_arg( $args ): string
```

## Описание

С помощью этой функции можно перестроить URL и добавить переменные запроса в строку запроса URL.
Есть два способа использования: либо одна пара ключ-значение, либо ассоциативный массив.
С одной парой ключ-значение:
add_query_arg( 'key', 'value', 'http://example.com' );С ассоциативным массивом:
add_query_arg( array(
'key1' => 'value1',
'key2' => 'value2',
), 'http://example.com' );Если в любом из вариантов URL не указан, используется текущий URL (значение $_SERVER['REQUEST_URI']).
Ожидается, что значения соответствующим образом закодированы с помощью urlencode() или rawurlencode().
Установка значения любой переменной запроса в логическое false удаляет ключ (см. remove_query_arg()).
Важно: возвращаемое значение add_query_arg() по умолчанию не экранируется. Вывод следует экранировать в последний момент с помощью esc_url() или аналогичной функции, чтобы снизить риск межсайтового скриптинга (XSS).

## Параметры

- `$key` `string|array` — обязательный. Либо ключ переменной запроса, либо ассоциативный массив переменных запроса.
- `$value` `string` — необязательный. Либо значение переменной запроса, либо URL, над которым выполняется действие.
- `$url` `string` — необязательный. URL, над которым выполняется действие.

## Возвращаемое значение

`string`

## Исходный код

Файл: `wp-includes/functions.php:1139`

```php
function add_query_arg( ...$args ) {
	if ( is_array( $args[0] ) ) {
		if ( count( $args ) < 2 || false === $args[1] ) {
			$uri = $_SERVER['REQUEST_URI'];
		} else {
			$uri = $args[1];
		}
	} else {
		if ( count( $args ) < 3 || false === $args[2] ) {
			$uri = $_SERVER['REQUEST_URI'];
		} else {
			$uri = $args[2];
		}
	}

	$frag = strstr( $uri, '#' );
	if ( $frag ) {
		$uri = substr( $uri, 0, -strlen( $frag ) );
	} else {
		$frag = '';
	}

	if ( 0 === stripos( $uri, 'http://' ) ) {
		$protocol = 'http://';
		$uri      = substr( $uri, 7 );
	} elseif ( 0 === stripos( $uri, 'https://' ) ) {
		$protocol = 'https://';
		$uri      = substr( $uri, 8 );
	} else {
		$protocol = '';
	}

	if ( str_contains( $uri, '?' ) ) {
		list( $base, $query ) = explode( '?', $uri, 2 );
		$base                .= '?';
	} elseif ( $protocol || ! str_contains( $uri, '=' ) ) {
		$base  = $uri . '?';
		$query = '';
	} else {
		$base  = '';
		$query = $uri;
	}

	wp_parse_str( $query, $qs );
	$qs = urlencode_deep( $qs ); // This re-URL-encodes things that were already in the query string.
	if ( is_array( $args[0] ) ) {
		foreach ( $args[0] as $k => $v ) {
			$qs[ $k ] = $v;
		}
	} else {
		$qs[ $args[0] ] = $args[1];
	}

	foreach ( $qs as $k => $v ) {
		if ( false === $v ) {
			unset( $qs[ $k ] );
		}
	}

	$ret = build_query( $qs );
	$ret = trim( $ret, '?' );
	$ret = preg_replace( '#=(&|$)#', '$1', $ret );
	$ret = $protocol . $base . $ret . $frag;
	$ret = rtrim( $ret, '?' );
	$ret = str_replace( '?#', '#', $ret );
	return $ret;
}
```

## История изменений

- 5.3.0 — Formalized the existing and already documented parameters by adding ...$args to the function signature.
- 1.5.0 — Introduced.

## Связанные

Использует: [`stripos`](https://chugunov.pro/api-wordpress/functions/stripos/), [`wp_parse_str`](https://chugunov.pro/api-wordpress/functions/wp_parse_str/), [`urlencode_deep`](https://chugunov.pro/api-wordpress/functions/urlencode_deep/), [`build_query`](https://chugunov.pro/api-wordpress/functions/build_query/).
Используется в: `WP_REST_Abilities_V1_Categories_Controller::get_items`, `WP_REST_Abilities_V1_List_Controller::get_items`, [`_wp_get_site_editor_redirection_url`](https://chugunov.pro/api-wordpress/functions/_wp_get_site_editor_redirection_url/), `WP_Automatic_Updater::has_fatal_error`, `WP_Plugin_Dependencies::check_plugin_dependencies_during_ajax`, `WP_Script_Modules::get_src`, `WP_REST_Font_Collections_Controller::get_items`, `WP_Plugin_Install_List_Table::get_more_details_link`, [`wp_get_plugin_action_button`](https://chugunov.pro/api-wordpress/functions/wp_get_plugin_action_button/), `WP_Plugins_List_Table::get_view_details_link`, `WP_REST_Global_Styles_Revisions_Controller::get_items`, [`wp_admin_bar_edit_site_menu`](https://chugunov.pro/api-wordpress/functions/wp_admin_bar_edit_site_menu/), `WP_REST_Sidebars_Controller::prepare_links`, [`core_auto_updates_settings`](https://chugunov.pro/api-wordpress/functions/core_auto_updates_settings/), `WP_REST_Block_Directory_Controller::prepare_links`, `WP_REST_Block_Types_Controller::prepare_links`, `Plugin_Installer_Skin::do_overwrite`, `Theme_Installer_Skin::do_overwrite`, `WP_MS_Themes_List_Table::column_autoupdates`, `WP_Privacy_Data_Removal_Requests_List_Table::column_email`, `WP_Privacy_Data_Removal_Requests_List_Table::column_next_steps`, `WP_MS_Sites_List_Table::get_views`, `WP_Privacy_Data_Export_Requests_List_Table::column_email`, `WP_Privacy_Data_Export_Requests_List_Table::column_next_steps`, `WP_Recovery_Mode_Link_Service::handle_begin_link`, `WP_Recovery_Mode_Link_Service::get_recovery_mode_begin_url`, [`wp_admin_bar_recovery_mode_menu`](https://chugunov.pro/api-wordpress/functions/wp_admin_bar_recovery_mode_menu/), [`resume_theme`](https://chugunov.pro/api-wordpress/functions/resume_theme/), [`wp_recovery_mode_nag`](https://chugunov.pro/api-wordpress/functions/wp_recovery_mode_nag/), `WP_Site_Health::get_test_rest_availability`, `WP_Site_Health::get_test_https_status`, [`resume_plugin`](https://chugunov.pro/api-wordpress/functions/resume_plugin/), [`wp_check_php_version`](https://chugunov.pro/api-wordpress/functions/wp_check_php_version/), `WP_REST_Search_Controller::get_items`, [`wp_get_script_polyfill`](https://chugunov.pro/api-wordpress/functions/wp_get_script_polyfill/), [`wp_get_code_editor_settings`](https://chugunov.pro/api-wordpress/functions/wp_get_code_editor_settings/), [`do_block_editor_incompatible_meta_box`](https://chugunov.pro/api-wordpress/functions/do_block_editor_incompatible_meta_box/), [`wp_send_user_request`](https://chugunov.pro/api-wordpress/functions/wp_send_user_request/), `WP_Privacy_Requests_Table::get_views`, `WP_Customize_Manager::handle_load_themes_request`.

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/add_query_arg/