Path Utilities and Helper Functions

This page documents the path manipulation and directory management utilities provided by the hypervel/filesystem package. These utilities simplify common filesystem operations related to path handling and directory management.

Overview

The package provides two main utilities for path and directory operations:

1. join_paths() function - Safely concatenates file paths with proper directory separator handling
2. Filesystem utility class - Provides directory management methods, extending the base Hyperf filesystem utility

These utilities are designed to work alongside the main filesystem adapters and drivers, providing low-level path manipulation and directory management capabilities.

Path Joining with join_paths()

The join_paths() function provides a cross-platform way to concatenate file path segments while handling directory separators correctly.

Function Signature

Implementation Details

The function processes path segments through the following steps:

1. Iterates through each path segment
2. Removes empty segments (except '0')
3. Normalizes each segment by prepending DIRECTORY_SEPARATOR and trimming leading separators
4. Concatenates the base path with all processed segments

Sources: src/Functions.php13-24

Path Processing Flow

Sources: src/Functions.php15-23

Usage Examples

The function handles various path concatenation scenarios:

Input	Output	Notes
join_paths('/var/www', 'storage', 'app')	/var/www/storage/app	Basic path joining
join_paths('/var/www', '', 'app')	/var/www/app	Empty segments removed
join_paths('/var/www', '/storage/')	/var/www/storage	Leading/trailing separators handled
join_paths(null, 'storage', 'app')	/storage/app	Null base path
join_paths('/path', '0')	/path/0	Zero string preserved

The function uses DIRECTORY_SEPARATOR constant to ensure cross-platform compatibility between Unix-like systems (/) and Windows (\).

Sources: src/Functions.php13-24

File Existence and State Checking

The filesystem adapter provides convenient methods for checking file and directory existence with intuitive naming:

File State Checking Methods

These helper methods provide semantic clarity by offering both positive and negative variants of existence checks, making code more readable and self-documenting.

Sources: src/FilesystemAdapter.php162-205

Testing and Assertion Helpers

The filesystem adapter includes specialized assertion methods for testing scenarios, integrating with PHPUnit for comprehensive filesystem testing:

Testing Assertion Flow

The assertion helpers provide fluent testing capabilities with automatic cache clearing and content verification options. These methods return the adapter instance for method chaining.

Assertion Method	Purpose	Parameters
assertExists()	Verify files exist	path (string|array), optional content
assertMissing()	Verify files don't exist	path (string|array)
assertDirectoryEmpty()	Verify directory is empty	directory (string)

Sources: src/FilesystemAdapter.php97-157

Content Processing Helpers

Several helper methods facilitate working with file content in specific formats and processing scenarios:

JSON Content Handling

The json() method provides direct JSON parsing of file contents with configurable options:

JSON Processing Helper

This helper combines file reading with JSON parsing, handling null content gracefully and accepting standard JSON decode flags.

Sources: src/FilesystemAdapter.php232-237

Content Manipulation

The adapter provides helpers for common content manipulation patterns:

Method	Operation	Use Case
prepend()	Add content to beginning	Log headers, file metadata
append()	Add content to end	Logging, data accumulation

Both methods handle non-existent files by creating them, and existing files by reading, modifying, and rewriting content.

Sources: src/FilesystemAdapter.php420-439

Directory Traversal Helpers

Specialized methods provide convenient ways to work with directory contents:

Directory Traversal Helpers

These methods provide filtered and sorted directory listings with options for recursive traversal, simplifying common directory processing tasks.

Sources: src/FilesystemAdapter.php716-758

Configuration and Metadata Helpers

The filesystem adapter exposes several methods for accessing underlying configuration and driver information:

Driver Access Methods

Method	Returns	Purpose
getDriver()	FilesystemOperator	Access Flysystem driver directly
getAdapter()	FlysystemAdapter	Access underlying Flysystem adapter
getConfig()	array	Access configuration values

Custom Functionality Registration

The buildTemporaryUrlsUsing() method allows registration of custom temporary URL generation logic:

Custom URL Generation Registration

This helper enables extending URL generation capabilities for adapters that don't natively support temporary URLs.

Sources: src/FilesystemAdapter.php795-814 src/FilesystemAdapter.php837-840

Error Handling Configuration

The throwsExceptions() helper method determines exception handling behavior based on configuration:

Exception Handling Configuration

This internal helper is used throughout the adapter to provide consistent error handling behavior based on user configuration preferences.

Sources: src/FilesystemAdapter.php845-848