Oihana PHP

getTimestampedDirectory.php

Table of Contents

Functions

getTimestampedDirectory()  : string
Get a timestamped file path using a formatted date and optional prefix/suffix.

Functions

getTimestampedDirectory()

Get a timestamped file path using a formatted date and optional prefix/suffix.

getTimestampedDirectory([string|null $date = null ][, string $basePath = Char::EMPTY ][, string $prefix = Char::EMPTY ][, string $suffix = Char::EMPTY ][, string|null $timezone = 'Europe/Paris' ][, string|null $format = 'Y-m-dTH:i:s' ][, bool $assertable = true ]) : string

Combines a date/time string (or the current time) with optional *extension, prefix, suffix, and base path to generate a unique file name. The file is not created on disk.

Asserts by default if the file exist, you can disabled the behavior with the boolean assertable argument.

Parameters
$date : string|null = null

Optional date/time string to use. If null or invalid, the current date/time is used ("now").

$basePath : string = Char::EMPTY

Optional base path in which to place the directory. Defaults to the current directory.

$prefix : string = Char::EMPTY

Optional string to prepend to the directory name (e.g., "/hello-2025-12-01T14:00:00"").

$suffix : string = Char::EMPTY

Optional string to append to the directory name (e.g., "/2025-12-01T14:00:00-hello"").

$timezone : string|null = 'Europe/Paris'

Timezone identifier (e.g., 'Europe/Paris'). Defaults to 'Europe/Paris'.

$format : string|null = 'Y-m-dTH:i:s'

Date format compatible with DateTime::format(). Defaults to 'Y-m-d\TH:i:s'.

$assertable : bool = true

Whether to validate the path with assertDirectory(). Defaults to true.

Tags
throws
DirectoryException

If the directory path is invalid or assertion fails.

example 
use function oihana\files\getTimestampedDirectory;

// Example 1: Generate directory path with current date/time, no prefix/suffix, current directory base
$dirPath = getTimestampedDirectory();
// e.g. "./2025-07-15T14:32:00"

// Example 2: Generate directory path with specific date, custom base path, and extension-like suffix
$dirPath = getTimestampedDirectory(
date: '2025-12-01 14:00:00',
basePath: '/var/backups',
suffix: '_archive'
);
// e.g. "/var/backups/2025-12-01T14:00:00_archive"

// Example 3: Add prefix and suffix, custom timezone and format, without assertion
$dirPath = getTimestampedDirectory
(
    prefix: 'backup_',
    suffix: '_final',
    timezone: 'UTC',
    format: 'Ymd_His',
    assertable: false
);
// e.g. "./backup_20250715_123200_final"
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

The full path of the generated directory.


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results