Intelephense PHP Language Server (CLI)

1.16.5 · active · verified Sun Apr 19

Intelephense is a high-performance PHP language server that provides robust IDE features such as code completion, parameter hints, diagnostics, formatting, and symbol navigation. It supports PHP 7 and 8, offering comprehensive static analysis and accurate type inference for modern PHP projects. While widely recognized as a VS Code extension, the `intelephense` npm package specifically distributes the command-line interface (CLI) of the language server. This CLI enables integration with various Language Server Protocol (LSP) clients beyond VS Code or facilitates its use in automated workflows like CI/CD pipelines for linting and diagnostics. Currently at version 1.16.5 on npm, the project is actively developed, ensuring regular updates to support new PHP features and maintain compatibility with evolving editor integrations. Its primary differentiators include its speed, detailed static analysis tailored for PHP, and a rich feature set that significantly enhances PHP development experience.

Common errors

```
command not found: intelephense
```
cause The Intelephense CLI executable is not in your system's PATH.

fix If installed globally (`npm i -g intelephense`), ensure npm's global bin directory is in your PATH. If installed locally, run `npx intelephense` or add `node_modules/.bin` to your PATH for script execution.
```
No PHP executable found. Please install PHP and add it to your PATH.
```
cause Intelephense could not locate a PHP executable on the system.

fix Install PHP (version 7 or later) and verify it's added to your system's PATH. You can test by running `php -v` in your terminal.
```
Error: EACCES: permission denied, open '/path/to/.intelephense/somefile'
```
cause Intelephense attempts to write to a directory for caching or indexing but lacks the necessary file system permissions.

fix Ensure the directory specified by `intelephense.storagePath` (or the default storage location) has write permissions for the user running Intelephense. You might need to change directory permissions or specify a different storage path.
```
Diagnostics for PHP files are inaccurate or not appearing.
```
cause This can be due to an outdated PHP version, incorrect `intelephense.stubs` configuration, or issues with PHP extensions.

fix Verify your `intelephense.stubs` setting includes all necessary PHP extensions you are using (e.g., `['php', 'json', 'pcre', 'standard', 'wordpress']`). Ensure your PHP installation and extensions are up-to-date and correctly configured.

Warnings

gotcha The full feature set of Intelephense (including certain advanced diagnostics, refactoring, and other premium LSP capabilities) requires a paid license. While basic functionality is available, premium features will be locked without a valid license, even when using the CLI.
Fix: Purchase a premium license from the official Intelephense website (intelephense.com) and configure it in your editor or via the server's configuration files if applicable.
gotcha Intelephense requires a PHP executable to be installed and accessible in your system's PATH. If PHP is not found or the version is incompatible, the server will fail to start or provide accurate diagnostics.
Fix: Ensure PHP (version 7 or higher) is installed on your system and its executable directory is included in your system's PATH environment variable. Verify by running `php -v` in your terminal.
gotcha Performance issues or incorrect diagnostics can sometimes stem from missing or misconfigured PHP stub files (`intelephense.stubs`) or an incorrect `intelephense.storagePath` pointing to a non-writable directory.
Fix: Check the Intelephense documentation for recommended stub configurations and ensure the `storagePath` is set to a writable directory for caching and indexing. For VS Code users, these are typically configured in `settings.json`.
breaking Prior to version 1.0, some configuration options and command-line arguments might have differed. While the core LSP functionality remained, direct CLI usage and specific settings could require adjustments.
Fix: It is highly recommended to use Intelephense versions 1.0 or higher for stability and modern PHP support. Consult the changelog for specific migration steps if upgrading from pre-1.0 versions.

Install

npm install intelephense npm
yarn add intelephense yarn
pnpm add intelephense pnpm

Imports

runIntelephense
wrong:
```
import { intelephense } from 'intelephense';
```
correct:
```
import { spawn } from 'node:child_process'; const intelephenseProcess = spawn('intelephense', ['--version'], { stdio: 'inherit' });
```
Intelephense is primarily a CLI tool and does not export JavaScript/TypeScript modules for direct import. Its functionality is accessed by spawning its executable.

runDiagnostics

wrong:

intelephense.diagnostics('/path/to/project');

correct:

import { exec } from 'node:child_process'; exec('intelephense diagnostics /path/to/project --json', (error, stdout, stderr) => { if (error) console.error(`Error: ${error.message}`); console.log(stdout); });

To integrate Intelephense diagnostics into a Node.js workflow, execute the `diagnostics` command via `child_process.exec` or `spawn`. Use `--json` for programmatic output.

resolveExecutablePath

wrong:

import { getPath } from 'intelephense';

correct:

import { resolve } from 'node:path'; import { existsSync } from 'node:fs'; const intelephenseBin = resolve(process.cwd(), 'node_modules', '.bin', 'intelephense'); if (existsSync(intelephenseBin)) console.log(`Intelephense executable found at: ${intelephenseBin}`);

When installed via npm, the `intelephense` executable is typically located in the `node_modules/.bin/` directory relative to your project root.

Quickstart

This quickstart demonstrates how to install Intelephense locally, create a sample PHP file, and then programmatically run diagnostics on it using Node.js's `child_process` module to capture and parse the output.

import { execSync } from 'node:child_process';
import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';

const projectRoot = './tmp_php_project';
const phpFilePath = join(projectRoot, 'index.php');

if (!existsSync(projectRoot)) {
  mkdirSync(projectRoot);
}

// Create a sample PHP file for diagnostics
const phpContent = `<?php

class MyClass {
    public function greet(string $name): string {
        return 'Hello, ' . $name;
    }
}

$obj = new MyClass();
// Missing semicolon here intentionally for diagnostics
echo $obj->greet('World')

// Undefined variable to demonstrate diagnostics
$undefinedVar = $nonExistentVar;
`;

writeFileSync(phpFilePath, phpContent);

console.log('Running Intelephense diagnostics on the sample PHP file...');

try {
  // Run diagnostics and capture output
  const output = execSync(`intelephense diagnostics ${projectRoot} --json`, { encoding: 'utf8' });
  const diagnostics = JSON.parse(output);

  console.log('Intelephense Diagnostics Report:');
  if (diagnostics.length > 0) {
    diagnostics.forEach(diag => {
      console.log(`- [${diag.severity}] ${diag.message} at ${diag.uri}:${diag.range.start.line + 1}:${diag.range.start.character + 1}`);
    });
  } else {
    console.log('No diagnostics reported (might indicate no issues or configuration problem).');
  }
} catch (error) {
  console.error('Failed to run Intelephense diagnostics:', error.message);
  if (error.stderr) console.error(error.stderr);
  console.error('Make sure PHP is installed and in your PATH, and intelephense is installed via `npm i -g intelephense` or `npm i intelephense`.');
}

// Clean up (optional)
// require('node:fs').rmSync(projectRoot, { recursive: true, force: true });

view raw JSON →