Pomm Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require pomm-project/pomm-bundle
   

   Use Symfony Flex recipe (if available) to auto-configure basic DATABASE_URL support.

2. Register Bundle Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       PommProject\PommBundle\PommBundle::class => ['all' => true],
   ];
   

3. First Use Case Inject the pomm service (ModelManager) into a controller/service:

   use PommProject\PommBundle\Pomm\PommInterface;
   
   class MyController {
       public function __construct(private PommInterface $pomm) {}
   
       public function index() {
           $session = $this->pomm->getSession('db'); // Default session
           $result = $session->query('SELECT 1')->fetch();
           return new Response($result[0]);
       }
   }
   

Where to Look First

• Configuration: Check config/packages/pomm.yaml (auto-generated by Flex).
• Session Management: Explore pomm.yaml for session definitions (e.g., db).
• Doctrine Bridge: If using Doctrine, review PommProject\PommBundle\Doctrine\PommDriver.

Implementation Patterns

Core Workflows

1. Session-Based Queries Use the pomm service to fetch sessions and execute queries:

   $session = $this->pomm->getSession('db');
   $result = $session->query('SELECT * FROM users WHERE id = ?', [1]);
   

2. Parameterized Configuration Override default session parameters in pomm.yaml:

   pomm:
       sessions:
           db:
               driver: pdo_mysql
               host: '%env(DATABASE_HOST)%'
               dbname: '%env(DATABASE_NAME)%'
   

3. Event Listeners Attach Pomm events (e.g., pomm.session.connect) via Symfony’s event dispatcher:

   $dispatcher->addListener('pomm.session.connect', function ($event) {
       $session = $event->getSession();
       $session->setLogger(new \Monolog\Logger('pomm'));
   });
   

4. Doctrine Integration Use the PommDriver to bridge Pomm with Doctrine entities:

   $driver = new \PommProject\PommBundle\Doctrine\PommDriver($this->pomm);
   $entityManager->getConnection()->getDriver()->connect($driver);
   

Integration Tips

• Environment Variables: Prefer %env() in pomm.yaml for secrets (e.g., password).
• Session Factories: Extend \PommProject\PommBundle\Session\SessionFactory for custom sessions.
• Command Bus: Combine with Symfony’s CommandBus for async queries:

  $this->pomm->getSession('db')->query('...')->then(function ($result) {
      // Handle result
  });
  

Gotchas and Tips

Pitfalls

1. Session Naming Collisions Ensure session names in pomm.yaml (e.g., db) match those used in code. Defaults to db if unspecified.

2. Driver Mismatches Verify the driver key in pomm.yaml matches installed Pomm drivers (e.g., pdo_mysql, postgres).

3. Lazy Loading Sessions are lazy-loaded; call getSession() before use to trigger initialization.

4. Symfony 5+ Deprecations If using Symfony 5.1+, replace AppKernel registration with bundles.php (see Getting Started).

Debugging

• Profiler Panel: Enable via Flex recipe (adds /_pomm route for session stats).
• Logging: Configure Pomm’s logger in pomm.yaml:

  pomm:
      logger: '@monolog.logger.pomm'
  

• Query Errors: Use try-catch with Pomm\Exception\RuntimeException for query failures.

Extension Points

1. Custom Drivers Implement \Pomm\Driver\DriverInterface and register via:

   pomm:
       drivers:
           my_driver: App\Driver\MyDriver
   

2. Session Factories Override the factory in services.yaml:

   services:
       App\Session\CustomFactory: ~
       pomm.session_factory: '@App\Session\CustomFactory'
   

3. Event Subscribers Subscribe to Pomm events (e.g., pomm.session.query) for query interception:

   $dispatcher->addSubscriber(new class implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return ['pomm.session.query' => 'onQuery'];
       }
       public function onQuery(QueryEvent $event) {
           // Modify query or result
       }
   });
   

Config Quirks

• Flex Auto-Config: If using Flex, avoid manual parameters.yml for DATABASE_URL (use .env).
• YAML Indentation: Ensure pomm.yaml uses 2-space indentation (YAML strictness).
• Default Session: The db session is auto-configured but requires DATABASE_URL in .env.