adachsoft/sandbox-contracts

Shared sandbox contracts and value objects for file-based tools.

v0.1.0 2026-04-08 15:14 UTC

Requires

• php: ^8.3
• adachsoft/normalized-safe-path: ^0.1

Requires (Dev)

• adachsoft/php-code-style: ^0.4.3
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^13.1
• rector/rector: ^2.4

MIT

• Arkadiusz Adach

• filesystem
• security
• sandbox
• contracts
• paths

README

Shared sandbox contracts and value objects for AdachSoft file-based tools.

Installation

composer require adachsoft/sandbox-contracts

Usage

use AdachSoft\SandboxContracts\Factory\SandboxPathFactory;
use AdachSoft\SandboxContracts\Config\ArraySandboxExtractor;

// Direct creation
$factory = new SandboxPathFactory();
$sandbox = $factory->create('/mnt/php/projects/project_1/');
$fullPath = $sandbox->resolve('src/Service/MyService.php');
// "> "/mnt/php/projects/project_1/src/Service/MyService.php""

// From config array (e.g. inside a ToolFactory::create(ConfigMap $config))
$extractor = new ArraySandboxExtractor(new SandboxPathFactory());
$sandbox = $extractor->extract($config->toArray());

How consuming libraries should use this

In any ToolFactory or workflow step that needs a sandbox:

1. Accept ArraySandboxExtractorInterface via constructor (DI preferred) OR instantiate ArraySandboxExtractor directly as convenience.
2. Call $sandbox = $this->extractor->extract($config->toArray()).

3. Pass $sandbox into the tool/step

   - never pass raw base_path string further.

4. Inside the tool/step call $sandbox->resolve($userProvidedPath) before any file operation.