Zend Framework: Zend_Path Component Proposal

Proposed Component Name	Zend_Path
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Path
Proposers	Stefan Gehrig Matthew Weier O'Phinney (Zend Liaison)
Revision	0.1 - 29 March 2008: opened proposal. 0.1.1 - 3 April 2008: Changed layout to use decks. 0.2 - 13 April 2008: Added methods to handle include path. 0.3 - 15 April 2008: Added object oriented approach propsed by Thomas Fritz 0.4 - 5 July 2008: Changed repository location (wiki revision: 22)

This component will provide system-independent path constants such as directory Separator, path separator and volume separator.
This component will provide an easy method to change a file extension.
This component will provide an easy method to combine two or more paths or a path and a file.
This component will be able to extract the directory name from a path.
This component will be able to extract the file extension from a path. The "extension" in the context of this proposal is defined as the part after the last period of the filename.
This component will be able to extract the file name from a path.
This component will be able to extract the file name without extension from a path.
This component will be able to retrieve the root path for a given path.
This component will be able to determine the system's temp path.
This component will be able to normalize a path (resolving '..' - like realpath() does) even on paths that do not currently exist on the filesystem.
This component will provide convenience methods to work with the PHP include path.

4. Dependencies on Other Framework Components

none

5. Theory of Operation

The component simply provides static methods which can be called whenever appropriate.

6. Milestones / Tasks

Milestone 1: [DONE] Write initial proposal
Milestone 2: [CURRENT] Review by community
Milestone 3: [DONE] Checked in at http://svn2.assembla.com/svn/zf-proposals/trunk
Milestone 4: Review by Zend
Milestone 5: Component incubated
Milestone 6: [DONE] Write unit tests
Milestone 7: Write documentation
Milestone 8: Component cored

7. Class Index

Zend_Path
Zend_Path_Item

8. Use Cases

9. Class Skeletons

/**
 * Zend_Path provides methods to work with filesystem paths.
 *
 * @category   Zend
 * @package    Zend_Path
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
final class Zend_Path
{
    /**
     * Singleton pattern implementation makes "new" unavailable.
     *
     */
    private function __construct()
    {}

    /**
     * Singleton pattern implementation makes "clone" unavailable.
     *
     */
    private function __clone()
    {}

    /**
     * Creates a Zend_Path_Item for the given path to provide an 
     * object oriented interface to Zend_Path-methods.
     *
     * @param  string $path
     * @return Zend_Path_Item
     * @throws InvalidArgumentException
     */
    public static function factory($path)
    {
        /** 
         * Zend_Path_Item
         */
        require_once 'Zend/Path/Item.php';
        return new Zend_Path_Item($path);
    }

    /**
     * Return the directory separator for the current system.
     * 
     * Returns '/' on Unix-based machines and '\' on Windows-based machines.
     *
     * @return string
     */
    public static function getDirectorySeparator() { }
    
    /**
     * Return the alternative directory separator for the current system.
     * 
     * Returns '/' for every system as Windows can work with '/'-paths.
     *
     * @return string
     */
    public static function getAltDirectorySeparator() { }
    
    /**
     * Return the path separator for the current system.
     * 
     * Returns ':' on Unix-based machines and ';' on Windows-based machines.
     *
     * @return string
     */
    public static function getPathSeparator() { }

    /**
     * Return the volume separator for the current system.
     *
     * As volume separators are a Windows-specific issue, this method
     * returns '/' on all Unix-based machines and ':' on Windows.
     * 
     * @return string
     */
    public static function getVolumeSeparator() { }

    /**
     * Change the extension of a file in a given path.
     *
     * If the given path does not haven an extension, the extension
     * provided gets appended to the path.
     * 
     * @param  string $path
     * @param  string $extension
     * @return string
     */
    public static function changeExtension($path, $extension) { }

    /**
     * Combines two paths to a single path.
     *
     * If $path2 is rooted, $path2 is returned.
     * If either $path1 or $path2 is null or empty, the other path is returned
     * respectively.
     * 
     * @param  string $path1
     * @param  string $path2
     * @return string
     */
    public static function combine($path1, $path2) { }

    /**
     * Returns the directory name of a given path.
     * 
     * The directory name in this context is everything until the
     * last '/' or '\' in the given path string.
     *
     * @param  string $path
     * @return string
     */
    public static function getDirectoryName($path) { }

    /**
     * Returns the extension of a file in a given path.
     *
     * The extension in this context is defined as the part of the string
     * after the *last* period. The extension is returned without the '.'.
     * 
     * @param  string $path
     * @return string
     */
    public static function getExtension($path) { }

    /**
     * Returns the filename of a given path.
     * 
     * The returned string is not necessarily a real file. It
     * can also be a directory. This method just returns the part
     * of the string after the last  '/' or '\' in the given path string.
     * The returned filename includes the file extension if one is present.
     *
     * @param  string $path
     * @return string
     */
    public static function getFilename($path) { }

    /**
     * Returns the filename without its extension of a given path.
     *
     * The returned string is not necessarily a real file. It
     * can also be a directory. This method just returns the part
     * of the string after the last  '/' or '\' and before the last '.'
     * in the given path string.
     * 
     * @param  string $path
     * @return string
     */
    public static function getFilenameWithoutExtension($path) { }

    /**
     * Returns the full path for a given relative path.
     *
     * If $path is already rooted $path1 will be returned unchanged.
     * 
     * @param  string $path
     * @return string
     */
    public static function getFullPath($path) { }

    /**
     * Returns the root path of a given path.
     * 
     * If the given path is not rooted, an empty string will be returned.
     * On Unix-based machines this will always be '/'. On Windows machines
     * a 'full' root ('C:\' e.g.) will be returned if the given path includes
     * a drive letter, otherwise '\' will be returned
     *
     * @param  string $path
     * @return string
     */
    public static function getPathRoot($path) { }

    /**
     * Returns a random filename.
     *
     * This method is a mere wrapper around uniqid(rand(), true).
     * 
     * @return string
     */
    public static function getRandomFileName() { }

    /**
     * Returns the path to a random temporary file in the current
     * system's temp-path.
     *
     * @return string
     */
    public static function getTempFileName() { }

    /**
     * Returns the current system's temp-path.
     * 
     * This method tries to determine the temp-path using several
     * attemps according to a snippet by minghong at gmail dot com
     * @link http://de3.php.net/manual/en/function.sys-get-temp-dir.php#71332
     *
     * @return string
     */
    public static function getTempDirectory() { }

    /**
     * Returns true if the file in a given path has an extension. 
     *
     * @param  string $path
     * @return boolean
     */
    public static function hasExtension($path) { }

    /**
     * Checks if the given path is rooted.
     *
     * Returns true on Unix machines if the path starts with '/'.
     * Returns true on Windows machines if the path starts with
     * '/', '\' or with '[A-Z]:'.
     * 
     * @param  string $path
     * @return boolean
     */
    public static function isPathRooted($path) { }
    
    /**
     * Resolves '..' and '.' in a given rooted path.
     *
     * If the given path is not rooted the path is returned unchanged.
     * 
     * @param  string $path
     * @return string
     */
    public static function normalizePath($path) { }
    
    /**
     * Sets the PHP include path to the given path(s).
     * The method returns the old include path.
     * 
     * Several arguments can be specified and will be assembled
     * to the new include path in the order specified.
     * Arguments can be strings or arrays of strings whereas
     * arrays will be handled like multiple arguments.
     *
     * @param  string|array $path,...
     * @return string
     */
    public static function setIncludePath($path) { }
    
    /**
     * Prepends the given path(s) to the current PHP include path.
     * The method returns the old include path.
     * 
     * Several arguments can be specified and will be assembled
     * to the new include path in the order specified.
     * Arguments can be strings or arrays of strings whereas
     * arrays will be handled like multiple arguments.
     *
     * @param  string|array $path,...
     * @return string
     */
    public static function prependToIncludePath($path) { }
    
    /**
     * Appends the given path(s) to the current PHP include path.
     * The method returns the old include path.
     * 
     * Several arguments can be specified and will be assembled
     * to the new include path in the order specified.
     * Arguments can be strings or arrays of strings whereas
     * arrays will be handled like multiple arguments.
     *
     * @param  string|array $path,...
     * @return string
     */
    public static function appendToIncludePath($path) { }
}

/**
 * Zend_Path_Item provides an object oriented interface to path items.
 *
 * @category   Zend
 * @package    Zend_Path
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Path_Item
{
    /**
     * Creates a new Zend_Path_Item
     *
     * @param  string $path
     * @throws InvalidArgumentException
     */
    public function __construct($path)
    { }
    
    /**
     * Return the path.
     *
     * @return string
     */
    public function getPath()
    { }
    
    /**
     * Return a string representation of this path.
     *
     * @see    getPath()
     * @return string
     */
    public function __toString()
    { }
    
    /**
     * Change the extension of a file in a given path.
     *
     * @see    Zend_Path::changeExtension()
     * @param  string $newExtension
     * @return Zend_Path_Item
     */
    public function changeExtension($newExtension)
    { }

    /**
     * Combines two paths to a single path.
     *
     * @see    Zend_Path::combine()
     * @param  string|Zend_Path_Item $path2
     * @return Zend_Path_Item
     */
    public function combine($path2)
    { }

    /**
     * Returns the directory name of a given path.
     * 
     * @see    Zend_Path::getDirectoryName()
     * @return string
     */
    public function getDirectoryName()
    { }

    /**
     * Returns the extension of a file in a given path.
     *
     * @see    Zend_Path::getExtension()
     * @return string
     */
    public function getExtension()
    { }

    /**
     * Returns the filename of a given path.
     * 
     * @see    Zend_Path::getFilename()
     * @return string
     */
    public function getFilename()
    { }

    /**
     * Returns the filename without its extension of a given path.
     *
     * @see    Zend_Path::getFilenameWithoutExtension()
     * @return string
     */
    public function getFilenameWithoutExtension()
    { }

    /**
     * Returns the full path for a given relative path.
     *
     * @see    Zend_Path::getFullPath()
     * @return Zend_Path_Item
     */
    public function getFullPath()
    { }

    /**
     * Returns the root path of a given path.
     * 
     * @see    Zend_Path::getPathRoot()
     * @return Zend_Path_Item
     */
    public function getPathRoot()
    { }

    /**
     * Returns true if the file in a given path has an extension. 
     *
     * @see    Zend_Path::hasExtension()
     * @return boolean
     */
    public function hasExtension()
    { }

    /**
     * Checks if the given path is rooted.
     *
     * @see    Zend_Path::isPathRooted()
     * @return boolean
     */
    public function isPathRooted()
    { }
    
    /**
     * Resolves '..' and '.' in a given rooted path.
     *
     * @see    Zend_Path::normalizePath()
     * @return Zend_Path_Item
     */
    public function normalizePath()
    { }
    
    /**
     * Checks if path is within the given root path.
     *
     * @see    Zend_Path::isWithinPath()
     * @param  string $rootPath
     * @return boolean
     */
    public function isWithinPath($rootPath)
    { }
    
}

Page Operations

Browse Space

Zend_Path Proposal - Stefan Gehrig

Labels

Zend Framework: Zend_Path Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons