README

Three small helpers for code that writes files:

File store: read and write JSON, write text, create directories, glob.
PHP class writer: generate a PHP class from value objects and write it to disk, refusing to overwrite an existing file. Useful for code generators and scaffolding tools.
Markdown converter: turn simple Markdown into an HTML fragment or a styled standalone page.

Each helper sits behind an interface, so your own code can depend on the interface and swap in a fake in tests.

Requirements

PHP 8.5+

Installation

composer require rmb32/filesystem

Usage

Each factory returns only its interface:

use Rmb32\Filesystem\Api\Factory\FileStoreFactory;
use Rmb32\Filesystem\Api\Factory\MarkdownConverterFactory;
use Rmb32\Filesystem\Api\Factory\PhpClassWriterFactory;

$files = new FileStoreFactory()->create();            // FileStore
$classes = new PhpClassWriterFactory()->create();     // PhpClassWriter
$markdown = new MarkdownConverterFactory()->create(); // MarkdownConverter

Reading and writing files

$files->ensureDirectory('var/settings');   // creates missing parent directories too
$files->writeJson('var/settings/site.json', ['title' => 'My site', 'theme' => 'dark']);

$files->readJson('var/settings/site.json'); // ['title' => 'My site', 'theme' => 'dark']
$files->exists('var/settings/site.json');   // true
$files->glob('var/settings/*.json');        // ['var/settings/site.json']
$files->write('var/notes.txt', "Plain text\n");

writeJson() writes pretty-printed JSON with unescaped slashes and a trailing newline. readJson() accepts only a JSON object: invalid JSON throws a JsonException, and anything else throws a RuntimeException. A write that fails also throws a RuntimeException.

Generating a PHP class

Describe the class with the PhpClass, Method and Parameter value objects:

use Rmb32\Filesystem\Api\ValueObject\Method;
use Rmb32\Filesystem\Api\ValueObject\Parameter;
use Rmb32\Filesystem\Api\ValueObject\PhpClass;

$greeter = new PhpClass(
    namespace: 'App\Greeting',
    name: 'Greeter',
    useStatements: ['App\Greeting\GreeterInterface', 'Override'],
    implements: ['GreeterInterface'],
    methods: [
        new Method(
            name: 'greet',
            parameters: [new Parameter('name', 'string')],
            returnType: 'string',
            body: 'return "Hello, {$name}!";',
            attributes: ['Override'],
        ),
    ],
);

$classes->write('src/Greeting/Greeter.php', $greeter);

This writes src/Greeting/Greeter.php, creating the folder if needed:

<?php

declare(strict_types=1);

namespace App\Greeting;

use App\Greeting\GreeterInterface;
use Override;

final class Greeter implements GreeterInterface
{
    #[Override]
    public function greet(string $name): string
    {
        return "Hello, {$name}!";
    }
}

Running it a second time throws RuntimeException: src/Greeting/Greeter.php already exists., so a generator never overwrites a class someone has since edited. Classes are final unless you pass isFinal: false. (string) $greeter gives you the source without writing it.

Converting Markdown to HTML

$markdown->toHtmlFragment("# Release notes\n\n- **Faster** start-up\n  - see [the guide](guide.md)");

<h1>Release notes</h1>
<ul>
<li><strong>Faster</strong> start-up
<ul>
<li>see <a href="guide.html">the guide</a>
</li></ul>
</li></ul>

toStandalonePage($title, $markdown) wraps the same HTML in a complete page with a small built-in stylesheet.

The converter supports a deliberately small subset of Markdown: # to ### headings, paragraphs, - bullets (nested by two spaces), **bold** and [links](...). Everything else is escaped and shown as text. Links to .md files are rewritten to .html, so a folder of Markdown documents converted one by one still links up.

rmb32 / filesystem

Package info

Security

Statistics