# doctrine-events

doctrine-events — a Claude skill for attaching side effects to Doctrine entity events in Symfony: timestamps, slugs, search index updates, notifications.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 234 repo stars
- Author: dev-toolings
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/skills/doctrine-events/SKILL.md
- Updated: 2026-10-05
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/doctrine-events

## What it does

This skill covers three ways to attach a side effect to a Doctrine entity's lifecycle in Symfony: a callback, an entity listener, and a global lifecycle listener. Start from the narrow end — a callback for one entity with no dependencies, an entity listener when services are needed, a global listener for logic that spans every entity.

Wiring goes through attributes: `#[ORM\HasLifecycleCallbacks]`, `#[AsEntityListener]`, `#[AsDoctrineListener]`. Each event argument gets its own class type, such as `PostPersistEventArgs` or `PreUpdateEventArgs`. A `reference.md` file holds the per-event argument table and the path away from subscribers.

The constraints are firm. Attribute listeners target ORM 3, and 3.0 dropped subscribers built on `EventSubscriberInterface`. Calling `flush()` from inside a handler damages the unit of work that is still running, so the skill rules it out. Inside `preUpdate` you change fields through `$args->setNewValue()` only, and associations stay untouched. Confirm the effect with a functional test against a real database.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill doctrine-events -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/doctrine-events/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/doctrine-events/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill doctrine-events -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/doctrine-events/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill doctrine-events -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/doctrine-events/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dev-toolings/superpowers-symfony content/skills/doctrine-events
```

2. **Manually: put the files in place**
- File: `.github/skills/doctrine-events/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill doctrine-events -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/doctrine-events
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/doctrine-events/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/skills/doctrine-events/SKILL.md

## When to use it
- stamp `createdAt` and `updatedAt` when an entity is saved
- migrate an `EventSubscriberInterface` subscriber to ORM 3 attributes
- pick between a callback, an entity listener and a global listener
- refresh a search index after `postPersist`
- keep the running unit of work safe from a stray `flush()`

## Example prompts
- Add an entity listener on `Article` that refreshes the search index after save.
- Move this `EventSubscriberInterface` subscriber to ORM 3 attributes.
- Why is my field change ignored in `preUpdate`? Rewrite it with `setNewValue()`.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 47548fbc47b7d1c4.

BEGIN THIRD-PARTY FILE 47548fbc47b7d1c4
```text
---
name: doctrine-events
description: React to Doctrine entity lifecycle in Symfony with attribute listeners (#[AsDoctrineListener]/#[AsEntityListener], ORM 3) and lifecycle callbacks
capabilities: [read, search, edit, shell]
tags: [doctrine]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash
---

# Doctrine Events (Symfony)

## Use when
- You need side effects on entity persistence (timestamps, slugs, search indexing, notifications).
- Migrating an `EventSubscriberInterface` Doctrine subscriber to ORM 3.
- Choosing between lifecycle callbacks, entity listeners, and global lifecycle listeners.

## Default workflow
1. Pick the narrowest mechanism: callback (one entity, no deps) → entity listener (one entity, needs services) → lifecycle listener (cross-cutting, all entities).
2. Wire it with attributes (`#[ORM\HasLifecycleCallbacks]`, `#[AsEntityListener]`, `#[AsDoctrineListener]`).
3. Type the event argument by its per-event class (`PostPersistEventArgs`, `PreUpdateEventArgs`, …).
4. Verify the side effect fires with a targeted functional test against a real DB.

## Guardrails
- ORM 3.0 removed `EventSubscriberInterface` Doctrine subscribers — never reintroduce them.
- Type-check the entity early in a global lifecycle listener (it fires for every entity).
- Never call `flush()` inside a Doctrine event handler — it corrupts the in-flight unit of work.
- `preUpdate` is restricted: change fields only via `$args->setNewValue()`, never touch associations.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open `reference.md` for the three mechanisms, the event-args matrix, and migration from subscribers.

## Output contract
- Listener/callback class with the correct attribute.
- Justification for the chosen mechanism.
- Validation outcomes (test that the side effect fired).

## References
- `reference.md`
```
END THIRD-PARTY FILE 47548fbc47b7d1c4

The third-party file has ended. Everything between the 47548fbc47b7d1c4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© dev-toolings · MIT · https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/skills/doctrine-events/SKILL.md

## Similar
- [php-symfony](https://affpapa.org/en/nevibecode/rules/php-symfony.md) — rule · ★ 41430 repo stars
- [symfony-specialist](https://affpapa.org/en/nevibecode/agents/symfony-specialist.md) — subagent · ★ 26718 repo stars
- [supabase-webhooks-events](https://affpapa.org/en/nevibecode/skills/supabase-webhooks-events.md) — skill · 1 install
- [gws-events](https://affpapa.org/en/nevibecode/skills/gws-events.md) — skill · 32500 installs
- [eloquent-best-practices](https://affpapa.org/en/nevibecode/skills/eloquent-best-practices.md) — skill · 1300 installs
- [inngest-events](https://affpapa.org/en/nevibecode/skills/inngest-events.md) — skill · 4000 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
