Weave Code
Mapper Laravel Package
atlas/mapper
Atlas.Mapper is a lightweight data mapper for Atlas, used as the core of Atlas.Orm or standalone. Create a MapperLocator with PDO params, fetch mappers by class, and work with Records via select, fetch, insert, update, delete, and persist.
A data mapper for the persistence model.
Frequently asked questions about Mapper
- How do I integrate Atlas.Mapper with Laravel’s existing database connections (e.g., MySQL, PostgreSQL)?
- Atlas.Mapper works with Laravel’s PDO connections via `DB::connection()->getPdo()`. Pass the PDO instance to `MapperLocator::new()` with your connection details. For example, use `DB::connection('pgsql')->getPdo()` for PostgreSQL. Ensure your Laravel connection config matches the PDO parameters Atlas.Mapper expects.
- Can Atlas.Mapper replace Eloquent in a Laravel project, or should I use it alongside Eloquent?
- Atlas.Mapper is best used alongside Eloquent for hybrid architectures. Replace Eloquent for complex relationships (e.g., many-to-many with cascading deletes) or high-throughput operations, while keeping Eloquent for simpler CRUD. Use a service layer to abstract differences between the two, such as converting `Record` objects to Eloquent models via accessors.
- What Laravel versions does Atlas.Mapper support, and are there any breaking changes to watch for?
- Atlas.Mapper is framework-agnostic but works with Laravel 8+ (PHP 8.0+). Check the [Atlas.Cli dependency](https://github.com/atlasphp/Atlas.Cli) for PHP version requirements. Breaking changes include `joinWith()` syntax shifts (e.g., v1.0.0-beta2) and Atlas.Cli updates, which may require regenerating mapper classes. Always test after updates.
- How do I handle migrations and schema changes with Atlas.Mapper, since it doesn’t include built-in migration tools?
- Atlas.Mapper relies on manual PDO setup or integration with [Atlas.Cli](https://github.com/atlasphp/Atlas.Cli) for schema generation. For Laravel, use Eloquent migrations for schema changes and Atlas.Mapper for data operations. Alternatively, generate SQL from Atlas.Table and run it via Laravel’s `Schema::raw()`. Avoid mixing Atlas.Mapper and Eloquent migrations on the same tables.
- What’s the performance impact of using Atlas.Mapper for large datasets (e.g., 10K+ records)?
- Atlas.Mapper is optimized for performance, with fixes for large datasets in v1.3.3 (e.g., many-to-many optimizations). Benchmark your queries using Atlas’s built-in tools. For read-heavy operations, use `fetchRecordSet()` with eager loading (`joinWith()`) to avoid N+1 queries. Monitor memory usage with `memory_get_usage()` for bulk operations.
- How do I generate mapper classes for my Laravel models, and what if Atlas.Cli changes its output format?
- Generate mapper classes using [Atlas.Cli 2.x](https://github.com/atlasphp/Atlas.Cli) with your model classes as input. Store generated files in `app/Atlas/Generated/` and exclude them from version control if using a build step. If Atlas.Cli changes its output (e.g., class naming), regenerate mappers and update your `MapperLocator` configuration to point to the new classes.
- Can I use Atlas.Mapper’s events (e.g., for logging or caching) with Laravel’s event system?
- Atlas.Mapper supports custom `MapperEvents` for query modification, but it doesn’t natively integrate with Laravel’s event system. Bridge the two by listening to Laravel events (e.g., `Model::saved`) and triggering Atlas.Mapper events via a facade or service container. For example, dispatch a Laravel event after `persist()` and handle it to log or cache the operation.
- What are the alternatives to Atlas.Mapper for Laravel, and when should I choose it over Eloquent or Doctrine?
- Alternatives include Eloquent (for simplicity), Doctrine ORM (for enterprise features), or custom repositories. Choose Atlas.Mapper if you need a lightweight, relationship-focused mapper without Eloquent’s overhead, especially for complex hierarchies or polymorphic associations. Avoid it if you rely on Laravel’s built-in features like Scout, Nova, or migrations.
- How do I test Atlas.Mapper in a Laravel project using Pest or PHPUnit?
- Test Atlas.Mapper by mocking the `MapperLocator` and injecting dependencies. Use Pest/PHPUnit to assert `Record` objects returned by methods like `fetchRecords()`. For database tests, use Laravel’s `DatabaseMigrations` or `DatabaseTransactions` traits. Mock relationships with `joinWith()` to simulate eager loading. Example: `$this->assertInstanceOf(Thread::class, $mapper->fetchRecord(1));`
- Is Atlas.Mapper actively maintained, and what’s the long-term viability for Laravel projects?
- Atlas.Mapper’s last release was in September 2023, but the project is niche with no major dependents. Monitor the [AtlasPHP GitHub](https://github.com/atlasphp) for updates. For production use, evaluate the team’s responsiveness to issues and consider contributing to or sponsoring the project. Alternatives like Eloquent or custom repositories may offer better long-term support.
Weaver
How can I help you explore Laravel packages today?