{
    "slug": "magic_strings",
    "term": "Magic Strings",
    "category": "style",
    "difficulty": "beginner",
    "short": "Raw string literals used directly in code as identifiers or flags — prone to typos, hard to refactor, and lacking IDE support.",
    "long": "Magic strings are the string equivalent of magic numbers: inline string literals like 'admin', 'pending', or 'user_created' used as status values, event names, or configuration keys. They cause typo bugs that aren't caught until runtime, resist refactoring (no IDE rename support), and offer no context to readers. Replace them with constants, enums (PHP 8.1+), or class constants — these are findable, renameable, and document valid values in one place.",
    "aliases": [
        "magic string",
        "hardcoded string literal",
        "unnamed string constant"
    ],
    "tags": [
        "style",
        "code-smell",
        "maintainability"
    ],
    "misconception": "Magic strings are only a problem when the same string appears in multiple places. A single unexplained string like \"pending\" in a status check is still a magic string — a named constant Status::PENDING is refactoring-safe, self-documenting, and IDE-navigable.",
    "why_it_matters": "Magic strings are literal string values used directly in code without explanation or central definition — a typo in one copy goes undetected because there is no single source of truth to validate against.",
    "common_mistakes": [
        "Status values as strings scattered across the codebase: 'active', 'pending', 'inactive' — define as constants or enums.",
        "Event names as raw strings: event('user.created') — a typo in the listener silently misses the event.",
        "Config keys as inline strings repeated everywhere — one rename requires searching the whole codebase.",
        "Error message strings duplicated in multiple places — they diverge and give users inconsistent messages."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "magic_number",
        "enums",
        "naming_conventions"
    ],
    "prerequisites": [
        "magic_numbers",
        "clean_code_naming",
        "enums"
    ],
    "refs": [
        "https://en.wikipedia.org/wiki/Magic_string"
    ],
    "bad_code": "if ($user->role === 'admin') { /* typo risk */ }",
    "good_code": "if ($user->role === Role::ADMIN->value) { /* enum backed by string */ }",
    "quick_fix": "Replace string literals used as status codes, types, or identifiers with PHP 8.1 enums or class constants — they're refactoring-safe and PHPStan can verify exhaustiveness",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/magic_strings",
        "html_url": "https://codeclaritylab.com/glossary/magic_strings",
        "json_url": "https://codeclaritylab.com/glossary/magic_strings.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Magic Strings](https://codeclaritylab.com/glossary/magic_strings) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/magic_strings"
            }
        }
    }
}