Mapper Laravel Package

Product Decisions This Supports

• Database Abstraction Layer (DAL) Strategy: Adopting atlas/mapper enables a build vs. buy decision in favor of building a custom data access layer (DAL) on top of Atlas.Orm, rather than integrating third-party ORMs (e.g., Eloquent, Doctrine). This aligns with teams prioritizing domain-driven design (DDD) and type safety over convention-over-configuration.
• Performance-Critical Applications: The package’s focus on performance optimizations (e.g., large many-to-many datasets, benchmarking scripts) makes it ideal for high-traffic or data-intensive applications (e.g., SaaS platforms, analytics tools, or real-time systems).
• Relationship Management: Supports complex relationship modeling (many-to-many, one-to-one bidirectional, cascading deletes) without bloating the codebase with manual SQL joins or raw PDO queries. Critical for product roadmaps involving hierarchical data (e.g., nested comments, organizational charts).
• Developer Experience (DX): IDE-friendly features (e.g., type hints, PHPStorm metadata) reduce onboarding time for backend engineers, accelerating feature velocity in teams adopting PHP.
• Migration Path for Legacy Systems: Useful for gradual modernization of monolithic PHP applications with legacy databases, where replacing the entire ORM is costly. The mapper can coexist with existing PDO or raw SQL layers.

When to Consider This Package

• Avoid if:
  • Your team prioritizes rapid prototyping over long-term maintainability (e.g., startups with uncertain product-market fit). The learning curve for Atlas.Cli and custom mapper generation may slow iteration.
  • You need active community support or enterprise-grade documentation. The package has low stars (7) and no dependents, suggesting niche adoption.
  • Your application is simple CRUD with minimal relationships. Overhead of Atlas.Cli and mapper generation may not justify benefits.
  • You’re locked into Eloquent/Doctrine ecosystems with existing migrations, plugins, or team expertise. Integration costs could outweigh gains.
• Consider if:
  • You’re building a PHP-first greenfield project with complex data models (e.g., graph databases, multi-tenancy).
  • Performance is a non-negotiable (e.g., handling millions of records with many-to-many joins).
  • Your team values explicit over implicit (e.g., avoiding Eloquent’s "magic" methods like hasMany in favor of declarative relationships).
  • You need fine-grained control over SQL generation (e.g., custom query building for analytics or reporting).
  • You’re already using or willing to adopt the Atlas ecosystem (e.g., Atlas.Table, Atlas.Orm).

How to Pitch It (Stakeholders)

For Executives:

"Atlas.Mapper lets us own our data layer without sacrificing performance or flexibility. Think of it as a Swiss Army knife for PHP databases—ideal for scaling our [Product X] platform where complex relationships (e.g., user roles, nested transactions) are critical. By adopting this, we avoid vendor lock-in with ORMs like Eloquent, reduce technical debt from raw SQL, and future-proof our stack for high-traffic growth. The package’s focus on performance optimizations (e.g., handling large datasets efficiently) aligns with our goal to support [Y] concurrent users without costly infrastructure upgrades."

Key Outcomes:

• Faster development for data-heavy features (e.g., reporting, user hierarchies).
• Lower operational costs via optimized queries and reduced database load.
• Alignment with long-term tech vision (e.g., DDD, type safety).

For Engineering Leaders:

*"Atlas.Mapper is a lightweight, high-performance data mapper that gives us:

1. Precision: Explicit control over SQL generation (no magic methods) for complex queries.
2. Scalability: Optimized for large datasets (e.g., many-to-many joins) with benchmarked performance.
3. Tooling: IDE-friendly type hints and PHPStorm metadata to reduce bugs and onboarding time.
4. Flexibility: Works independently of Atlas.Orm, so we can adopt it incrementally or as a replacement for raw PDO.

Trade-offs:

• Requires initial setup with Atlas.Cli to generate mapper classes (one-time cost).
• Smaller community than Eloquent/Doctrine, but no vendor lock-in.

Proposed Adoption Path:

1. Pilot: Use in a non-critical module (e.g., admin dashboard) to validate DX and performance.
2. Gradual Rollout: Replace raw SQL or Eloquent in modules with complex relationships (e.g., orders, users).
3. Full Migration: Phase out legacy ORM usage over 6–12 months.

Ask: Approval to allocate [X] dev weeks for proof-of-concept and training on Atlas.Cli."*

For Developers:

*"Atlas.Mapper is like Eloquent’s strict, performant cousin—but without the magic. Here’s why it’s worth trying:

• No Surprises: Relationships are declarative (e.g., joinWith('LEFT foo AS foo_alias')) with no hidden SQL.
• Speed: Optimized for bulk operations (e.g., fetchRecordsBy()) and large many-to-many datasets.
• IDE Love: Type hints and PHPStorm metadata make autocompletion butter-smooth.
• Customization: Need a query Eloquent can’t handle? You’re in control—build it manually or extend the mapper.

How to Get Started:

1. Install via Composer: composer require atlas/mapper.
2. Generate mappers with Atlas.Cli: vendor/bin/atlas generate:mappers.
3. Use the locator to fetch mappers: $threadMapper = $mapperLocator->get(ThreadMapper::CLASS).
4. Query like a boss: $threads = $threadMapper->fetchRecordsBy(['author_id' => 1])->joinWith('comments').

Try It: Spin up a test project and compare performance with your current ORM for a complex query (e.g., nested joins)."*