Hack笔记

php官方关于phar手册的地址，不过由于这个模块比较相对比较冷僻，所以没有人翻译手册，这里针对一些常用的函数，对手册做一些简明的翻译。

public Phar::__construct ( string $fname [, int $flags [, string $alias ]] )

构造函数，用来构建Phar对象。

$fname是一个指向一个phar归档文件的路径或者要创建的归档文件存放的路径，注意这个文件的扩展名必须包含“.phar”。

$flags传入给父类RecursiveDirectoryIteratord的标志。

$alias在调用流功能时应引用此Phar归档的别名.

错误和异常：被调用2次时，抛BadMethodCallException异常，当$fname指定的归档文件打不开时抛UnexpectedValueException异常。

 

public array Phar::buildFromDirectory ( string $base_dir [, string $regex ] )

从指定目录中的文件构造phar归档，此方法需要 将 php.ini 中的 phar.readonly 设为 0 以适合 Phar 对象. 否则, 将抛出PharException.用目录中的内容填充phar归档文件，第2个可选参数是一个正则表达式，用来过滤内容，匹配正则表达式的包含到归档文件中，否则排除。如果想要控制的更精细，试试Phar::buildFromIterator()。

$base_dir指定要填充到归档文件内容的目录路径(相对路径和绝对路径均可)。

$regex是一个可选正则参数用来过滤目录内的文件，只有匹配正则表达式的文件路径会被填充到归档文件中。

返回将文件的内部路径映射到文件系统上文件的完整路径的关联数组。

 

public void Phar::addFile ( string $file [, string $localname ] )

将一个文件从文件系统添加到 phar 档案中，此方法需要 将 php.ini 中的 phar.readonly 设为 0 以适合 Phar 对象. 否则, 将抛出PharException。通过这个方法，任何文件或者 URL 可以被添加到 phar 档案中。如果第二个可选参数 localname 被设定， 那么文件则会以该参数为名称保存到档案中，此外，file 参数会被作为路径保存在档案中。 URLs 必须提交 localname 参数，否则会抛出异常。 这个方法与 ZipArchive::addFile() 类似.

$file需要添加到 phar 档案的文件在磁盘上的完全（绝对）或者相对路径。

$localname文件保存到档案时的路径。

没有返回值，失败时会抛出异常。

 

public bool Phar::setDefaultStub ([ string $index [, string $webindex ]] )

用来将归档文件的加载器或者引导脚本设置为默认的加载器(几个英文单词吃不准，后面是原文 Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader)。其实这个函数是Phar::createDefaultStub() 和Phar::setStub()的一个封装。

$index是一个归档文件内部的相对路径，如果在cli模式(命令行)下运行phar文件时执行的脚本。

$webindex是一个归档文件内部的相对路径，如果通过web浏览器访问phar归档文件时执行的脚本。

成功返回true，失败返回false。

 

public void Phar::compressFiles ( int $compression )

压缩当前phar归档中的文件。

$compression压缩时必须为Phar::GZ或 Phar::BZ2 ,或者使用 Phar::NONE 移除已有的压缩.

 

public bool Phar::extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] )

将归档文件中的内容解压到指定目录。解压归档文件到硬盘时，会保留他们在归档文件中的权限。可选参数允许你控制那些文件提取到硬盘上或者当它们存在时是否覆盖它们。第2个可选参数可以是字符串或者数组，表示提取文件或目录的名字。默认的这个函数不会覆盖存在的文件，不过可以通过将第3个参数设置为true启用强制覆盖存在的文件。

$pathto解压提取到硬盘的路径。

$files可选参数指定提取归档文件或目录的名字，或者提取文件或目录的名字的数组。

$overwrite设置为true启用强制覆盖。

成功返回true，不过更好的办法是检查异常，如果没有异常抛出就是成功。

 

final public static bool Phar::loadPhar ( string $filename [, string $alias ] )

使用别名加载任意的phar归档文件。一般用来从外部来读取归档文件中的内容。最常用的就是给归档文件一个别名，随后就可以使用别名来引用归档文件，或者用于加载仅包含数据且不用于在PHP脚本中执行/包含的Phar存档。

$filename要打开的归档文件的相对或者绝对路径。

$alias设置一个用来引用归档文件的别名。许多phar档案在phar档案中指定一个显式别名，如果别名已经被制定过时，会抛出一个PharException异常。

成功时返回 TRUE， 或者在失败时返回 FALSE。

php5.3以后有一个非常不错的特性phar，有些类似java中的jar包，就是可以把php应用程序打包到一个单独的phar归档文件中。其实这个特性以前很早貌似就用，只不过最早是用php写的，所以性能上面不是特别好，后面官方用c扩展重新写一遍，文档可以查看Phar文档，不过目前90%的内容是英文的，下面我对介绍进行了一点简单翻译,当然英语水平一般，错误之处欢迎指正啊。

Phar简介

Phar扩展提供了一种将整个php应用放入一个单独文件被称为”phar”的归档，包更容易的发布和安装的解决方案。除了提供这种服务，phar扩展也提供了一种抽象化的文件格式的方法来创建和管理tar或者zip文件通过PharData类，很像Pdo提供了一种统一的接口来访问不同的数据库。和PDO不同之处，Pdo不能将数据在不同的数据库之间转换，Phar可以通过一行代码就可以在tar,zip和phar之间转换文件格式。查看Phar::convertToExecutable()示例。

phar是什么？phar归档文件最显著的特征是组合很多文件文件到一个单独的文件中。就像这样，一个phar文档提供了一种方式来发布一个完成的php应用程序在一个单独的文件中并且可以通过这个文件来运行它而无需解压到硬盘上。此外，phar归档文件也可以像其他php文件一样去被PHP执行，同时可以通过命令行和一台web服务器。Phar就像一种为PHP应用程序设计的拇指驱动器（U盘）。

Phar实现这些功能通过Stream Wrapper。一般来说，要使用一个在Phar归档中的php脚本文件，你可以用include。

函数介绍

可以参考另一篇关于phar函数手册的博客。

简单案例

这是一个比较简单的demo，希望通过这个能对phar有个比较初步的了解。

目录树如下：

|____build.php
|____config.json
|____extractPhar.php
|____lib
| |____class
| | |____empty.txt
| |____func.php
| |____stub.php
|____phar.phar
|____test_phar.php

build.php为生成phar归档文件的php脚本，config.json文件其实没什么用，extractPhar.php为解压phar到指定目录的脚本，lib目录下面就是测试用的库函数，phar.phar是用build.php生成的归档文件，test_phar.php是测试phar归档文件的脚本。下面我们一个一个的介绍这里面涉及到的脚本文件。

[build.php]

</pre>
<pre><?php</pre>
<pre>try{
    $phar = new Phar('phar.phar',0,'my.phar');
    $phar->buildFromDirectory(__DIR__.'/lib/');
    //$phar->buildFromDirectory(__DIR__.'/lib/',"/\.php/");
    $phar->addFile("config.json","config");
    $phar->setDefaultStub('stub.php','stub.php');
    $phar->compressFiles(Phar::GZ);
}catch (Exception $e){
    echo $e->getMessage();
}</pre>
<pre>

这里需要注意把php.ini 中的 phar.readonly 设为 0 以适合 Phar 对象. 否则, 将抛出PharException。

[func.php]

</pre>
<pre>function println($str){
    echo $str."\n";
}

function myFunc($input=__FILE__){
    println('Input File:'.$input);
    println('File Path:'.__DIR__);
}</pre>
<pre>

[stub.php]

</pre>
<pre><?php

require_once 'func.php';
myFunc(__FILE__);</pre>
<pre>

[test_phar.php]

</pre>
<pre><?php
include_once 'phar.phar';
include_once 'phar://my.phar/func.php';
myFunc(__FILE__);
$content = file_get_contents("phar://my.phar/config");
println($content);</pre>
<pre>

[extractPhar.php]

</pre>
<pre><?php
$phar = new Phar('phar.phar');
$phar->extractTo('./extract/');</pre>
<pre>

通过命令行脚本执行”php build.php”可以生成phar.phar归档文件。可以直接用”php phar.phar”执行phar归档文件，
它会执行”setDefaultStub”设置stub文件。extractPhar.php会将phar.phar归档文件中的内容解压到extract目录下面，
方面我们查看phar归档中的内容。
test_phar.php的执行结果如下：

Input File:phar:///Users/king/www/test/Phar/phar.phar/stub.php
File Path:phar:///Users/king/www/test/Phar/phar.phar
Input File:/Users/king/www/test/Phar/test_phar.php
File Path:phar:///Users/king/www/test/Phar/phar.phar
{
 "name" : "phar test project",
 "path" : "~/www/test/Phar"
}

extractPhar.php解压的extract目录如下：
|____class
| |____empty.txt
|____config
|____func.php
|____stub.php