Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:121936
Message-ID: <8f4e3274-6489-4378-82db-fb4829770196@gmail.com>
Date: Wed, 6 Dec 2023 20:20:29 +0100
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Content-Language: en-US
To: PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Subject: Filesystem path APIs
From: dossche.niels@gmail.com (Niels Dossche)

Hi internals 

I'd like to start a pre-RFC discussion about filesystem path APIs in PHP.
The reason I bring this up is because of this recent feature request: https://github.com/php/php-src/issues/11258 

The feature request is about the following:
We already have some functions to work with paths in PHP, e.g. basename, dirname, realpath. 
We do not have some common path APIs that you can find in other languages like: path_join to join paths and path_normalize to normalize paths.

As not everyone may be familiar with such functions, I'll explain them briefly.

**Proposed Functions:**

1. path_join(string... $components): string;
This function concatenates the components with a / (or \ on Windows) between them and normalizes the path.
If the resulting path is empty then it'll return "." to indicate the current directory.
You may be wondering "Isn't this just implode?". Not really, it normalizes the path too, which means that components like "." are removed from the path, redundant slashes are removed, and if there are ".." components then they remove the previous component from the path.

It's also not the same thing as calling realpath after doing implode: realpath would not work for non-existent paths and it would allow escaping from the root. 
To demo the root escape problem:
path_join("..", "foo"); yields "foo"
Whereas realpath("../foo"); yields the absolute path of the "foo" file one directory up. 

Note: This function does not do any I/O.

2. path_normalize(string $path): string; 

This function only does the normalization part described above.
Note: This function also does not do any I/O.

**Examples:**

```php
// Example usage of path_join
$result = path_join('dir1', 'dir2', '..', 'file.txt'); // Resolves to 'dir1/file.txt'

// Example usage of path_normalize
$normalizedPath = path_normalize('dir1/../dir2'); // Resolves to 'dir2'
```


I think these would be great additions to PHP as working with paths and files is a core part of any programming language.

Furthermore, languages like Python and runtimes like Node.JS allow to join and normalize paths that are not native to the operating system PHP is running on.
E.g. it's possible to create a Posix-style path (what is used on Linux, macOS, BSD etc) on a Windows system.
This is sometimes necessary in order to construct a path to access a remote file on a Linux server to just give an example.

In PHP we could add functions like (just to give an example):
\Path\Windows\join for Windows paths 
\Path\Posix\join for Linux/macOS/Posix paths
\Path\join that automatically chooses one of the above depending on what operating system PHP runs on.
Similar approach for path_normalize.

There could be OOP-style alternatives too, e.g. Rust has a PathBuf struct with methods that are used to build paths.
However if we were to choose this route then we need to be aware that interoperability with existing filesystem functions would be much harder because they all work directly with strings at the moment. 

What do you think?

Kind regards
Niels