<?php
/**
 * File contains the ezcArchiveEntry class.
 *
 * @package Archive
 * @version 1.4.1
 * @copyright Copyright (C) 2005-2010 eZ Systems AS. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 */

/**
 * The ezcArchiveEntry class provides system-independent file information.
 *
 * ezcArchiveEntry provides file information about the file path, it's access rights and whether the file is an
 * directory, symbolic link, hard link, block-file, etc. The owner name, the group name, the last access time
 * are also available. ezcArchiveEntry can be used to get the file information directly from the file-system or
 * from an archive.
 *
 * The main purpose of ezcArchiveEntry is to provide information about:
 * - Files on the file-system that should be appended to the archive.
 * - Files currently in the archive that can be extracted to the file-system.
 *
 * Use the {@link getEntryFromFile()} to create an ezcArchiveEntry from a file in the filesystem.
 * Important is that the prefix is set.
 * This specifies which part of the path should be stripped, before the entry is appended to the archive.
 * See also {@link ezcArchive::append()} or {@link ezcArchive::appendToCurrent()}.
 *
 * When the ezcArchiveEntry is an entry in the archive, the {@link getPath()} method contains always an
 * relative path, and the prefix is not set.
 *
 * @package Archive
 * @version 1.4.1
 */
class ezcArchiveEntry
{
    /**
     * Is a regular file.
     */
    const IS_FILE = 0;

    /**
     * Is a hard link.
     */
    const IS_LINK = 1;

    /**
     * Is a symbolic link.
     */
    const IS_SYMBOLIC_LINK = 2;

    /**
     * Is a character device.
     */
    const IS_CHARACTER_DEVICE = 3;

    /**
     * Is a block device.
     */
    const IS_BLOCK_DEVICE = 4;

    /**
     * Is a directory.
     */
    const IS_DIRECTORY = 5;

    /**
     * Is a FIFO.
     */
    const IS_FIFO = 6;

    /**
     * Not used, is Tar specific?
     */
    const IS_RESERVED = 7;

    /**
     * Contains the file information.
     *
     * @var ezcArchiveFileStructure
     */
    protected $fileStructure;

    /**
     * The prefix of the file that may be removed from the path.
     *
     * @var string
     */
    protected $prefix;

    /**
     * Constructs an archiveEntry from the {@link ezcArchiveFileStructure}.
     *
     * The $struct parameter contains the raw file information.
     * This class encapsulates the file information structure and provides convenient methods to retrieve
     * the information.
     *
     * @param ezcArchiveFileStructure $struct
     */
    public function __construct( ezcArchiveFileStructure $struct )
    {
        $this->fileStructure =  $struct;
    }

    /**
     * Returns true when this entry represents a directory.
     *
     * @return bool
     */
    public function isDirectory()
    {
        return ( $this->fileStructure->type == self::IS_DIRECTORY );
    }

    /**
     * Returns true when this entry represents a file.
     *
     * @return bool
     */
    public function isFile()
    {
        return ( $this->fileStructure->type == self::IS_FILE );
    }

    /**
     * Returns true when this entry represents a hard link.
     *
     * @return bool
     */
    public function isHardLink()
    {
        return ( $this->fileStructure->type == self::IS_LINK );
    }

    /**
     * Returns true when this entry represents a symbolic link.
     *
     * @return bool
     */
    public function isSymLink()
    {
        return ( $this->fileStructure->type == self::IS_SYMBOLIC_LINK );
    }

    /**
     * Returns true when this entry represents a symbolic or a hard link.
     *
     * @return bool
     */
    public function isLink()
    {
        return ( $this->isHardLink() || $this->isSymLink() );
    }

    /**
     * Returns type of the entry.
     *
     * @return int   Possible values are: {@link IS_LINK}, {@link IS_SYMBOLIC_LINK}, {@link IS_CHARACTER_DEVICE}, {@link IS_BLOCK_DEVICE},
     * {@link IS_DIRECTORY}, or {@link IS_FIFO}.
     */
    public function getType()
    {
        return $this->fileStructure->type;
    }

    /**
     * Returns the user ID of the entry.
     *
     * @return int
     */
    public function getUserId()
    {
        return $this->fileStructure->uid;
    }

    /**
     * Returns the group ID of the entry.
     *
     * @return int
     */
    public function getGroupId()
    {
        return $this->fileStructure->gid;
    }

    /**
     * Returns the complete path or path without the prefix.
     *
     * By default the full path is returned, unless the $withPrefix is set
     * to true.
     *
     * @param bool $withPrefix
     *
     * @return string
     */
    public function getPath( $withPrefix = true )
    {
        if ( $withPrefix )
        {
            return $this->fileStructure->path;
        }
        else
        {
            return $this->getPathWithoutPrefix( $this->fileStructure->path, $this->prefix );
        }
    }

    /**
     * Returns the path without the prefix.
     *
     * The path without the prefix is returned.
     * If the prefix doesn't match with the complete path, the whole path is returned.
     *
     * @param string $completePath
     * @param string $prefix
     * @return string
     */
    private function getPathWithoutPrefix( $completePath, $prefix )
    {
        $prefixLength = strlen( $prefix );

        if ( strcmp( substr( $completePath, 0,  $prefixLength ), $prefix ) == 0 )
        {
            $i = 0;
            // Check next character
            while ( $completePath[$i + $prefixLength] == "/" )
            {
                $i++;
            }

            $result = substr( $completePath, $prefixLength + $i );
            return $result;
        }
        else
        {
            // No match.
            return $completePath;
        }
    }

    /**
     * Removes the prefix from the path and clears the prefix.
     *
     * This method is useful when it comes to adding a entry to an archive
     * and the complete path to the file is no longer needed.
     */
    public function removePrefixFromPath()
    {
        $this->fileStructure->path = $this->getPathWithoutPrefix( $this->fileStructure->path, $this->prefix );
        $this->prefix = "";
    }


    /**
     * Returns the link with or without prefix.
     *
     * This method is similar to {@link getPath()}, but returns the link instead of the path.
     * If the current does not represents a link, an empty string is returned.
     * Use the {@link isLink()} method to see if the current entry is a link.
     *
     * @param bool $withPrefix
     */
    public function getLink( $withPrefix = true )
    {
        if ( $withPrefix )
        {
            return $this->fileStructure->link;
        }
        else
        {
            return $this->getPathWithoutPrefix( $this->fileStructure->link, $this->prefix );
        }
    }

    /**
     * Returns a bit mask representing the permissions of this entry.
     *
     * It returns the permissions in octal numbers as a string, for example:
     * "0000755"
     *
     * @return string
     */
    public function getPermissions()
    {
        return $this->fileStructure->mode;
    }

    /**
     * Returns the file size.
     *
     * @return int
     */
    public function getSize()
    {
        return $this->fileStructure->size;
    }

    /**
     * Returns the modification time as a timestamp.
     *
     * @return int
     */
    public function getModificationTime()
    {
        return $this->fileStructure->mtime;
    }

    /**
     * Returns the last access time as a timestamp.
     *
     * @return int
     */
    public function getAccessTime()
    {
        return $this->fileStructure->atime;
    }

    /**
     * Returns the inode.
     *
     * @return int
     */
    public function getInode()
    {
        return $this->fileStructure->ino;
    }

    /**
     * Returns the major device number.
     *
     * @return int
     */
    public function getMajor()
    {
        return $this->fileStructure->major;
    }

    /**
     * Returns the minor device number.
     *
     * @return int
     */
    public function getMinor()
    {
        return $this->fileStructure->minor;
    }

    /**
     * Returns the device.
     *
     * FIXME DEPRECATED?
     *
     * @return int
     */
    public function getDevice()
    {
        return $this->fileStructure->device;
    }

    /**
     * Returns the permissions as a string.
     *
     * If the entry has all the permissions, it will return: "rwxrwx" Where the first three letters
     * represent the group permissions and the last three letters the user permissions.
     *
     * @return string
     */
    public function getPermissionsString()
    {
        $out = "";

        $perm = octdec( $this->getPermissions() );

        for ( $i = 6; $i >= 0; $i -= 3 )
        {
            $part = ( $perm >> $i );

            if ( $part & 4 )
            {
                $out .= "r";
            }
            else
            {
                $out .= "-";
            }

            if ( $part & 2 )
            {
                $out .= "w";
            }
            else
            {
                $out .= "-";
            }

            if ( $part & 1 )
            {
                $out .= "x";
            }
            else
            {
                $out .= "-";
            }
        }
        return $out;
    }

    /**
     * Returns the type string for the current type of the entry.
     *
     * Returns a type string for the current entry. If the entry is a:
     * - directory: "d".
     * - file: "-".
     * - symbolic link: "l".
     * - hard link: "h".
     *
     * @return string
     */
    public function getTypeString()
    {
        switch ( $this->fileStructure->type )
        {
            case self::IS_DIRECTORY:
                return "d";

            case self::IS_FILE:
                return "-";

            case self::IS_SYMBOLIC_LINK:
                return "l";

            case self::IS_LINK:
                return "h";

            default:
                return "Z";
        }
    }

    /**
     * Sets the prefix.
     *
     * @param string $prefix
     */
    public function setPrefix( $prefix )
    {
        $this->prefix = $prefix;
    }

    /**
     * Returns the prefix.
     *
     * @return string
     */
    public function getPrefix( )
    {
        return $this->prefix;
    }

    /**
     * Returns a string representing the current entry.
     *
     * @return string
     */
    public function __toString()
    {
        $out = $this->getTypeString();
        $out .= $this->getPermissionsString();

        $out .= " ";
        $out .= $this->getUserId() . " ";
        $out .= $this->getGroupId() . " ";
        $out .= str_pad( $this->getSize(), 7, " ", STR_PAD_LEFT ) . " ";
        $out .= date( "Y-m-d H:i:s ", $this->getModificationTime() );
        $out .= $this->getPath();

        $out .= ( $this->isLink() ? " -> " . $this->getLink() : "" );

        return $out;
    }

    /**
     * Create a file structure from a $file in the file system.
     *
     * @param string $file
     * @return ezcArchiveFileStructure
     */
    protected static function getFileStructureFromFile( $file )
    {
        clearstatcache();
        $stat = ( is_link( $file ) ? lstat( $file ) : stat( $file ) );
        $lstat = lstat( $file );

        // Set the file information.
        $struct = new ezcArchiveFileStructure();

        $struct->path = $file;
        $struct->gid =  $stat["gid"];
        $struct->uid =  $stat["uid"];
        $struct->mtime = $stat["mtime"];
        $struct->atime = $stat["atime"];
        $struct->mode = decoct( $stat["mode"] & ezcArchiveStatMode::S_PERM_MASK ); // First bits describe the type.
        $struct->ino = $stat["ino"];

        $struct->type = self::getLinkType( $stat );

        if ( $struct->type == ezcArchiveEntry::IS_FILE )
        {
            $struct->size = $stat["size"];
        }
        else
        {
            $struct->size = 0;
        }

        if ( $struct->type == ezcArchiveEntry::IS_SYMBOLIC_LINK )
        {
            $struct->link = readlink( $file );
        }

        $rdev = $stat["rdev"];
        if ( $rdev == -1 )
        {
            if ( $struct->type == ezcArchiveEntry::IS_BLOCK_DEVICE || $struct->type == ezcArchiveEntry::IS_CHARACTER_DEVICE)
            {
                throw new ezcArchiveException( "Cannot add a device to the TAR because the device type cannot be determined. Your system / PHP version does not support 'st_blksize'." );
            }

            $rdev = 0;
        }

        $struct->major = ( int ) ( $rdev / 256 );
        $struct->minor = ( int ) ( $rdev % 256 );

        return $struct;
    }

    /**
     * Returns one or an array of ezcArchiveEntry's from one or multiple files in the file system.
     *
     * One or multiple ezcArchiveEntry's are created upon the given files.
     * The prefix will directly set for the ezcArchiveEntry with $prefix.
     *
     * If $files contains a path to a file, then one ezcArchiveEntry will be created and returned.
     * If $files is an array of paths, then all those ezcArchiveEntry's will be created and returned in an array.
     *
     * When multiple files are given in an array, this method will search for hard links among other files in the array.
     *
     * @throws ezcArchiveEntryPrefixException if the prefix is invalid.
     *
     * @param string|array(string)  $files
     * @param string                $prefix
     * @return ezcArchiveEntry
     */
    public static function getEntryFromFile( $files, $prefix )
    {
        $isArray = true;
        if ( !is_array( $files ) )
        {
            $isArray = false;
            $files = array( $files );
        }

        $inodes = array();
        $i = 0;
        foreach ( $files as $file )
        {
            if ( !file_exists( $file ) && !is_link( $file ) )
                return false;

            $struct = self::getFileStructureFromFile( $file );

            // Check if it's a hardlink if the OS supports it, and handle it.
            if ( ezcBaseFeatures::supportsLink() )
            {
                if ( isset( $inodes[ $struct->ino ] ) )
                {
                    // Yes, it's a hardlink.
                    $struct->type = ezcArchiveEntry::IS_LINK;
                    $struct->size = 0;
                    $struct->link = $inodes[ $struct->ino ];
                }
                else
                {
                    $inodes[ $struct->ino ] = $struct->path;
                }
            }

            $entry[$i] = new ezcArchiveEntry( $struct );
            $entry[$i]->setPrefix( $prefix );

            if ( isset( $prefix ) && strlen( $prefix ) > 0 )
            {
                if ( strlen( $entry[$i]->getPath() ) == strlen( $entry[$i]->getPath( false ) ) )
                {
                    throw new ezcArchiveEntryPrefixException( $prefix, $file );
                }
            }

            $i++;
        }

        return ( $isArray ? $entry : $entry[0] );
    }

    /**
     * Returns an ezcArchiveEntry-type that corresponds to the ezcArchiveStatMode-type
     *
     * @param ezcArchiveStatMode $stat Possible values are: {@link ezcArchiveStatMode::S_IFIFO}, {@link ezcArchiveStatMode::S_IFCHR},
     *                                 {@link ezcArchiveStatMode::S_IFDIR}, {@link ezcArchiveStatMode::S_IFBLK},
     *                                 {@link ezcArchiveStatMode::S_IFREG}, or {@link ezcArchiveStatMode::S_IFLNK}.
     *
     * @return int                    Possible values are: {@link IS_LINK}, {@link IS_SYMBOLIC_LINK}, {@link IS_CHARACTER_DEVICE},
     *                                 {@link IS_BLOCK_DEVICE}, {@link IS_DIRECTORY}, or {@link IS_FIFO}.
     */
    protected static function getLinkType( $stat )
    {
        switch ( $stat["mode"] & ezcArchiveStatMode::S_IFMT )
        {
            case ezcArchiveStatMode::S_IFIFO:
                return ezcArchiveEntry::IS_FIFO;

            case ezcArchiveStatMode::S_IFCHR:
                return ezcArchiveEntry::IS_CHARACTER_DEVICE;

            case ezcArchiveStatMode::S_IFDIR:
                return ezcArchiveEntry::IS_DIRECTORY;

            case ezcArchiveStatMode::S_IFBLK:
                return ezcArchiveEntry::IS_BLOCK_DEVICE;

            case ezcArchiveStatMode::S_IFREG:
                return ezcArchiveEntry::IS_FILE;

            case ezcArchiveStatMode::S_IFLNK:
                return ezcArchiveEntry::IS_SYMBOLIC_LINK;

            // Hardlinks are not resolved here. FIXME?
        }

        return false;
    }
}
?>