Amp Sql Profiler Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Target Use Case: The package is specifically designed for Symfony applications using Amp (ReactPHP’s successor) where Doctrine is not viable (e.g., async-first architectures). It bridges the gap by integrating with Symfony’s WebProfilerBundle to provide SQL profiling for Amp’s SQL connections (e.g., Amp\Postgres\PostgresConnectionPool).
• Key Fit Criteria:
  • Async-First Systems: Ideal for applications leveraging Amp’s non-blocking SQL drivers (e.g., PostgreSQL, MySQL) where traditional Doctrine profiling is incompatible.
  • Symfony Ecosystem: Tight integration with Symfony’s profiler toolbar and data collectors, reducing dev overhead for async SQL debugging.
  • Transaction Support: Basic transaction profiling (though limited by Amp’s lack of savepoints/prepared statements).
• Misalignment Risks:
  • Non-Amp Projects: Useless for traditional PHP/Symfony apps using Doctrine ORM or PDO.
  • Prepared Statements: Explicitly unsupported; may break queries relying on this feature.
  • Symfony Version Lock: Hard dependency on Symfony 6/7 (web-profiler-bundle v6|7).

Integration Feasibility

• Low-Coupling Design: The bundle wraps Amp\Sql\Pool via a factory pattern, requiring minimal code changes (replacing Pool with ProfiledPool in DI).
• Dev-Only Scope: Intended for development/testing environments (explicitly marked as dev in bundles.php).
• Circular Dependency Workaround: Requires explicit YAML configuration to resolve ProfiledPool ↔ Pool circularity (e.g., profiling PostgresConnectionPool directly).
• Backward Compatibility: No breaking changes to existing Amp SQL usage; profiling is opt-in.

Technical Risk

• Limited Adoption: 0 stars/dependents suggests unproven stability. Risk of:
  • Undocumented edge cases (e.g., nested transactions, custom Amp SQL drivers).
  • Performance overhead in profiling (though likely negligible in dev).
• Feature Gaps:
  • No prepared statement support → SQL injection risks if queries are dynamically built.
  • No transaction savepoints → limited debugging for complex transactions.
• Symfony Versioning: Tied to symfony/web-profiler-bundle:^6|^7; may require updates if upgrading Symfony major versions.
• Amp Versioning: Depends on amphp/sql:^2; ensure compatibility with your Amp stack.

Key Questions for TPM

1. Async SQL Strategy:
   • Is Amp SQL the primary database layer, or a secondary/fallback? If the latter, does this bundle add value?
   • Are prepared statements critical for security/compliance? If yes, this bundle is a blocker.
2. Symfony Version:
   • Is the team locked into Symfony 6/7? If upgrading to 8+, this bundle may need replacement.
3. Profiling Needs:
   • Are there specific SQL bottlenecks (e.g., slow queries, connection leaks) that this would address?
   • Does the team use Doctrine QueryBuilder (which might work with Amp) or raw SQL?
4. Alternatives:
   • Could custom logging (e.g., Amp\Loop::onTick) or third-party tools (e.g., Blackfire) suffice?
   • Is there interest in extending this bundle (e.g., adding prepared statement support)?
5. CI/CD Impact:
   • Will this bundle break tests if enabled in test environments? (Readme recommends dev only.)
6. Long-Term Viability:
   • Is the maintainer (ScriptFUSION) active? Low stars suggest low priority.
   • Are there plans to migrate from Amp to another async library (e.g., ReactPHP)?

Integration Approach

Stack Fit

• Primary Use Case: Symfony 6/7 applications using Amp SQL drivers (e.g., Amp\Postgres\PostgresConnectionPool) without Doctrine.
• Secondary Use Case: Apps mixing Amp SQL with Doctrine QueryBuilder (limited utility).
• Incompatible Stacks:
  • Traditional PDO/Doctrine ORM apps.
  • Symfony 8+ (unless bundle is updated).
  • Non-Symfony PHP apps.

Migration Path

1. Assessment Phase:
   • Audit SQL layer: Confirm use of Amp SQL drivers (not Doctrine).
   • Verify Symfony version compatibility (web-profiler-bundle:^6|^7).
   • Check for prepared statements/transaction savepoints in critical paths.
2. Installation:
   • Add via Composer (dev-only):

     composer require --dev async/amp-sql-profiler-bundle
     

   • Enable in bundles.php (Symfony Flex auto-configures; manual add if needed):

     ScriptFUSION\AmpSqlProfilerBundle\AmpSqlProfilerBundle::class => ['dev' => true],
     

3. Configuration:
   • Replace Amp\Sql\Pool with ProfiledPool in services_dev.yaml:

     ScriptFUSION\AmpSqlProfilerBundle\ProfiledPool:
       arguments:
         - '@Amp\Postgres\PostgresConnectionPool'  # Specify concrete pool
     Amp\Postgres\PostgresConnectionPool: ~
     

4. Validation:
   • Test in a dev environment (not CI/CD).
   • Verify profiler toolbar shows SQL queries.
   • Check for regressions in transactional behavior.

Compatibility

• Amp SQL Drivers: Works with any Amp\Sql\Pool implementation (e.g., PostgreSQL, MySQL).
• Symfony Profiler: Requires web-profiler-bundle (already present in most Symfony apps).
• PHP 8.2+: Hard dependency; ensure runtime compatibility.
• No Doctrine: Explicitly designed for non-Doctrine Amp SQL usage.

Sequencing

1. Phase 1 (Dev-Only):
   • Enable in development for debugging.
   • Document exclusion from test/prod environments.
2. Phase 2 (Optional):
   • Extend bundle for missing features (e.g., prepared statements) if critical.
   • Fork/replace if maintainer abandons the project.
3. Phase 3 (Monitoring):
   • Track false positives/negatives in profiling data.
   • Assess performance impact (if any) in dev.

Operational Impact

Maintenance

• Dev-Only Bundle: Minimal runtime impact; no production maintenance.
• Dependency Updates:
  • Monitor amphp/sql, symfony/web-profiler-bundle, and PHP 8.x compatibility.
  • Risk of breakage if Symfony upgrades to v8+ without bundle updates.
• Customization:
  • Limited extensibility (no public API for adding features like prepared statements).
  • May need forking if gaps are critical.

Support

• Debugging:
  • Provides query backtraces and transaction summaries via Symfony Profiler.
  • Reduces manual logging for async SQL issues.
• Limitations:
  • No support for prepared statements → manual instrumentation may be needed.
  • Transaction savepoints unsupported → complex workflows may require alternative logging.
• Community:
  • No active maintainer (0 stars, no recent commits). Support risks include:
    • Unanswered issues.
    • Abandonware if Amp ecosystem shifts.

Scaling

• Performance:
  • Profiling adds minimal overhead (only in dev). No impact on production.
  • Potential for memory leaks if profiling is enabled in long-running processes (e.g., CLI workers).
• Production Readiness:
  • Not for production: Explicitly dev-only. No caching or optimization features.
  • No impact on scaling; purely a debugging tool.

Failure Modes

Ramp-Up

• Onboarding Time: Low (5–15 minutes for setup).
  • Requires:
    1. Composer install.
    2. DI configuration.
    3. Profiler toolbar verification.
• Learning Curve: Moderate for teams unfamiliar with:
  • Symfony Profiler data collectors.
  • Amp SQL internals (e.g., connection pools).
• **