Yii Ray Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require spatie/yii-ray
   

   Ensure spatie/ray is installed in your project (required for Ray functionality).

2. Configure Ray Add the following to your Yii2 config/web.php or config/console.php:

   'components' => [
       'ray' => [
           'enabled' => true,
           'auth' => [
               'id' => 'your-ray-app-id',
               'secret' => 'your-ray-app-secret',
           ],
       ],
   ],
   

   Retrieve your id and secret from myray.app.

3. First Use Case Trigger a debug dump in a controller or service:

   use Spatie\Ray\Ray;
   
   public function actionIndex()
   {
       $data = ['user' => User::find(1), 'posts' => Post::all()];
       Ray::dump($data); // Sends to Ray
       return $this->render('index');
   }
   

   Launch Ray on your desktop to view the output.

Implementation Patterns

Core Workflows

1. Debugging Data Replace var_dump() or Yii::debug() with Ray’s fluent methods:

   Ray::info('User loaded', ['id' => $user->id]); // Logs with metadata
   Ray::dump($queryResult); // Inspects complex objects
   

2. Performance Profiling Measure execution time in critical paths:

   Ray::startTiming('database_query');
   $users = User::all();
   $time = Ray::stopTiming('database_query');
   Ray::info("Query took {$time}ms");
   

3. Error Handling Catch exceptions and log them to Ray:

   try {
       // Risky operation
   } catch (\Exception $e) {
       Ray::exception($e, ['context' => 'user_profile']);
   }
   

4. Integration with Yii Components Hook into Yii events (e.g., yii\base\Application::EVENT_BEFORE_ACTION) to log requests:

   Yii::$app->on(Application::EVENT_BEFORE_ACTION, function () {
       Ray::info('Request started', [
           'uri' => Yii::$app->request->url,
           'method' => Yii::$app->request->method,
       ]);
   });
   

5. Conditional Debugging Disable Ray in production by toggling enabled in config or using:

   if (Yii::$app->get('ray')->isEnabled()) {
       Ray::dump($data);
   }
   

Gotchas and Tips

Pitfalls

1. Authentication Errors

   • Issue: Ray fails silently if id/secret are invalid.
   • Fix: Verify credentials in myray.app and check for typos in config/web.php.

2. Performance Overhead

   • Issue: Excessive Ray::dump() calls may slow down requests.
   • Fix: Use conditionally (e.g., only in dev environment) or batch logs.

3. Yii Caching Conflicts

   • Issue: Cached views may not reflect Ray logs if the app restarts.
   • Fix: Clear cache (php yii cache/flush) or use Ray::flush() to reset the session.

4. HTML/Markdown Rendering

   • Issue: Complex HTML or Markdown may not display correctly.
   • Fix: Use Ray::image() for screenshots or simplify content for readability.

Debugging Tips

• Ray Server Status: Check if the MCP server is running (http://localhost:8000 by default).
• Network Issues: Ensure your machine can reach mcp.myray.app (whitelist if behind a proxy).
• Environment Variables: Store RAY_ID/RAY_SECRET in .env for security:

  RAY_ID=your-app-id
  RAY_SECRET=your-app-secret
  

  Then reference them in config:

  'auth' => [
      'id' => getenv('RAY_ID'),
      'secret' => getenv('RAY_SECRET'),
  ],
  

Extension Points

1. Custom Log Channels Extend Ray to log to Yii’s yii\log\Logger:

   Yii::$app->log->targets['ray'] = [
       'class' => \Spatie\Ray\Yii\LogTarget::class,
   ];
   

2. Middleware Integration Create a middleware to log requests/responses:

   public function handle($request, \Closure $next)
   {
       Ray::info('Incoming request', ['uri' => $request->url]);
       $response = $next($request);
       Ray::info('Response status', ['status' => $response->statusCode]);
       return $response;
   }
   

3. Ray in Tests Use Ray in PHPUnit tests for debugging:

   public function testUserCreation()
   {
       $user = User::create(['name' => 'Test']);
       Ray::dump($user); // Debug test data
       $this->assertTrue($user->save());
   }
   

4. Theming Customize Ray’s UI by passing themes:

   Ray::setTheme('dark'); // or 'light', 'custom'