rfc:streamline-phar-api

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

  • 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

  • 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

  • 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

  • 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?
rfc/streamline-phar-api.1206716467.txt.gz · Last modified: 2017/09/22 13:28 (external edit)