Typesense Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Search-Centric Use Case: Ideal for Symfony applications requiring fast, typo-tolerant search (e.g., e-commerce, content platforms, or internal tools with complex queries). Leverages Typesense’s open-source alternative to Algolia with lower cost and self-hosting flexibility.
• Doctrine Integration: Seamlessly bridges Doctrine ORM and Typesense via automatic indexing listeners, reducing manual mapping overhead. The Doctrine object transformer abstracts schema synchronization (e.g., id alignment).
• Symfony Ecosystem Fit: Follows Symfony’s bundle pattern, aligning with dependency injection, configuration management (bundles.php, .env), and event-driven architecture (Doctrine listeners).
• Limitation: No built-in real-time sync for bulk updates/deletes (relies on Doctrine events; may lag for high-write workloads).

Integration Feasibility

• Low Friction: Minimal setup (Composer + config) with zero PHP code changes for basic indexing/search. The typesense-php SDK handles HTTP/JSON communication.
• Customization Points:
  • Field Mapping: Explicit fields config in acseo_typesense.yml allows granular control over indexed properties (e.g., title, author).
  • Collection Naming: Prefix support (collection_prefix) aids multi-tenant or namespaced deployments.
  • Search Services: Pre-built services (e.g., searchCollection) simplify query construction (e.g., search('query')->getResults()).
• Dependency Risk: Relies on external Typesense server (self-hosted or cloud). Network latency/availability becomes a critical path.

Technical Risk

• Schema Drift: Typesense schema must manually align with Doctrine entities if fields change (no auto-migration tool). Risk mitigated by:
  • Idempotent Indexing: Bundle uses id for synchronization (avoids duplicates).
  • Explicit Field Config: Forces clarity on indexed fields.
• Performance:
  • Indexing Overhead: Doctrine listeners add write-time latency (configurable via event priority).
  • Query Performance: Depends on Typesense tuning (e.g., num_tiers, filter_by).
• Security:
  • API Key Exposure: .env keys are not encrypted by default (use Symfony’s ParameterBag or vault for production).
  • CORS/Network: Typesense server must be accessible from Symfony (no proxy abstraction in bundle).

Key Questions

1. Search Requirements:
   • Are queries predominantly full-text (title/body) or faceted (filters like author, year)? Typesense excels at both but requires schema design.
   • What’s the query volume? Typesense handles thousands of QPS but may need scaling (sharding, replicas).
2. Data Freshness:
   • Is real-time sync critical (e.g., inventory updates)? If not, batch indexing (e.g., cron jobs) reduces listener overhead.
   • How are soft-deletes handled? Bundle lacks built-in support (may need custom Doctrine lifecycle callbacks).
3. Deployment:
   • Is Typesense self-hosted or managed (e.g., Typesense Cloud)? Affects scaling, backups, and cost.
   • What’s the failover strategy for Typesense downtime? Bundle has no retry/circuit-breaker logic.
4. Maintenance:
   • Who manages Typesense schema updates (e.g., adding fields)? Manual process today.
   • Are there custom search features (e.g., synonyms, custom analyzers) requiring Typesense config?

Integration Approach

Stack Fit

• Symfony 5.4+: Bundle targets modern Symfony with PHP 8.0+ (check compatibility with typesense-php).
• Doctrine ORM: Optimized for relational entities (no native support for MongoDB/Propel).
• Typesense Server: Requires v0.24.0+ (check typesense-php compatibility). Supports:
  • Self-hosted: Docker/K8s deployments.
  • Cloud: Typesense Cloud (configure url/key in .env).
• Alternatives Considered:
  • Elasticsearch: More complex but feature-rich (e.g., aggregations).
  • Meilisearch: Simpler but younger ecosystem.
  • Algolia: Managed but costly for high-volume searches.

Migration Path

1. Pilot Phase:
   • Index a Single Entity: Start with Book (from README) to validate:
     • Doctrine → Typesense sync.
     • Search query performance.
   • Monitor: Track indexing latency (Doctrine listener) and query response times.
2. Gradual Rollout:
   • Add Collections: Configure additional entities in acseo_typesense.yml.
   • Hybrid Search: Use Typesense for search-heavy queries, Doctrine for CRUD.
3. Cutover:
   • Deprecate Legacy Search: Replace custom WHERE/LIKE queries with Typesense.
   • Fallback Plan: Implement a cache layer (e.g., Redis) for Typesense queries to handle outages.

Compatibility

• Symfony Components:
  • Dependency Injection: Bundle uses Symfony’s container (no conflicts).
  • Event System: Doctrine listeners integrate via doctrine.orm.events.
• Typesense PHP SDK:
  • Version Pinning: Lock typesense/typesense-php to a stable version in composer.json.
  • Custom Extensions: If missing features (e.g., multi-collection queries), extend the SDK directly.
• Database:
  • PostgreSQL/MySQL: Doctrine support is universal.
  • NoSQL: Unsupported (bundle assumes relational entities).

Sequencing

1. Infrastructure Setup:
   • Deploy Typesense (Docker example: docker run -p 8108:8108 -v $(pwd)/data:/data/typesense typesense/search:0.24.0).
   • Configure .env (TYPESENSE_URL, TYPESENSE_KEY).
2. Bundle Configuration:
   • Define collections in config/packages/acseo_typesense.yml (start with 1–2 entities).
   • Example:

     acseo_typesense:
         collections:
             books:
                 entity: App\Entity\Book
                 fields:
                     id: ~
                     title: { type: string }
                     author: { type: string, optional: true }
                     published_at: { type: int64, sort: true }
     

3. Testing:
   • Unit Tests: Mock Typesense client to test search services.
   • Integration Tests: Verify Doctrine listeners index entities correctly.
   • Load Test: Simulate peak queries (e.g., 1000 QPS) to validate Typesense scaling.
4. Monitoring:
   • Logging: Add monolog handlers for Typesense client errors.
   • Metrics: Track:
     • Indexing latency (Doctrine events).
     • Query response times.
     • Typesense server CPU/memory.

Operational Impact

Maintenance

• Bundle Updates:
  • Minor Versions: Likely safe (follow typesense-php updates).
  • Major Versions: Test thoroughly (schema changes may break indexing).
• Typesense Maintenance:
  • Schema Management: Manual process today (tooling like Typesense CLI or custom scripts can help).
  • Backups: Critical for self-hosted deployments (Typesense provides dump/restore commands).
• Dependency Management:
  • Composer: Lock typesense-php version to avoid breaking changes.
  • Symfony: Ensure compatibility with LTS releases (e.g., Symfony 6.2).

Support

• Vendor Lock-in:
  • Low: Typesense is open-source; no proprietary APIs.
  • Migration Path: Data can be exported via Typesense API if switching providers.
• Community:
  • Limited: Bundle has 0 stars/dependents (risk of unanswered issues).
  • Workarounds: Leverage typesense-php GitHub issues or Typesense community.
• SLAs:
  • Self-hosted: No guarantees; requires internal monitoring (e.g., Prometheus + Grafana).
  • Cloud: Typesense Cloud offers SLAs (check their terms).

Scaling

• Horizontal Scaling:
  • Typesense: Scale by adding more nodes (sharding) or replicas for read-heavy workloads.
  • Symfony: Bundle is stateless; scale app servers independently.
• Performance Tuning:
  • Indexing: Adjust Doctrine listener priority (@Order) to minimize write impact.
  • Queries: Optimize Typesense config:
    • num_tiers: Reduce for faster searches (tradeoff: accuracy).
    • filter_by: Pre-filter results to reduce payload size.
• Caching:
  • **Query