config-schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "$comment": "`taplo` and the corresponding VS Code plugins only support version draft-04 of JSON Schema, see <https://taplo.tamasfe.dev/configuration/developing-schemas.html>. draft-07 is mostly compatible with it, newer versions may not be.",
  "title": "PHPantom Configuration",
  "description": "User configuration schema for .phpantom.toml: per-project settings for the PHPantom PHP language server.",
  "type": "object",
  "properties": {
    "php": {
      "type": "object",
      "description": "PHP version and language settings.",
      "properties": {
        "version": {
          "type": "string",
          "description": "Override the detected PHP version (e.g. \"8.3\"). When unset, PHPantom infers from composer.json's platform or require.php.",
          "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
        }
      }
    },
    "diagnostics": {
      "type": "object",
      "description": "Toggle individual diagnostic providers.",
      "properties": {
        "unresolved-member-access": {
          "type": "boolean",
          "description": "Report member access (->, ?->, ::) on subjects whose type could not be resolved. Useful for discovering gaps in type coverage but produces too many diagnostics on codebases without comprehensive type annotations.",
          "default": false
        },
        "extra-arguments": {
          "type": "boolean",
          "description": "Report calls that pass more arguments than the function accepts. PHP silently ignores extra arguments to user-defined functions, and many libraries exploit this for flexible APIs.",
          "default": false
        },
        "report-magic-properties": {
          "type": "boolean",
          "description": "Report unknown property access on classes with __get when virtual properties are defined (via @property docblock tags, Laravel Eloquent column inference, or other providers). Matches PHPStan's reportMagicProperties behaviour.",
          "default": false
        },
        "workspace": {
          "type": "boolean",
          "description": "Compute diagnostics for the whole workspace in the background after startup and the full index finish, so project-wide problems appear for files that are not open in the editor. Requires the default \"full\" indexing strategy.",
          "default": true
        },
        "workspace-external": {
          "type": "boolean",
          "description": "Run configured external tools (PHPStan, PHPCS, Mago) once over the whole project after workspace diagnostics finish. Each tool only runs when it is enabled and has its own project-level configuration file (phpstan.neon, phpcs.xml, mago.toml).",
          "default": true
        },
        "ignore": {
          "type": "array",
          "description": "Rules that suppress matching diagnostics, similar to PHPStan's ignoreErrors. Each rule may constrain by message (regex), path (glob relative to workspace root), and/or identifier (diagnostic code). A diagnostic is suppressed when it matches every constraint present on a rule; omitted constraints match anything.",
          "items": {
            "type": "object",
            "description": "A single ignore rule. At least one constraint (message, path, or identifier) must be present.",
            "properties": {
              "message": {
                "type": "string",
                "description": "Regex matched against the diagnostic message."
              },
              "path": {
                "type": "string",
                "description": "Glob matched against the file path relative to the workspace root. Follows gitignore-style glob syntax: * does not cross /, use ** to match across directories."
              },
              "identifier": {
                "type": "string",
                "description": "Diagnostic identifier (the diagnostic code, e.g. \"unused_import\", \"deprecated_usage\")."
              }
            }
          }
        }
      }
    },
    "indexing": {
      "type": "object",
      "description": "Controls how PHPantom discovers classes across the workspace.",
      "properties": {
        "strategy": {
          "type": "string",
          "description": "The indexing strategy for class discovery. \"full\" (default): scan PHP files, then background-parse user files to populate symbol and reference indexes. \"composer\": use Composer's classmap, fall back to self-scan. \"self\": scan all PHP files, ignore classmap. \"none\": no proactive scanning, classmap only.",
          "enum": [
            "composer",
            "self",
            "full",
            "none"
          ],
          "default": "full"
        }
      }
    },
    "semantic_tokens": {
      "type": "object",
      "description": "Controls LSP semantic token highlighting.",
      "properties": {
        "mode": {
          "type": "string",
          "description": "Semantic token emission mode. \"contextual\" emits only context-sensitive tokens that complement editor syntax highlighting. \"full\" emits the complete semantic token stream. \"off\" disables semantic tokens.",
          "enum": [
            "contextual",
            "full",
            "off"
          ],
          "default": "contextual"
        }
      }
    },
    "laravel": {
      "type": "object",
      "description": "Laravel-specific analysis settings.",
      "properties": {
        "schema": {
          "type": "object",
          "description": "Controls Laravel database schema dump scanning for Eloquent model property inference.",
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Enable Laravel schema dump scanning. When enabled, PHPantom scans database/schema by default.",
              "default": true
            },
            "paths": {
              "type": "array",
              "description": "Schema dump files or directories to scan, relative to the workspace root unless absolute. Defaults to [\"database/schema\"].",
              "items": {
                "type": "string"
              },
              "default": [
                "database/schema"
              ]
            }
          }
        },
        "migrations": {
          "type": "object",
          "description": "Controls Laravel migration scanning for Eloquent model property inference.",
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Enable Laravel migration scanning. When enabled, PHPantom scans direct PHP files in non-vendor database/migrations directories by default.",
              "default": true
            },
            "paths": {
              "type": "array",
              "description": "Migration files or directories to scan, relative to the workspace root unless absolute. Direct PHP files in directories are scanned; subdirectories are not scanned.",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "formatting": {
      "type": "object",
      "description": "Controls the formatting strategy. PHPantom ships a built-in formatter (PER-CS 2.0 style). Projects with php-cs-fixer or PHP_CodeSniffer in composer.json require-dev automatically use those tools instead. Explicit configuration here always takes priority.",
      "properties": {
        "pint": {
          "type": "string",
          "description": "Command or path to run Laravel Pint. Unset: auto-detect from composer.json require-dev. Empty string: disable Pint. Any other value: use as the command."
        },
        "php-cs-fixer": {
          "type": "string",
          "description": "Command or path to run php-cs-fixer. Unset: auto-detect from composer.json require-dev. Empty string: disable php-cs-fixer. Any other value: use as the command."
        },
        "phpcbf": {
          "type": "string",
          "description": "Command or path to run phpcbf. Unset: auto-detect from composer.json require-dev. Empty string: disable phpcbf. Any other value: use as the command."
        },
        "timeout": {
          "type": "integer",
          "description": "Maximum runtime in milliseconds per external formatting tool before it is killed. Applied per tool, not for the combined pipeline.",
          "default": 10000,
          "minimum": 0
        }
      }
    },
    "phpstan": {
      "type": "object",
      "description": "PHPStan proxy settings. PHPantom can run PHPStan in editor mode on each file save and surface its errors as LSP diagnostics.",
      "properties": {
        "command": {
          "type": "string",
          "description": "Command or path to run PHPStan. Unset: auto-detect via vendor/bin/phpstan then $PATH. Empty string: disable PHPStan integration. Any other value: use as the command."
        },
        "memory-limit": {
          "type": "string",
          "description": "Memory limit passed to PHPStan via --memory-limit.",
          "default": "1G"
        },
        "timeout": {
          "type": "integer",
          "description": "Maximum runtime in milliseconds before PHPStan is killed.",
          "default": 60000,
          "minimum": 0
        }
      }
    },
    "phpcs": {
      "type": "object",
      "description": "PHP_CodeSniffer proxy settings. PHPantom can run PHPCS on each file save and surface its findings as LSP diagnostics.",
      "properties": {
        "command": {
          "type": "string",
          "description": "Command or path to run PHPCS. Unset: auto-detect via vendor/bin/phpcs then $PATH. Empty string: disable PHPCS integration. Any other value: use as the command."
        },
        "standard": {
          "type": "string",
          "description": "Coding standard to enforce (e.g. \"PSR12\"). Unset: PHPCS uses its own default detection (phpcs.xml / phpcs.xml.dist in the project root, then its built-in default)."
        },
        "timeout": {
          "type": "integer",
          "description": "Maximum runtime in milliseconds before PHPCS is killed.",
          "default": 30000,
          "minimum": 0
        }
      }
    },
    "mago": {
      "type": "object",
      "description": "Mago proxy settings. Mago is only activated when mago.toml exists at the workspace root. PHPantom can run mago lint and mago analyze on each file save and surface their findings as LSP diagnostics.",
      "properties": {
        "command": {
          "type": "string",
          "description": "Command or path to run Mago. Unset: auto-detect via vendor/bin/mago then $PATH. Empty string: disable Mago integration. Any other value: use as the command."
        },
        "lint-timeout": {
          "type": "integer",
          "description": "Maximum runtime in milliseconds before mago lint is killed.",
          "default": 30000,
          "minimum": 0
        },
        "analyze-timeout": {
          "type": "integer",
          "description": "Maximum runtime in milliseconds before mago analyze is killed.",
          "default": 60000,
          "minimum": 0
        }
      }
    }
  }
}