Oihana PHP

tarLinkEntries.php

Table of Contents

Functions

tarLinkEntries()  : array<int, array{name: string, target: string, hard: bool}>
Reads the headers of an uncompressed tar archive and returns the link entries it holds.
tarHeaderSize()  : int
The size a tar header declares.
tarPaxRecords()  : array<string, string>
The records of a pax extended header.
tarReadBlock()  : string|null
One whole 512-byte block, or `null` when the stream has no more to give.

Functions

tarLinkEntries()

Reads the headers of an uncompressed tar archive and returns the link entries it holds.

tarLinkEntries(string $tarFile[, string|null $compression = null ]) : array<int, array{name: string, target: string, hard: bool}>

PharData is the only reader this library has when there is no GNU tar, and it cannot see a link: a link entry comes back from its iterator as a regular file of size 0, with isLink() answering false, and extractTo() writes an empty file in its place. Asking it is therefore not an option, and the headers are read here instead — they are plain, fixed and documented.

A compressed archive is read through its stream wrapper, which is the only way to see its links at all: PharData::decompress() rewrites the archive to decompress it, and since it cannot represent a link it writes a regular empty file in its place. The link is gone from the .tar it produces, so the compressed stream has to be read before it, not after.

Both kinds of link are reported, '2' (symbolic) and '1' (hard), along with GNU long names ('L', 'K') and the path/linkpath records of a pax header ('x'), since any of them can carry the name or the target of the entry that follows.

Parameters
$tarFile : string

Path to a tar archive.

$compression : string|null = null

Its compression, from CompressionType, or null when the archive is a plain .tar. Only gzip and bzip2 can be read here, since those are the two PHP has a stream wrapper for.

Tags
throws
RuntimeException

If the file cannot be read, is not a tar archive, or holds a block that is not a header.

example 
use function oihana\files\archive\tar\tarLinkEntries;

foreach ( tarLinkEntries( '/tmp/site.tar' ) as $link )
{
    // [ 'name' => 'wp-content/uploads' , 'target' => '/var/data/uploads' , 'hard' => false ]
}
author

Marc Alcaraz (ekameleon)

since
1.6.0
Return values
array<int, array{name: string, target: string, hard: bool}> —

The link entries, in the order the archive holds them.

tarHeaderSize()

The size a tar header declares.

tarHeaderSize(string $header) : int

Octal, as the format has always had it, unless the field's high bit is set: GNU writes a base-256 integer there for a size the twelve octal digits cannot hold.

Parameters
$header : string

One 512-byte tar header.

Tags
author

Marc Alcaraz (ekameleon)

since
1.6.0
Return values
int —

The declared size in bytes.

tarPaxRecords()

The records of a pax extended header.

tarPaxRecords(string $data) : array<string, string>

Each record is "<length> <keyword>=<value>\n", and the length counts itself, so the records are walked by the length they declare rather than split on a separator a value may contain.

Parameters
$data : string

The pax header's data blocks, trimmed to its declared size.

Tags
author

Marc Alcaraz (ekameleon)

since
1.6.0
Return values
array<string, string> —

The records, keyed by keyword.

tarReadBlock()

One whole 512-byte block, or `null` when the stream has no more to give.

tarReadBlock(resource $handle) : string|null

fread() on a compressed stream answers with what the inflater has ready rather than what was asked for, so a block is gathered until it is whole.

Parameters
$handle : resource

An open archive stream.

Tags
author

Marc Alcaraz (ekameleon)

since
1.6.0
Return values
string|null —

The block, or null at the end of the stream.

On this page

Search results