jbzoo/path

PHP virtual path library

7.0.2 2025-09-27 23:39 UTC

README

CI Coverage Status Psalm Coverage Psalm Level CodeFactor Stable Version Total Downloads Dependents GitHub License

A PHP library for creating memory-based aliases for your project file system. This virtual path system allows you to map logical names to physical directories, making file access and URL generation much easier and more maintainable.

Features

  • ๐Ÿš€ Virtual Path Mapping: Create logical aliases for filesystem paths
  • ๐Ÿ”— URL Generation: Automatically generate URLs from file paths
  • ๐Ÿ“ Multiple Path Support: Add multiple directories under the same alias
  • ๐Ÿ” File Resolution: Find files across multiple registered paths
  • ๐Ÿงน Path Normalization: Clean and normalize file paths
  • โšก Performance Optimized: Faster than native PHP realpath() in many scenarios

Requirements

  • PHP 8.2 or higher
  • Composer for installation

Installation

composer require jbzoo/path

Quick Start

Basic Usage

<?php

use JBZoo\Path\Path;

// Create path instance
$path = new Path();

// Set root directory
$path->setRoot(__DIR__);

// Add path aliases
$path
    ->add(__DIR__ . '/assets/css', 'css')
    ->add(__DIR__ . '/assets/js', 'js')
    ->add([
        __DIR__ . '/themes/default/css',
        __DIR__ . '/themes/custom/css'
    ], 'theme-css');

// Find files using aliases
echo $path->get('css:main.css');        // Returns: /project/assets/css/main.css
echo $path->get('js:app.js');           // Returns: /project/assets/js/app.js

// Generate URLs (if root is web accessible)
echo $path->url('css:main.css');        // Returns: https://example.com/assets/css/main.css

// Clean and normalize paths
echo Path::clean('path\\to//file.txt'); // Returns: 'path/to/file.txt'

Advanced Examples

// Add virtual paths (extending existing aliases)
$path->add('css:vendor/bootstrap');
$path->add('css:vendor/fontawesome');

// Get all registered paths for an alias
$cssPaths = $path->getPaths('css:');
// Returns array of all CSS directories

// Check if file exists in any registered path
if ($path->get('css:custom.css')) {
    echo '<link rel="stylesheet" href="' . $path->url('css:custom.css') . '">';
}

// Multiple file types under one alias
$path->add([
    __DIR__ . '/public/images',
    __DIR__ . '/uploads/images',
    __DIR__ . '/cache/optimized'
], 'images');

// Will search in all image directories
$logoPath = $path->get('images:logo.png');

Performance

JBZoo Path provides excellent performance compared to native PHP functions. See detailed benchmarks here.

Subject Groups Iterations Revisions Mean StdDev RStdDev Memory Performance
benchBaseline 3 10000 2.53ฮผs 0.11ฮผs 4.39% 6,291,456b 1.00x
benchNative 3 10000 138.22ฮผs 0.46ฮผs 0.33% 6,291,456b 54.64x
benchJBZooPath 3 10000 192.58ฮผs 0.87ฮผs 0.45% 6,291,456b 76.13x

Development

Running Tests

# Install/update dependencies
make update

# Run all tests and code style checks
make test-all

# Run only PHPUnit tests
make test

# Run only code style checks
make codestyle

Project Structure

src/
โ”œโ”€โ”€ Path.php       # Main Path class
โ””โ”€โ”€ Exception.php  # Custom exception class

tests/
โ”œโ”€โ”€ PathTest.php              # Main test suite
โ”œโ”€โ”€ PathPhpStormProxyTest.php # IDE integration tests
โ”œโ”€โ”€ PathPackageTest.php       # Package validation tests
โ””โ”€โ”€ phpbench/                 # Performance benchmarks

License

MIT