函数文档

wp_raise_memory_limit()

💡 云策文档标注

概述

wp_raise_memory_limit() 函数用于在内存密集型处理中尝试提高 PHP 内存限制。它仅允许提高现有限制,防止降低,并支持多种上下文以适配不同场景。

关键要点

  • 函数旨在提升 PHP 内存限制,适用于管理后台、图像处理、WP-Cron 等内存密集型任务。
  • 接受可选参数 $context,默认为 'admin',其他值包括 'image'、'cron' 或任意自定义上下文。
  • 通过 WP_MAX_MEMORY_LIMIT 常量定义最大限制,并应用相应过滤器(如 admin_memory_limit)进行动态调整。
  • 返回设置后的限制值(整数或字符串)或失败时返回 false。
  • 内部依赖 wp_is_ini_value_changeable() 和 wp_convert_hr_to_bytes() 等辅助函数。

代码示例

function wp_raise_memory_limit( $context = 'admin' ) {
    // Exit early if the limit cannot be changed.
    if ( false === wp_is_ini_value_changeable( 'memory_limit' ) ) {
        return false;
    }

    $current_limit     = ini_get( 'memory_limit' );
    $current_limit_int = wp_convert_hr_to_bytes( $current_limit );

    if ( -1 === $current_limit_int ) {
        return false;
    }

    $wp_max_limit     = WP_MAX_MEMORY_LIMIT;
    $wp_max_limit_int = wp_convert_hr_to_bytes( $wp_max_limit );
    $filtered_limit   = $wp_max_limit;

    switch ( $context ) {
        case 'admin':
            $filtered_limit = apply_filters( 'admin_memory_limit', $filtered_limit );
            break;
        case 'image':
            $filtered_limit = apply_filters( 'image_memory_limit', $filtered_limit );
            break;
        case 'cron':
            $filtered_limit = apply_filters( 'cron_memory_limit', $filtered_limit );
            break;
        default:
            $filtered_limit = apply_filters( "{$context}_memory_limit", $filtered_limit );
            break;
    }

    $filtered_limit_int = wp_convert_hr_to_bytes( $filtered_limit );

    if ( -1 === $filtered_limit_int || ( $filtered_limit_int > $wp_max_limit_int && $filtered_limit_int > $current_limit_int ) ) {
        if ( false !== ini_set( 'memory_limit', $filtered_limit ) ) {
            return $filtered_limit;
        } else {
            return false;
        }
    } elseif ( -1 === $wp_max_limit_int || $wp_max_limit_int > $current_limit_int ) {
        if ( false !== ini_set( 'memory_limit', $wp_max_limit ) ) {
            return $wp_max_limit;
        } else {
            return false;
        }
    }

    return false;
}

注意事项

  • 函数仅在内存限制可更改时生效,否则直接返回 false。
  • 如果当前内存限制为 -1(无限制),函数也会返回 false,避免不必要的操作。
  • 自定义上下文会触发动态过滤器 {$context}_memory_limit,便于插件扩展。
  • 返回值类型灵活,可以是整数(字节)或简写字符串(如 '256M')。

📄 原文内容

Attempts to raise the PHP memory limit for memory intensive processes.

Description

Only allows raising the existing limit and prevents lowering it.

Parameters

$contextstringoptional
Context in which the function is called. Accepts either 'admin', 'image', 'cron', or an arbitrary other context. If an arbitrary context is passed, the similarly arbitrary ‘$context_memory_limit’ filter will be invoked. Default 'admin'.

Return

int|string|false The limit that was set or false on failure.

Source

function wp_raise_memory_limit( $context = 'admin' ) {
	// Exit early if the limit cannot be changed.
	if ( false === wp_is_ini_value_changeable( 'memory_limit' ) ) {
		return false;
	}

	$current_limit     = ini_get( 'memory_limit' );
	$current_limit_int = wp_convert_hr_to_bytes( $current_limit );

	if ( -1 === $current_limit_int ) {
		return false;
	}

	$wp_max_limit     = WP_MAX_MEMORY_LIMIT;
	$wp_max_limit_int = wp_convert_hr_to_bytes( $wp_max_limit );
	$filtered_limit   = $wp_max_limit;

	switch ( $context ) {
		case 'admin':
			/**
			 * Filters the maximum memory limit available for administration screens.
			 *
			 * This only applies to administrators, who may require more memory for tasks
			 * like updates. Memory limits when processing images (uploaded or edited by
			 * users of any role) are handled separately.
			 *
			 * The `WP_MAX_MEMORY_LIMIT` constant specifically defines the maximum memory
			 * limit available when in the administration back end. The default is 256M
			 * (256 megabytes of memory) or the original `memory_limit` php.ini value if
			 * this is higher.
			 *
			 * @since 3.0.0
			 * @since 4.6.0 The default now takes the original `memory_limit` into account.
			 *
			 * @param int|string $filtered_limit The maximum WordPress memory limit. Accepts an integer
			 *                                   (bytes), or a shorthand string notation, such as '256M'.
			 */
			$filtered_limit = apply_filters( 'admin_memory_limit', $filtered_limit );
			break;

		case 'image':
			/**
			 * Filters the memory limit allocated for image manipulation.
			 *
			 * @since 3.5.0
			 * @since 4.6.0 The default now takes the original `memory_limit` into account.
			 *
			 * @param int|string $filtered_limit Maximum memory limit to allocate for image processing.
			 *                                   Default `WP_MAX_MEMORY_LIMIT` or the original
			 *                                   php.ini `memory_limit`, whichever is higher.
			 *                                   Accepts an integer (bytes), or a shorthand string
			 *                                   notation, such as '256M'.
			 */
			$filtered_limit = apply_filters( 'image_memory_limit', $filtered_limit );
			break;

		case 'cron':
			/**
			 * Filters the memory limit allocated for WP-Cron event processing.
			 *
			 * @since 6.3.0
			 *
			 * @param int|string $filtered_limit Maximum memory limit to allocate for WP-Cron.
			 *                                   Default `WP_MAX_MEMORY_LIMIT` or the original
			 *                                   php.ini `memory_limit`, whichever is higher.
			 *                                   Accepts an integer (bytes), or a shorthand string
			 *                                   notation, such as '256M'.
			 */
			$filtered_limit = apply_filters( 'cron_memory_limit', $filtered_limit );
			break;

		default:
			/**
			 * Filters the memory limit allocated for an arbitrary context.
			 *
			 * The dynamic portion of the hook name, `$context`, refers to an arbitrary
			 * context passed on calling the function. This allows for plugins to define
			 * their own contexts for raising the memory limit.
			 *
			 * @since 4.6.0
			 *
			 * @param int|string $filtered_limit Maximum memory limit to allocate for this context.
			 *                                   Default WP_MAX_MEMORY_LIMIT` or the original php.ini `memory_limit`,
			 *                                   whichever is higher. Accepts an integer (bytes), or a
			 *                                   shorthand string notation, such as '256M'.
			 */
			$filtered_limit = apply_filters( "{$context}_memory_limit", $filtered_limit );
			break;
	}

	$filtered_limit_int = wp_convert_hr_to_bytes( $filtered_limit );

	if ( -1 === $filtered_limit_int || ( $filtered_limit_int > $wp_max_limit_int && $filtered_limit_int > $current_limit_int ) ) {
		if ( false !== ini_set( 'memory_limit', $filtered_limit ) ) {
			return $filtered_limit;
		} else {
			return false;
		}
	} elseif ( -1 === $wp_max_limit_int || $wp_max_limit_int > $current_limit_int ) {
		if ( false !== ini_set( 'memory_limit', $wp_max_limit ) ) {
			return $wp_max_limit;
		} else {
			return false;
		}
	}

	return false;
}

Hooks

apply_filters( ‘admin_memory_limit’, int|string $filtered_limit )

Filters the maximum memory limit available for administration screens.

apply_filters( ‘cron_memory_limit’, int|string $filtered_limit )

Filters the memory limit allocated for WP-Cron event processing.

apply_filters( ‘image_memory_limit’, int|string $filtered_limit )

Filters the memory limit allocated for image manipulation.

apply_filters( “{$context}_memory_limit”, int|string $filtered_limit )

Filters the memory limit allocated for an arbitrary context.

Changelog

Version Description
4.6.0 Introduced.