rfc:streamline-phar-api

Request for comments: Streamline Phar API

  • Version: 0.1
  • Date: 2008-03-28
  • Author: Lars Strojny, based on ideas from Elizabeth M. Smith, Marcus Boerger, Benjamin Schulz
  • Status: Under development

Abstract

This proposal aims to streamline the Phar API to make it more usable and intuitive.

Basic 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. Not being able to write an archive either means it is disabled in the php.ini (see Phar::canWrite()) or that PHP can't write to the requested location of the phar archive. PharFileInfo must overload the method in order to accomplish that.

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'

Adding static create()-factory method

Proposal

Add a static create method to allow the convenient creation of a Phar-archive from the file system. The create()-method will take two arguments. The first argument is a string with the path to the archive. The second argument is a string with the path to the directory containing the files to be added to the archive. create() will return a Phar-object.

Code
$phar = Phar::create('test.phar', 'path/to/source/dir'); // Adds every file and subdirectory to test.phar

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?

DirectoryIterator

Implement DirectoryIterator

Let DirectoryIterator implement the ArrayAccess interface. By accessing an array index of a directory iterator, the related SplFileInfo object is returned.

Code

$iterator = new DirectoryIterator(__DIR__);
$file = $iterator['file'];

SplFileObject

Overload getContent()/setContent()

It is necessary to overload getContent()/setContent() in SplFileObject to properly reset internal flags. This is merely an implementation detail of the SplFileInfo::getContent()/setContent().

Extended change proposals

SplFileObject

Rename methods

Renamed methods
  • eof() => isEndOfFile()
  • fflush() => flush()
  • fgetc() => getChar()
  • fgetcvs() => getCsv()
  • fgets() => getLine()
  • fgetss() => getStripped()
  • flock() => lock()
  • fpassthru() => getRest()
  • fseek() => seek()
  • fstat() => stat()
  • ftell() => getLine()
  • ftruncate() => truncate()
  • fwrite() => write()
Proposal

Rename this methods to make their names more OO-alike, but leave the old names as deprecated aliases and remove them in PHP 6. This belongs to the extended change proposal as it would be practical to do but is not strictly related to Phar.

rfc/streamline-phar-api.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1