Yamlok Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dubiy/yamlok
   

   Add the service provider to config/app.php under providers:

   Dubiy\Yamlok\YamlokServiceProvider::class,
   

2. Publish Config (if needed):

   php artisan vendor:publish --provider="Dubiy\Yamlok\YamlokServiceProvider"
   

   This creates config/yamlok.php. Update the file key to point to your YAML file (e.g., app/config/settings.yml).

3. First Use Case: Load and dump a YAML file:

   use Dubiy\Yamlok\Facades\Yamlok;
   
   $data = Yamlok::read(); // Loads YAML as associative array
   Yamlok::write($data);  // Overwrites YAML file with array
   

Implementation Patterns

Core Workflows

1. Reading YAML:

   // Load YAML into an array
   $config = Yamlok::read('path/to/custom.yml'); // Optional: Override config path
   
   // Merge with existing config (if using facade)
   $merged = array_merge(Yamlok::getConfig(), $customData);
   

2. Writing YAML:

   // Update and save
   $updatedData = Yamlok::getConfig(); // Get current config
   $updatedData['new_key'] = 'value';
   Yamlok::write($updatedData);
   
   // Write to a custom file
   Yamlok::write($data, 'path/to/output.yml');
   

3. Dynamic Configuration: Use the facade in controllers/services to fetch/update settings:

   // In a service
   public function __construct() {
       $this->settings = Yamlok::getConfig();
   }
   

4. Environment-Specific Files: Override the config path dynamically:

   $env = env('APP_ENV');
   $file = "config/settings.{$env}.yml";
   $data = Yamlok::read($file);
   

Integration Tips

• Cache Bypass: Disable caching for real-time updates (see Gotchas).
• Validation: Validate YAML structure before writing:

  if (!is_array($data)) {
      throw new \InvalidArgumentException('Data must be an array.');
  }
  

• Events: Extend with events for pre/post-read/write hooks (e.g., logging, encryption):

  Yamlok::extend(function ($yamlok) {
      $yamlok->onRead(function ($data) {
          // Pre-process data
      });
  });
  

Gotchas and Tips

Pitfalls

1. Caching:

   • By default, Yamlok caches parsed YAML for performance. To disable caching (e.g., for live updates):

     Yamlok::setCache(false);
     

   • Clear cache manually (if enabled):

     php artisan yamlok:clear-cache
     

     (Note: This command is not documented in the README but inferred from the TODO list.)

2. File Permissions:

   • Ensure the target YAML file is writable by the web server user:

     chmod 664 app/config/settings.yml
     

3. YAML Syntax Errors:

   • Invalid YAML will throw exceptions. Use a validator like Symfony/Yaml for pre-checks:

     use Symfony\Component\Yaml\Yaml as SymfonyYaml;
     try {
         SymfonyYaml::parseFile($file);
     } catch (\Exception $e) {
         // Handle error
     }
     

4. Global Config Overrides:

   • The dubiy_yamlok.file config is not documented as dynamic. To change it at runtime:

     Yamlok::setConfigPath('new/path.yml');
     

Debugging Tips

• Log Parsed Data:

  Yamlok::extend(function ($yamlok) {
      $yamlok->onRead(function ($data) {
          \Log::debug('YAML loaded:', ['data' => $data]);
      });
  });
  

• Check for Typos:
  • The facade method is Yamlok::read() (not Yamlok::load() or similar).

Extension Points

1. Custom Parsers: Override the default parser (Symfony Yaml) by binding a new parser to the container:

   $this->app->bind('yaml.parser', function () {
       return new \Custom\Yaml\Parser();
   });
   

2. Pre/Post Hooks: Use the extend() method to add logic before/after operations:

   Yamlok::extend(function ($yamlok) {
       $yamlok->onWrite(function ($data, $file) {
           // Encrypt sensitive data
           $data['secret'] = encrypt($data['secret']);
       });
   });
   

3. TODO: Cache Removal:

   • The README mentions "remove cache" as a TODO. Implement a cache invalidation system:

     // Example: Add a cache timestamp to the config
     $cacheFile = storage_path('yamlok_cache.json');
     if (file_exists($cacheFile) && filemtime($cacheFile) > now()->subHours(1)->timestamp) {
         // Use cached data
     } else {
         // Re-parse YAML
     }