Pomm Foundation Laravel Package

Technical Evaluation

Architecture Fit

• PostgreSQL-Centric DBAL: The package is a PostgreSQL-specific alternative to Laravel’s Eloquent or Doctrine DBAL, offering deep integration with PostgreSQL features (e.g., hstore, composite types, LISTEN/NOTIFY, JSONB). This aligns well with Laravel applications leveraging PostgreSQL’s advanced capabilities (e.g., multi-tenancy, geospatial data, or complex JSON hierarchies).
• Modular Design: The Session + ClientHolder + Pooler triad enables fine-grained control over database interactions, making it suitable for:
  • Custom query builders (e.g., domain-specific languages for complex queries).
  • Real-time systems (via LISTEN/NOTIFY support).
  • Type-safe data handling (e.g., PgBackedEnum, PgComposite).
• Laravel Compatibility: While not Laravel-native, it integrates via Composer and can coexist with Eloquent (e.g., for raw SQL or PostgreSQL-specific operations). The PSR-3 logging support ensures compatibility with Laravel’s logging stack.

Integration Feasibility

• Low Friction: Requires only ext-pgsql (not PDO) and PHP 8.4+, which is aligned with Laravel’s current LTS support (Laravel 10+).
• Hybrid Use Cases:
  • Replace Eloquent for PostgreSQL-heavy logic (e.g., raw queries, type conversions).
  • Augment Eloquent (e.g., use PommFoundation for LISTEN/NOTIFY or hstore operations while keeping Eloquent for CRUD).
• Dependency Injection: The Service Manager pattern supports integration with Laravel’s container (e.g., bind SessionBuilder as a singleton).

Technical Risk

• Learning Curve:
  • Architecture Complexity: The Session/ClientHolder/Pooler model differs from Eloquent’s active record pattern. Teams unfamiliar with Pomm may require 2–4 weeks of ramp-up.
  • Type System: Heavy use of PHP 8.4+ features (enums, typed properties) may require codebase modernization (e.g., Rector for legacy Laravel apps).
• Known Limitations:
  • Composite Types in Non-Public Schemas: Workaround required (manual schema inspection or query adjustments).
  • No ActiveRecord: Not a replacement for Eloquent’s ORM; best suited for raw SQL, query building, or data transformation.
• Performance:
  • Prepared Queries: Optimized for reuse but may introduce memory overhead for high-concurrency apps (e.g., ConverterHolder caching).
  • Result Iterators: Seekable iterators add flexibility but may increase GC pressure in long-running scripts.

Key Questions for PMs

1. Use Case Alignment:
   • Is the primary need PostgreSQL-specific features (e.g., hstore, LISTEN/NOTIFY, composite types) or generic CRUD (Eloquent suffices)?
   • Will the team adopt this as a primary DBAL or use it alongside Eloquent?
2. Team Expertise:
   • Does the team have PostgreSQL/PHP expertise, or is this a black-box integration?
   • Is the team comfortable with modular, non-ORM architectures?
3. Migration Path:
   • How will existing Eloquent queries/models be refactored or wrapped?
   • Are there legacy queries that rely on PDO (this package uses ext-pgsql)?
4. Scaling Considerations:
   • Will the app handle high concurrency (e.g., 10K+ connections)? If so, test ConverterHolder caching behavior.
   • Are there real-time requirements (LISTEN/NOTIFY) that Eloquent doesn’t support?
5. Maintenance:
   • Who will triage issues (upstream vs. Conserto fork)?
   • Is the team prepared for occasional BC changes (e.g., ConverterHolder semantics)?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • PHP 8.4+: Aligns with Laravel 10+ (LTS).
  • PSR-3 Logging: Integrates with Laravel’s Log facade.
  • Service Container: Can be bound as a singleton or context-bound service.
• PostgreSQL Features:
  • Replaces PDO/Eloquent for PostgreSQL-specific operations (e.g., hstore, JSONB, LISTEN).
  • Complements Eloquent for hybrid architectures (e.g., use Pomm for raw queries, Eloquent for models).
• Tooling:
  • Rector/PHP-CS-Fixer: Supports modernization of legacy Laravel codebases.
  • Atoum Tests: Can be adapted for Laravel’s testing stack (e.g., via FoundationSessionAtoum).

Migration Path

1. Pilot Phase (2–4 Weeks):
   • Isolate PostgreSQL-Specific Logic: Identify queries/models using hstore, JSONB, or LISTEN/NOTIFY.
   • Wrap Existing Code: Create a PommFoundation facade to abstract differences from Eloquent.

     // Example: PommFoundation facade
     Facades\Pomm::query("SELECT * FROM users WHERE hstore_data @> '{\"active\": \"true\"}'");
     

   • Test Performance: Compare query execution times (Pomm’s prepared queries may differ from Eloquent’s).
2. Hybrid Integration:
   • Query Builder: Use Pomm’s SimpleQueryManager for raw SQL while keeping Eloquent for models.
   • Event Listeners: Replace Laravel’s queue listeners with Pomm’s LISTEN/NOTIFY for real-time updates.
   • Type Conversion: Replace Eloquent accessors with Pomm’s converters (e.g., PgBackedEnum for enum fields).
3. Full Adoption (Optional):
   • Replace Eloquent Queries: Migrate to Pomm’s query builder for all PostgreSQL interactions.
   • Custom ORM Layer: Build a thin layer on top of Pomm to mimic Eloquent’s active record pattern.

Compatibility

Sequencing

1. Phase 1: Infrastructure Setup
   • Install package: composer require conserto/pomm-foundation.
   • Configure DSN in Laravel’s .env or a config file.
   • Bind SessionBuilder to Laravel’s container:

     $app->singleton('pomm.session', fn() => new \PommProject\Foundation\SessionBuilder()->get());
     

2. Phase 2: Pilot Features
   • Implement a Pomm facade for hstore/JSONB queries.
   • Replace 1–2 Eloquent queries with Pomm equivalents (e.g., LISTEN/NOTIFY).
3. Phase 3: Hybrid Integration
   • Create a query repository pattern to abstract Pomm/Eloquent differences.
   • Migrate event listeners to Pomm’s observers.
4. Phase 4: Full Adoption (Optional)
   • Replace Eloquent’s query builder with Pomm’s SimpleQueryManager.
   • Deprecate PDO usage in favor of ext-pgsql.

Operational Impact

Maintenance

• Pros:
  • Active Fork: Conserto provides bug fixes, PHP 8.4+ support, and enum enhancements.
  • Tooling: Composer scripts (test, stan, rector) reduce manual maintenance (e.g., auto-fix PHPCS issues).
  • Documentation: AGENTS.md and CHANGELOG clarify BC policies and caching behavior.
• Cons:
  • Upstream Dependence: Issues may require coordination with Conserto (not Laravel core).
  • Custom Converters: Overriding built-in converters (e.g., PgString) requires understanding ConverterHolder semantics.
• Laravel-Specific:
  • Package Updates: Monitor for Laravel version conflicts (e.g., PHP 8.4+ requirements).
  • Logging: Ensure PS