This is an old revision of the document!
Request for comments: Streamline Phar API
Abstract
This proposal aims to streamline the Phar API to make it more usable and intuitive.
Concrete change proposals
Phar
Modifying Phar archive content
Related methods
- offsetSet()
- offsetGet()
- offsetExists()
- offsetUnset()
Proposal
In the current API, every path is represented by a single array index. This is counter intuitive, as a multi-dimensional structure (the archive) is represented as a single dimensional array accessible object. The idea is to change that object to represent every path element (e.g. “bar” in “foo/bar/baz”) as a single index. This would be accomplished by letting the DirectoryIterator implement ArrayAccess.
Code
$phar = new Phar('test.phar'); $phar['path']['to']['file'] = 'test'; // Set content 'test' in path/to/file
Adding isWritable() method
Proposal
Add an isWritable() method to determine whether an archive can be written or not.
Code
$phar = new Phar('test.phar'); if ($phar->isWritable()) { $phar['path']['to']['file'] = "test"; }
Adding createDirectory()
Proposal
Add the method Phar->createDirectory() to explicitly create a new directory. createDirectory() will return another Phar object and takes a dirname (string) as an argument.
Code
$phar = new Phar('test.phar'); $dir = $phar->createDirectory('foo'); $dir['file'] = 'content'; // Set the file 'foo/file' to 'content'
SplFileInfo
PharFileInfo is derived from SplFileInfo. Every change in SplFileInfo will be visible in PharFileInfo.
setContent/getContent
Proposal
Add two simple methods to write/retrieve content.
Code
$file = new SplFileInfo("file"); $file->setContent('foo'); echo $file->getContent(); // returns 'foo'
get*Time() methods
Related methods
- getMTime()
- getATime()
- getCTime()
Proposal
Rename the methods to make them more independent from their origin, the UNIX naming scheme and therefore better to understand for a people with non-UNIX backgrounds. Leave the original method names but trigger deprecation warnings and remove them in PHP 6.
- getMTime() => getModificationTime()
- getATime() => getAccessTime()
- getCTime() => getCreateTime()
PharFileInfo
setCompressed*() methods
Related methods
- setCompressedBZIP2()
- setCompressedGZ()
- setUncompressed()
Proposal
Unify this methods to a single method compress(). The compress method will take one argument indicating the compression algorithm. The compression algorithm is represented as a Phar class constant. The setUncompressed() method should be renamed to uncompress().
Code
$file->compress(Phar::BZ2); // Compress with bzip2 $file->compress(Phar::GZ); // Compress with gzip $file->uncompress();
isCompressed*() methods
Related methods
- isCompressedBZIP2()
- isCompressedGZ()
- isCompressed()
Proposal
Unify this methods to one PharFileInfo::isCompressed(). The new isCompressed() would take an optional argument with the compression algorithm. The compression algorithm is represented as a Phar class constant.
Code
$file->isCompressed(); // Is the file compressed at all? $file->isCompressed(Phar::GZ); // Is the file gzip compressed? $file->isCompressed(Phar::BZ2); // Is the file bzip compressed?