Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

# Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

### 説明

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用して、新しい Phar アーカイブに PHP 起動ローダスタブを追加します。あるいは、既存の Phar アーカイブのローダスタブを置き換えます。

Phar アーカイブのローダスタブは、 このようにアーカイブを直接インクルードした際に使用されます。

    <?php
    include 'myphar.phar';
    ?>

あるいは、単にこのように実行した際にも使用されます。

    php myphar.phar

`phar` ストリームラッパーを使用して次のようにファイルをインクルードした際には、 ローダにはアクセスしません。

    <?php
    include 'phar://myphar.phar/somefile.php';
    ?>

### パラメータ

`stub`

  文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。

`length`
  `stub` の長さ（バイト単位）。
  警告

  第一引数に resource を指定して `length` 引数を渡すことは、 PHP 8.3.0 以降では非推奨です。 かわりに `$phar->setStub(stream_get_contents($resource))` を使ってください。

### 戻り値

常に `true` を返します。

### エラー / 例外

php.ini で phar.readonly が有効になっている場合に UnexpectedValueException がスローされます。 変更をディスクに書き込む際に何らかの問題が発生した場合は PharException がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。
8.3.0 | resource と `length` を渡して Phar::setStub() をコールすることは、 推奨されなくなりました。 `$phar->setStub(stream_get_contents($resource));` に置き換えるべきです。

### 例

例1 Phar::setStub() の例

    <?php

    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['a.php'] = '<?php var_dump("Hello");';
        $p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://brandnewphar.phar/a.php';
        var_dump($p->getStub());

        $p['b.php'] = '<?php var_dump("World");';
        $p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://brandnewphar.phar/b.php';
        var_dump($p->getStub());
    } catch (Exception $e) {
        echo 'brandnewphar.phar での書き込み操作に失敗しました: ', $e;
    }
    ?>

上の例の出力は以下となります。

    string(5) "Hello"
    string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
    string(5) "World"
    string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"

### 参考

- Phar::getStub() - Phar アーカイブの PHP ローダーあるいは起動スタブを返す
- Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open