Psysh Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev ameenross/psysh-bundle
   

2. Enable the Bundle: Add to app/AppKernel.php (Symfony 2.x) or config/bundles.php (Symfony 3.x+):

   // Symfony 2.x
   if (in_array($this->getEnvironment(), ['dev', 'test'])) {
       $bundles[] = new Fidry\PsyshBundle\PsyshBundle();
   }
   

   // Symfony 3.x+
   return [
       // ...
       Fidry\PsyshBundle\PsyshBundle::class => ['dev' => true, 'test' => true],
   ];
   

3. First Use Case: Run the PsySH REPL directly:

   app/console psysh
   

   • Access the Symfony container via $app['kernel'] or $kernel = $app['kernel'].
   • Inspect services: $app['service_id'].

Implementation Patterns

Daily Workflows

1. Debugging Controllers/Commands:

   • Attach to a running Symfony process (e.g., web server) using Psy\Shell::start().
   • Example:

     $kernel = $app['kernel'];
     $kernel->boot();
     $request = $app['request_stack']->getCurrentRequest();
     // Inspect/modify $request or other objects interactively.
     

2. Service Inspection:

   • List all services:

     $container = $app;
     $container->getServiceIds();
     

   • Dump a service’s configuration:

     dump($container->getDefinition('service_id')->getArguments());
     

3. Database Queries:

   • Use Doctrine’s EntityManager directly:

     $em = $app['doctrine.orm.entity_manager'];
     $em->createQuery('SELECT u FROM AppBundle:User u')->getResult();
     

4. Event Listeners/Subscribers:

   • Inspect event dispatchers:

     $dispatcher = $app['event_dispatcher'];
     $dispatcher->getListeners('kernel.request');
     

5. Custom Commands:

   • Extend Psy\Shell for project-specific REPL commands:

     class CustomPsyShell extends Psy\Shell {
         public function __construct($app) {
             parent::__construct();
             $this->bind('app', $app);
             $this->bind('kernel', $app['kernel']);
         }
     }
     

   • Register in PsyshBundle config (if supported) or override the command.

Integration Tips

1. Environment-Specific Config:

   • Use config/packages/dev/psysh.yaml (Symfony 3.4+) or app/config/config_dev.yml (Symfony 2.x) to customize:

     fidry_psysh:
         enabled: true
         commands: ['app/console psysh:custom']
     

2. Autoloading Helpers:

   • Add project-specific aliases to ~/.psyshrc.php:

     Psy\Configuration::getInstance()->setFileFinder(new Psy\FileFinder([
         __DIR__.'/../src',
         __DIR__.'/../vendor',
     ]));
     

3. Symfony Debug Toolbar Integration:

   • Use Psy\Shell to inspect the _profiler or _token_storage:

     $profiler = $app['profiler'];
     $profiler->collect();
     

4. Testing:

   • Attach to PHPUnit tests via Psy\Shell::start() in setUp():

     public function setUp(): void {
         if (getenv('PSYSH')) {
             Psy\Shell::start();
         }
     }
     

   • Run tests with:

     PSYSH=1 phpunit
     

Gotchas and Tips

Pitfalls

1. Symfony 3.x+ Compatibility:

   • The bundle is primarily tested for Symfony 2.x. For Symfony 3.x+, ensure Psy\Psysh v0.3+ is compatible with your PHP version (e.g., PHP 7.1+ may need newer PsySH).

2. Container Access:

   • The $app variable in PsySH is the service container, not the Kernel. Access services via $app['service_id'], not $app->getService().

3. Namespace Conflicts:

   • Avoid naming custom classes PsyshBundle or PsyShell to prevent collisions with the bundle’s classes.

4. Performance in Production:

   • The bundle is dev/test-only. Accidentally enabling it in production will expose the REPL endpoint (/psysh).

5. Doctrine Proxy Issues:

   • If using Doctrine ORM, enable proxy generation in config/packages/dev/doctrine.yaml:

     orm:
         proxy_dir: '%kernel.cache_dir%/doctrine/orm/Proxies'
         proxy_namespace: 'AppBundle\Proxy'
     

Debugging Tips

1. PsySH Crashes:

   • Check for unclosed braces or syntax errors in the REPL. Use exit to quit gracefully.
   • Clear PsySH’s cache if commands stop working:

     rm -rf ~/.cache/psysh/
     

2. Service Not Found:

   • Verify the service ID is correct (case-sensitive). Use:

     $app->getServiceIds(); // List all services
     

3. Doctrine Lazy Loading:

   • Initialize proxies manually if lazy-loading fails:

     $entity = $em->getRepository('AppBundle:User')->find(1);
     $em->getUnitOfWork()->getEntityManager()->refresh($entity);
     

4. Custom Autoloading:

   • If classes aren’t found, ensure vendor/autoload.php is loaded in PsySH:

     require __DIR__.'/../../../vendor/autoload.php';
     

Extension Points

1. Custom PsySH Commands:

   • Create a command class extending Psy\Command\Command and register it in the bundle’s config:

     fidry_psysh:
         commands:
             - AppBundle\Command\CustomPsyCommand
     

2. Override the Shell:

   • Extend Fidry\PsyshBundle\Command\PsyshCommand to modify behavior:

     class CustomPsyshCommand extends PsyshCommand {
         protected function getShellClass() {
             return CustomPsyShell::class;
         }
     }
     

3. Add Custom Bindings:

   • Bind project-specific objects in Psy\Shell:

     $shell->bind('my_service', $app['my_service']);
     $shell->bind('logger', $app['logger']);
     

4. Integrate with Symfony Debug:

   • Use Psy\Shell to dump Symfony’s debug data:

     dump($app['debug.parameter_bag']->all());