Articulate Symfony Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require denisyu-1/articulate-symfony
   

   Ensure Articulate\Symfony\ArticulateSymfonyBundle is enabled in config/bundles.php.

2. Configuration: Create config/packages/articulate.yaml with a basic setup:

   articulate:
     connection:
       dsn: '%env(resolve:DATABASE_URL)%'
     paths:
       entities: '%kernel.project_dir%/src/Entity'
       migrations: '%kernel.project_dir%/migrations/Articulate'
   

3. First Use Case: Define an entity (e.g., src/Entity/Book.php):

   namespace App\Entity;
   
   use Articulate\Modules\Entity\Entity;
   
   #[Entity]
   class Book
   {
       #[Id]
       private int $id;
   
       #[Column]
       private string $title;
   }
   

   Run migrations:

   bin/console articulate:migrate
   

Implementation Patterns

Dependency Injection

• EntityManager: Inject EntityManager into services for CRUD operations:

  use Articulate\Modules\EntityManager\EntityManager;
  
  final class BookService
  {
      public function __construct(private EntityManager $em) {}
  
      public function createBook(string $title): Book
      {
          $book = new Book();
          $book->title = $title;
          $this->em->persist($book);
          $this->em->flush();
          return $book;
      }
  }
  

• Connection: Use Articulate\Connection for raw queries:

  use Articulate\Connection;
  
  final class RawQueryService
  {
      public function __construct(private Connection $connection) {}
  
      public function fetchBooks(): array
      {
          return $this->connection->query('SELECT * FROM books')->fetchAll();
      }
  }
  

Workflows

1. Entity Lifecycle:

   • Define entities with #[Entity], #[Id], and #[Column] attributes.
   • Use EntityManager::persist(), flush(), and remove() for changes.

2. Migrations:

   • Generate migrations via bin/console articulate:diff.
   • Apply with bin/console articulate:migrate.

3. Validation:

   • Validate entities with bin/console articulate:validate.

4. Caching:

   • Leverage cache configurations (e.g., result, statement) for performance.

Integration Tips

• Symfony Forms: Bind entities to forms using EntityType:

  use Symfony\Bridge\Doctrine\Form\Type\EntityType;
  
  $builder->add('book', EntityType::class, [
      'class' => Book::class,
      'choice_label' => 'title',
  ]);
  

• Doctrine Bridge: If using Doctrine, map Articulate entities to Doctrine entities for hybrid workflows (requires custom logic).

Gotchas and Tips

Pitfalls

1. Entity Naming:

   • Ensure entity class names match table names (e.g., Book → books). Override with #[Table(name: "custom_name")].

2. Migration Conflicts:

   • Run articulate:diff before articulate:migrate to avoid schema mismatches.
   • Backup migrations if rolling back.

3. Caching Quirks:

   • Clear caches (cache:clear) after schema changes to avoid stale queries.
   • Second-level cache (second_level_ttl) may cause stale data if TTL is too long.

4. Debugging:

   • Enable logging (logging: enabled: true) for SQL queries and errors.
   • Use bin/console articulate:validate to catch entity definition issues early.

Tips

1. Custom Attributes: Extend Articulate’s attributes (e.g., #[Index], #[Unique]) for advanced schema control.

2. Environment-Specific Configs: Override articulate.yaml per environment (e.g., articulate_test.yaml) for testing.

3. Event Listeners: Attach listeners to EntityManager for pre/post-persist/remove logic:

   $em->getEventManager()->addEventListener(
       EntityEvents::PRE_PERSIST,
       fn($event) => $event->getEntity()->setCreatedAt(new \DateTime())
   );
   

4. Performance:

   • Use EntityManager::createQueryBuilder() for complex queries:

     $books = $this->em->createQueryBuilder(Book::class)
         ->where('title LIKE :title')
         ->setParameter('title', '%PHP%')
         ->getQuery()
         ->getResult();
     

5. Testing:

   • Use EntityManager::beginTransaction()/rollback() for transactional tests:

     $this->em->beginTransaction();
     try {
         $this->em->persist($book);
         $this->em->flush();
         $this->em->commit();
     } catch (\Exception $e) {
         $this->em->rollback();
     }