Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PECL phar >= 2.0.0)

Phar::buildFromIterator — Construir un archivo phar desde un iterador

Descripción

public Phar::buildFromIterator ( Iterator $iter [, string $base_directory ] ) : array

Nota:

Este método requiere que la opción de php.ini phar.readonly esté establecida a 0 para que trabaje con objetos Phar. De otra manera, se lanzará una excepción de tipo PharException.

Rellena un archivo phar desde un iterador. Están soportados dos estilos de iteradores, los iteradores que mapean el nombre de fichero dentro del phar al nombre del fichero en disco, y los iteradores como DirectoryIterator que devuelven objetos de la clase SplFileInfo. Se requiere el segundo parámetro para los iteradores que devuelven objetos de la clase SplFileInfo.

Parámetros

iter

Cualquier iterador que mapee de forma asociativa el fichero phar a la ubiciación o que devuelva objetos de la clase SplFileInfo

base_directory

Para los iteradores que devuelven objetos de la clase SplFileInfo, es la porción de cada ruta completa de fichero a eliminar cuando de añada al archivo phar

Valores devueltos

Phar::buildFromIterator() devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.

Ejemplos

Ejemplo #1 Un ejemplo de Phar::buildFromIterator() con SplFileInfo

Para la mayoría de los archivos tar/zip, el archivo reflejará la distribución real de directorios, y el segundo estilo es el más útil. Por ejemplo, para crear un archivo phar que contenga los ficheros n esta distribución de muestra de directorios: 

/ruta/al/proyecto/
                  config/
                         dist.xml
                         debug.xml
                  lib/
                      fichero1.php
                      fichero2.php
                  src/
                      procesa_algo.php
                  www/
                      index.php
                  cli/
                      index.php

Este código podría usarse para añadir estos ficheros al archivo phar "proyecto.phar":

<?php
// crear con el alias "proyecto.phar"
$phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/ruta/al/proyecto')),
    '/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

El fichero proyecto.phar se puede usar inmediatamente. Phar::buildFromIterator() no establece valores como la compresión y metainformación, que se puede hacer después de crear el archivo phar.

Como observación interesante, Phar::buildFromIterator() también se puede usar para copiar el contenido de un archivo phar existente, ya que los objetos de la clase Phar descienden de la clase DirectoryIterator:

<?php
// crear con el alias "proyecto.phar"
$phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/ruta/a/otro_phar.phar')),
    'phar:///ruta/a/otro_phar.phar/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

Ejemplo #2 Un ejemplo de Phar::buildFromIterator() con otros iteradores

La segunda forma de iterador se puede usar con cualquier iterador que devuelva un mapeo clave => valor, tal como un objeto de la clase ArrayIterator:

<?php
// crear con el alias "proyecto.phar"
$phar = new Phar('proyecto.phar', 0, 'proyecto.phar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'fichero/interno.php' => dirname(__FILE__) . '/algun_fichero.php',
        'otro/fichero.jpg' => fopen('/rota/a/archivo_grande.jpg', 'rb'),
     )));
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

Errores/Excepciones

Este método lanza una excepción de tipo UnexpectedValueException cuando el iterador devuelve valores incorrectos, tales como una clave de tipo integer en lugar de una cadena, una excepción de tipo BadMethodCallException cuando se pasa un iterador basado en SplFileInfo sin un parámetro base_directory, o una excepción de tipo PharException si hubo errores al guardar el archivo phar.

Ver también