README
¶
Shopware Language Server
Framework-aware code intelligence for Shopware and Symfony projects.
Shopware Language Server understands how PHP classes, Twig templates, routes, services, configuration, translations, Administration components, and DAL definitions connect. It brings completion, navigation, diagnostics, refactoring, and project tooling to those connections instead of treating every file as an isolated document.
Use it to find framework mistakes while editing, move through a large project without searching for string identifiers by hand, and run the same analysis in VS Code, CI, the command line, or an AI client.
[!NOTE] This repository may be ahead of the latest tagged release. Install a preview build to evaluate features that have not reached the Marketplace or Open VSX stable channel yet.
Why use it?
Most PHP tooling stops at classes, methods, and types. Shopware and Symfony applications also depend on relationships expressed through service IDs, route names, Twig strings, XML/YAML configuration, translation keys, entity metadata, and JavaScript component registrations.
Shopware Language Server indexes that application graph and keeps it available while you work.
| When you are... | Shopware Language Server helps by... |
|---|---|
| Following a service, route, template, snippet, or config key | Completing the identifier and navigating directly to its declaration |
| Editing PHP, Twig, XML, YAML, Vue, JavaScript, TypeScript, or SCSS | Connecting references across languages instead of analyzing one file at a time |
| Upgrading Shopware or Symfony | Reporting deprecated APIs, unsafe inheritance, changed Twig blocks, and version-specific behavior before runtime |
| Building a plugin or application | Generating validated scaffolds, service definitions, snippets, and DAL entity changes |
| Reviewing or running CI | Reusing the editor's diagnostics through the shopware-lsp check command |
| Working with an AI coding agent | Giving it the same definitions, references, diagnostics, code actions, and generators through MCP |
The server is open source, runs locally, and stores its workspace index in a project-specific SQLite cache. Unsaved editor documents take precedence over the on-disk index, so navigation and diagnostics follow what you are actually editing.
What you get
Shopware intelligence
- Storefront and Administration snippet completion, hover, navigation, diagnostics, creation actions, and translation extraction.
- Twig template, block, route, icon, theme configuration, system configuration, and feature-flag intelligence.
- Twig block versioning that follows inheritance across Shopware core, vendor packages, themes, and custom extensions.
- Administration component completion for components, props, slots, events, methods, computed properties, and extension blocks.
- Shopware DAL completion, navigation, type inference, diagnostics, migrations, and a visual entity designer for definitions, mappings, and extensions.
- App Script, migration, Store metadata, and extension-aware project support.
Symfony intelligence
- Service IDs, aliases, parameters, tags, autowiring, decorators, factories, and service configuration across PHP, XML, and YAML.
- Routes, controllers, route parameters, imports, URLs, and references across PHP, Twig, XML, YAML, JavaScript, and TypeScript.
- Doctrine ORM/ODM metadata, repositories, QueryBuilder, DQL, DBAL tables, and custom types.
- Console commands, Messenger messages and handlers, events and listeners, forms, validation, security, Serializer targets, Stimulus controllers, assets, environment variables, and bundle configuration.
- Symfony UX Twig and Live Component props, actions, events, listeners, blocks, templates, and cross-language references.
PHP and Twig semantics
-
Unused PHP import hints, individual removal fixes, and Organize Imports for class, function, and constant imports, including aliases and groups.
-
Extract Variable for PHP expressions and Extract Method/Function for selected statements, with nested control flow, multiple outputs, collision-free names, and versioned edits.
-
PHP document outlines, semantic occurrence highlights, folding, and expanding selections that follow unsaved source edits.
-
Native, lossless PHP and Twig parsers designed for incomplete editor input.
-
Native Twig/HTML document formatting with separate Shopware Administration and Storefront block-indentation behavior and editor-provided tab settings.
-
Workspace-wide PHP symbols, inheritance, traits, types, PHPDoc generics, flow-sensitive inference, completion, hover, definitions, references, signature help, rename, and diagnostics.
-
Typed Twig variables from controllers, components, globals, forms, and annotations, including Twig 3.29 documentation comments, member completion, hover documentation, and navigation back to PHP.
-
Framework-aware diagnostics for missing symbols, incompatible arguments, invalid configuration, deprecated APIs,
@finalinheritance, and more.
Project tools
- Searchable route, service, command, Doctrine entity, form type, Twig extension, component, template usage, and profiler request browsers.
- Safe scaffolds for controllers, commands, form types, Twig extensions, compiler passes, tests, service files, and Shopware DAL models.
- One production analysis path shared by the editor, CLI, MCP server, and refactoring engine.
The full feature and configuration reference contains the complete catalog. The Symfony capability map tracks detailed framework coverage.
Install
VS Code
Shopware Language Server requires VS Code 1.101 or newer.
- Install Shopware Language Server from the Visual Studio Marketplace.
- Open a Shopware or Symfony workspace folder.
- Start editing. The platform-specific extension package includes the server executable and starts it automatically for supported projects.
VSCodium and other Open VSX clients can install the extension from Open VSX.
The default activation mode is conservative. The extension starts only when it
recognizes Shopware Composer metadata, a Shopware app manifest, Symfony's
config/bundles.php, or an explicit .config/shopware/lsp.yaml file. It does
not index unrelated PHP projects.
Preview builds
Odd-minor tags (for example 0.3.0) run the
Pre-release workflow,
which builds platform-specific pre-release VSIX packages for macOS, Linux,
Alpine, and Windows and attaches them to a GitHub pre-release. The marketplaces
only accept numeric major.minor.patch versions, so the extension follows the
VS Code convention: odd minors are pre-releases, even minors are stable.
- Open the latest pre-release on GitHub Releases.
- Download the VSIX for your operating system and architecture.
- Run Extensions: Install from VSIX... in VS Code.
After approval through the gated preview deployment environment, pre-release
packages are also published to the pre-release channel of the Marketplace and
Open VSX. Use the stable channel for production installations.
Zed
The Zed extension provides language-server support,
MCP tools for the Agent Panel, snippets, and optional generator tasks. Install
it as a development extension by selecting editors/zed in Zed's Install
Dev Extension action. Rust via rustup is required to compile the extension;
the server binary is downloaded automatically.
Other editors and standalone use
Download a server archive from
GitHub Releases, place the
shopware-lsp executable on your PATH, and configure your editor to start it
over stdin/stdout. Running the binary without a subcommand starts the language
server.
See custom commands for custom protocol commands and a Neovim example. Editor integrators can use the versioned PhpStorm integration guide.
Try it in five minutes
After the initial workspace index completes:
- Put the cursor on a route name in Twig
path()or PHPgenerateUrl()and use Go to Definition. - Open a service configuration file and complete a service ID, tag, class, parameter, constructor argument, or configured method.
- Open a Twig template and complete a template path, snippet key, component, route, asset, form field, or typed variable member.
- Run Symfony: Browse Routes... or Symfony: Locate Service... from the command palette.
- Run Shopware: New File... to preview a framework-aware scaffold.
Diagnostics include quick fixes where a deterministic edit is available. They can also be configured or suppressed for a file, directory, extension, or the whole workspace.
Supported files
| File type | Examples of framework support |
|---|---|
| PHP | Semantic types, completion, navigation, references, rename, diagnostics, code actions, code lenses |
| Twig and HTML | Formatting, templates, blocks, routes, translations, components, forms, assets, Stimulus, typed variables |
| XML and YAML | Services, routes, Doctrine mappings, configuration, translations, validation, security |
| JavaScript and TypeScript | Administration components, snippets, routes, assets, Stimulus |
| Vue | Shopware Administration component templates, scripts, styles, props, slots, events, and blocks |
| SCSS | Theme variables, feature flags, classes, colors, completion, navigation, diagnostics |
| JSON | Snippets, theme configuration, Composer and Shopware metadata, entity snapshots |
| Dotenv, Dockerfile, and Compose | Environment declarations, definitions, references, and hover |
Configuration
No configuration file is required for normal projects. Use Shopware:
Configure Language Server... for a searchable settings UI, or commit
.config/shopware/lsp.yaml when the team should share the same policy.
# yaml-language-server: $schema=https://raw.githubusercontent.com/shopware/shopware-lsp/main/internal/projectconfig/schema.json
version: 1
shopware:
targetVersion: "6.7"
indexing:
# Files above this size are skipped before reading and parsing.
maxFileSizeMiB: 8
exclude:
- "**/generated/**"
diagnostics:
overrides:
- files: [src/Generated/**]
enabled: false
Root configuration controls features, domains, indexing, PHP extensions, the
Shopware target version, diagnostics, MCP tools, and CLI defaults. A plugin or
extension may contain its own .config/shopware/lsp.yaml for diagnostics below
that directory. VS Code user and workspace settings remain local overrides.
See the project configuration reference and the bundled JSON schema for every option.
Large workspaces can set shopwareLSP.memoryLimitMiB to trade indexing CPU for
a lower soft memory limit. The default 0 uses the server's balanced runtime
policy; 512 MiB is a practical opt-in starting point when memory pressure is
more important than indexing speed.
Command line and CI
The standalone binary exposes the same workspace, indexes, diagnostics, and refactoring engine used by the editor.
# Inspect project detection without creating a workspace cache.
shopware-lsp -root /path/to/project -json project-info
# Index once, then run configured diagnostics over source and tests.
shopware-lsp -root /path/to/project index
shopware-lsp -root /path/to/project check src tests
# Query framework-aware navigation from scripts or CI.
shopware-lsp -root /path/to/project definition src/Controller.php:24:18
shopware-lsp -root /path/to/project references src/Controller.php:24:18
shopware-lsp -root /path/to/project workspace-symbol customer.detail
CLI positions are one-based file:line:column values. check can fail on a
configured severity threshold, while refactoring commands preview a diff unless
write mode is explicitly requested. Run shopware-lsp help for the full
command catalog.
MCP and AI clients
VS Code automatically exposes one Shopware MCP server per supported workspace folder. AI clients receive the same diagnostics, code actions, hover, definitions, references, symbol search, scaffolds, and DAL entity workflow as the editor.
Other MCP clients can start the standalone server over stdin/stdout:
{
"mcpServers": {
"shopware": {
"command": "/absolute/path/to/shopware-lsp",
"args": ["-root", "/absolute/path/to/project", "mcp"]
}
}
}
Read and preview tools do not modify files. Applying a code action requires an exact action title, scaffolds preview their diff by default, and all workspace edits are validated against the workspace root. MCP tools can be disabled in VS Code settings or in committed project configuration.
Documentation
- Documentation index — start here for architecture
- Full feature, command, configuration, and performance reference
- Symfony feature coverage
Architecture, for contributors:
- System architecture
- Parser, CST, and query architecture
- Indexing and persistence
- LSP server, documents, and providers
- Diagnostics and quick-fix pipeline
- Refactoring engine
- PHP semantic engine
- PhpStorm and editor integration
- Custom LSP commands and Neovim example
- Maintainability guide
Contributing
The repository pins Go, Node.js, golangci-lint, and VSIX tooling in
mise.toml.
mise install
mise run setup
mise run check
Read AGENTS.md for the architecture, contributor workflow, and testing expectations.
License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
debug_ast
command
|
|
|
generate_phpstorm_stubs
command
|
|
|
internal
|
|
|
admin/twigmigration
Package twigmigration contains versioned Administration Twig component migrations.
|
Package twigmigration contains versioned Administration Twig component migrations. |
|
appscript
Package appscript indexes Shopware script hooks and facade availability.
|
Package appscript indexes Shopware script hooks and facade availability. |
|
asset
Package asset indexes Symfony public assets and Webpack Encore entries and provides editor-independent reference extraction for Twig and PHP.
|
Package asset indexes Symfony public assets and Webpack Encore entries and provides editor-independent reference extraction for Twig and PHP. |
|
doctrine
Package doctrine provides editor-independent Doctrine ORM metadata and framework semantics.
|
Package doctrine provides editor-independent Doctrine ORM metadata and framework semantics. |
|
httpclient
Package httpclient resolves Symfony HttpClient option declarations and references from the shared PHP semantic index.
|
Package httpclient resolves Symfony HttpClient option declarations and references from the shared PHP semantic index. |
|
integration
Package integration owns the stable editor-integration catalog shared by LSP clients and MCP.
|
Package integration owns the stable editor-integration catalog shared by LSP clients and MCP. |
|
language
Package language owns the registry of syntax frontends available to the application.
|
Package language owns the registry of syntax frontends available to the application. |
|
lsp/inspections
Package inspections contains diagnostic inspections that bind their quick fixes while reporting byte-oriented problems.
|
Package inspections contains diagnostic inspections that bind their quick fixes while reporting byte-oriented problems. |
|
lsp/phpanalysis
Package phpanalysis shares linked PHP semantic state between LSP features operating on the same immutable text document.
|
Package phpanalysis shares linked PHP semantic state between LSP features operating on the same immutable text document. |
|
lsp/phpsemantic
Package phpsemantic exposes the PHP semantic graph through LSP features.
|
Package phpsemantic exposes the PHP semantic graph through LSP features. |
|
parser/bytescan
Package bytescan provides allocation-free byte searches for parser hot paths.
|
Package bytescan provides allocation-free byte searches for parser hot paths. |
|
parser/javascript
Package javascriptparser provides the shared lossless JavaScript/TypeScript parser used by the language server.
|
Package javascriptparser provides the shared lossless JavaScript/TypeScript parser used by the language server. |
|
parser/json
Package jsonparser provides the lossless, error-tolerant JSON parser used by the language server.
|
Package jsonparser provides the lossless, error-tolerant JSON parser used by the language server. |
|
parser/parsekit
Package parsekit is the language-agnostic parser engine extracted from the twig parser: the trivia-skipping token cursor, the event/marker machinery, the sink that replays events into a cst.Tree (re-attaching trivia and resolving forward-parent chains), the recovery loop and the diagnostic types.
|
Package parsekit is the language-agnostic parser engine extracted from the twig parser: the trivia-skipping token cursor, the event/marker machinery, the sink that replays events into a cst.Tree (re-attaching trivia and resolving forward-parent chains), the recovery loop and the diagnostic types. |
|
parser/scss
Package scssparser provides the lossless, error-tolerant SCSS parser used by the language server.
|
Package scssparser provides the lossless, error-tolerant SCSS parser used by the language server. |
|
parser/twig
Package twigparser provides the in-process Twig parser used by the language server.
|
Package twigparser provides the in-process Twig parser used by the language server. |
|
parser/twig/ast
Package ast provides typed wrappers over the untyped syntax tree, a port of ludtwig-parser's syntax/typed.rs.
|
Package ast provides typed wrappers over the untyped syntax tree, a port of ludtwig-parser's syntax/typed.rs. |
|
parser/twig/formatter
Private formatting IR node types.
|
Private formatting IR node types. |
|
parser/twig/lexer
Package lexer is a hand-written, mode-less, maximal-munch tokenizer for the combined HTML + Twig grammar.
|
Package lexer is a hand-written, mode-less, maximal-munch tokenizer for the combined HTML + Twig grammar. |
|
parser/twig/parser
Package parser turns a template source string into a lossless syntax tree via Parse.
|
Package parser turns a template source string into a lossless syntax tree via Parse. |
|
parser/twig/query
Package query contains semantic Twig CST queries shared by LSP consumers and indexers.
|
Package query contains semantic Twig CST queries shared by LSP consumers and indexers. |
|
parser/twig/syntax
Package syntax defines the lossless concrete syntax tree (CST) shared by the whole twig-go stack: the Kind inventory, the Node/Token element types, the Builder used by the parser sink, tree-walking iterators, the DebugTree printer, TextRange, and LineIndex.
|
Package syntax defines the lossless concrete syntax tree (CST) shared by the whole twig-go stack: the Kind inventory, the Node/Token element types, the Builder used by the parser sink, tree-walking iterators, the DebugTree printer, TextRange, and LineIndex. |
|
parser/xml
Package xmlparser provides the lossless, error-tolerant XML parser used by the language server.
|
Package xmlparser provides the lossless, error-tolerant XML parser used by the language server. |
|
parser/xpath
Package xpathparser provides the lossless, error-tolerant XPath parser used for Symfony DomCrawler embedded expressions.
|
Package xpathparser provides the lossless, error-tolerant XPath parser used for Symfony DomCrawler embedded expressions. |
|
parser/yaml
Package yamlparser provides the lossless, error-tolerant YAML parser used by the language server.
|
Package yamlparser provides the lossless, error-tolerant YAML parser used by the language server. |
|
phar
Package phar reads PHP Archive (PHAR) files without invoking PHP or extracting the whole archive into memory.
|
Package phar reads PHP Archive (PHAR) files without invoking PHP or extracting the whole archive into memory. |
|
php/binder
Package binder converts the lossless PHP CST into immutable semantic documents.
|
Package binder converts the lossless PHP CST into immutable semantic documents. |
|
php/imports
Package imports analyzes namespace imports against the current PHP snapshot.
|
Package imports analyzes namespace imports against the current PHP snapshot. |
|
php/inference
Package inference performs local expression and control-flow type analysis over bound PHP semantic documents.
|
Package inference performs local expression and control-flow type analysis over bound PHP semantic documents. |
|
php/languagelevel
Package languagelevel centralizes the PHP version required by language syntax understood by the permissive PHP parser.
|
Package languagelevel centralizes the PHP version required by language syntax understood by the permissive PHP parser. |
|
php/literal
Package literal derives PHP literal types directly from lossless syntax.
|
Package literal derives PHP literal types directly from lossless syntax. |
|
php/phpdoc
Package phpdoc parses type-bearing PHPDoc tags into the shared semantic type algebra.
|
Package phpdoc parses type-bearing PHPDoc tags into the shared semantic type algebra. |
|
php/phpstormmeta
Package phpstormmeta parses the declarative subset of .phpstorm.meta.php files into typed semantic contracts.
|
Package phpstormmeta parses the declarative subset of .phpstorm.meta.php files into typed semantic contracts. |
|
php/project
Package project loads the Composer model that defines a PHP workspace.
|
Package project loads the Composer model that defines a PHP workspace. |
|
php/refactoring
Package refactoring builds PHP refactorings against immutable source snapshots.
|
Package refactoring builds PHP refactorings against immutable source snapshots. |
|
php/resolver
Package resolver implements PHP name, hierarchy, member, and signature resolution over semantic snapshots.
|
Package resolver implements PHP name, hierarchy, member, and signature resolution over semantic snapshots. |
|
php/rewrite
Package phprewrite provides lossless, composable PHP source rewrites on top of the immutable PHP CST.
|
Package phprewrite provides lossless, composable PHP source rewrites on top of the immutable PHP CST. |
|
php/semantic
Package semantic contains PHP symbols, scopes, references, and immutable document snapshots.
|
Package semantic contains PHP symbols, scopes, references, and immutable document snapshots. |
|
php/stubs
Package stubs supplies version-aware semantic declarations for PHP runtime symbols that do not exist in project source.
|
Package stubs supplies version-aware semantic declarations for PHP runtime symbols that do not exist in project source. |
|
php/stubs/catalog
Package catalog defines the compact, generated PHP runtime stub format.
|
Package catalog defines the compact, generated PHP runtime stub format. |
|
php/stubs/generate
Package generate builds the embedded runtime catalog from JetBrains' phpstorm-stubs repository.
|
Package generate builds the embedded runtime catalog from JetBrains' phpstorm-stubs repository. |
|
php/suppression
Package suppression parses source-level diagnostic suppression directives and matches them to Shopware LSP's stable PHP diagnostic identifiers.
|
Package suppression parses source-level diagnostic suppression directives and matches them to Shopware LSP's stable PHP diagnostic identifiers. |
|
php/types
Package types defines the semantic PHP type algebra.
|
Package types defines the semantic PHP type algebra. |
|
projectconfig
Package projectconfig owns the committed and editor-supplied configuration shared by the language server and CLI.
|
Package projectconfig owns the committed and editor-supplied configuration shared by the language server and CLI. |
|
rewrite
Package rewrite builds validated, lossless source edits from immutable CST elements.
|
Package rewrite builds validated, lossless source edits from immutable CST elements. |
|
runtimeconfig
Package runtimeconfig applies process-wide runtime defaults used by the language-server executable.
|
Package runtimeconfig applies process-wide runtime defaults used by the language-server executable. |
|
shopware
Package shopware contains Shopware-specific semantic extensions layered on top of the framework-neutral PHP engine.
|
Package shopware contains Shopware-specific semantic extensions layered on top of the framework-neutral PHP engine. |
|
shopware/dal
Package dal indexes Shopware entity definitions independently of the PHP semantic index so non-PHP frontends can resolve technical entity and field names without knowing about PHP internals.
|
Package dal indexes Shopware entity definitions independently of the PHP semantic index so non-PHP frontends can resolve technical entity and field names without knowing about PHP internals. |
|
shopware/entityschema
Package entityschema models Shopware DAL entities independently from their PHP representation.
|
Package entityschema models Shopware DAL entities independently from their PHP representation. |
|
textutil
Package textutil contains small, allocation-conscious text transforms shared by language frontends and semantic analysis.
|
Package textutil contains small, allocation-conscious text transforms shared by language frontends and semantic analysis. |