Siler Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require leocavalcante/siler
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       LeoCavalcante\Siler\SilerServiceProvider::class,
   ],
   

2. First Use Case: Flat-File Storage Store a simple array in a flat file (e.g., data/users.json):

   use LeoCavalcante\Siler\Facades\Siler;
   
   $users = ['john' => ['name' => 'John Doe', 'email' => 'john@example.com']];
   Siler::store('users', $users); // Auto-detects JSON format
   

3. Retrieve Data

   $users = Siler::load('users');
   

4. Configuration Publish the config file (optional):

   php artisan vendor:publish --provider="LeoCavalcante\Siler\SilerServiceProvider"
   

   Customize storage paths, formats, or encryption in config/siler.php.

Implementation Patterns

1. Data Abstraction Workflows

• CRUD with Flat Files

  // Create/Update
  Siler::store('config', ['theme' => 'dark', 'notifications' => true]);
  
  // Read
  $config = Siler::load('config');
  
  // Delete
  Siler::delete('config');
  

• File Format Flexibility Use different formats (JSON, YAML, PHP arrays) by specifying the extension:

  Siler::store('data', ['key' => 'value'], 'yaml'); // Saves as data.yaml
  

• Namespacing Organize files hierarchically:

  Siler::store('app/settings', ['debug' => false]); // Saves to `app/settings.json`
  

2. Integration with Laravel

• Cache Integration Cache loaded data to avoid repeated disk I/O:

  $cachedData = Cache::remember('siler_users', now()->addHours(1), function () {
      return Siler::load('users');
  });
  

• Event Listeners Trigger events on file operations (e.g., log changes):

  Siler::store('logs', $newLogEntry);
  // Fires `Siler\Events\FileStored` event
  

• Artisan Commands Create custom commands to manage siler data:

  use LeoCavalcante\Siler\Facades\Siler;
  
  class ImportUsersCommand extends Command {
      public function handle() {
          $users = Siler::load('users');
          // Process users...
      }
  }
  

3. Advanced Features

• Encryption Enable encryption in config/siler.php:

  'encryption' => [
      'enabled' => true,
      'key' => env('SILER_ENCRYPTION_KEY'),
  ],
  

  Now all stored data is encrypted automatically.

• File Locking Prevent race conditions with file locks:

  Siler::store('counter', ['value' => 1], [], true); // $lock = true
  

• Custom Drivers Extend Siler\Drivers\DriverInterface to support alternative storage (e.g., S3, Redis):

  class S3Driver implements DriverInterface {
      public function store($path, $data, array $options) {
          // Custom S3 logic
      }
  }
  

Gotchas and Tips

Pitfalls

1. File Permissions Ensure the storage directory (storage/siler) is writable:

   chmod -R 775 storage/siler
   

   Symptom: Silent failures or Permission denied errors.

2. Serialization Issues Avoid storing non-serializable objects (e.g., closures, resources). Use arrays or JSON-compatible data. Workaround: Convert objects to arrays manually:

   Siler::store('user', (array) $userModel);
   

3. Caching Pitfalls Disabling Laravel’s cache (e.g., Cache::forget('siler_*')) won’t clear Siler’s disk files. Delete manually if needed:

   Siler::delete('config');
   

4. Archived Package Risks The package is archived (no updates since 2021). Test thoroughly in staging and consider forking if critical bugs arise.

Debugging Tips

• Enable Logging Add to config/siler.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs file operations to storage/logs/siler.log.

• Verify File Paths Check the resolved path with:

  dd(Siler::getPath('users')); // Outputs full path (e.g., `storage/siler/users.json`)
  

• Validate Formats If data loads as null, verify:

  • The file exists at the expected path.
  • The file format matches the extension (e.g., .json for JSON).

Extension Points

1. Custom Formats Add support for new formats (e.g., CSV) by extending Siler\Drivers\FileDriver:

   class CsvDriver extends FileDriver {
       protected function encode($data) {
           return $this->arrayToCsv($data);
       }
   }
   

2. Pre/Post-Store Hooks Use Laravel’s register method in the service provider to add logic:

   Siler::extend('csv', function () {
       return new CsvDriver();
   });
   

3. Fallback Drivers Define a fallback driver in config/siler.php for missing files:

   'drivers' => [
       'default' => 'file',
       'fallback' => 'cache', // Uses Cache::get() if file doesn’t exist
   ],
   

Performance Considerations

• Batch Operations For bulk writes, use Siler::batch() to reduce I/O:

  Siler::batch([
      'users' => $userData,
      'settings' => $configData,
  ]);
  

• Avoid Over-Fetching Load only necessary keys if using arrays:

  $user = Siler::load('users.john'); // Loads only 'john' from users.json