Oihana PHP

untarAssertExtractable.php

Table of Contents

Functions

untarAssertExtractable()  : array<int, string>
Checks what an archive holds against what the caller allows, before anything is written.

Functions

untarAssertExtractable()

Checks what an archive holds against what the caller allows, before anything is written.

untarAssertExtractable(array<int, array{name: string, size: int, directory: bool}> $entries, string $outputPath[, bool $overwrite = true ][, int|null $maxExtractedSize = null ][, bool $allowUnsafeLinks = false ]) : array<int, string>

The three guarantees of untar() that cannot be made while extracting — a refusal to overwrite, the decompression-bomb cap, and the dry run that reports and does nothing — all come down to the same question asked of a listing. Both engines produce that listing, so the question is asked in one place: a cap enforced one way for the system tar and another for PharData would be two caps, and one of them would be wrong.

All of it happens before the first byte is extracted. A cap that fires half way leaves a directory the caller has to clean up, and a refusal to overwrite that fires on the fourth file has already overwritten three.

Parameters
$entries : array<int, array{name: string, size: int, directory: bool}>

What the archive holds, from untarEntries() or read off a PharData iterator.

$outputPath : string

Where the archive would be extracted.

$overwrite : bool = true

When false, an existing target is refused.

$maxExtractedSize : int|null = null

Cap on the total uncompressed size; null for none.

$allowUnsafeLinks : bool = false
Tags
throws
RuntimeException

If a name escapes the output directory, a target exists while $overwrite is false, or the total exceeds the cap.

example 
use function oihana\files\archive\tar\{tarBinary, untarAssertExtractable, untarEntries};

$files = untarAssertExtractable
(
    untarEntries( tarBinary() , '/backups/site.tar.gz' ) ,
    '/var/www/staging' ,
    false ,
    2 * 1024 * 1024 * 1024
) ;
author

Marc Alcaraz (ekameleon)

since
1.5.0
Return values
array<int, string> —

The names of the files the archive holds, directories left out — the list a dry run returns.

On this page

Search results