View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFDEV:Zend Proposal Zone Template}
{composition-setup}

{zone-data:component-name}
Zend_Path
{zone-data}

{zone-data:proposer-list}
[Stefan Gehrig|mailto:gehrig@ishd.de]
[Matthew Weier O'Phinney (Zend Liaison)|~matthew]
{zone-data}

{zone-data: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|#comment-43837]
0.4 - 5 July 2008: Changed repository location
{zone-data}

{zone-data:overview}
Zend_Path is a collection of helper methods to improve file and path handling regardless of the underlying operating system (Windows or Unix-based). It mimics the interface of the .NET System.IO.Path static class.
{zone-data}

{zone-data:references}
* [PHP Manual Filesystem Functions|http://de3.php.net/manual/en/ref.filesystem.php]
* [.NET Framework Class Library Path Class (System.IO.Path)|http://msdn2.microsoft.com/en-us/library/system.io.path.aspx]
* [Method to mimic sys_get_temp_dir()|http://de3.php.net/manual/en/function.sys-get-temp-dir.php#71332]
{zone-data}

{zone-data:requirements}
* 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.
{zone-data}

{zone-data:dependencies}
none
{zone-data}

{zone-data:operation}
The component simply provides static methods which can be called whenever appropriate.
{zone-data}

{zone-data:milestones}
* 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
{zone-data}

{zone-data:class-list}
* Zend_Path
* Zend_Path_Item
{zone-data}

{zone-data:use-cases}
{deck:id=Use Cases}
{card:label=UC-01}
Change the extension of a file
{code}
$path='/tmp/upload/file.jpg';
$newPath=Zend_Path::changeExtension($path, 'upload.jpg');
// $newPath will contain '/tmp/upload/file.upload.jpg'
{code}
{card}
{card:label=UC-02}
Combine two paths
{code}
$path1='/home/www/views';
$path2='main/index.php';
$newPath=Zend_Path::combine($path1, $path2); // it doesn't matter whether $path1 ends with '/' or not
// $newPath will contain '/home/www/views/main/index.php'
{code}
{card}
{card:label=UC-03}
Extract directory name
{code}
$path='/home/www/views/myfile.php';
$newPath=Zend_Path::getDirectoryName($path);
// $newPath will contain '/home/www/views'
{code}
{card}
{card:label=UC-04}
Extract file extension
{code}
$path='/tmp/uploads/file.jpg';
$ext=Zend_Path::getExtension($path);
// $ext will contain 'jpg'
{code}
{card}
{card:label=UC-05}
Extract file name
{code}
$path='/tmp/uploads/file.jpg';
$file=Zend_Path::getFilename($path);
// $file will contain 'file.jpg'
{code}
{card}
{card:label=UC-06}
Extract file name wihout extension
{code}
$path='/tmp/uploads/file.jpg';
$file=Zend_Path::getFilenameWithoutExtension($path);
// $file will contain 'file'
{code}
{card}
{card:label=UC-07}
Get full rooted path
{code}
// script running in /home/scripts
$path='uploads/file.jpg';
$newPath=Zend_Path::getFullPath($path);
// $newPath will contain '/home/scripts/uploads/file.jpg'
{code}
{card}
{card:label=UC-08}
Get path to a random temp file
{code}
$temp=Zend_Path::getTempFileName();
// $temp will contain e.g. '/tmp/cdsbhjdscfdkj'
{code}
{card}
{card:label=UC-09}
Does the given path have an extension?
{code}
$path='/tmp/uploads/file.jpg';
$hasExt=Zend_Path::hasExtension($path);
// $hasExt will contain true

$path='/tmp/uploads/file';
$hasExt=Zend_Path::hasExtension($path);
// $hasExt will contain false
{code}
{card}
{card:label=UC-10}
Is a given path rooted?
{code}
$path='/tmp/uploads/file.jpg';
$isRooted=Zend_Path::isPathRooted($path);
// $isRooted will contain true

$path='../uploads/file';
$isRooted=Zend_Path::isPathRooted($path);
// $isRooted will contain false
{code}
{card}
{card:label=UC-11}
Resolve '..' and '.' in a given path
{code}
$path='/path1/path2-1/path3-1/../../path2-2'
$newPath=Zend_Path::normalizePath($path);
// $newPath will contain '/path1/path2-2'
{code}
{card}
{deck}
{zone-data}

{zone-data:skeletons}
{deck:id=Class Skeletons}
{card:label=Zend_Path}
{code}
/**
* 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) { }
}
{code}
{card}
{card:label=Zend_Path_Item}
{code}
/**
* 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)
{ }

}
{code}
{card}
{deck}
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>