Symfony Orion Engine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in your Laravel project (note: this is a Symfony bundle, so you'll need a bridge or wrapper like symfony/bridge or use it in a Symfony-based Laravel app like Laravel Octane with Symfony components):

   composer require cortezvini97/symfony-orion-engine-bundle
   

2. Configuration Register the bundle in your Symfony kernel (if using Octane/Symfony) or create a Laravel service provider to wrap its functionality. Example for Laravel:

   // config/app.php (providers)
   App\Providers\OrionEngineServiceProvider::class,
   
   // app/Providers/OrionEngineServiceProvider.php
   public function register()
   {
       $this->app->singleton('orion.engine', function ($app) {
           return new \OrionEngine\Engine(); // Adjust namespace if needed
       });
   }
   

3. First Use Case Use the Orion Engine to parse and evaluate templates (e.g., for dynamic content generation):

   use OrionEngine\Engine;
   
   $engine = app('orion.engine');
   $template = "{{ user.name }} is {{ user.age }} years old.";
   $data = ['user' => ['name' => 'John', 'age' => 30]];
   $output = $engine->render($template, $data);
   // Output: "John is 30 years old."
   

Key Files to Explore

• src/Engine.php: Core logic for template rendering.
• src/Compiler.php: Handles template compilation (if applicable).
• README.md: Check for Symfony-specific setup instructions.

Implementation Patterns

Common Workflows

1. Dynamic Template Rendering Use Orion Engine for server-side templating in APIs or CLI tools:

   $emailTemplate = "{{ greeting }}, {{ user.name }}!";
   $rendered = $engine->render($emailTemplate, [
       'greeting' => 'Hello',
       'user' => ['name' => 'Alice']
   ]);
   

2. Integration with Laravel Views Extend Laravel’s Blade engine by adding Orion as a fallback or hybrid parser:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       View::composer('*', function ($view) {
           $view->with('orion', app('orion.engine'));
       });
   }
   

   Then in Blade:

   {{ $orion->render($dynamicTemplate, $data) }}
   

3. CLI Command Processing Parse user input or config files dynamically:

   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class ParseCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $template = $input->getArgument('template');
           $data = json_decode($input->getArgument('data'), true);
           $output->writeln(app('orion.engine')->render($template, $data));
       }
   }
   

Integration Tips

• Caching Compiled Templates Wrap the engine in a cache layer to avoid recompiling templates:

  $cacheKey = md5($template);
  $rendered = Cache::remember($cacheKey, now()->addHours(1), function () use ($template, $data) {
      return $engine->render($template, $data);
  });
  

• Error Handling Use try-catch to handle template syntax errors gracefully:

  try {
      $output = $engine->render($template, $data);
  } catch (\OrionEngine\Exception\ParseError $e) {
      Log::error("Template error: " . $e->getMessage());
      return response()->json(['error' => 'Invalid template'], 400);
  }
  

• Security Sanitize user-provided templates to prevent injection:

  $safeTemplate = preg_replace('/[^a-zA-Z0-9\s\.\{\}\[\]\-\_\+\/\:\,\@]/', '', $userInput);
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency

   • The bundle is Symfony-first. If your Laravel app isn’t Symfony-aware (e.g., no Octane or Symfony components), you’ll need to:
     • Manually port dependencies (e.g., symfony/console for CLI features).
     • Use a wrapper like spatie/laravel-symfony-support (if available).
   • Workaround: Fork the package and remove Symfony-specific code, or use it only for template logic.

2. Template Syntax Quirks

   • Orion may use double curly braces ({{ }}) for variables, which could conflict with Laravel Blade’s {{ }} syntax. Escape or alias the engine:

     $engine->render('{{{ user.name }}}', $data); // Triple braces to escape Blade
     

   • Tip: Use a unique delimiter (e.g., [[ ]]) by extending the Compiler class.

3. Performance Overhead

   • Orion’s template compilation (if enabled) adds runtime overhead. Disable it for static templates:

     $engine = new \OrionEngine\Engine(['compilation' => false]);
     

4. Namespace Collisions

   • The bundle may pull in Symfony namespaces (e.g., Symfony\Component\Yaml\Yaml). If your project uses these, conflicts may arise.
   • Fix: Use fully qualified namespaces or alias them in Composer’s autoload.psr-4.

5. Limited Laravel Ecosystem

   • No native support for Laravel’s service container, Blade, or Eloquent. You’ll need to bridge functionality manually (e.g., pass Eloquent models to the engine as arrays).

Debugging Tips

• Enable Verbose Errors Configure the engine to throw detailed exceptions:

  $engine = new \OrionEngine\Engine(['debug' => true]);
  

• Log Compiled Templates Override the Compiler class to log generated code:

  class CustomCompiler extends \OrionEngine\Compiler
  {
      public function compile($template)
      {
          $compiled = parent::compile($template);
          Log::debug("Compiled template: " . $compiled);
          return $compiled;
      }
  }
  

• Test Edge Cases Validate templates with:

  • Empty data arrays.
  • Nested objects/arrays.
  • Malformed syntax (e.g., unclosed braces).

Extension Points

1. Custom Functions Extend Orion’s functionality by adding custom filters/functions:

   $engine->addFunction('uppercase', function ($str) {
       return strtoupper($str);
   });
   

   Usage in template:

   {{ uppercase(user.name) }}
   

2. Template Inheritance Implement layout templates by preprocessing the engine:

   $layout = "{{ yield('content') }}";
   $content = "{{ user.name }}"; // Dynamic content
   $engine->render($layout, ['content' => $content]);
   

3. Integration with Laravel Events Trigger template rendering on events (e.g., illuminate.mail.events.MessageSending):

   event(new MessageSending($message));
   // In listener:
   $message->setBody(app('orion.engine')->render($template, $data));
   

4. Middleware for API Responses Use Orion to dynamically generate API responses:

   Route::get('/dynamic', function () {
       return response()->json([
           'data' => app('orion.engine')->render($apiTemplate, $data)
       ]);
   });