{
    "slug": "composer_scripts",
    "term": "Composer Scripts & Hooks",
    "category": "php",
    "difficulty": "intermediate",
    "short": "Composer's scripts section automates tasks triggered on lifecycle events (install, update) or run manually — cache clearing, migrations, asset builds.",
    "long": "Composer scripts are shell commands or PHP callables in the scripts key of composer.json, executed automatically on lifecycle events (post-install-cmd, post-update-cmd, post-autoload-dump) or manually with composer run. Common uses: clearing caches, running migrations, generating IDE helper files, and compiling assets. Security concern: scripts from third-party packages run with the same privileges as the Composer process — always audit composer.json of new dependencies before running composer install in CI. Use --no-scripts to disable all scripts when trust is uncertain, such as when first evaluating a package.",
    "aliases": [
        "Composer scripts",
        "composer.json scripts",
        "Composer hooks"
    ],
    "tags": [
        "php",
        "composer",
        "devops",
        "automation"
    ],
    "misconception": "Composer scripts are only useful for running tests. Composer scripts can automate code generation, asset compilation, cache clearing, database migrations, and any shell command — they form a lightweight task runner built into every PHP project.",
    "why_it_matters": "Composer scripts automate common tasks (tests, linting, code generation) as project-level commands — they ensure every developer and CI pipeline runs tasks identically without separate documentation.",
    "common_mistakes": [
        "Not defining scripts for common tasks — developers run different commands and the team drifts.",
        "Scripts that run dev-only tools (phpstan, phpcs) without guarding against --no-dev production installs.",
        "Forgetting to chain scripts with @script syntax — duplicating command lists in multiple script entries.",
        "Not documenting custom scripts — composer run without arguments lists available scripts, but descriptions help."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "composer",
        "continuous_integration",
        "supply_chain_attack"
    ],
    "prerequisites": [
        "composer",
        "continuous_integration",
        "php_cs_fixer"
    ],
    "refs": [
        "https://getcomposer.org/doc/articles/scripts.md"
    ],
    "bad_code": "// No scripts defined — every dev runs slightly different commands:\n{\n  \"require\": {\"php\": \">=8.1\"},\n  \"require-dev\": {\"phpunit/phpunit\": \"^10\"}\n  // Missing: scripts.test, scripts.lint, scripts.analyse\n}",
    "good_code": "// composer.json scripts — automate common tasks\n{\n  \"scripts\": {\n    \"test\":     \"phpunit --colors=always\",\n    \"lint\":     \"phpcs --standard=PSR12 src/ tests/\",\n    \"lint:fix\": \"phpcbf --standard=PSR12 src/ tests/\",\n    \"analyse\":  \"phpstan analyse src/ --level=6\",\n    \"audit\":    \"composer audit\",\n    \"ci\":       [\"@lint\", \"@analyse\", \"@test\", \"@audit\"]\n  },\n  \"scripts-descriptions\": {\n    \"test\": \"Run PHPUnit test suite\",\n    \"ci\":   \"Run full CI pipeline locally\"\n  }\n}\n\n// Run:\n// $ composer test\n// $ composer ci\n// $ composer lint:fix",
    "quick_fix": "Define scripts in composer.json for common tasks: test, lint, analyse, check — then CI runs composer test instead of knowing the exact PHPUnit invocation",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/composer_scripts",
        "html_url": "https://codeclaritylab.com/glossary/composer_scripts",
        "json_url": "https://codeclaritylab.com/glossary/composer_scripts.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": "[Composer Scripts & Hooks](https://codeclaritylab.com/glossary/composer_scripts) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/composer_scripts"
            }
        }
    }
}