Open-source project
thecodingmachine/safe avatar
thecodingmachine/safe

Every PHP core function has a second definition in the Safe namespace

All PHP functions, rewritten to throw exceptions instead of returning false

2,496 stars173 forksPHPMIT

At a glance

What is it?
thecodingmachine/safe redeclares PHP core functions so that an error throws instead of returning false, and nothing changes until a file imports the variant. The migration tooling renames calls, it does not repair the error handling around them, and the PHPStan rule that keeps the imports honest lives in a separate package.
Who is it for?
This fits a codebase that already runs PHPStan and wants failure to show up during review rather than in a log nobody reads, because the rule is the only thing that turns intent into enforcement and nothing at all happens at a call site that was never imported. It does not fit a project hoping for one switch that repairs error handling everywhere, since the automated pass stops at the function name.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 12 days ago.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • thecodingmachine/safe2,496 ★ · +0
Star history
Repository2026-09-302026-11-15
thecodingmachine/safe2.5k2.5k

0 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Safe is a second namespace, not a wrapper layer

safe does not wrap PHP core functions in objects or route them through a service. It redeclares them. Every function keeps the name it already has and gains a second definition inside the `Safe` namespace, and the documentation is explicit that the new functions act exactly as the old ones except that they throw an exception properly when an error is encountered. The only edit to a working file is the import:

php
use function Safe\file_get_contents;
use function Safe\json_decode;

// This code is both safe and simple!
$content = file_get_contents('foobar.json');
$foobar = json_decode($content);

That single design choice is both the appeal and the catch. Because nothing at a call site changes until the file imports the variant, a codebase can carry both spellings indefinitely, and a call nobody bothered to edit keeps the silent `false` return that the library exists to remove. The premise is spelled out at the top of the documentation: most core functions predate exception support, most of us are too lazy to check every single return, and the resulting code is incorrect twice over when `json_decode` receives the `false` that `file_get_contents` produced.

A thousand functions from about eighty five files on every request

The loading cost is the trade the project states outright. Safe loads more than a thousand functions from roughly eighty five files on each request, and the documentation puts the price at about 700 microseconds per request, calling the impact quite low. The supporting detail is kept in `performance/README.md`, which explains how the impact was measured.

Read the two figures together and the shape of the cost becomes plain. It is a fixed load per request rather than a per-call price, so a script that calls one wrapped function pays the same bill as a controller that calls a hundred. The claim also arrives without the context needed to check it: no PHP version, no hardware and no benchmark method appear beside the number in the documentation, only the pointer to the separate page. That page is not part of this repository's visible documentation, so the figure stands on trust, and the honest way to use it is as an order of magnitude for a request that already does real work.

The Rector pass renames calls and leaves the old guard standing

Automated migration is one command, and the documentation is candid about how little the tool decides:

bash
vendor/bin/rector process src/ --config vendor/thecodingmachine/safe/rector-migrate.php

The configuration ships in the repository root as `rector-migrate.php`, and the note under the command says to replace `src/` with the path to your own source directory. What the pass performs is a dumb replacement of the function names. It will not modify the way `false` return values are handled, so code that was already doing error handling has to be dealt with by hand. The documentation shows the intermediate state:

php
if (!\Safe\mkdir($dirPath)) {
    // Do something on error
}

That file parses and runs, and the guard is now unreachable, because `Safe\mkdir` throws rather than returning `false`. Every site already checking a return value becomes a quiet behaviour change until somebody rewrites it, and rewriting is exactly the step no tool performs. The form offered as the finished replacement carries an unbalanced parenthesis in the call itself, so it is a shape to retype rather than a block to paste.

The PHPStan rule is a separate package behind a fixed vendor path

The project answers its own adoption worry with static analysis, and the warning text shows what an unsafe call produces:

bash
composer require --dev thecodingmachine/phpstan-safe-rule
yml
includes:
    - vendor/thecodingmachine/phpstan-safe-rule/phpstan-safe-rule.neon

The message names the line to add, telling you the function can return `FALSE` instead of throwing an exception and that `use function Safe\file_get_contents;` belongs at the beginning of the file. The package name and that include path together show where the rule actually lives: not in this repository, but in `thecodingmachine/phpstan-safe-rule`, with the neon entry written against one fixed location inside `vendor`. A project that keeps its vendor directory somewhere else, or that assembles several PHPStan configurations, has to correct that line before the rule loads at all. The library installs with the usual line:

bash
composer require thecodingmachine/safe

Class coverage stops at two DateTime wrappers

Function coverage is stated as complete: all PHP functions that can return `false` on error are part of Safe. Class coverage is not, and the boundary is explicit rather than implied. The documentation names exactly two additional classes, `Safe\DateTime` and `Safe\DateTimeImmutable`, whose methods throw exceptions instead of returning false. No other class wrapper is mentioned, and no list of covered methods is given for those two.

Method calls therefore stay manual, the same discipline the library set out to remove for functions, and the framework's own claim about being both safe and simple does not extend to objects you construct. The analysis report described in the documentation speaks about functions, warning on each unsafe one, so a team that adopts the rule gets a signal about its function calls and nothing about the state of its object graph. Whether the rule inspects the two throwing classes as well is not stated anywhere in this repository, which means a migration plan built on the assumption that it does has no support in the documentation.

The dev container pins PHP 8.1 while no version floor is documented

The development environment is one Compose service named `app`, built from `thecodingmachine/php:8.1-v4-apache`, with the repository mounted over `/var/www/html`. That image is the PHP version the project is worked on day to day. The README does not state a minimum PHP version for the library, does not state a maximum, and does not say which revision of the PHP documentation the generated function set was produced from, so the floor has to be established by trying the library rather than by reading about it.

The repository root carries the tooling for a library that expects to be checked like one: `phpstan.neon`, `phpcs.xml.dist` and `phpunit.xml.dist` sit beside `composer.json`, together with a `tests/` tree and a `.devcontainer/` directory. A contributor therefore runs the same analysis and style configuration the library is developed under, which matters for anyone copying this repository as the starting point for their own static analysis setup around safe functions.

What you read in the library is generated output

The documentation is explicit about where the function files come from: they are auto-generated from the PHP doc, and `CONTRIBUTING.md` explains how to regenerate them and how to contribute to the library. The repository layout agrees, keeping `generated/`, `generator/`, `lib/` and `tests/` as separate top-level directories rather than one flat source tree.

Generated code changes the review question. A diff touching a function body is something a maintainer did not type, and contributors are pointed at a regeneration step instead of at an editor. It also means the coverage claim follows whatever the generator emits from the documentation it reads, and this repository does not say which revision of that documentation it consumes, so the line between functions that are wrapped and functions that are not is settled by the generator rather than by a rule a reader can verify by eye. The release history shows the same shape: the newest tag is v3.4.0 from 2026-02-15, and the default branch was pushed to again on 2026-08-17.

Editorial conclusion

This fits a codebase that already runs PHPStan and wants failure to show up during review rather than in a log nobody reads, because the rule is the only thing that turns intent into enforcement and nothing at all happens at a call site that was never imported. It does not fit a project hoping for one switch that repairs error handling everywhere, since the automated pass stops at the function name. Before adopting, establish which PHP version the generated function set was produced against, as no floor is documented; budget for converting the existing guards by hand, because each one survives the migration as an unreachable branch; and type the exception form yourself, since the finished snippet offered in the documentation has an unbalanced parenthesis in it.

Frequently asked questions

What does thecodingmachine/safe actually change about a PHP core function?

It redeclares it in the Safe namespace under the same name, so the only edit at a call site is a use function import. The new functions behave exactly like the originals except that they throw an exception when an error occurs instead of returning false.

How do I get PHPStan to flag unsafe function calls in an existing project?

Add thecodingmachine/phpstan-safe-rule as a development dependency, then include vendor/thecodingmachine/phpstan-safe-rule/phpstan-safe-rule.neon from your phpstan.neon. Each unsafe call is reported with the use function line to add at the top of the file.

Will the Rector migration fix error handling in my legacy code?

No. The documentation states that the refactoring only performs a dumb replacement of functions and does not modify the way false return values are handled. A guard such as if (!\Safe\mkdir($dirPath)) keeps compiling while its branch becomes unreachable, and converting it to a try and catch on \Safe\FilesystemException is left to you.

Is PHP safe to use?

This repository does not address the safety of the PHP language as a whole. It targets one specific behaviour: core functions that return false on error are redeclared so they throw, together with two classes, Safe\DateTime and Safe\DateTimeImmutable, whose methods throw instead of returning false.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. thecodingmachine/safe on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/thecodingmachine-safe.svg)](https://hysenlabs.com/projects/thecodingmachine-safe)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/thecodingmachine-safe.svg)](https://hysenlabs.com/projects/thecodingmachine-safe)

Was this useful?