PHPLint for Nova

Check PHP syntax when you save, with errors and warnings in Nova's Issues sidebar and at their reported lines in the editor.

PHPLint uses your installed PHP command-line interpreter. It complements Nova's PHP editing features by checking syntax against the PHP version you choose. It does not run, format or modify your PHP code.

Version 1.0 adds per-project settings, manual checks, PHP installation detection and optional error and success notifications.

Requirements

Install PHP CLI on your Mac. For example, with Homebrew:

brew install php

Install PHPLint from Nova's Extension Library, then open a local project. Under Project → Project Settings → Languages & Extensions → PHPLint, use Check PHP Installation to confirm the executable and version.

Choose a PHP version matching the one running your website. Syntax accepted by PHP 8.4 may not work on an older server, and deprecations vary between versions.

Lint on save

Save a local PHP file to check it. PHPLint processes only that saved file—not the whole project or its included files.

Supported filename extensions are .php, .php3–.php8, .phtml and .inc. Files using Nova's PHP syntax are also recognised.

Syntax errors appear in Issues and at the line reported by PHP. Fix the error and save again to clear it. Results for other files are retained. The Extension Console records the PHP output and which file was checked.

Manual linting

Choose Extensions → PHPLint → Lint Now or Editor → PHPLint Now. The Editor command is available for a saved document using PHP syntax. You can also search for PHPLint: Lint Now in the Command Palette and assign a key binding in Nova.

Lint Now works even when Lint on Save is No. It checks the saved file; save any unsaved edits first and click into the PHP document to focus it. The Extensions command remains available without a focused document and explains if there is no suitable local PHP file to check. The Editor command depends on a focused, saved PHP-syntax document. Remote documents are rejected when the command runs.

Use Extensions → PHPLint → Check Install without focusing a document. It is also available as PHPLint: Check PHP Installation in the Command Palette and as a button in project settings.

Notifications

Enable Success Notifications to confirm successful checks, both on save and when using Lint Now. Enable Error Notifications to show syntax-error popups when Show Errors is Yes. Both notification settings default to No.

• ✅ PHP syntax check passed — no syntax errors reported.
• ⚠️ PHP syntax check passed with warnings — PHP also reported warnings or other output, even if warnings are hidden in Issues.
• ❌ PHP syntax error — PHP reported a syntax or compile-time fatal error.

Success is not added as an entry in Issues; fixing a file and checking it again clears its old errors. PHPLint does not automatically open the Issues sidebar, so enable error notifications if you want an alert while it is hidden. Passing a syntax check does not guarantee the script will run correctly.

Project settings

General

• Lint on Save: Automatically check saved PHP files. Default: Yes.

Issues & Notifications

• Show Errors: Syntax errors and compile-time fatal errors. Default: Yes.
• Show Warnings: Compile-time warnings and notices. Default: Yes.
• Show Deprecations: Compile-time deprecations, displayed as warnings. Default: Yes.
• Error Notifications: Also show a popup for syntax errors when Show Errors is Yes. Default: No.
• Success Notifications: Confirm successful automatic and manual checks with a popup, noting any warnings. Default: No.

Visibility changes immediately hide or restore existing diagnostics without running PHP again. Full diagnostic output remains in the Extension Console, even when a category is hidden. Hiding errors does not make invalid PHP valid.

Installation failures, unsupported files and other problems that prevent linting are explained separately. PHP startup or configuration warnings without a valid source location are logged rather than marked against an unrelated code line.

If PHP is unavailable or a check times out, the last diagnostics remain visible. They describe the previous check, not a new result. Restore the PHP installation and check again to refresh them.

PHP Installation

• PHP Executable: Select a detected PHP CLI installation or enter a custom executable path. Automatic checks Nova's PATH, /opt/homebrew/bin/php, /usr/local/bin/php and /usr/bin/php. Spaces in paths are supported. You can enter the path to a version-specific Homebrew or other PHP installation.
• Check PHP Installation: Display the version and executable currently used for linting.

PHP uses its normal CLI configuration, with plain-text diagnostic display and all error-reporting categories enabled for the lint invocation. This does not change your php.ini. Changing the executable clears existing diagnostics; save or use Lint Now to check with the newly selected version.

What PHP lint can—and cannot—find

PHP's -l option checks syntax without executing the source. It can report parse errors, compile-time fatal errors, and some warnings and deprecations.

It does not run your application, follow includes, validate business logic, or find ordinary runtime problems such as undefined variables and missing functions. It is not a full static analyser or coding-style checker.

PHP generally stops at the first blocking error. The reported line can be where parsing failed rather than where the mistake began—for example, a missing brace earlier in the file. PHP provides line numbers, not exact error columns.

If another PHP extension also supplies diagnostics, duplicate reports may appear. Disable PHPLint's automatic checking or adjust its visible categories if you prefer the other extension's diagnostics.

Remote projects

PHPLint requires saved local files and a local PHP CLI executable. It cannot run the PHP interpreter on a remote server. Attempting to lint a remote file shows a clear warning without starting PHP.

For remote websites, use a local project, lint locally and upload through Nova Publishing.

Upgrading from 0.3.1 and earlier

Settings are now per project; there is no global settings screen.

Please note: your old global PHP executable path continues to be used until you customise this project's settings. The executable selector initially shows Automatic or an already saved project choice, not the old global path.

The first change to any PHPLint project setting saves all displayed choices and defaults for that project. Global preferences are then ignored, including after reopening the project. If you previously used a custom PHP installation, select its path explicitly when switching to project settings.

Opening a project, viewing settings or checking the PHP installation does not change your saved preferences. Checks now run when you save, or when you explicitly choose Lint Now.

Troubleshooting

• Nothing happens: Check Lint on Save is Yes, the file is saved locally and it is recognised as PHP. Check the Extension Console, or focus the code and use Lint Now.
• PHP not found: Install PHP CLI, then choose its executable and use Check PHP Installation. Nova's PATH may differ from Terminal's. Some macOS versions do not include PHP.
• Terminal and Nova disagree: Compare the PHP versions and configuration used by each. Choose the executable matching your website.
• Warnings seem noisy: Turn off Show Warnings or Show Deprecations. Syntax errors remain visible unless you explicitly disable them.
• No success popup: Set Success Notifications to Yes. It applies to both manual and save-triggered checks; automatic checks also require Lint on Save to be Yes.
• Editor command unavailable: Focus a saved PHP document. Use Extensions → PHPLint → Check Install for an installation check without editor focus.
• No exact character underline: PHP reports a line number only; PHPLint marks that line rather than guessing a column.

Changelog

Version 1.0.1

• Add a GitHub Sponsors link to the extension details.

Version 1.0

• Add project-based settings, with compatibility for an existing global PHP executable until project settings are customised.
• Check local PHP files on save and show errors, warnings and deprecations in Issues and at their reported lines in the editor.
• Add independent visibility controls for errors, warnings and deprecations, plus optional syntax-error notifications.
• Add Lint Now to the Extensions menu and Command Palette, plus PHPLint Now in the Editor menu, available independently of lint-on-save.
• Add optional success notifications for both manual and save-triggered checks, with ✅ success, ⚠️ warning and ❌ error indicators. Success and error popups default to off.
• Detect PHP CLI installations and provide an executable selector and version/status check through Check Install and project settings.
• Improve diagnostic reporting and explain missing executables, failed checks and timeouts. Keep full PHP output in the Extension Console.
• Keep each file's diagnostics until it is checked again and clear resolved errors without removing other files' results.
• Explain unsupported remote files without attempting to lint them locally.
• Add a shaded PHP-blue icon and updated setup, upgrade and troubleshooting guidance.

Version 0.1

• Initial release

Version 0.2

• Added try catch to resolve issue https://github.com/VineCode/PHPLint.novaextension/issues/1

Version 0.3

• Fix to escape the file path
  • https://github.com/VineCode/PHPLint.novaextension/issues/2
  • https://github.com/VineCode/PHPLint.novaextension/issues/3

MIT License

Copyright (c) 2020 Vine Code Limited

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.