Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

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: 23)

Table of Contents

1. 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.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • 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

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
proposal proposal Delete
proposals proposals Delete
path path Delete
filesystem filesystem Delete
files files Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Apr 10, 2008

    <p>I like this proposal, it makes some stuff quite easier. On most systems you have to struggle with the tmp_filename functions. A common ways is always good there. I'd like to see this component moving to the core.</p>

  2. Apr 10, 2008

    <p>I'd really like to see this in core. Maybe some functions can be added to search files in a path and function to help construct include paths:</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    public static function setIncludePath($dir, ...) { }
    public static function addIncludePath($dir, ...) { }
    ]]></ac:plain-text-body></ac:macro>
    <p>Maybe a good thing to note somewhere: What is an extention? Is it the part after the last or the first period?</p>

    1. Apr 13, 2008

      <p>Hi Vincent,</p>

      <p>good question about the definition of the "extension". In my opinion it should be the part after the last <strong>period</strong>. That's the way windows handles this (e.g. the extension of "my.word.document.docx" is "docx").</p>

      <p>I added you proposed methods regarding the include paths to the proposal. Thanks a lot.</p>

  3. Apr 14, 2008

    <p>Hi Stefan!<br />
    I'd also like to see this in core.</p>

    <p>And as Vincent noted, some methods would be nice to add. Like the Search methods if path is an directory.</p>

    <p>A method which can be used to check if a given path is within a defined 'root path'.</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    $path = '/home/user/gallery/foo/bar/picture123.jpg';
    public static function isWithinPath($path, '/home/user/gallery') {}
    ]]></ac:plain-text-body></ac:macro>
    <p>I would also allow to instantiate a new instance of Zend_Path like Zend_Uri.<br />
    So you can:</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    $path = Zend_Path:factory('/home/user/foo.jpg');
    $path->getExtension();
    $path->getDirectoryName();
    $path->isWithinPath('/home/user');

    // More methods:
    $path->addRegex('/([a-zA-Z0-9-\\])\/([a-zA-Z0-9])\.jpg/');
    // or perhaps with existing Zend_Validators...
    $path->addValidator(new Zend_Validator_Regex());
    ]]></ac:plain-text-body></ac:macro>

    1. Apr 15, 2008

      <p>Hi Thomas,</p>

      <p>Thanks a lot for your comment. </p>

      <p>I added you ideas to the proposal:</p>
      <ul class="alternate">
      <li>Zend_Path::isWithinPath() to check if a given path is located within a defined root path.</li>
      <li>Zend_Path:factory() and the accompanying Zend_Path_Item class that represents a single filesystem item. The Zend_Path_Item simple proxies all calls to the static Zend_Path-methods.</li>
      </ul>

      <p>Regarding your proposal about addRegex() or allowing the addition of validators to a path-object, I actually have to admint that I don't know what you want this to do. Do you want a path validation function? If so, I'd think that a method name <strong>validate()</strong> would be more catchy.</p>

      <p>Best regards</p>

      <p>Stefan</p>

  4. Apr 27, 2008

    <p>Checked in at SVN url <a class="external-link" href="http://svn2.assembla.com/svn/zf-proposals/Zend_Path/trunk">http://svn2.assembla.com/svn/zf-proposals/Zend_Path/trunk</a>.</p>

  5. Jul 05, 2008

    <p>Changend SVN url to <a class="external-link" href="http://svn2.assembla.com/svn/zf-proposals/trunk">http://svn2.assembla.com/svn/zf-proposals/trunk</a></p>

  6. Aug 29, 2008

    <p>I was looking for exactly this, so I've checked-out your SVN.</p>

    <p>This looks very very promising <ac:emoticon ac:name="laugh" /><br />
    I hope it gets in the core fast! I will start using it from now</p>

    <p>But I think there's a small bug in:</p>
    <ul class="alternate">
    <li>Path.php 23 2008-07-05 08:57:19Z sgehrig</li>
    </ul>

    <p>Because the idea of this class is to unify all paths to the forwards slashes, right?<br />
    While the following will replace all '/' for the OS specific directory separator:</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    private static function _normalizeDirectorySeparators($path)

    Unknown macro: { return str_replace(self}

    ]]></ac:plain-text-body></ac:macro>

    <p>So I think this should be like:</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    private static function _normalizeDirectorySeparators($path)

    Unknown macro: { return str_replace(self}

    ]]></ac:plain-text-body></ac:macro>

    <p>Thanks</p>

    1. Aug 29, 2008

      <p>Hi Patrick,</p>

      <p>I hope the code keeps what it promises <ac:emoticon ac:name="wink" /></p>

      <p>Regarding your "bug":<br />
      Actually it was my idea to normalize directory separators to its system specfic default, which means a forward slash on all non-Windows-OSs and the backslash on Windows-OSs. Personally I'd have no problem to normalize everything to forward slashes but I have no experience if this'd induce some side-effects or even problems on Windows-OSs.<br />
      Are there any problems when normalizing to the system-specific directory separator?</p>

      <p>Best regards</p>

      <p>Stefan</p>

      1. Aug 29, 2008

        <p>> Actually it was my idea to normalize directory separators to its system specfic default<br />
        Sounds good, but then the current _normalizeDirectorySeparators function does not meet the goal. Because now you only replace the '/' with the OS-specific separator, but to completely meet the goal you should replace the '\' and '/' to a OS-specific separator.</p>

        <p>I always set all my paths in config-files based on the *nix directory separator ('/'), but when running on Windows there often the '/' and '\' are combined in one path because I use something like </p>
        <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[dirname(__FILE__) . $config->path]]></ac:plain-text-body></ac:macro>

        <p>To get this working I think the _normalizeDirectorySeparators function should be something like this:</p>
        <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
        $path = str_replace('
        ', self::getDirectorySeparator(), $path);
        $path = str_replace('/', self::getDirectorySeparator(), $path);
        return $path;
        ]]></ac:plain-text-body></ac:macro>

        <p>I'll try and do some more tests this weekend <ac:emoticon ac:name="smile" /></p>

        1. Aug 29, 2008

          <p>Hi Patrick,</p>

          <p>you're right... I changed the method to your proposed code.<br />
          Are you using the component on a Windows system? I'm asking because I haven't tested Zend_Path on *nix-based systems yet.</p>

          <p>Best regards</p>

          <p>Stefan</p>

          1. Aug 30, 2008

            <p>You don't actually need a getDirectorySeparator() method. You can just replace it with DIRECTORY_SEPARATOR PHP constant. There is no need to make a function call out of it.</p>

            1. Aug 30, 2008

              <p>Hi Goran,</p>

              <p>you're actually right. getDirectorySeparator() just proxies to DIRECTORY_SEPARATOR - it's just another way of accessing the PHP constant - there is no need to use that one if you're happy with the PHP constant. It's in there just to provide a complete API.</p>

  7. Oct 20, 2008

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Rejection</ac:parameter><ac:rich-text-body>
    <p>The Zend team is rejecting this proposal at this time.</p>

    <p>In almost every case, the methods proposed are wrappers for existing PHP function calls and/or constants, and are more verbose. In a few cases, they wrap multiple function calls, bringing added value, but we do not feel these cases justify the creation of the class.</p>

    <p>There are several methods, however, that we would like to add to Zend_Loader:</p>
    <ul>
    <li>getTempFileName()/getTempFileDirectory()</li>
    <li>set/prepend/appendPrefixPath()<br />
    These go along with the duties already present in Zend_Loader and would simplify and/or augmet the current functionality. We invite the proposal author to submit feature requests to the tracker for adding these methods.</li>
    </ul>
    </ac:rich-text-body></ac:macro>