Psysh Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require alexmasterov/psysh-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       AlexMasterov\PsyshBundle\PsyshBundle::class => ['dev' => true],
   ];
   

3. Run PsySH:

   php bin/console psysh:shell
   

First Use Case

• Debugging Controllers/Commands: Inject a controller or command class into the REPL for interactive testing.

  # config/services.yaml
  App\Controller\HomeController:
      tags: ['psysh.variable']
  

  Then access $homeController in PsySH.

Implementation Patterns

Common Workflows

1. Preloading Variables:

   • Use psysh.variable tag to auto-load services into the REPL:

     # config/services.yaml
     services:
         App\Service\Mailer:
             tags: ['psysh.variable']
     

   • Or define variables in config/packages/psysh.yaml:

     psysh:
         variables:
             - { db: '@doctrine.dbal.connection' }
             - { user: App\Entity\User::class }
     

2. Customizing PsySH Behavior:

   • Configure PsySH via config/packages/psysh.yaml:

     psysh:
         color_mode: forced
         use_tab_completion: true
         startup_message: 'Welcome to your Symfony REPL!'
     

3. Integrating with Tests:

   • Use PsySH in phpunit.xml.dist for debugging:

     <env name="PSYSH" value="1"/>
     

   • Add a test listener to auto-launch PsySH on failures.

4. Dynamic Variable Injection:

   • Create a custom compiler pass to inject runtime variables:

     // src/DependencyInjection/Compiler/PsyshCompilerPass.php
     public function process(ContainerBuilder $container) {
         $variables = $container->getParameter('psysh.variables');
         foreach ($variables as $name => $service) {
             $container->setParameter("psysh.variable.$name", $service);
         }
     }
     

Integration Tips

• Symfony Events: Bind PsySH to kernel events (e.g., console.terminate) for post-request debugging.
• Environment-Specific Configs: Use %kernel.environment% in psysh.yaml to toggle features (e.g., disable PsySH in production).
• Custom Commands: Extend PsyshCommand to add project-specific helpers:

  // src/Command/CustomPsyshCommand.php
  class CustomPsyshCommand extends PsyshCommand {
      protected function configure() {
          $this->setName('app:psysh');
          $this->addOption('model', null, InputOption::VALUE_REQUIRED, 'Load a model class');
      }
  
      protected function execute(InputInterface $input, OutputInterface $output) {
          $variables = [];
          if ($modelClass = $input->getOption('model')) {
              $variables['model'] = $modelClass;
          }
          $this->psysh->setVariables($variables);
          parent::execute($input, $output);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Service Container Scope:

   • Variables loaded via psysh.variable are singletons by default. Use autowire: true and public: false in services.yaml to avoid scope issues:

     services:
         App\Service\TransientService:
             public: false
     

2. PsySH Version Mismatch:

   • The bundle requires PsySH ^0.9. Ensure compatibility:

     composer require psy/psysh:^0.9
     

   • Avoid mixing with older PsySH versions (e.g., 0.8), which may break tab completion or syntax highlighting.

3. Configuration Overrides:

   • Bundle configs in config/packages/psysh.yaml override defaults. Use !import to merge configs:

     imports:
         - { resource: '@PsyshBundle/Resources/config/config.yaml' }
     psysh:
         <<: *default_config  # Merge defaults
         color_mode: forced
     

4. Debugging in CI/CD:

   • PsySH may fail in headless environments (e.g., GitHub Actions). Disable it via:

     # config/packages/dev/psysh.yaml
     psysh:
         enabled: '%env(bool:PSYSH_ENABLED)%'
     

     Then set PSYSH_ENABLED=false in CI.

5. Memory Leaks:

   • Long-running PsySH sessions can leak memory. Use --no-history to avoid persisting state:

     php bin/console psysh:shell --no-history
     

Debugging Tips

• Inspect Loaded Variables:

  >>> get_defined_vars()
  

  Lists all available variables in the REPL.

• Clear PsySH Cache: If configs aren’t applying, clear the cache:

  php bin/console cache:clear
  

• Enable Verbose Mode: Run PsySH with -v to debug initialization:

  php bin/console psysh:shell -v
  

Extension Points

1. Custom Variable Providers:

   • Implement PsyshVariableProviderInterface to dynamically load variables:

     class UserVariableProvider implements PsyshVariableProviderInterface {
         public function getVariables() {
             return ['user' => User::find(1)];
         }
     }
     

   • Register the provider in services.yaml:

     services:
         App\Service\UserVariableProvider:
             tags: ['psysh.variable_provider']
     

2. Hook into PsySH Initialization:

   • Override the PsyshCommand class to modify the REPL environment:

     // src/Command/CustomPsyshCommand.php
     class CustomPsyshCommand extends PsyshCommand {
         protected function getPsyshConfig() {
             $config = parent::getPsyshConfig();
             $config['startup_message'] = 'Custom message!';
             return $config;
         }
     }
     

3. Add Custom Helpers:

   • Extend PsySH’s runtime by defining helper functions in config/packages/psysh.yaml:

     psysh:
         default_includes:
             - '%kernel.project_dir%/config/psysh_helpers.php'
     

   • Example psysh_helpers.php:

     function dumpEntity($entity) {
         return (new \Symfony\Component\VarDumper\Cloner\VarCloner())->cloneVar($entity);
     }