Title: _unzip_file_pclzip
Published: April 25, 2014
Last modified: May 20, 2026

---

# _unzip_file_pclzip( string $file, string $to, string[] $needed_dirs = array() ): true|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#description)
    - [See also](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#see-also)
 * [Parameters](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#wp--skip-link--target)

This function’s access is marked private. This means it is not intended for use 
by plugin or theme developers, only by core. It is listed here for completeness.

Attempts to unzip an archive using the PclZip library.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#description)󠁿

This function should not be called directly, use `unzip_file()` instead.

Assumes that [WP_Filesystem()](https://developer.wordpress.org/reference/functions/wp_filesystem/)
has already been called and set up.

### 󠀁[See also](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#see-also)󠁿

 * [unzip_file()](https://developer.wordpress.org/reference/functions/unzip_file/)

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#parameters)󠁿

 `$file`stringrequired

Full path and filename of ZIP archive.

`$to`stringrequired

Full path on the filesystem to extract archive to.

`$needed_dirs`string[]optional

A partial list of required folders needed to be created.

Default:`array()`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#return)󠁿

 true|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) True
on success, [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
on failure.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#source)󠁿

    ```php
    function _unzip_file_pclzip( $file, $to, $needed_dirs = array() ) {
    	global $wp_filesystem;

    	mbstring_binary_safe_encoding();

    	require_once ABSPATH . 'wp-admin/includes/class-pclzip.php';

    	$archive = new PclZip( $file );

    	$archive_files = $archive->extract( PCLZIP_OPT_EXTRACT_AS_STRING );

    	reset_mbstring_encoding();

    	// Is the archive valid?
    	if ( ! is_array( $archive_files ) ) {
    		return new WP_Error( 'incompatible_archive', __( 'Incompatible Archive.' ), $archive->errorInfo( true ) );
    	}

    	if ( 0 === count( $archive_files ) ) {
    		return new WP_Error( 'empty_archive_pclzip', __( 'Empty archive.' ) );
    	}

    	$uncompressed_size = 0;

    	// Determine any children directories needed (From within the archive).
    	foreach ( $archive_files as $archive_file ) {
    		if ( str_starts_with( $archive_file['filename'], '__MACOSX/' ) ) { // Skip the OS X-created __MACOSX directory.
    			continue;
    		}

    		// Don't extract invalid files:
    		if ( 0 !== validate_file( $archive_file['filename'] ) ) {
    			continue;
    		}

    		$uncompressed_size += $archive_file['size'];

    		$needed_dirs[] = $to . untrailingslashit( $archive_file['folder'] ? $archive_file['filename'] : dirname( $archive_file['filename'] ) );
    	}

    	// Enough space to unzip the file and copy its contents, with a 10% buffer.
    	$required_space = $uncompressed_size * 2.1;

    	/*
    	 * disk_free_space() could return false. Assume that any falsey value is an error.
    	 * A disk that has zero free bytes has bigger problems.
    	 * Require we have enough space to unzip the file and copy its contents, with a 10% buffer.
    	 */
    	if ( wp_doing_cron() ) {
    		$available_space = function_exists( 'disk_free_space' ) ? @disk_free_space( WP_CONTENT_DIR ) : false;

    		if ( $available_space && ( $required_space > $available_space ) ) {
    			return new WP_Error(
    				'disk_full_unzip_file',
    				__( 'Could not copy files. You may have run out of disk space.' ),
    				compact( 'uncompressed_size', 'available_space' )
    			);
    		}
    	}

    	$needed_dirs = array_unique( $needed_dirs );

    	foreach ( $needed_dirs as $dir ) {
    		// Check the parent folders of the folders all exist within the creation array.
    		if ( untrailingslashit( $to ) === $dir ) { // Skip over the working directory, we know this exists (or will exist).
    			continue;
    		}

    		if ( ! str_contains( $dir, $to ) ) { // If the directory is not within the working directory, skip it.
    			continue;
    		}

    		$parent_folder = dirname( $dir );

    		while ( ! empty( $parent_folder )
    			&& untrailingslashit( $to ) !== $parent_folder
    			&& ! in_array( $parent_folder, $needed_dirs, true )
    		) {
    			$needed_dirs[] = $parent_folder;
    			$parent_folder = dirname( $parent_folder );
    		}
    	}

    	asort( $needed_dirs );

    	// Create those directories if need be:
    	foreach ( $needed_dirs as $_dir ) {
    		// Only check to see if the dir exists upon creation failure. Less I/O this way.
    		if ( ! $wp_filesystem->mkdir( $_dir, FS_CHMOD_DIR ) && ! $wp_filesystem->is_dir( $_dir ) ) {
    			return new WP_Error( 'mkdir_failed_pclzip', __( 'Could not create directory.' ), $_dir );
    		}
    	}

    	/** This filter is documented in wp-admin/includes/file.php */
    	$pre = apply_filters( 'pre_unzip_file', null, $file, $to, $needed_dirs, $required_space );

    	if ( null !== $pre ) {
    		return $pre;
    	}

    	// Extract the files from the zip.
    	foreach ( $archive_files as $archive_file ) {
    		if ( $archive_file['folder'] ) {
    			continue;
    		}

    		if ( str_starts_with( $archive_file['filename'], '__MACOSX/' ) ) { // Don't extract the OS X-created __MACOSX directory files.
    			continue;
    		}

    		// Don't extract invalid files:
    		if ( 0 !== validate_file( $archive_file['filename'] ) ) {
    			continue;
    		}

    		if ( ! $wp_filesystem->put_contents( $to . $archive_file['filename'], $archive_file['content'], FS_CHMOD_FILE ) ) {
    			return new WP_Error( 'copy_failed_pclzip', __( 'Could not copy file.' ), $archive_file['filename'] );
    		}
    	}

    	/** This filter is documented in wp-admin/includes/file.php */
    	$result = apply_filters( 'unzip_file', true, $file, $to, $needed_dirs, $required_space );

    	unset( $needed_dirs );

    	return $result;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/file.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-admin/includes/file.php#L1868)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-admin/includes/file.php#L1868-L1994)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#hooks)󠁿

 [apply_filters( ‘pre_unzip_file’, null|true|WP_Error $result, string $file, string $to, string[] $needed_dirs, float $required_space )](https://developer.wordpress.org/reference/hooks/pre_unzip_file/)

Filters archive unzipping to override with a custom process.

 [apply_filters( ‘unzip_file’, true|WP_Error $result, string $file, string $to, string[] $needed_dirs, float $required_space )](https://developer.wordpress.org/reference/hooks/unzip_file/)

Filters the result of unzipping an archive.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#related)󠁿

| Uses | Description | 
| [wp_doing_cron()](https://developer.wordpress.org/reference/functions/wp_doing_cron/)`wp-includes/load.php` |

Determines whether the current request is a WordPress cron request.

  | 
| [untrailingslashit()](https://developer.wordpress.org/reference/functions/untrailingslashit/)`wp-includes/formatting.php` |

Removes trailing forward slashes and backslashes if they exist.

  | 
| [mbstring_binary_safe_encoding()](https://developer.wordpress.org/reference/functions/mbstring_binary_safe_encoding/)`wp-includes/functions.php` |

Sets the mbstring internal encoding to a binary safe encoding when func_overload is enabled.

  | 
| [reset_mbstring_encoding()](https://developer.wordpress.org/reference/functions/reset_mbstring_encoding/)`wp-includes/functions.php` |

Resets the mbstring internal encoding to a users previously set encoding.

  | 
| [validate_file()](https://developer.wordpress.org/reference/functions/validate_file/)`wp-includes/functions.php` |

Validates a file name and path against an allowed set of rules.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [WP_Error::__construct()](https://developer.wordpress.org/reference/classes/wp_error/__construct/)`wp-includes/class-wp-error.php` |

Initializes the error.

  |

[Show 3 more](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#)

| Used by | Description | 
| [unzip_file()](https://developer.wordpress.org/reference/functions/unzip_file/)`wp-admin/includes/file.php` |

Unzips a specified ZIP file to a location on the filesystem via the WordPress Filesystem Abstraction.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/_unzip_file_pclzip/?output_format=md#changelog)󠁿

| Version | Description | 
| [3.0.0](https://developer.wordpress.org/reference/since/3.0.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2F_unzip_file_pclzip%2F)
before being able to contribute a note or feedback.