jbzoo / path
PHP virtual path library
Installs: 94 284
Dependents: 7
Suggesters: 0
Security: 0
Stars: 7
Watchers: 3
Forks: 1
Open Issues: 0
Requires
- php: ^8.2
- jbzoo/data: ^7.2
- jbzoo/utils: ^7.3
Requires (Dev)
- jbzoo/toolbox-dev: ^7.2
README
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