Usephul

functions.php

Tags
author

Alwin Garside alwin@garsi.de

copyright

2025 The Empaphy Project

license

MIT

Table of Contents

Functions

basename()  : string
Returns the trailing name component of a given path.
components()  : array<string|int, mixed>
Returns an array of path components for the given path.
directory_separator()  : non-empty-string
Returns the directory separator used in the given path, supported by the current platform.
dirname()  : string
Returns a parent directory's path.
extension()  : string
Returns the extension component of a given path without the extension.
extension_replace()  : ($path is "" ? "" : string)
Replace the extension of a path with a new value.
filename()  : string
Returns the name component of a given path without the extension.
suffix()  : string
Returns a suffix for the given path based on a given set of separators.
suffix_replace()  : string
Replace a suffix in a path with a new value.

Functions

basename()

Returns the trailing name component of a given path.

basename(string $path[, string $suffix = '' ]) : string

Given a string containing the path to a file or directory, this function will return the trailing name component.

Note:

basename() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".

Caution: basename() is locale-aware, so for it to see the correct basename with multibyte character paths, the matching locale must be set using the setlocale() function. If path contains characters which are invalid for the current locale, the behavior of basename() is undefined.

Parameters
$path : string

A path.

On Windows, both slash (/) and backslash (\) are used as directory separator characters. In other environments, it is the forward slash (/).

$suffix : string = ''

If the name component ends in suffix, this will also be cut off.

Tags
see
dirname()
  • Returns a parent directory's path
see
extension()
  • Returns extension component of a path
see
filename()
  • Returns basename of a path, without extension
see
pathinfo()
  • Returns information about a file path
Return values
string —

Returns the base name of the given path.

components()

Returns an array of path components for the given path.

components(string $path) : array<string|int, mixed>

Empty components (i.e., successive directory separators) are disregarded. Additionally, path seperators at the start or end of path are also disregarded.

For example:

components('foo/bar');    // Will return ['foo', 'bar']
components('/foo//bar/'); // Will return ['foo', 'bar']
components('/');          // Will return ['']
components('');           // Will return [''];

Note:

components() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".

Caution: components() is locale-aware, so for it to see the correct basename with multibyte character paths, the matching locale must be set using the setlocale() function. If path contains characters which are invalid for the current locale, the behavior of components() is undefined.

Caution: This function behaves differently on Windows compared to *nix.

components('\\');   // Will return [''] on Windows and ['\'] on *nix.
components('C:\\'); // Will return [''] on Windows and ['C:\'] on *nix.
Parameters
$path : string

A path to split into its components.

On Windows, both slash (/) and backslash (\) are used as directory separator characters. In other environments, it is the forward slash (/).

Return values
array<string|int, mixed>

directory_separator()

Returns the directory separator used in the given path, supported by the current platform.

directory_separator(string $path[, non-empty-string $directory_separator = DIRECTORY_SEPARATOR ]) : non-empty-string
Parameters
$path : string

Path for which to determine the directory separator.

$directory_separator : non-empty-string = DIRECTORY_SEPARATOR

By default, this is set to DIRECTORY_SEPARATOR, but you can override it for testing purposes.

Return values
non-empty-string

dirname()

Returns a parent directory's path.

dirname(string $path[, int<1, max> $levels = 1 ]) : string

Given a string containing the path of a file or directory, this function will return the parent directory's path that is levels up from the current directory.

Note:

dirname() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".

Caution: On Windows, dirname() assumes the currently set codepage, so for it to see the correct directory name with multibyte character paths, the matching codepage must be set. If path contains characters which are invalid for the current codepage, the behavior of dirname() is undefined.

On other systems, dirname() assumes path to be encoded in an ASCII compatible encoding. Otherwise, the behavior of the function is undefined.

Parameters
$path : string

A path.

On Windows, both slash (/) and backslash (\) are used as directory separator characters. In other environments, it is the forward slash (/).

$levels : int<1, max> = 1

The number of parent directories to go up.

This must be an integer greater than 0.

Tags
see
basename()
  • Returns trailing name component of a path
see
pathinfo()
  • Returns information about a file path
see
realpath()
  • Returns canonicalized absolute pathname
Return values
string —

Returns the path of a parent directory. If there are no slashes in path, a dot ('.') is returned, indicating the current directory. Otherwise, the returned string is path with any trailing /component removed.

Caution: Be careful when using this function in a loop that can reach the top-level directory as this can result in an infinite loop.

<?php
dirname('.');    // Will return '.'.
dirname('/');    // Will return `\` on Windows and '/' on *nix.
dirname('\\');   // Will return `\` on Windows and '.' on *nix.
dirname('C:\\'); // Will return 'C:\' on Windows and '.' on *nix.
?>

extension()

Returns the extension component of a given path without the extension.

extension(string $path) : string

Given a string containing the path to a file or directory, this function will return the extension component.

extension('/root/dir/sub/name.suf.ext'); // returns 'ext'
extension('/root/dir/sub/name.ext');     // returns 'ext'
extension('/root/dir/sub/.ext');         // returns 'ext'
extension('/root/dir/sub/name');         // returns ''
extension('/root/dir/sub/');             // returns ''

Note:

If the path has more than one extension, extension() returns only the last one.

Note:

extension() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".

Caution extension() is locale-aware, so for it to parse a path containing multibyte characters correctly, the matching locale must be set using the setlocale() function.

Parameters
$path : string

A path.

Tags
see
dirname()
  • Returns a parent directory's path
see
basename()
  • Returns trailing name component of a path
see
filename()
  • Returns basename of a path, without extension
see
pathinfo()
  • Returns information about a file path
Return values
string —

The extension component of path. If the path has no extension component, an empty string is returned.

extension_replace()

Replace the extension of a path with a new value.

extension_replace(string $path[, null|string $replacement = null ][, string $suffix = '' ]) : ($path is "" ? "" : string)

If replacement is left empty, the extension is removed from path, including the seperating period (.).

For the intents of this function, path is considered to have an extension if there is a period (.) which is not the first character of the basename.

Parameters
$path : string

A path.

$replacement : null|string = null

The replacement extension. If null, the extension is removed along with the preceding period (.).

$suffix : string = ''

If the filename in path is suffixed with suffix, then the suffix is also replaced along with the extension. Additionally, if suffix contains an extension – i.e. starts with a period (.) – then it will always be replaced in path, even if the value of path starts with suffix.

Return values
($path is "" ? "" : string) —

The modified path.

filename()

Returns the name component of a given path without the extension.

filename(string $path[, string $suffix = '' ]) : string

Given a string containing the path to a file or directory, this function will return the trailing name component without the extension.

filename('/root/dir/sub/name.suf.ext'); // returns 'name.suf'
filename('/root/dir/sub/name.ext');     // returns 'name'
filename('/root/dir/sub/name');         // returns 'name'
filename('/root/dir/sub/.ext');         // returns ''
filename('/root/dir/sub/');             // returns 'sub'

filename('/root/dir/sub/name.suf.ext', '.ext') // returns 'name.suf'
filename('/root/dir/sub/name.suf.ext', '.suf') // returns 'name'
filename('/root/dir/sub/name.suf.suf', '.suf') // returns 'name'
filename('/root/dir/sub/name.ext',     '.suf') // returns 'name'
filename('/root/dir/sub/name.suf',     '.suf') // returns 'name'
filename('/root/dir/sub/name',         '.suf') // returns 'name'
filename('/root/dir/sub/.suf.ext',     '.suf') // returns ''
filename('/root/dir/sub/',             '.suf') // returns 'sub'
filename('/root/dir/sub/',             'sub')  // returns ''

Note:

If the path has more than one extension, filename() only strips the last one.

Note:

filename() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".

Caution filename() is locale-aware, so for it to parse a path containing multibyte characters correctly, the matching locale must be set using the setlocale() function.

Parameters
$path : string

A path.

$suffix : string = ''

If the name component ends in suffix, this will also be cut off.

Tags
see
dirname()
  • Returns a parent directory's path
see
basename()
  • Returns trailing name component of a path
see
extension()
  • Returns extension component of a path
see
pathinfo()
  • Returns information about a file path
Return values
string —

Returns the name component of path.

suffix()

Returns a suffix for the given path based on a given set of separators.

suffix(string $path[, string $separator = '-' ], string ...$separators) : string

A suffix is defined as the part of the basename after the last separator character in separators, and before the extension.

suffix('/path/to/name-suf',     '-'); // returns '-suf'
suffix('/path/to/name-suf.ext', '-'); // returns '-suf'
suffix('/path/to/name.suf.ext', '.'); // returns '.suf'
Parameters
$path : string

A path.

$separator : string = '-'

Specifies the separator strings.

$separators : string

Specifies additional separator strings.

Return values
string

suffix_replace()

Replace a suffix in a path with a new value.

suffix_replace(string $path, string $suffix, string ...$separators) : string

If replacement is left empty, the suffix is removed from path.

Parameters
$path : string

A path.

$suffix : string

The new suffix. If empty, the suffix is removed.

$separators : string

You can provide multiple separator strings to identify the existing suffix. If no separator is provided, the suffix will simply be added to the filename component of the path.

Return values
string —

The modified path.


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results