README

一个用于创建和读取（不使用phar扩展）PHP存档的PHP库。

要求

PHP >= 5.3.3
Phine 异常 >= 1.0.0
Phine 观察者 >= 2.0.0
Phine 路径 >= 1.0.0

安装

$ composer require "phine/phar=~1.0"

用法

构建存档

要创建新的存档，您需要创建一个新的 Builder 实例。有两种方法可以实现：使用现有的 Phar 实例或创建一个新的实例。

use Phine\Phar\Builder;

// using an existing Phar instance
$builder = new Builder($phar);

// create a new Phar instance
$builder = Builder::create('/path/to/archive.phar');

有了新的 Builder 实例，您现在可以访问一些看似与 Phar 类相同的方法

addEmptyDir()
addFile()
addFromString()
buildFromDirectory()
buildFromIterator()
setStub()

事实上，它们与它们的 Phar 对应物有完全相同的结果。不同之处在于，每个方法都可以被观察，并且可以在实际执行操作（如添加空目录、从磁盘添加文件等）之前更改传递给每个方法的参数。最简单的例子是使用 addFromString() 方法执行搜索和替换。

观察一个动作

Builder 类基于 phine/observer 库，因此您可能需要阅读该库提供的文档。要观察一个动作（即“主题”），您需要创建自己的 Phine\Observer\ObserverInterface 实现。

use Phine\Observer\SubjectInterface;
use Phine\Observer\ObserverInterface;

/**
 * Replaces occurrences of "{name}" with "world".
 */
class Replace implements ObserverInterface
{
    /**
     * {@inheritDoc}
     */
    public function receiveUpdate(SubjectInterface $subject)
    {
        // get the arguments for the addFromString() method
        $arguments = $subject->getArguments();

        // replace "{name}" with "world"
        $arguments['contents'] = str_replace(
            '{name}',
            'world',
            $arguments['contents']
        );
    }
}

现在我们有了观察者，我们需要将其实例注册到构建器事件中。特别是，我们感兴趣的是 Builder::ADD_STRING 事件，这是构建器用于 addFromString() 方法的。

// register our observer
$builder->observe(Builder::ADD_STRING, new Replace());

将观察者注册到 addFromString() 方法后，每次调用它时，所有 {name} 的出现都将替换为字符串 world。所以，如果我们添加以下内容

$builder->addFromString(
    'hello.php',
    <<<CODE
<?php

echo "Hello, {name}!\n";
CODE
);

消息 Hello, {name}! 将被替换为 Hello, world!。

可用事件

每个存档相关方法都有一个事件

Builder::ADD_DIR - 用于 addEmptyDir()。
Builder::ADD_FILE - 用于 addFile()。
Builder::ADD_STRING - 用于 addFromString()。
Builder::BUILD_DIR - 用于 buildFromDirectory()。
Builder::BUILD_ITERATOR - 用于 buildFromIterator()。
Builder::SET_STUB - 用于 setStub()。

如上面的示例观察者所示，您可以通过在提供的 $subject 上调用 getArguments() 方法来检索每个这些方法的参数。参数的名称与方法的参数名称相同。您可以通过查看API文档来找到完整的列表。

生成占位符

该库提供了一种简单的方法来为您存档生成存根。使用存根生成器，您可以集成由 Phar 类提供的功能，要求文件，甚至可以嵌入一些代码，如果未安装 phar 扩展，则可以自动解压存档。

use Phine\Phar\Stub;

$banner = <<<BANNER
This stub has been licensed under blah blah blah.

Copyright (c) 2199 Hulk Smash
BANNER
;

$builder->setStub(
    Stub::create()
        ->setBanner($banner)
        ->mapPhar('alias.phar')
        ->addRequire('src/hello.php')
        ->selfExtracting()
        ->getStub()
);

上面的示例设置了一个横幅注释，将流别名设置为 alias.phar，并允许存档在未安装 phar 扩展的机器上自动解压和运行。

#!/usr/bin/env php
<?php

/*
 * This stub has been licensed under blah blah blah.
 *
 * Copyright (c) 2199 Hulk Smash
 */

if (class_exists('Phar')) {
$include = 'phar://' . __FILE__;
Phar::mapPhar('alias.phar');
} else {
$include = Extract::from(__FILE__)->to();
set_include_path($include . PATH_SEPARATOR . get_include_path());
}

require $include . '/src/hello.php';

final class Extract
{
    // ...snip...
}

__HALT_COMPILER();

您需要阅读API文档以了解存根生成器提供的所有功能。

解压存档

如果未安装 phar 扩展并且您需要解压存档的内容，那么 Extract 类将是您的良伴。它将使用存档解析器读取清单并将内容提取到您选择的目录。

use Phine\Phar\Archive;
use Phine\Phar\Extract;

$archive = Archive::create('/path/to/archive.phar');

$extract = new Extract($archive);
$extract->extractTo('/path/to/output/dir');

作为可选操作，您可以为 extractTo() 方法的第二个参数提供一个可调用的函数。该可调用的函数将接收一个 Phine\Phar\Manifest\Entry 实例，并用于确定存档中的文件是否应该被提取。

use Phine\Phar\Manifest\Entry;

$extract->extractTo(
    '/path/to/output/dir',
    function (Entry $entry) {
        if ('.php' !== substr($entry->getName(), -3, 3)) {
            return true; // skip this file
        }
    }
);

在上面的示例中，该可调用的函数将检查每个文件是否以 .php 结尾。如果文件不以 .php 结尾，它将通过返回 true 被跳过。任何其他返回值都将被 Extract 类忽略。

验证签名

如果需要在未安装 phar 扩展的机器上验证存档的签名，您将想要使用 Signature 类。如果您需要验证使用私钥签名的存档，您仍然需要 openssl 扩展。

use Phine\Phar\Signature;

if (Signature::create('/path/to/archive.phar')->verifySignature()) {
    // the signature was successfully verified
} else {
    // the verification failed!
}

文档

您可以在此处找到API文档。您还可能在此维基上找到教程、技巧等更多信息。

许可证

此库可在MIT许可证下获得。

phine / phar

维护者

详情