---
title: "Use enums instead of magic strings · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/data-shapes/enums-not-strings
updated: 2026-10-20
licence: "All rights reserved"
---

# Use enums instead of magic strings

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Required
- Chapter: [Data shapes](https://agentwranglers.se/playbook/architecture/data-shapes)
- Rule: Give every fixed set of values an enum or union type. Never compare against loose strings such as `"paid"`.
- How: Define the set once, and use it in signatures, database mapping and tests. The type checker then catches typos and missing cases. At an API boundary, also follow [use enums for fixed values](https://agentwranglers.se/playbook/api-design/requests-and-responses/api-enums), so clients survive values added later.
- Check: The tools flag unhandled cases. Examples are typescript-eslint `switch-exhaustiveness-check` and PHPStan's check that a `match` covers every enum case. Reviewers fail comparisons of status fields with string literals.

Example:

```php
// Bad: a typo compiles and fails quietly
if ($order->status === 'payed') { /* ... */ }

// Good: the set of values is a type
enum OrderStatus: string { case Pending = 'pending'; case Paid = 'paid'; case Refunded = 'refunded'; }
if ($order->status === OrderStatus::Paid) { /* ... */ }
```

```python
from enum import StrEnum

class OrderStatus(StrEnum):
    PENDING = "pending"
    PAID = "paid"
    REFUNDED = "refunded"

if order.status is OrderStatus.PAID: ...
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers architecture playbook: https://agentwranglers.se/playbook/architecture/data-shapes/enums-not-strings`.

- Previous: [Model each state as its own type](https://agentwranglers.se/playbook/architecture/data-shapes/states-as-types)
- Next: [Give each function one return type](https://agentwranglers.se/playbook/architecture/data-shapes/one-return-type)
- [Data shapes](https://agentwranglers.se/playbook/architecture/data-shapes)