PHPackages                             ctw/ctw-temp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. ctw/ctw-temp

ActiveLibrary

ctw/ctw-temp
============

Easily create, use and destroy temporary files and directories.

1.0.1(yesterday)017↑2723.5%BSD-3-ClausePHP ^8.5

Since Jul 22Compare

[ Source](https://github.com/jonathanmaron/ctw-temp)[ Packagist](https://packagist.org/packages/ctw/ctw-temp)[ RSS](/packages/ctw-ctw-temp/feed)WikiDiscussions Synced today

READMEChangelogDependencies (3)Versions (3)Used By (0)

Package "ctw/ctw-temp"
======================

[](#package-ctwctw-temp)

Zero-dependency generator for per-user, per-application temporary files and directories
on disk, for PHP 8.5+ applications.

Features
--------

[](#features)

- Builds temporary paths of the form `[/]/[/]`, defaulting to real disk (`/var/tmp/php`) instead of the RAM-backed `sys_get_temp_dir()`.
- Optional per-user/group `` segment isolates one user's files from another's on shared hosts.
- Provisions the tree in two permission tiers: a world-writable shared base and per-user directories beneath it.
- Atomically creates uniquely named files, with deletion guarded against path traversal outside the directory.
- Consistent `Path`/`File` method naming and a single exception interface for catching every failure mode.
- No package dependencies; requires only `ext-posix`.

Introduction
------------

[](#introduction)

### Why This Library Exists

[](#why-this-library-exists)

Applications commonly derive a temporary working directory from `sys_get_temp_dir()`. Since Debian 14, that location (`/tmp`) is a **`tmpfs`**(RAM-backed) mount that fills up quickly under write-heavy workloads such as image processing, PDF generation, or page caching.

`ctw/ctw-temp` moves temporary storage onto real disk (default `/var/tmp/php`) and encapsulates the path-construction logic — previously duplicated inline across the application — behind a single, tested class with **no package dependencies**.

It replaces constructions such as:

```
define('APP_PATH_TEMP', sprintf(
    '%s/%s_%s_temp',
    sys_get_temp_dir(),
    'www.example.com',
    hash('crc32b', 'www-data_www-data'),
));
mkdir(APP_PATH_TEMP, 0777, true);
```

with:

```
use Ctw\Temp\Temp;

$temp = new Temp('www.example.com');     // base defaults to /var/tmp/php
define('APP_PATH_TEMP', $temp->createPath());
```

### The Path Model

[](#the-path-model)

```
[/]/[/]

```

For example:

```
/var/tmp/php/78b43994/www.example.com/page-cache

```

SegmentMeaningConfigurableDefaultRequired`basePath`Base path holding the temporary treeyes`/var/tmp/php`–`hash``crc32b` of the sanitized `_` (8 hex chars)on/offincluded–`id`Application identifier or hostname––**yes**`levelN`Optional n-level directory, or a list of nested directoriesyesomittednoThe `hash` segment isolates one user/group's files from another's on shared hosts. It is derived from the process user and group via the POSIX extension (encapsulated in `Ctw\Temp\Posix`, injectable into `Temp`), so `ext-posix` is required.

Requirements
------------

[](#requirements)

- PHP 8.5+
- `ext-posix`

Installation
------------

[](#installation)

```
composer require ctw/ctw-temp
```

Usage
-----

[](#usage)

```
use Ctw\Temp\Temp;

// Full constructor signature (only $id is required):
$temp = new Temp(
    id: 'www.example.com',
    levelN: 'page-cache',   // optional extra directory
    includeUserGroup: true, // include the per-user/group  segment
    basePath: '/var/tmp/php', // default
);

$temp->getPath();       // '/var/tmp/php/78b43994/www.example.com/page-cache'

$temp->createPath();    // mkdir -p; throws RuntimeException if not writable
$temp->existsPath();    // bool

// Create and later delete a uniquely named file inside the directory:
$file = $temp->createFile('report', 'pdf'); // '/…/report-a1b2c3d4e5f6a7b8.pdf'
$temp->deleteFile($file);

$temp->clearPath();     // empty the directory, keep it (e.g. cache reset)
$temp->deletePath();    // recursively remove the directory and its contents
```

`$levelN` also accepts a list, which nests one directory per element:

```
$temp = new Temp('www.example.com', ['page-cache', 'v2']);
$temp->getPath(); // '/var/tmp/php/78b43994/www.example.com/page-cache/v2'
```

### Public API

[](#public-api)

Method names carry a `Path` (directory) or `File` (file) qualifier so it is always clear which is being operated on. In the source, directory operations and file operations are grouped into separate, clearly marked sections.

MethodOperates onDescription`getPath(): string`–The assembled path (does not create it).`createPath(): string`directoryCreate the directory recursively; throws if it cannot be written.`deletePath(): bool`directoryRecursively delete the directory and its contents.`existsPath(): bool`directoryWhether the directory currently exists.`clearPath(): void`directoryRemove the directory's contents but keep the directory.`createFile(string $name, string $ext)`fileAtomically create a uniquely named file; returns its absolute path.`deleteFile(string $file): bool`fileDelete a file inside the directory (refuses paths outside it).### Errors

[](#errors)

Every exception implements `Ctw\Temp\Exception\ExceptionInterface`, so a single `catch (ExceptionInterface $e)` traps them all. Specific types let you catch individual failure modes:

ExceptionExtendsThrown when`InvalidBasePathException``InvalidArgumentException`the configured base path is empty`InvalidPathSegmentException``InvalidArgumentException`an `id`/`levelN` segment is empty or unsafe`DirectoryNotCreatedException``RuntimeException`a base or per-user directory cannot be created`DirectoryNotWritableException``RuntimeException`the temporary directory exists but is not writable`FileNotCreatedException``RuntimeException`a unique file cannot be created`PathTraversalException``RuntimeException`a `deleteFile()` target resolves outside the directory`PosixUnavailableException``RuntimeException`the POSIX extension is required but not loaded`RuntimeException` and `InvalidArgumentException` (both in `Ctw\Temp\Exception`) remain as intermediate base classes for broad catches.

Permissions
-----------

[](#permissions)

`createPath()` provisions the tree in two tiers:

- the **shared base path** (`/var/tmp/php`) is created world-writable (`0777`, forced with `chmod()` so it survives the umask), like `/tmp`, so both a CLI/deploy user and the web server user (`www-data`) can create their own `` subtree beneath it;
- the **per-user directories** below it use `0755` (configurable via the `pathMode` constructor argument) and are owned by the creating user.

Whichever process runs first creates and opens up the base; the other then finds it already in place. No manual provisioning step is required, though ops may pre-create `/var/tmp/php` with mode `0777` if preferred.

Testing
-------

[](#testing)

```
composer test     # PHPUnit test suite (with coverage)
composer qa       # Rector (dry-run), ECS, and PHPStan (max level)
composer qa-fix   # Apply Rector and ECS fixes, then run PHPStan
```

Contributing
------------

[](#contributing)

Create a feature branch, keep the code `declare(strict_types=1);` and PSR-12 compliant, run `composer qa` until it reports no issues, and open a merge request.

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md).

License
-------

[](#license)

BSD-3-Clause. See [LICENSE.md](LICENSE.md).

Maintainer
----------

[](#maintainer)

Maintained by CTW. Report issues and propose changes on the project's repository.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance100

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/18d8bc9bdee8ab1b0cfccce6a06d2438acbed3a58b0046c4834c5678f6769342?d=identicon)[jonathanmaron](/maintainers/jonathanmaron)

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ctw-ctw-temp/health.svg)

```
[![Health](https://phpackages.com/badges/ctw-ctw-temp/health.svg)](https://phpackages.com/packages/ctw-ctw-temp)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)