Neon Laravel Package

Technical Evaluation

Architecture fit: Poor alignment with Laravel’s native config stack (PHP arrays, YAML, JSON). NEON’s human-readable syntax and Nette-specific features (e.g., AST parsing, DateTimeImmutable generation) introduce unnecessary complexity for Laravel’s ecosystem. The package’s standalone nature and lack of Laravel integration hooks (e.g., config() helper, config:cache) make it a non-native dependency. While v3.4.x’s phpDoc improvements enhance IDE support, they do not resolve the core architectural mismatch.

Integration feasibility: Technically possible but high-effort due to:

1. No Laravel-native integration: Requires custom config loaders (e.g., wrapping Neon::decodeFile() in a service provider) to bridge NEON and Laravel’s config() system.
2. Format incompatibility: NEON’s strict UTF-8 enforcement and syntax (e.g., 0o777, """ multiline strings) clash with Laravel’s permissive YAML/JSON handling.
3. Backward compatibility risks: Laravel’s config:cache may fail if NEON configs are dynamically modified post-caching (e.g., Neon::decodeFile()’s atomicity is irrelevant here).

Technical risk:

• License ambiguity: NOASSERTION license (despite GitHub’s MIT claim) could pose legal risks for enterprise use.
• PHP version constraints: v3.4.x requires PHP 8.2–8.5, which may exclude legacy Laravel projects (e.g., LTS 8.0/8.1).
• Breaking changes in minor versions: v3.4.0+ introduced BC breaks (e.g., removed on/off syntax, DateTimeImmutable generation), despite being marked as non-breaking in v3.4.8.
• Static analysis friction: Stricter phpDoc types (v3.4.8) may conflict with older Laravel projects using loose type hints.

Key questions:

1. Why NEON? Does the team have a specific use case (e.g., legacy Nette migration, external NEON-based APIs) that justifies deviating from Laravel’s native YAML/JSON?
2. Migration path: Are existing configs in NEON, or is this a proactive format shift? If the latter, what’s the ROI vs. maintaining YAML/JSON?
3. Tooling compatibility: Will the team’s static analysis (e.g., Psalm, PHPStan) handle the stricter phpDoc types in v3.4.8 without false positives?
4. Performance impact: NEON’s AST parsing adds overhead vs. Laravel’s native file_get_contents() + yaml_parse(). Is this acceptable for the use case?
5. Long-term maintenance: Who will handle NEON-specific issues (e.g., Neon::encode() edge cases) if the Nette team deprioritizes Laravel support?

Integration Approach

Stack fit: Mismatched. Laravel’s config system is optimized for:

• YAML/JSON: Native support via Illuminate/Config and config:cache.
• PHP arrays: Direct config('key') access with no parsing overhead.
• Environment variables: .env integration via Illuminate/Foundation.

NEON’s Nette-centric features (e.g., DateTimeImmutable decoding, entity chaining) are irrelevant to Laravel’s use cases. The v3.4.x phpDoc improvements do not address this gap.

Migration path: Not viable for Laravel core configs. Options:

1. Isolated use case: Restrict NEON to non-critical configs (e.g., third-party plugins, microservices) via a custom NeonConfigLoader service.
   • Example:

     // app/Providers/NeonConfigServiceProvider.php
     public function register()
     {
         $this->app->bind('neon', function () {
             return new NeonConfigLoader(base_path('config/neon'));
         });
     }
     

   • Limitation: Still requires manual file mapping (e.g., neon:config → Laravel’s config()).
2. Hybrid approach: Use NEON for external data (e.g., API responses, user-uploaded configs) via Neon::decode()/Neon::encode(), but never for Laravel’s core configs.
3. Abandon NEON: Prefer Laravel’s native formats or Symfony’s YAML component for YAML needs.

Compatibility:

• PHP 8.2+: Required for v3.4.x. Laravel 9+ supports this, but older projects (e.g., LTS 8.0) would need upgrades.
• UTF-8 enforcement: NEON throws exceptions on invalid UTF-8 (v3.2.0+), which may break Laravel’s lenient handling of config files.
• Caching conflicts: config:cache may fail if NEON configs are modified post-cache (e.g., during runtime). Workaround: Exclude NEON files from caching or use Neon::decodeFile() dynamically.
• Static analysis: Stricter phpDoc types (v3.4.8) may cause issues with tools like PHPStan if not configured properly.

Sequencing:

1. Assess necessity: Confirm NEON is not a solution in search of a problem (Laravel’s YAML/JSON suffice for 99% of use cases).
2. Isolate scope: If adopted, restrict to non-critical configs (e.g., plugin settings) via a dedicated service.
3. Test thoroughly: Validate config:cache compatibility, UTF-8 handling, and static analysis tooling.
4. Document limitations: Clearly mark NEON configs as non-cached and non-standard in the codebase.

Operational Impact

Maintenance:

• High overhead: No Laravel-specific support means troubleshooting falls to the team. Example issues:
  • Neon::decodeFile() failing silently on invalid UTF-8.
  • config:cache ignoring NEON files or throwing errors.
  • Static analysis tools flagging phpDoc types as incorrect.
• Dependency bloat: Adding NEON for a single use case introduces no Laravel benefits (e.g., no DI integration, no config() helper support).
• Version pinning: Requires manual updates to track Nette’s NEON releases (e.g., v3.4.8 → v3.4.9), with no Laravel-specific changelogs.

Support:

• Limited ecosystem: No Laravel packages extend NEON (e.g., no laravel-neon wrappers). Support is Nette-focused, leaving Laravel teams to debug integration issues alone.
• Community knowledge: Most Laravel devs are unfamiliar with NEON’s syntax (e.g., 0o777, """ strings), increasing onboarding time.
• Error messages: NEON’s exceptions (e.g., INF/NAN encoding throws) may confuse Laravel teams expecting Symfony-style errors.

Scaling:

• Performance: NEON’s AST parsing is slower than Laravel’s native YAML/JSON parsing for large configs. Benchmark before adoption.
• Concurrency: Neon::decodeFile()’s atomicity is irrelevant in Laravel’s file-caching model. Risk: Race conditions if multiple processes read/write NEON configs simultaneously.
• Multi-environment: NEON configs must be manually synced across environments (e.g., .neon files in config/), unlike Laravel’s .env system.

Failure modes:

1. Silent corruption: Invalid UTF-8 or control characters (e.g., INF) may be silently replaced (v3.4.7’s U+FFFD fallback), leading to runtime bugs.
2. Caching conflicts: config:cache may ignore NEON files or fail if they’re modified post-cache. Workaround: Exclude NEON files from caching or use dynamic loading.
3. Static analysis breaks: Stricter phpDoc types (v3.4.8) may cause false positives in tools like Psalm if not configured.
4. Backward compatibility: Minor version bumps (e.g., v3.4.8 → v3.4.9) could introduce unannounced API changes, despite being marked as non-breaking.

Ramp-up:

• Developer onboarding: Teams must learn NEON’s syntax (e.g., 0b11001, """ strings) and tooling (e.g., neon-lint).
• Tooling setup: Configure static analysis tools (e.g., PHPStan) to handle NEON’s phpDoc types without false positives.
• CI/CD adjustments: Add NEON-specific linting/validation steps (e.g., neon-lint) to catch syntax errors early.
• Documentation gap: No Laravel-specific guides exist for NEON integration. Teams must reverse-engineer solutions (e.g., custom config loaders).