Neon Laravel Package

Getting Started

Install via Composer:

composer require nette/neon

First use case: Load a NEON config file in Laravel’s config() helper.

use Nette\Neon\Neon;

// Load NEON file into PHP array
$config = Neon::decodeFile(app_path('config/custom.neon'));

// Merge with Laravel’s config (e.g., in a service provider)
config(['custom' => $config]);

Where to look first:

• Neon Class Docs (core methods: decode(), encode(), decodeFile()).
• AST Traverser for advanced parsing (e.g., validation).
• Release Notes for PHP version compatibility (v3.4.x requires PHP 8.2+).

Implementation Patterns

1. Configuration Loading

Workflow: Replace Laravel’s YAML/JSON configs with NEON for Nette-compatible projects.

// config/app.php
return [
    'custom' => Neon::decodeFile(__DIR__ . '/custom.neon'),
];

Tip: Use Neon::decodeFile() in a custom config loader (e.g., NeonConfigLoader) to integrate with Laravel’s config() helper.

2. Dynamic NEON Generation

Use case: Generate NEON configs dynamically (e.g., for feature flags).

$flags = [
    'experimental' => true,
    'beta' => ['users' => ['admin', 'dev']],
];

$neon = Neon::encode($flags, 4); // Indent with 4 spaces
file_put_contents(storage_path('app/flags.neon'), $neon);

3. AST-Based Validation

Use case: Validate NEON syntax or enforce schema rules.

use Nette\Neon\Ast\Traverser;

$ast = Neon::decode($neonString, Neon::STRICT);
$traverser = new Traverser();
$traverser->onEnterNode(function ($node) {
    if ($node instanceof \Nette\Neon\Ast\ScalarNode && $node->value === 'debug') {
        throw new \RuntimeException("'debug' is reserved!");
    }
});
$traverser->traverse($ast);

4. Hybrid Configs (NEON + Laravel)

Pattern: Merge NEON configs with Laravel’s native arrays.

$neonConfig = Neon::decodeFile(config_path('neon_config.neon'));
config(['neon' => array_merge(
    config('neon.defaults', []),
    $neonConfig
)]);

5. CLI Tools

Use case: Parse NEON in Artisan commands.

// In a custom Artisan command
$neonData = Neon::decodeFile($this->argument('neon_file'));
$this->info('Loaded NEON: ' . Neon::encode($neonData));

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • v3.4.x requires PHP 8.2–8.5. Use composer require nette/neon:^3.3 for PHP 7.4+.
   • Fix: Check composer.json constraints or use composer why-not nette/neon:^3.3.

2. UTF-8 Strictness:

   • NEON throws exceptions on invalid UTF-8 (unlike Laravel’s YAML).
   • Fix: Validate files with mb_detect_encoding() or use Neon::decode($content, Neon::FORGIVING).

3. BC Breaks in v3.x:

   • Neon::decode() no longer strips BOM (v3.3.1).
   • DateTimeImmutable is used instead of DateTime (v2.4.0).
   • Fix: Update tests and configs if migrating from v2.x.

4. Large Integers:

   • Integers beyond PHP_INT_MAX are decoded as strings (v3.4.3).
   • Fix: Cast explicitly: (int) $neonData['big_number'].

5. Special Values:

   • INF, NAN, and null in keys throw exceptions (v3.4.1).
   • Fix: Use Neon::encode($value, Neon::FORGIVING) to skip problematic values.

6. AST Traversal Quirks:

   • Traverser::traverse() modifies the AST in-place.
   • Fix: Clone the AST with Neon::decode($neon, Neon::STRICT) if immutability is needed.

Debugging Tips

• Validate NEON Syntax:

  try {
      $data = Neon::decode($neonString, Neon::STRICT);
  } catch (\Nette\Neon\Exception $e) {
      report($e); // Log via Laravel’s error handler
      throw new \RuntimeException("Invalid NEON: " . $e->getMessage());
  }
  

• Pretty-Print NEON:

  $neon = Neon::encode($data, 4); // 4-space indent
  file_put_contents('debug.neon', $neon);
  

• Check File Encoding:

  $content = file_get_contents('config.neon');
  if (!mb_check_encoding($content, 'UTF-8')) {
      throw new \RuntimeException("NEON file must be UTF-8 encoded!");
  }
  

Extension Points

1. Custom Encoder/Decoder: Override Neon\Encoder or Neon\Decoder for domain-specific types (e.g., UUIDs).

   class CustomEncoder extends \Nette\Neon\Encoder {
       public function encode($value) {
           if ($value instanceof \Ramsey\Uuid\Uuid) {
               return $value->toString();
           }
           return parent::encode($value);
       }
   }
   

2. Neon Linter: Use the built-in neon-lint CLI tool or integrate it into Laravel’s testing:

   composer require --dev nette/neon
   ./vendor/bin/neon-lint config.neon
   

3. Neon Config Caching: Cache decoded NEON configs in Laravel’s cache:

   $cacheKey = 'neon:config';
   $config = cache()->remember($cacheKey, now()->addHours(1), function () {
       return Neon::decodeFile(config_path('custom.neon'));
   });
   

4. IDE Support: Enable PHPStan or Psalm with the updated phpDoc (v3.4.8+):

   # phpstan.neon
   includes:
       - vendor/nette/neon/src
   

Performance Notes

• decodeFile() is atomic (v3.3.4) but slower than file_get_contents() + decode().
• AST Traversal is memory-intensive for large files. Use Traverser::DontTraverseChildren to optimize.
• Encoding: Prefer Neon::encode($data, 0) for compact output (no indentation).