# TarballExtractor

> Extracts an npm package tarball (gzip-compressed or plain tar) into a directory, stripping the first path component.

[API reference](/docs/api/index.md) › [Foxy](/docs/extensions/foxy/reference/index.md) › [Native](/docs/extensions/foxy/reference/native/index.md) › TarballExtractor

| final readonly class | `Foxy\Native\TarballExtractor` |
| --- | --- |
| Source | [`src/Native/TarballExtractor.php`](https://github.com/php-forge/foxy/blob/main/src/Native/TarballExtractor.php#L42) |

Extracts an npm package tarball (gzip-compressed or plain tar) into a directory, stripping the first path component.

Reads POSIX ustar, PAX extended headers (`path` and `size` records) and GNU long names. Directories and regular
files are created; symbolic links, hard links and unknown entry types are skipped. A file whose mode carries an
execute bit is made executable (`0755`); modification times are not preserved.

See also: <https://pubs.opengroup.org/onlinepubs/9799919799/utilities/pax.html>.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`__construct()`](#method-__construct) | Creates a tarball extractor using Composer's filesystem abstraction. | `TarballExtractor` |
| [`extract()`](#method-extract) | Extracts the tarball into the destination directory, creating it first. | `TarballExtractor` |

## Method details

### __construct() <span id="method-__construct"></span>

```php
public function __construct(Composer\Util\Filesystem $fs)
```

Creates a tarball extractor using Composer's filesystem abstraction.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$fs` | `Composer\Util\Filesystem` | Filesystem used to create directories. |

### extract() <span id="method-extract"></span>

```php
public function extract(string $tarball, string $destination, string $label): void
```

Extracts the tarball into the destination directory, creating it first.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$tarball` | `string` | Path of the `.tgz` (or plain `.tar`) file. |
| `$destination` | `string` | Directory that receives the package contents. |
| `$label` | `string` | Name of the tarball used in error messages, the tarball URL in production. |

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the tarball cannot be opened, is not a valid ustar archive, is truncated, holds an entry outside the package directory, or an entry cannot be written.