From 9c9bcdd1da4cb326bcf7ce34d9bd6690ee16832e Mon Sep 17 00:00:00 2001 From: Moritz Wirger Date: Wed, 2 Sep 2026 12:36:41 +0200 Subject: [PATCH 1/3] Make disabling formatting explicit --- src/config/tests.rs | 16 ++++++++++++++++ src/config/tools.rs | 9 ++++----- src/formatting/tests.rs | 5 +++++ 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/src/config/tests.rs b/src/config/tests.rs index e536990a8..201fab8b6 100644 --- a/src/config/tests.rs +++ b/src/config/tests.rs @@ -771,6 +771,22 @@ fn formatting_empty_string_disables_tool() { assert_eq!(config.formatting.php_cs_fixer.as_deref(), Some("")); assert_eq!(config.formatting.phpcbf.as_deref(), Some("")); assert_eq!(config.formatting.pint.as_deref(), Some("")); + assert!(!config.formatting.is_disabled()); +} + +#[test] +fn formatting_disabled_disables_tool() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join(CONFIG_FILE_NAME); + std::fs::write( + &path, + "[formatting]\ndisabled = true\nphp-cs-fixer = \"\"\nphpcbf = \"\"\npint = \"\"\n", + ) + .unwrap(); + let config = load_config(dir.path()).unwrap(); + assert_eq!(config.formatting.php_cs_fixer.as_deref(), Some("")); + assert_eq!(config.formatting.phpcbf.as_deref(), Some("")); + assert_eq!(config.formatting.pint.as_deref(), Some("")); assert!(config.formatting.is_disabled()); } diff --git a/src/config/tools.rs b/src/config/tools.rs index 5a4535274..9cf6989f4 100644 --- a/src/config/tools.rs +++ b/src/config/tools.rs @@ -18,6 +18,8 @@ use serde::Deserialize; #[derive(Debug, Clone, Default, Deserialize)] #[serde(default)] pub struct FormattingConfig { + /// Explicitly disable all formatting + pub disabled: Option, /// Command (path or name) to run php-cs-fixer. /// /// - `None` (default) — check `require-dev` in `composer.json`; @@ -90,12 +92,9 @@ impl FormattingConfig { self.timeout.unwrap_or(10_000) } - /// Whether formatting is entirely disabled (every tool explicitly - /// set to an empty string). + /// Whether formatting is explicitly disabled pub fn is_disabled(&self) -> bool { - crate::formatting::Tool::ALL - .into_iter() - .all(|tool| tool.configured(self) == Some("")) + self.disabled == Some(true) } } diff --git a/src/formatting/tests.rs b/src/formatting/tests.rs index d64473856..265b366fa 100644 --- a/src/formatting/tests.rs +++ b/src/formatting/tests.rs @@ -272,6 +272,7 @@ fn malformed_mago_toml_returns_error_not_panic() { #[test] fn strategy_both_disabled() { let config = FormattingConfig { + disabled: Some(false), pint: Some(String::new()), php_cs_fixer: Some(String::new()), phpcbf: Some(String::new()), @@ -287,6 +288,7 @@ fn strategy_both_disabled() { #[test] fn strategy_explicit_commands() { let config = FormattingConfig { + disabled: Some(false), pint: None, php_cs_fixer: Some("/usr/bin/php-cs-fixer".to_string()), phpcbf: Some("/usr/bin/phpcbf".to_string()), @@ -311,6 +313,7 @@ fn strategy_explicit_commands() { #[test] fn strategy_one_explicit_one_disabled() { let config = FormattingConfig { + disabled: Some(false), pint: None, php_cs_fixer: Some("/usr/bin/php-cs-fixer".to_string()), phpcbf: Some(String::new()), @@ -639,6 +642,7 @@ fn strategy_explicit_overrides_require_dev() { // User explicitly set a different path. let config = FormattingConfig { + disabled: Some(false), pint: None, php_cs_fixer: Some("/opt/php-cs-fixer".to_string()), phpcbf: Some(String::new()), @@ -904,6 +908,7 @@ fn execute_builtin_reformats_messy_class() { fn execute_disabled_returns_none() { let content = " Date: Tue, 8 Sep 2026 11:13:02 +0200 Subject: [PATCH 2/3] Invert logic --- src/config/tests.rs | 2 +- src/config/tools.rs | 4 ++-- src/formatting/tests.rs | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/config/tests.rs b/src/config/tests.rs index 201fab8b6..54e6f70f6 100644 --- a/src/config/tests.rs +++ b/src/config/tests.rs @@ -780,7 +780,7 @@ fn formatting_disabled_disables_tool() { let path = dir.path().join(CONFIG_FILE_NAME); std::fs::write( &path, - "[formatting]\ndisabled = true\nphp-cs-fixer = \"\"\nphpcbf = \"\"\npint = \"\"\n", + "[formatting]\nenabled = false\nphp-cs-fixer = \"\"\nphpcbf = \"\"\npint = \"\"\n", ) .unwrap(); let config = load_config(dir.path()).unwrap(); diff --git a/src/config/tools.rs b/src/config/tools.rs index 9cf6989f4..3d756e13b 100644 --- a/src/config/tools.rs +++ b/src/config/tools.rs @@ -19,7 +19,7 @@ use serde::Deserialize; #[serde(default)] pub struct FormattingConfig { /// Explicitly disable all formatting - pub disabled: Option, + pub enabled: Option, /// Command (path or name) to run php-cs-fixer. /// /// - `None` (default) — check `require-dev` in `composer.json`; @@ -94,7 +94,7 @@ impl FormattingConfig { /// Whether formatting is explicitly disabled pub fn is_disabled(&self) -> bool { - self.disabled == Some(true) + self.enabled == Some(false) } } diff --git a/src/formatting/tests.rs b/src/formatting/tests.rs index 265b366fa..5c69bfd37 100644 --- a/src/formatting/tests.rs +++ b/src/formatting/tests.rs @@ -272,7 +272,7 @@ fn malformed_mago_toml_returns_error_not_panic() { #[test] fn strategy_both_disabled() { let config = FormattingConfig { - disabled: Some(false), + enabled: Some(true), pint: Some(String::new()), php_cs_fixer: Some(String::new()), phpcbf: Some(String::new()), @@ -288,7 +288,7 @@ fn strategy_both_disabled() { #[test] fn strategy_explicit_commands() { let config = FormattingConfig { - disabled: Some(false), + enabled: Some(true), pint: None, php_cs_fixer: Some("/usr/bin/php-cs-fixer".to_string()), phpcbf: Some("/usr/bin/phpcbf".to_string()), @@ -313,7 +313,7 @@ fn strategy_explicit_commands() { #[test] fn strategy_one_explicit_one_disabled() { let config = FormattingConfig { - disabled: Some(false), + enabled: Some(true), pint: None, php_cs_fixer: Some("/usr/bin/php-cs-fixer".to_string()), phpcbf: Some(String::new()), @@ -642,7 +642,7 @@ fn strategy_explicit_overrides_require_dev() { // User explicitly set a different path. let config = FormattingConfig { - disabled: Some(false), + enabled: Some(true), pint: None, php_cs_fixer: Some("/opt/php-cs-fixer".to_string()), phpcbf: Some(String::new()), @@ -908,7 +908,7 @@ fn execute_builtin_reformats_messy_class() { fn execute_disabled_returns_none() { let content = " Date: Mon, 16 Nov 2026 07:17:54 +0100 Subject: [PATCH 3/3] Finalize PR --- config-schema.json | 4 ++++ docs/CHANGELOG.md | 2 ++ docs/configuration.md | 5 ++++- src/config/tests.rs | 31 ++++++++++++++++++++++--------- src/config/tools.rs | 10 +++++++--- src/format_cli/tests.rs | 18 +++++++++++++++++- src/formatting/blade/tests.rs | 4 +--- src/formatting/mod.rs | 4 ++-- src/formatting/tests.rs | 23 ++++++++++++++++++++++- 9 files changed, 81 insertions(+), 20 deletions(-) diff --git a/config-schema.json b/config-schema.json index 8fa629968..d835dafc7 100644 --- a/config-schema.json +++ b/config-schema.json @@ -246,6 +246,10 @@ "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": { + "enabled": { + "type": "boolean", + "description": "Whether formatting is enabled at all. Unset or true: format with the resolved strategy. false: answer no formatting requests, the built-in formatter included." + }, "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." diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d1165bcd1..7c1464b40 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -201,6 +201,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Stubs that override.** List stub files and directories under `[stubs] paths` in `.phpantom.toml`, and what they declare wins over every other declaration of the same name, PHP's own built-in stubs included. Use it for hand-written stubs of a PHP extension or to correct a signature you disagree with. Stub files are never analysed or edited, and an editor extension can pass a bundled stubs directory the same way. See [configuration.md](configuration.md#stubs). - **The other folders of a multi-root workspace resolve.** Classes, functions, and constants declared in another folder of the editor's workspace now complete, resolve, and jump to their declaration from this one. That folder is treated as a library, like `vendor/`, so its own diagnostics and renames stay with the folder itself. Adding or removing a folder takes effect without a restart. - **Stub packages installed with Composer.** A stub package such as `php-stubs/wordpress-stubs` or `php-stubs/woocommerce-stubs` works like a `[stubs]` path with nothing to configure, so WordPress and WooCommerce functions and classes resolve in a theme or plugin that requires them. An installed `jetbrains/phpstorm-stubs` takes over PHP's own functions and classes, and go-to-definition on a built-in opens it there. Installing, updating, or removing a package takes effect without a restart. +- **Turn formatting off.** `enabled = false` under `[formatting]` in `.phpantom.toml` stops PHPantom from formatting, built-in formatter included. Contributed by @enwi. ### Changed @@ -215,6 +216,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Diagnostic identifiers follow one naming scheme.** Ahead of 1.0, these were renamed: `invalid_member_access` is now `inaccessible_member`, `invalid_laravel_trans` is `invalid_laravel_translation`, `invalid_command_parameter` is `invalid_laravel_command_parameter`, `missing_view_variable`, `unused_view_variable` and `type_mismatch_view_variable` are `missing_blade_variable`, `unused_blade_variable` and `type_mismatch_blade_variable`, and `blade_signature_widens_layout` is `incompatible_blade_signature`. The old names keep working in `[[diagnostics.ignore]]`, `@phpantom-ignore` and `analyze --code`, and the config and command line warn when they meet one. The [Diagnostics Reference](diagnostics.md) lists every identifier. - **Configuration names follow one spelling.** Ahead of 1.0, every section and key in `.phpantom.toml` is kebab-case: `[semantic_tokens]` is now `[semantic-tokens]`, `[inlay_hints]` is `[inlay-hints]`, and `report-magic-properties` under `[diagnostics]` is `magic-properties`, to match the other diagnostic toggles. The old names keep working, with a warning that names the new one. - **A member used on a class that cannot be found is reported as `unknown_class`.** "Cannot check method save(), because type App\Models\User could not be resolved" used to carry `unknown_member`. It now carries `unknown_class`, so ignoring missing classes covers it too, and `unknown_member` is left for members a class really lacks. +- **Disabling every external formatter keeps the built-in one.** Setting `pint`, `php-cs-fixer`, and `phpcbf` all to `""` under `[formatting]` now formats with the built-in formatter instead of turning formatting off. Use `enabled = false` to turn it off. Contributed by @enwi. - **Updated embedded phpstorm-stubs.** Adds the `ps`, `proctitle`, and `yaz` extensions, updates Judy and Relay, and corrects many parameter and return types to match the PHP documentation, including `oci_fetch_object()`, `pg_loopen()`, and nullable RdKafka message payloads. #### Performance and memory diff --git a/docs/configuration.md b/docs/configuration.md index 879bdbc28..e63e629af 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -306,6 +306,7 @@ Your editor can switch these off too, see [Editor-supplied inlay hint toggles](# | Key | Type | Default | Description | | -------------- | ------- | ------- | ----------- | +| `enabled` | boolean | unset | Whether formatting is enabled at all. Unset or `true`: format with the strategy below. `false`: turn formatting off, built-in formatter included. | | `pint` | string | unset | Command or path for Laravel Pint. Unset: auto-detect from `require-dev`. `""`: disable. | | `pint-blade` | boolean | unset | Whether `.blade.php` files are formatted by Pint's `Pint/laravel_blade` rule. Unset: follow the workspace `pint.json`. `true`: send them to Pint with `--blade`. `false`: never. | | `blade-formatter` | string | unset | Command or path for [blade-formatter](https://github.com/shufo/blade-formatter), used for `.blade.php` files. Unset: use it when the project does (see below). `""`: never. Any other value: always, even over Pint. | @@ -428,7 +429,9 @@ PHPantom ships a built-in PHP formatter (mago-formatter) that works out of the b 1. **Explicit config wins.** A tool path set under `[formatting]` in `.phpantom.toml` (`pint`, `php-cs-fixer`, or `phpcbf`) is always used. Setting a tool to `""` disables it. 2. **Composer `require-dev` wins over the built-in formatter.** If `composer.json` lists `laravel/pint`, `friendsofphp/php-cs-fixer`, or `squizlabs/php_codesniffer` in `require-dev`, PHPantom resolves the binary through Composer's bin-dir and runs it as a subprocess. A `phpcs.xml`, `.phpcs.xml`, `phpcs.xml.dist`, or `.phpcs.xml.dist` file at the workspace root certifies phpcbf the same way, so a project that only pulls `squizlabs/php_codesniffer` in transitively (e.g. through `slevomat/coding-standard`) is still detected. These tools discover their own project config (`pint.json`, `.php-cs-fixer.php`, `.phpcs.xml`, etc.) as they normally would. -3. **Otherwise, the built-in formatter is used.** +3. **Otherwise, the built-in formatter is used.** This includes projects that set every external tool to `""`. + +To turn formatting off entirely, set `enabled = false` under `[formatting]`. **Formatting a selection** (`textDocument/rangeFormatting`) works with every one of these. None of them can format part of a file, so PHPantom formats the whole file and applies only the changes on the selected lines. A change that runs past the edge of the selection is applied whole, so the file never ends up half-formatted mid-statement, and lines the formatter moved (sorted imports, for example) are moved as a unit rather than dropped or duplicated. diff --git a/src/config/tests.rs b/src/config/tests.rs index 54e6f70f6..6c3a33a4c 100644 --- a/src/config/tests.rs +++ b/src/config/tests.rs @@ -775,21 +775,34 @@ fn formatting_empty_string_disables_tool() { } #[test] -fn formatting_disabled_disables_tool() { +fn formatting_enabled_false_disables_formatting() { let dir = tempfile::tempdir().unwrap(); let path = dir.path().join(CONFIG_FILE_NAME); - std::fs::write( - &path, - "[formatting]\nenabled = false\nphp-cs-fixer = \"\"\nphpcbf = \"\"\npint = \"\"\n", - ) - .unwrap(); + std::fs::write(&path, "[formatting]\nenabled = false\n").unwrap(); let config = load_config(dir.path()).unwrap(); - assert_eq!(config.formatting.php_cs_fixer.as_deref(), Some("")); - assert_eq!(config.formatting.phpcbf.as_deref(), Some("")); - assert_eq!(config.formatting.pint.as_deref(), Some("")); + assert_eq!(config.formatting.enabled, Some(false)); assert!(config.formatting.is_disabled()); } +#[test] +fn formatting_enabled_true_is_not_disabled() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join(CONFIG_FILE_NAME); + std::fs::write(&path, "[formatting]\nenabled = true\n").unwrap(); + let config = load_config(dir.path()).unwrap(); + assert!(!config.formatting.is_disabled()); +} + +#[test] +fn formatting_enabled_unset_is_not_disabled() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join(CONFIG_FILE_NAME); + std::fs::write(&path, "[formatting]\ntimeout = 5000\n").unwrap(); + let config = load_config(dir.path()).unwrap(); + assert_eq!(config.formatting.enabled, None); + assert!(!config.formatting.is_disabled()); +} + #[test] fn formatting_defaults() { let config = Config::default(); diff --git a/src/config/tools.rs b/src/config/tools.rs index 3d756e13b..bf2b48b2f 100644 --- a/src/config/tools.rs +++ b/src/config/tools.rs @@ -14,11 +14,15 @@ use serde::Deserialize; /// Explicit configuration in `.phpantom.toml` always takes priority: /// set a tool path to use it, or set it to `""` to disable it. /// When no external tool is configured or detected, the built-in -/// formatter is used. +/// formatter is used. `enabled = false` turns formatting off entirely. #[derive(Debug, Clone, Default, Deserialize)] #[serde(default)] pub struct FormattingConfig { - /// Explicitly disable all formatting + /// Whether formatting is enabled at all. + /// + /// - `None` (default) or `true` — format with the resolved strategy. + /// - `false` — answer no formatting requests, built-in formatter + /// included. pub enabled: Option, /// Command (path or name) to run php-cs-fixer. /// @@ -92,7 +96,7 @@ impl FormattingConfig { self.timeout.unwrap_or(10_000) } - /// Whether formatting is explicitly disabled + /// Whether formatting is turned off with `enabled = false`. pub fn is_disabled(&self) -> bool { self.enabled == Some(false) } diff --git a/src/format_cli/tests.rs b/src/format_cli/tests.rs index 4cc404e7d..b35875997 100644 --- a/src/format_cli/tests.rs +++ b/src/format_cli/tests.rs @@ -188,7 +188,7 @@ fn formatting_disabled_in_config_reports_no_run_at_all() { write_file( dir.path(), ".phpantom.toml", - "[formatting]\npint = \"\"\nphp-cs-fixer = \"\"\nphpcbf = \"\"\n", + "[formatting]\nenabled = false\n", ); assert!( @@ -198,6 +198,22 @@ fn formatting_disabled_in_config_reports_no_run_at_all() { assert_eq!(run(options(dir.path(), true)), 0); } +#[test] +fn every_external_tool_disabled_still_formats_with_the_builtin_formatter() { + let dir = workspace(&[("src/Foo.php", " (Vec, Vec) { diff --git a/src/formatting/blade/tests.rs b/src/formatting/blade/tests.rs index 1a6dd1117..1ee2a31a4 100644 --- a/src/formatting/blade/tests.rs +++ b/src/formatting/blade/tests.rs @@ -1242,9 +1242,7 @@ fn blade_strategy_is_builtin_without_pint() { #[test] fn blade_strategy_is_disabled_when_formatting_is() { let config = FormattingConfig { - pint: Some(String::new()), - php_cs_fixer: Some(String::new()), - phpcbf: Some(String::new()), + enabled: Some(false), ..FormattingConfig::default() }; let strategy = resolve_blade_strategy(None, &config, None, None, PhpVersion::default()); diff --git a/src/formatting/mod.rs b/src/formatting/mod.rs index 65623ddd3..56cf7eb38 100644 --- a/src/formatting/mod.rs +++ b/src/formatting/mod.rs @@ -185,13 +185,13 @@ pub enum FormattingStrategy { /// the workspace root. /// /// Resolution rules: -/// - If `config.is_disabled()` (every tool set to `""`) → `Disabled`. +/// - If `config.is_disabled()` (`enabled = false`) → `Disabled`. /// - If any tool has an explicit non-empty path in config → /// `External` with those tools. /// - Otherwise every tool the project's metadata selects (see /// [`Tool::detected`]) and whose binary the Composer bin-dir holds → /// `External`. -/// - Otherwise → `BuiltIn`. +/// - Otherwise (including when every tool is set to `""`) → `BuiltIn`. /// /// `phpcs_standard` is the `[phpcs]` standard, handed on to phpcbf. pub fn resolve_strategy( diff --git a/src/formatting/tests.rs b/src/formatting/tests.rs index 5c69bfd37..b54ff3a76 100644 --- a/src/formatting/tests.rs +++ b/src/formatting/tests.rs @@ -270,7 +270,17 @@ fn malformed_mago_toml_returns_error_not_panic() { } #[test] -fn strategy_both_disabled() { +fn strategy_disabled() { + let config = FormattingConfig { + enabled: Some(false), + ..FormattingConfig::default() + }; + let strategy = resolve_strategy(None, &config, None, None, None); + assert!(matches!(strategy, FormattingStrategy::Disabled)); +} + +#[test] +fn strategy_all_tools_disabled_falls_back_to_builtin() { let config = FormattingConfig { enabled: Some(true), pint: Some(String::new()), @@ -282,6 +292,17 @@ fn strategy_both_disabled() { timeout: None, }; let strategy = resolve_strategy(None, &config, None, None, None); + assert!(matches!(strategy, FormattingStrategy::BuiltIn(None))); +} + +#[test] +fn strategy_disabled_wins_over_explicit_command() { + let config = FormattingConfig { + enabled: Some(false), + php_cs_fixer: Some("/usr/bin/php-cs-fixer".to_string()), + ..FormattingConfig::default() + }; + let strategy = resolve_strategy(None, &config, None, None, None); assert!(matches!(strategy, FormattingStrategy::Disabled)); }