Symfony Laravel Package

Getting Started

Minimal Setup

1. Enable Contrib Recipes (Symfony 4+):

   composer config extra.symfony.allow-contrib true
   

2. Install the Bundle:

   composer require atlas/symfony ~1.0
   

3. Configure .env (replace placeholders):

   ATLAS_PDO_DSN=mysql:host=localhost;dbname=your_db
   ATLAS_PDO_USERNAME=your_user
   ATLAS_PDO_PASSWORD=your_password
   

4. Generate Mappers (skeleton files for tables):

   mkdir -p src/DataSource
   php bin/console atlas:skeleton
   

   • Verify atlas.yaml under config/packages/ for directory/namespace paths.

First Use Case: Fetching a Record

// src/Service/ThreadService.php
namespace App\Service;

use Atlas\Orm\Atlas;
use App\DataSource\Thread\Thread;

class ThreadService {
    public function __construct(private Atlas $atlas) {}

    public function getThread(int $id) {
        return $this->atlas->fetchRecord(Thread::class, $id);
    }
}

• Autowire Atlas via Symfony’s DI container (no manual instantiation).
• Test with php bin/console debug:container Atlas to verify service availability.

Implementation Patterns

1. Dependency Injection & Autowiring

• Atlas as a Service: Always inject Atlas via constructor (type-hinted).

  public function __construct(Atlas $atlas) { ... }
  

• Mapper Classes: Generated in src/DataSource/ (e.g., Thread.php).
  • Use these to define relationships, behaviors, or custom methods.

  // src/DataSource/Thread/Thread.php
  namespace App\DataSource\Thread;
  
  use Atlas\Orm\Mapper;
  
  class Thread extends Mapper {
      public function getPosts() {
          return $this->hasMany(Post::class);
      }
  }
  

2. Transactions

• Auto-Transactions: Enable via atlas.yaml:

  atlas:
      orm:
          atlas:
              transaction_class: Atlas\Orm\Transaction\AutoTransact
  

• Manual Transactions:

  $this->atlas->beginTransaction();
  try {
      $this->atlas->fetchRecord(...);
      $this->atlas->commit();
  } catch (\Exception $e) {
      $this->atlas->rollBack();
  }
  

3. Query Logging (Profiler)

• Enable in atlas.yaml:

  atlas:
      orm:
          atlas:
              log_queries: true
  

• View logged queries in Symfony Profiler under the "Atlas" tab.

4. Custom PDO Options

• Configure in atlas.yaml:

  connections:
      default:
          dsn: '%env(ATLAS_PDO_DSN)%'
          options:
              !php/const PDO::ATTR_EMULATE_PREPARES: false
  

5. Relationships & Behaviors

• Define Relationships in mapper classes:

  class User extends Mapper {
      public function getPosts() {
          return $this->hasMany(Post::class);
      }
  }
  

• Add Behaviors (e.g., timestamps):

  use Atlas\Orm\Behavior\Timestampable;
  
  class Post extends Mapper {
      use Timestampable;
  }
  

6. Command-Line Workflows

• Regenerate Mappers after schema changes:

  php bin/console atlas:skeleton
  

• Run Migrations (if using Atlas CLI):

  php bin/console atlas:migrate
  

Gotchas and Tips

Pitfalls

1. Namespace/Directory Mismatch:

   • If atlas:skeleton fails, verify atlas.cli.config.input.directory and namespace in atlas.yaml match your src/DataSource/ setup.
   • Fix: Update atlas.yaml or regenerate with correct paths.

2. PDO Connection Issues:

   • Ensure .env variables (ATLAS_PDO_*) are correctly set and the database is reachable.
   • Debug: Enable log_queries: true and check profiler for errors.

3. Transaction Leaks:

   • Unclosed transactions can block connections. Always wrap operations in try/catch with commit()/rollBack().
   • Use AutoTransact for simplicity (but test edge cases).

4. Case Sensitivity:

   • Atlas converts table names to singular by default (e.g., threads → Thread).
   • Override in atlas.cli.transform if needed:

     atlas:
         cli:
             transform:
                 threads: ForumThread
     

5. Profiler Not Showing Queries:

   • Ensure log_queries: true and the Symfony Profiler toolbar is enabled in config/packages/dev/profiler.yaml.

Debugging Tips

• Query Logging:

  $this->atlas->getLogger()->setLevel(\Psr\Log\LogLevel::DEBUG);
  

• Dump Records:

  var_dump($record->toArray());
  

• Check Generated SQL: Enable log_queries and inspect the profiler.

Extension Points

1. Custom Mappers: Extend Atlas\Orm\Mapper to add domain logic:

   class CustomMapper extends Mapper {
       public function customMethod() { ... }
   }
   

2. Event Listeners: Use Atlas events (e.g., Atlas\Orm\Event\BeforeSave) via Symfony’s event dispatcher:

   # config/services.yaml
   services:
       App\EventListener\AtlasListener:
           tags:
               - { name: kernel.event_listener, event: atlas.before_save, method: onBeforeSave }
   

3. Custom Transactions: Implement Atlas\Orm\Transaction\TransactionInterface for advanced control.

Performance Quirks

• Eager Loading: Use with() to avoid N+1 queries:

  $thread = $this->atlas->fetchRecord(Thread::class, 1, ['posts']);
  

• Batch Operations: For bulk inserts/updates, use RecordSet methods:

  $records = $this->atlas->fetchAll(Thread::class);
  $records->each(fn($record) => $record->setStatus('active'));
  $this->atlas->saveAll($records);
  

IDE Support

• Copy the PHPStorm meta file for autocompletion:

  cp vendor/atlas/orm/resources/phpstorm.meta.php ./.phpstorm.meta.php
  

• Configure PHPStorm to recognize src/DataSource/ as a "Sources" root.