Search by

moonlydays / php-vpk

MoonlyDays

Valve's VPK archive implementation for PHP.

Package info

github.com/MoonlyDays/php-vpk

pkg:composer/moonlydays/php-vpk

Statistics

Installs: 42

Dependents: 0

Suggesters: 0

Stars: 2

Open Issues: 0

2.0.2 2026-11-19 21:51 UTC

This package is auto-updated.

Last update: 2026-11-19 21:52:58 UTC


README

A pure-PHP library for reading and writing Valve's VPK archive format — the package format used by Source engine games such as Team Fortress 2, Counter-Strike: Source, and Half-Life 2.

Supports VPK v1 and v2 directory files, including preload data and file data embedded in the _dir.vpk itself. No native extensions required beyond ext-mbstring.

Installation

composer require moonlydays/php-vpk

Requires PHP 8.5 or newer.

Usage

use MoonlyDays\VPK\VpkArchive;
use MoonlyDays\VPK\VpkEntry;

$archive = VpkArchive::fromPath('/path/to/tf2_misc_dir.vpk');

// List every file in the archive
foreach ($archive as $path => $entry) {
    echo $path, ' (', $entry->size(), ' bytes)', PHP_EOL;
}

// Look up and read a single file (paths are case-insensitive, either slash style)
if ($archive->has('materials/console/background01.vmt')) {
    $contents = $archive->read('materials/console/background01.vmt');
}

// Find files by glob
$materials = $archive->find('materials/*.vmt');

// Extract a single file, preserving its archive path
$archive->extractFileTo('materials/console/background01.vmt', __DIR__ . '/out');

// Or extract everything (optionally filtered)
$archive->extractTo(__DIR__ . '/out', fn (VpkEntry $entry) => $entry->extension === 'vmt');

$archive->close();

Extracting to Flysystem or a Laravel disk

extractTo() and extractFileTo() also accept a Flysystem filesystem, so you can extract straight to S3, SFTP, an in-memory filesystem, or any Laravel disk. Install league/flysystem (version 3) to use it; the library works without it.

// Any Flysystem filesystem
$archive->extractTo($filesystem);

// A Laravel disk: pass its underlying Flysystem driver
$archive->extractTo(Storage::disk('s3')->getDriver());
$archive->extractFileTo('materials/logo.vtf', Storage::disk('public')->getDriver(), overwrite: true);

Files keep their archive paths, relative to the filesystem's root. To extract under a folder, use a disk whose root (or prefix) points there. Flysystem errors are rethrown as a VpkException, with the original exception as its previous.

Building an archive

use MoonlyDays\VPK\VpkBuilder;

// One self-contained file, with every file's data stored inside it
VpkBuilder::create()
    ->addDirectory(__DIR__ . '/my_mod')                  // every file below the directory
    ->addFile('materials/logo.vtf', __DIR__ . '/logo.vtf')
    ->addString('scripts/version.txt', '1.0.0')
    ->build(__DIR__ . '/my_mod.vpk');

// A "_dir.vpk" plus numbered chunks of at most 100 MB each
$archive = VpkBuilder::create()
    ->addDirectory(__DIR__ . '/my_mod')
    ->chunkSize(100 * 1024 * 1024)
    ->build(__DIR__ . '/pak01_dir.vpk');

build() writes a VPK v1 archive and returns it opened as a VpkArchive. File data is streamed, so large files are never loaded into memory. The output is reproducible: entries are sorted, so the same input always produces the same bytes.

How VPK files are laid out

A VPK archive is split across multiple files on disk:

  • <name>_dir.vpk — holds the header and the directory tree
  • <name>_000.vpk, <name>_001.vpk, ... — hold the actual file payloads

You always open the _dir.vpk file. The sibling chunk files must live in the same directory; the library opens them lazily as needed and caches the handles until close() is called.

API

Methods that take an entry accept either an in-archive path (string) or a VpkEntry.

MoonlyDays\VPK\VpkArchive

Opening and header

Method Description
static fromPath(string $vpkPath): self Open a _dir.vpk. Throws VpkException if the file can't be read or the header signature is invalid.
path(): string Path of the _dir.vpk file.
version(): int VPK format version.
treeSize(), fileDataSectionSize(), archiveMd5SectionSize(), otherMd5SectionSize(), signatureSectionSize() Header section sizes in bytes (0 when the version doesn't define them).

Browsing

Method Description
entries(): list<VpkEntry> Every entry, in directory order.
files(): list<string> Every file path.
has(string $path): bool Whether a path exists. Case-insensitive; accepts / or \.
entry(string $path): ?VpkEntry Look up an entry by path.
count(): int Number of entries. The archive is also Countable and iterable as path => VpkEntry.
directories(): list<string> Unique directory paths ('' is the root).
extensions(): list<string> Unique extensions, without the leading dot.
filesIn(string $directory, bool $recursive = false): list<VpkEntry> Entries in a directory, optionally including subdirectories.
find(string $pattern): list<VpkEntry> Entries matching a case-insensitive glob such as materials/*.vmt. * also matches across /.
filter(callable $callback): list<VpkEntry> Entries accepted by $callback(VpkEntry): bool.
totalSize(): int Combined size of every file, in bytes.

Reading

Method Description
read($entry): string Full contents as a string. Convenient for small files.
stream($entry): resource A rewound, readable php://temp stream with the contents. The caller should fclose it.
writeTo($entry, resource $destination): void Stream the contents into an open, writable stream without buffering them in memory.
verify($entry): bool Check the contents against the stored CRC32. Returns false on a mismatch.

Extracting

Method Description
extractFileTo($entry, string|FilesystemOperator $target, bool $overwrite = false): void Extract one file into a directory or Flysystem filesystem, preserving its archive path. Refuses paths that would escape the target.
extractFileAs($entry, string $destination, bool $overwrite = false): void Extract one file to an explicit file path.
extractTo(string|FilesystemOperator $target, ?callable $filter = null, bool $overwrite = false): int Extract every file (or those accepted by $filter) into a directory or Flysystem filesystem. Returns the number of files extracted or already present.
close(): void Close cached chunk-file handles. Safe to call repeatedly; handles are reopened on demand.

Reading and extraction methods throw a VpkException when the path is unknown, its chunk file is missing, its data is truncated, or the destination can't be written; extractTo stops at the first failure. Files that already exist on disk are left untouched unless $overwrite is true.

MoonlyDays\VPK\VpkBuilder

Method Description
static create(): self Start an empty archive.
addFile(string $path, string $file): self Add the file at $file under the archive path $path.
addString(string $path, string $contents): self Add $contents under the archive path $path.
addDirectory(string $dir, string $prefix = ''): self Add every file below $dir, keeping its relative path (under $prefix, if given).
chunkSize(int $bytes): self Split data into <name>_NNN.vpk chunks of at most $bytes. A larger file gets a chunk of its own.
has(string $path): bool, count(): int Whether a path was added, and how many.
build(string $path): VpkArchive Write the archive, replacing existing files, and open it. With chunkSize(), $path must end in _dir.vpk.

Archive paths accept either slash style. Adding the same path twice (case-insensitively) replaces the first one. Paths that are absolute, contain .././empty segments, : or NUL bytes are rejected. Offsets and sizes are limited to 4 GiB per file and per chunk (or per single-file archive).

MoonlyDays\VPK\VpkEntry

A single file record. Public properties: path, directory, name, extension, plus the raw on-disk fields CRC, PreloadBytes, ArchiveIndex, EntryOffset, EntryLength and Terminator.

Method Description
fileName(): string Name with extension, e.g. wood.vmt.
size(): int Total size in bytes (preload data + archived data).
hasPreloadData(): bool Whether part of the file is stored inline in the directory.
isStoredInDirectory(): bool Whether the data lives in the _dir.vpk itself rather than a numbered chunk.
crcHex(): string CRC as 8 lowercase hex characters, matching hash('crc32b', ...).
isIn(string $directory, bool $recursive = false): bool Whether the entry lives in $directory (or below it).

MoonlyDays\VPK\VpkException

Thrown with a descriptive message when a _dir.vpk can't be opened, has an invalid header signature or ends unexpectedly, and when reading or extracting an entry fails (unknown path, missing or truncated chunk, unwritable destination, or a path that would escape the target directory).

Development

composer install
composer test    # run the Pest suite
composer lint    # run Laravel Pint and Rector

The test suite generates all VPK fixtures at runtime, so no binary test data is committed to the repository.

License

Released under the MIT License.