README

OleF is a PHP port of the OpenMCDF library (version 2.4), originally written in C# for the .NET platform. It allows developers to manipulate Microsoft Compound Document Files (also known as OLE structured storage).

In addition to porting the OpenMCDF logic, several .NET framework classes and functionalities were reimplemented to provide equivalent behavior in PHP, as these are not natively available in the language.

This port is inspired by and partially based on code and ideas from:

OpenMCDF (C#/.NET, MPL-2.0)
olefile (Python, BSD)
Microsoft .NET Framework (C#, MIT)

Features

Read/write operations on streams and storages
Traversal of the structure tree
Support for version 3 and 4 of the OLE specification
Lazy loading to minimize memory usage
Intuitive API for working with structured files
OLE Properties extension for DocumentSummaryInfo and SummaryInfo streams

Performance

OleF requires the ds PHP extension or php-ds/php-ds polyfill. While both provide the same functionality, there's a significant performance difference:

ext-ds (native C extension): Recommended for production use
php-ds/php-ds (PHP polyfill): 51x slower on average, up to 7,067x slower for large operations

Example performance differences:

Creating 256 streams: ext-ds ~6.9s, php-ds ~5m 52s (51x slower)
800MB file operations: ext-ds ~22m, php-ds ~1d 19h (would exhaust 8GB memory)
Large file append (2.1GB): ext-ds ~20s, php-ds ~39.5h (7,067x slower)

Performance Measurements

Tests were performed on:

Hardware: AMD Ryzen 9 9950X, 192GB RAM, Samsung SSD 990 PRO
OS: Arch Linux 6.15.4
PHP: 8.4.7 (AUR optimized build)
ext-ds: git version (php84-ds-git r1.3d2762f-1)
php-ds/php-ds: v1.7.0

For best performance, install the native extension:

# Debian/Ubuntu
sudo apt-get install php-ds

# macOS with Homebrew
pecl install ds

# Or compile from source
git clone https://github.com/php-ds/ext-ds
cd ext-ds
phpize
./configure
make
sudo make install

Usage Examples

Create a new compound file

$b = str_repeat("\x00", 10000);

$of = new \OleF\OleFile;
$myStream = $of->RootStorage->addStream('MyStream');

$myStream->setData($b);
$of->saveAs('MyCompoundFile.cfs');
$of->close();

Open an existing file (e.g., Excel workbook) and read a stream

//A xls file should have a Workbook stream
$of = \OleF\OleFile::open('report.xls');
$foundStream = $of->RootStorage->getStream('Workbook');
$temp = $foundStream->getData();
// do something with $temp
$of->close();

Add storage and stream items

// Open existing file in update mode (or create new one first)
$of = \OleF\OleFile::open('existing.cfs', true);
$st = $of->RootStorage->addStorage('MyStorage');
$sm = $st->addStream('MyStream');

Remove items

$of->RootStorage->delete('AStream'); // 'AStream' item is assumed to exist

Commit changes

$of->RootStorage->addStream('MyStream')->setData($buffer);
$of->commit();

Purge unused space (shrink file)

\OleF\OleFile::shrinkOleFile('MultipleStorage_Deleted_Compress.cfs');

Handle OLE Properties

$of = \OleF\OleFile::open('report.xls');
$pc = new \OleF\Extensions\OLEProperties\OLEPropertiesContainer($of->RootStorage->getStream("\x05SummaryInformation"));
foreach ($pc->Properties as $p) {
    // ...
}

More about OLE Compound Files

Compound files store multiple streams of information (such as document summary and user data) in a single container. This file format is used by many applications, including all Microsoft Office documents up to the 2007 release, Windows thumbnail cache files (thumbs.db), Outlook .msg files, Visual Studio .suo files, and some audio/video editing project files.

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

All files derived from or inspired by the above projects are subject to the terms of their respective licenses (primarily MPL-2.0).
Contributions to this project must be compatible with MPL-2.0.
For details, see the LICENSE file.

Contributing

Please respect the MPL-2.0 license and credit original authors when contributing.

Author: Lopo
Project URL: https://github.com/Lopo/OleF

lopo / olef

Maintainers

Details