Runtime Laravel Package

Getting Started

Minimal Steps

1. Verify Necessity:

   • Confirm if jane/runtime is absolutely required for your Laravel app. Given its deprecated status, audit dependencies to identify alternatives (e.g., Symfony components, Laravel’s built-in tools).
   • Run:

     composer why jane/runtime
     

     to trace usage in your project.

2. Isolation Setup:

   • If unavoidable, isolate the package in a separate namespace or Service Provider to minimize conflicts:

     // config/app.php
     'providers' => [
         App\Providers\JaneRuntimeProvider::class,
     ],
     

     // app/Providers/JaneRuntimeProvider.php
     namespace App\Providers;
     use Illuminate\Support\ServiceProvider;
     use Jane\Runtime\Runtime;
     
     class JaneRuntimeProvider extends ServiceProvider
     {
         public function register()
         {
             $this->app->singleton('jane.runtime', function () {
                 return new Runtime();
             });
         }
     }
     

3. First Use Case:

   • Dynamic YAML Execution (if applicable):

     use Illuminate\Support\Facades\App;
     
     $runtime = App::make('jane.runtime');
     $result = $runtime->execute(storage_path('workflows/test.yaml'));
     

   • JSONPointer/URI Handling (if needed):

     $pointer = new \Jane\Runtime\JsonPointer('/path/to/field');
     $data = $pointer->get($jsonArray);
     

4. Key Files to Inspect:

   • vendor/jane/runtime/src/Runtime.php – Core execution logic.
   • vendor/jane/runtime/src/Context.php – State management.
   • vendor/jane/runtime/src/JsonPointer.php – Niche JSON traversal (if used).

Implementation Patterns

Workflows in Laravel

1. Service Provider Integration:

   • Bind the runtime to Laravel’s container only if critical:

     // app/Providers/JaneRuntimeProvider.php
     public function boot()
     {
         $this->app->afterResolving('jane.runtime', function ($runtime) {
             // Post-registration logic (e.g., default context)
             $runtime->setContext(new \Jane\Runtime\Context());
         });
     }
     

2. YAML Workflow Execution:

   • Store workflows in storage/workflows/ and load dynamically:

     public function runWorkflow(string $name, array $params = [])
     {
         $path = storage_path("workflows/{$name}.yaml");
         if (!file_exists($path)) {
             throw new \RuntimeException("Workflow {$name} not found.");
         }
         return app('jane.runtime')->execute($path, $params);
     }
     

   • Validate YAML with Laravel’s Illuminate\Support\Facades\Validator before execution.

3. Context Sharing:

   • Attach Laravel-specific data (e.g., user auth) to the runtime context:

     $context = app('jane.runtime')->getContext();
     $context->set('user', auth()->user());
     

4. Action Extensibility:

   • Register custom actions without modifying Jane’s core:

     $runtime = app('jane.runtime');
     $runtime->registerAction('laravel_action', function ($args) {
         return Model::where($args['key'], $args['value'])->get();
     });
     

Integration Tips

• Avoid Global Runtime Hooks:
  • JanePHP’s spl_autoload_register or runtime hooks may conflict with Laravel’s autoloader. Use Laravel’s service container instead.
• Queue Heavy Workflows:
  • Offload long-running workflows to Laravel Queues:

    dispatch(new ExecuteWorkflowJob($workflowName, $params));
    

• Fallback to Laravel Alternatives:
  • Replace Jane-specific features with Laravel’s tools:

    Jane Feature	Laravel Alternative
    YAML Parsing	Symfony\Component\Yaml\Yaml::parse()
    URI Handling	Illuminate\Support\Str::of() or league/uri
    JSONPointer	Custom implementation or php-json-pointer

Gotchas and Tips

Pitfalls

1. Dependency Conflicts:

   • Symfony 3.x vs. Laravel’s Symfony 6.x:
     • Error: Class 'Symfony\Component\Yaml\Yaml' not found.
     • Fix: Isolate Jane’s dependencies in a separate Composer platform config:

       // composer.json
       "config": {
           "platform-check": false,
           "preferred-install": {
               "symfony/yaml": "3.1.*"
           }
       }
       

     • Better: Replace with symfony/yaml:^6.0.

2. PHP 8.x Incompatibility:

   • Deprecated Features: JanePHP uses create_function(), array_walk with by-reference, etc.
   • Fix: Use a PHP 7.4 compatibility layer or rewrite affected code:

     // Before (PHP 7.4+)
     $callback = fn($item) => $item * 2;
     array_walk($items, $callback);
     

3. State Management Issues:

   • Jane’s Context class may not play well with Laravel’s dependency injection.
   • Tip: Use Laravel’s request scope or session for shared state:

     $context = app('jane.runtime')->getContext();
     $context->set('request_id', request()->id);
     

4. No Laravel Facades:

   • JanePHP lacks Laravel’s Facade pattern. Workaround:

     // Create a facade manually
     use Illuminate\Support\Facades\Facade;
     class JaneRuntime extends Facade { protected static function getFacadeAccessor() { return 'jane.runtime'; } }
     

5. Testing Challenges:

   • Jane’s test suite is PHPUnit 4/5.x-based. Use Laravel’s phpunit.xml to override:

     <php>
         <env name="PHPUNIT_VERSION" value="9.5"/>
     </php>
     

Debugging Tips

1. Enable Jane’s Debug Mode:

   $runtime = app('jane.runtime');
   $runtime->setDebug(true); // Logs workflow execution
   

2. Log Workflow Steps:

   • Extend Jane\Runtime\Context to log actions:

     $context = app('jane.runtime')->getContext();
     $context->setLogger(app('log'));
     

3. Isolate for Testing:

   • Use Laravel’s FreshTestCase to reset the container before tests:

     public function setUp(): void
     {
         parent::setUp();
         $this->artisan('config:clear');
     }
     

Extension Points

1. Custom Workflow Steps:

   • Override Jane\Runtime\Workflow to add Laravel-specific steps:

     class LaravelWorkflow extends \Jane\Runtime\Workflow
     {
         public function addLaravelStep(string $name, callable $callback)
         {
             $this->steps[$name] = $callback;
         }
     }
     

2. Replace Serialization:

   • Jane uses Symfony’s Serializer. Replace with Laravel’s json_encode() or spatie/laravel-serializable-models:

     $runtime = app('jane.runtime');
     $runtime->setSerializer(function ($data) {
         return json_encode($data, JSON_PRETTY_PRINT);
     });
     

3. URI Handling:

   • Swap Jane’s League\Uri with Laravel’s Illuminate\Support\Str:

     $runtime = app('jane.runtime');
     $runtime->setUriParser(function ($uri) {
         return Str::of($uri)->toArray();
     });
     

Configuration Quirks

1. No Laravel Config Support:

   • Jane’s runtime expects hardcoded paths (e.g., ./workflows/). Override with:

     $runtime = app('jane.runtime');
     $runtime->setWorkflowDir(storage_path('app/workflows'));
     

2. Autoloading Issues:

   • Jane’s classes may not autoload in Laravel. Ensure composer dump-autoload is run after installation.

3. Environment-Specific Behavior:

   • JanePHP assumes a CLI environment. For Laravel’s HTTP context, mock $_SERVER:

     putenv('HTTP_HOST=localhost');
     

Migration Checklist

1. Audit Usage:
   • Search for Jane\Runtime in your codebase:

     grep -r "Jane\\Runtime" .
     

2. Replace Core Features:
   • YAML: symfony/yaml:^6.0
   • URI: league/uri:^6.0 or Illuminate\Support\Str
   • JSONPointer: Custom implementation or php-json-pointer
3. **Test Incrementally