{
    "slug": "pdo_fetch_modes",
    "term": "PDO Fetch Modes",
    "category": "php",
    "difficulty": "beginner",
    "short": "Constants controlling how PDO returns rows — as arrays, objects, or custom classes.",
    "long": "PDO::FETCH_ASSOC returns associative arrays (column name keys). PDO::FETCH_OBJ returns stdClass objects. PDO::FETCH_CLASS maps rows directly into a specified class. PDO::FETCH_COLUMN returns a single column as a flat array. PDO::FETCH_KEY_PAIR returns a two-column result as key→value pairs. Setting PDO::ATTR_DEFAULT_FETCH_MODE on the connection avoids repeating the constant on every fetch() call.",
    "aliases": [
        "PDO::FETCH_ASSOC",
        "PDO::FETCH_OBJ",
        "PDO::FETCH_CLASS",
        "fetchAll modes"
    ],
    "tags": [
        "php",
        "database",
        "pdo"
    ],
    "misconception": "FETCH_OBJ is better than FETCH_ASSOC. Both are fine — FETCH_ASSOC is safer because array access is explicit and less likely to collide with object method names.",
    "why_it_matters": "Choosing the right fetch mode reduces boilerplate — FETCH_ASSOC is safe and predictable, FETCH_CLASS removes manual mapping from result arrays to domain objects.",
    "common_mistakes": [
        "Using the default FETCH_BOTH which returns both numeric and named keys, wasting memory.",
        "Forgetting to set a default fetch mode and using different modes inconsistently across the codebase.",
        "Using FETCH_OBJ on untrusted data where property names may conflict with magic methods."
    ],
    "when_to_use": [
        "Use FETCH_ASSOC as the default for all queries — explicit, predictable, no memory waste.",
        "Use FETCH_CLASS when mapping query results directly to domain model objects.",
        "Use FETCH_KEY_PAIR when building id→name lookup maps from two-column queries."
    ],
    "avoid_when": [
        "Avoid FETCH_BOTH — it duplicates every value under both numeric and named keys, wasting memory.",
        "Avoid FETCH_OBJ on untrusted column names — property names from user-controlled data can shadow object methods."
    ],
    "related": [
        "pdo",
        "prepared_statement",
        "db_transactions"
    ],
    "prerequisites": [
        "pdo",
        "prepared_statement"
    ],
    "refs": [
        "https://www.php.net/manual/en/pdostatement.fetch.php"
    ],
    "bad_code": "// FETCH_BOTH wastes memory — every value stored twice\n$row = $stmt->fetch(PDO::FETCH_BOTH); // ['id'=>1, 0=>1, 'email'=>'...', 1=>'...']",
    "good_code": "$pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);\n\n// FETCH_ASSOC — safe default\n$row = $stmt->fetch(); // ['id' => 1, 'email' => '...']\n\n// FETCH_CLASS — auto-map to domain object\n$stmt->setFetchMode(PDO::FETCH_CLASS, User::class);\n$user = $stmt->fetch(); // User instance with properties set\n\n// FETCH_COLUMN — flat array of one column\n$emails = $stmt->fetchAll(PDO::FETCH_COLUMN, 0);\n\n// FETCH_KEY_PAIR — id => name map\n$map = $pdo->query('SELECT id, name FROM roles')->fetchAll(PDO::FETCH_KEY_PAIR);",
    "quick_fix": "Set PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC in the PDO constructor options array",
    "effort": "low",
    "created": "2026-03-31",
    "updated": "2026-03-31",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/pdo_fetch_modes",
        "html_url": "https://codeclaritylab.com/glossary/pdo_fetch_modes",
        "json_url": "https://codeclaritylab.com/glossary/pdo_fetch_modes.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": "[PDO Fetch Modes](https://codeclaritylab.com/glossary/pdo_fetch_modes) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/pdo_fetch_modes"
            }
        }
    }
}