Psysh Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexmasterov/psysh-bundle
   

2. Enable the Bundle: Add to config/bundles.php:

   AlexMasterov\PsyshBundle\PsyshBundle::class => ['dev' => true],
   

3. First Use: Run the PsySH shell directly:

   php bin/console psysh:shell
   

   This launches an interactive REPL with Symfony’s container pre-loaded.

First Use Case

• Debugging Controllers/Commands: Inject a controller/service into the REPL to inspect its state:

  php bin/console psysh:shell --var=@some_controller
  

  Or configure via config/packages/psysh.yaml:

  psysh:
    variables:
      - @some_controller
  

Implementation Patterns

Common Workflows

1. Pre-Loading Variables:

   • Services: Tag services in services.yaml for auto-injection:

     services:
       App\Service\MailService:
         tags: ['psysh.variable']
     

   • Custom Variables: Define in config/packages/psysh.yaml:

     psysh:
       variables:
         - { user: App\Entity\User::find(1) }
         - { db: '@doctrine.dbal.connection' }
     

2. Integration with Artisan Commands: Use PsySH to debug commands interactively:

   php bin/console psysh:shell --var=@app.command.mailer
   

   Then inspect $mailer->getOptions() or modify state dynamically.

3. Event Listeners/Debugging: Attach to kernel events (e.g., kernel.request) and inspect request/response:

   // In REPL:
   >>> $event = new GetResponseForControllerResultEvent($controller, $request, $response);
   >>> $listener->onKernelRequest($event, $request->get('some_key'));
   

4. Testing Edge Cases: Simulate user input or exceptions in REPL:

   >>> $user = new User(); $user->setRole('admin');
   >>> $controller->handle($request)->getStatusCode(); // Test logic
   

Advanced Patterns

• Custom PsySH Configuration: Extend the bundle’s PsyshServiceProvider to add:

  • Custom aliases (e.g., ls → dump()).
  • Auto-completion for your entities/services.
  • Example:

    // src/Psysh/PsyshServiceProvider.php
    public function register()
    {
        $this->app['psysh']->addConfig([
            'variables' => ['@router' => $this->app->get('router')],
            'aliases' => ['routes' => 'dump($this->app->get(\'router\')->getRouteCollection())'],
        ]);
    }
    

• Environment-Specific Variables: Use %kernel.environment% in psysh.yaml:

  psysh:
    variables:
      - { debug: '%kernel.debug%' }
      - { env: '%env(APP_ENV)%' }
  

Gotchas and Tips

Pitfalls

1. Container Not Available in All Contexts:

   • PsySH relies on Symfony’s container. If you run psysh:shell outside bin/console, the container may not be initialized.
   • Fix: Always use php bin/console psysh:shell.

2. Variable Naming Conflicts:

   • Avoid naming variables the same as PsySH’s built-ins (e.g., ls, exit).
   • Tip: Prefix custom variables (e.g., user_1 instead of user).

3. Performance in Large Apps:

   • Pre-loading all services can slow down REPL startup.
   • Tip: Use lazy-loading or limit variables:

     psysh:
       variables:
         - @service.a  # Only load specific services
     

4. Debugging in CI/CD:

   • PsySH is disabled in prod by default (dev: true in bundles.php).
   • Tip: Use --env=dev to force-enable:

     php bin/console --env=dev psysh:shell
     

Debugging Tips

• Inspect Container Services: List all available services in REPL:

  >>> $container->getServiceIds();
  >>> $container->has('service.name') ? 'Exists' : 'Missing';
  

• Clear PsySH Cache: If variables aren’t loading, clear the cache:

  php bin/console cache:clear
  

• Enable Verbose Output: Debug PsySH initialization:

  php bin/console debug:config psysh
  

Extension Points

1. Custom Commands: Create a command to pre-load PsySH with specific variables:

   // src/Command/DebugUserCommand.php
   namespace App\Command;
   
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class DebugUserCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $this->getApplication()->find('psysh:shell')->run([
               '--var' => ['@user_repository', '@mailer'],
           ]);
       }
   }
   

2. Override PsySH Configuration: Use a compiler pass to modify PsySH’s config dynamically:

   // src/DependencyInjection/Compiler/PsyshPass.php
   public function process(ContainerBuilder $container)
   {
       $definition = $container->findDefinition('psysh');
       $definition->addMethodCall('addConfig', [
           ['variables' => ['@custom_service']],
       ]);
   }
   

3. Integrate with Xdebug: Use PsySH to inspect Xdebug sessions:

   >>> xdebug_break(); // Trigger Xdebug
   >>> $this->app->get('debug.stopwatch')->get('event_name')->getDuration();