Jackalope Fs Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (ensure compatibility with Symfony 6):

   composer require jackalope/jackalope-fs
   

   Verify jackalope/jackalope (v2.x+) is installed as a dependency:

   composer require jackalope/jackalope:^2.0
   

2. Basic Usage Initialize the filesystem adapter with Symfony 6 compatibility:

   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 (unchanged):

   // 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 (unchanged):

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

2. Node Traversal Recursively list files/directories (unchanged):

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

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

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

Laravel-Specific Tips

• Service Provider Binding Bind the adapter in AppServiceProvider (unchanged):

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

• Configuration Store filesystem paths in .env (unchanged):

  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);
   

4. Symfony 6 Compatibility

   • Breaking Change: If using Symfony components (e.g., Psr\Log\LoggerInterface), ensure they are v6-compatible.
   • Dependency Conflict: Avoid mixing jackalope/jackalope:^1.0 (Symfony 5) with ^2.0 (Symfony 6). Run:

     composer require jackalope/jackalope:^2.0 --update-with-dependencies
     

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 (unchanged):

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

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

   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 (unchanged):

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

4. Symfony 6 Event Dispatcher If integrating with Symfony 6, leverage its EventDispatcherInterface:

   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   $dispatcher = new EventDispatcher();
   $filesystem = new Filesystem($adapter, $dispatcher);
   
   // Register Symfony 6 listeners if needed
   $dispatcher->addListener('node.set_content', [new SymfonyListener(), 'handle']);