Project Configuration
=====================

Create ``.symfony-lsp.json`` at the workspace root to share settings between
every editor and the command line:

.. code-block:: json

    {
        "version": 1,
        "environment": "dev",
        "translationDiagnostics": true
    }

``version`` is required and must be the number ``1``. Unknown keys, invalid
values and entries that match no application are reported as errors instead
of being ignored.

Settings
--------

``projectRoots``
    The Symfony applications to analyze, relative to the workspace or
    absolute inside it. Omit it to discover them automatically. A root
    outside the workspace is an error, wherever it comes from: this file,
    the editor settings or ``--project-root``.

``phpCommand``
    The command that runs your application, such as ``["php"]`` or
    ``["symfony", "php"]``. Defaults to ``["php"]``.

``containerProjectRoot``
    The absolute project path seen by a ``phpCommand`` that runs in a
    container. See `Docker support`_.

``environment``
    The Symfony environment to analyze. Defaults to ``dev``.

``kernel``
    The kernel to boot, for applications that ship several. See below.

``debug``
    Whether to boot Symfony in debug mode. Defaults to ``true``. Symfony
    exposes the metadata this tool reads in debug mode only, so ``false``
    disables runtime analysis.

``runtimeIndexing``
    Whether the application may be executed at all. Defaults to ``true``.

``releaseMetadata``
    Whether the Symfony version check may fetch ``symfony.com/releases.json``.
    Set it to ``false`` to avoid that network access.

``bridgeTimeout``
    Seconds allowed for each application run. Defaults to ``300``. Raise it
    for slow containers.

``translationDiagnostics``
    Whether missing translation keys are reported. Defaults to ``false``.

``excludePaths``
    Project-relative patterns to leave out of the analysis.

Every setting except ``projectRoots`` can also be set per project.

Several Applications in One Workspace
-------------------------------------

Top-level settings apply to every discovered application; ``projects``
overrides them for one, keyed by its workspace-relative path:

.. code-block:: json

    {
        "version": 1,
        "projectRoots": [".", "apps/admin"],
        "environment": "dev",
        "projects": {
            "apps/admin": {
                "phpCommand": ["docker", "compose", "exec", "-T", "php", "php"],
                "containerProjectRoot": "/app"
            }
        }
    }

An application is discovered when its ``composer.json`` requires
``symfony/framework-bundle``, directly or through ``composer.lock``, and it's
declared as a project or provides ``bin/console``. Set ``projectRoots`` for
an unconventional layout.

Selecting a Kernel
------------------

One kernel is analyzed at a time. When a single Composer install ships
several, name the one to boot:

.. code-block:: json

    {
        "version": 1,
        "kernel": "Api\\Kernel"
    }

A value containing ``/`` or ending in ``.php`` is a project-relative entry
point instead, which suits kernels that need their own bootstrap:

.. code-block:: json

    {
        "version": 1,
        "kernel": "bin/websiteconsole"
    }

The entry point must return the application closure, as the front controllers
generated by Symfony Flex do. A configured kernel is never replaced by
another: if it can't be found or created, the failure is reported instead.

Env files are loaded from the kernel's project directory. A bundle can
therefore be analyzed from its root while booting the test application it
ships, such as ``Acme\Tests\Application\Kernel`` under
``tests/Application/``.

Switch kernels from your editor with its switch-kernel command, or check them
one at a time with ``symfony-lsp check --kernel=...``.

Excluding Paths
---------------

Use ``excludePaths`` for embedded fixtures or generated sources that your
``.gitignore`` doesn't cover:

.. code-block:: json

    {
        "version": 1,
        "excludePaths": [
            "tests/Rule/Fixtures/**",
            "generated/"
        ]
    }

Patterns are relative to each application root. ``*`` and ``?`` stay inside
one path segment, ``**`` crosses directories, and a pattern ending in ``/``
excludes the whole directory. Excluded files produce no diagnostics and don't
feed navigation, but a path passed explicitly to ``symfony-lsp check`` is
still analyzed, which lets you inspect a fixture on purpose.

Precedence
----------

Per-project entries override top-level ones, editor settings override the
file, and command-line options override both. Lists are replaced, not merged,
so an empty project-level ``excludePaths`` clears the top-level one.

Workspace trust, the server executable and its memory limit stay in your
editor's own settings. A configuration file alone never grants trust: an
editor still asks before running your application. The command line has no
such prompt and runs it unless you pass ``--source-only``.

.. _`Docker support`: docker.rst