Jackalope Fs Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require jackalope/jackalope-fs
   

   Ensure you have jackalope/jackalope installed (dependency):

   composer require jackalope/jackalope
   

2. Basic Usage Initialize the filesystem adapter:

   use Jackalope\Filesystem\Filesystem;
   use Jackalope\Filesystem\FilesystemAdapter;
   
   $adapter = new FilesystemAdapter('/path/to/your/filesystem');
   $filesystem = new Filesystem($adapter);
   

3. First Use Case: File Operations Test basic CRUD operations:

   // Create a file
   $filesystem->createFile('/test.txt')->setContent('Hello, Jackalope!');
   
   // Read a file
   $content = $filesystem->getNode('/test.txt')->getContent();
   
   // Check if a file exists
   $exists = $filesystem->nodeExists('/test.txt');
   

Implementation Patterns

Common Workflows

1. Integration with Laravel Filesystem Use the adapter as a drop-in replacement for Laravel’s Filesystem contract:

   use Illuminate\Contracts\Filesystem\Filesystem as LaravelFilesystem;
   
   $adapter = new FilesystemAdapter(storage_path('app'));
   $laravelFilesystem = new LaravelFilesystem($adapter);
   

2. Node Traversal Recursively list files/directories:

   foreach ($filesystem->getNode('/')->getChildren() as $child) {
       if ($child->isFile()) {
           // Handle file
       }
   }
   

3. Event-Driven Operations Hook into preSetContent/postSetContent for logging/auditing:

   $filesystem->getNode('/file.txt')->setContent('data', function ($node) {
       // Pre-operation logic
   });
   

Laravel-Specific Tips

• Service Provider Binding Bind the adapter in AppServiceProvider:

  $this->app->bind(
      \Jackalope\Filesystem\Filesystem::class,
      fn() => new Filesystem(new FilesystemAdapter(storage_path('app')))
  );
  

• Configuration Store filesystem paths in .env:

  JACKALOPE_PATH=/custom/path
  

  Access via:

  $adapter = new FilesystemAdapter(config('jackalope.path'));
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity The adapter respects OS-level case sensitivity (e.g., /File.txt ≠ /file.txt on Linux). Fix: Normalize paths or use strtolower() for comparisons.

2. Permission Handling PHP’s FilesystemIterator may fail silently on restricted directories. Fix: Use FilesystemAdapter::checkAccess() before operations.

3. Symbolic Links The adapter follows symlinks by default. Disable with:

   $adapter = new FilesystemAdapter('/path', false);
   

Debugging

• Node Existence Checks Use nodeExists() before operations to avoid NodeNotFoundException:

  if (!$filesystem->nodeExists('/nonexistent')) {
      $filesystem->createNode('/nonexistent');
  }
  

• Content Encoding Ensure content is UTF-8 encoded to avoid corruption when reading/writing.

Extension Points

1. Custom Node Types Extend Jackalope\Filesystem\NodeInterface for domain-specific logic:

   class CustomNode implements NodeInterface {
       public function getMetadata() { ... }
   }
   

2. Adapter Wrappers Decorate FilesystemAdapter to add caching or logging:

   class LoggingAdapter implements FilesystemAdapterInterface {
       protected $adapter;
   
       public function __construct(FilesystemAdapter $adapter) {
           $this->adapter = $adapter;
       }
   
       public function get($uri) {
           Log::debug("Accessing: $uri");
           return $this->adapter->get($uri);
       }
   }
   

3. Event Listeners Use Jackalope\Filesystem\EventDispatcher to trigger events:

   $dispatcher = new EventDispatcher();
   $filesystem = new Filesystem($adapter, $dispatcher);
   $dispatcher->addListener('node.set_content', function ($event) {
       // Handle content changes
   });