Struct DocumentStore 

pub struct DocumentStore { /* private fields */ }

Implementations

impl DocumentStore

pub fn new() -> Self

pub fn interactive_read_guard(&self) -> InteractiveReadGuard<'_>

Mark an interactive read (a request the user is waiting on) as in flight for the guard’s lifetime. Background bulk writers poll Self::yield_to_interactive_reads between files and pause while any guard is live, giving the read a write-free window to complete.

pub fn settled_write_rev_guard(&self) -> (InteractiveReadGuard<'_>, u64)

Take an interactive-read guard, wait (bounded ~50 ms) for in-flight background writes to go quiet, and return the settled write revision.

For user-facing sweeps that abort when Self::write_rev advances: snapshotting the revision this way ensures only genuine user edits — not the background scan the guard just paused — void the sweep. Sleeps; call from a blocking thread only.

pub fn yield_to_interactive_reads(&self)

Pause the calling (background-writer) thread while interactive reads are in flight, up to 500 ms per call. Bounded so a wedged reader can only slow the scan, never stop it; callers invoke this per file, so sustained interactive traffic keeps yielding at each boundary.

pub fn begin_reanalyze(&self) -> IndexCancel

Install a fresh cancel token for a dependent-diagnostics sweep, cancelling whichever sweep was previously in flight. Pass the returned token to reanalyze_dependents_cancellable; when a newer edit calls this again the old token flips and that older sweep stops at its next file boundary instead of racing this one to publish stale diagnostics.

pub fn begin_warm_sweep(&self) -> IndexCancel

Install a fresh cancel token for an analysis warm sweep, cancelling any sweep previously in flight. Mirrors Self::begin_reanalyze but on a separate slot: edit-triggered diagnostic sweeps and background warming must not cancel each other.

pub fn warm_analysis_sweep(&self, priority: &[Uri], cancel: &IndexCancel)

Drive every workspace file through mir’s memoized analyze_file query so later reference/rename requests are memo hits instead of cold analyses (~20 ms per file on real code — a few hundred candidate files makes an interactive request take seconds).

priority files (and the files declaring the classes they reference — the user’s working set) are warmed first, so requests against open files go warm within the sweep’s first seconds even on workspaces where the full sweep takes much longer.

Background-priority: processes files in small chunks, yielding to interactive reads at each boundary, and stops at the next boundary once cancel flips. Re-running after edits is cheap — unaffected files revalidate via salsa without re-analysis. Blocking; call from spawn_blocking.

pub fn flush_analysis_cache(&self)

Persist mir’s staged analysis-cache entries (reference postings) to disk. No-op when nothing changed since the last flush.

pub fn warm_sweeps_completed(&self) -> u64

Warm sweeps that ran to completion. See $/php-lsp/debugStats.

pub fn warm_start_replays_completed(&self) -> u64

pub fn mark_index_ready(&self)

Mark the workspace reference index as fully built. Called by the scan when its final phase completes (alongside $/php-lsp/indexReady).

pub fn is_index_ready(&self) -> bool

Whether the workspace reference index has finished building.

pub fn write_rev(&self) -> u64

Snapshot of the write-revision counter. Long-running reads should capture this before starting and pass it to cancellable operations; if the counter advances, those operations abort and return empty rather than looping indefinitely against a newly-invalidated database.

pub fn set_session_cache_dir(&self, dir: PathBuf)

Set the directory used to persist stub-parse and analysis results across server restarts. Subsequent calls are silently ignored (OnceLock semantics).

If a session was already built — an early request (e.g. the editor’s restored-buffer didOpen racing initialized) builds one on demand — it was pinned in-memory-only: nothing it computes is ever flushed, and the next launch replays nothing, silently re-paying the whole cold cost every session. Drop it so the next analysis_session() rebuilds with the cache attached; the few analyses done that early re-ingest on demand.

pub fn set_autoload_uris(&self, uris: Vec<Uri>)

Register URIs discovered from composer.json autoload.files entries. These PHP files define global helper functions (e.g. tap() in Laravel) that are not class-resolvable via PSR-4. Clears analysis_cache so the next per-file analysis pre-ingests them into the AnalysisSession before running mir’s FileAnalyzer.

pub fn analysis_session(&self, php_version: PhpVersion) -> Arc<AnalysisSession>

Get or build the AnalysisSession for the given PHP version. Rebuilds when the version changes (e.g. user flipped config). The session owns the shared salsa db and AnalysisCache; lazy-loads vendor files via the shared PSR-4 map. Built-in stubs are not pre-loaded: mir’s prepare_ast_for_analysis ingests the stubs each analyzed file references, and [crate::types::stub_members] faults in single stub files for builtin member/hover lookups.

pub fn current_analysis_session(&self) -> Arc<AnalysisSession>

Get-or-build the AnalysisSession for the current workspace PHP version — a single lock acquisition on the common (already-built) path. Replaces self.analysis_session(self.workspace_php_version()), which took two separate locks per call.

pub fn workspace_php_version(&self) -> PhpVersion

Current PHP version tracked by the workspace input.

pub fn class_subtype_urls(&self, class_fqn: &str) -> Vec<Uri>

File URIs of all direct and transitive subclasses of class_fqn, resolved via mir’s inheritance graph. Returns an empty vec when the mir session hasn’t ingested the class yet (cold start, excluded paths).

Used by goto_implementation and subtypes to scope their lookups to the correct files, fixing aliased extends and FQN-qualified forms that the raw-name subtypes_of map misses.

pub fn psr4_arc(&self) -> Arc<ArcSwap<Psr4Map>>

Return the Arc<ArcSwap<Psr4Map>> so callers can share it. Backend clones this arc at construction time so writes (e.g. loading composer.json on initialized) are immediately visible to PSR-4 resolution during analysis without extra plumbing.

pub fn mirror_text(&self, uri: &Uri, text: &str)

Mirror a file’s current text into the salsa layer. Creates the FileText input on first sight, otherwise updates text on the existing input (bumping the salsa revision so downstream queries invalidate).

pub fn mirror_text_arc(&self, uri: &Uri, text_arc: Arc<str>)

Like [mirror_text] but takes an already-allocated Arc<str>.

Callers that already hold an Arc<str> (e.g. ingest_from_doc reusing ParsedDoc::source_arc()) use this to avoid a second allocation and to ensure text_cache and parsed_cache hold the same Arc pointer — enabling Arc::ptr_eq validation in get_parsed_cached.

pub fn seed_cached_index(&self, uri: &Uri, index: Arc<FileIndex>) -> bool

Phase K2: pre-seed a FileIndex loaded from the on-disk cache onto the FileText input for uri. The next file_index call for that file returns the cached index directly, skipping parse + extract.

Must be called before any file_index(db, sf) call for this file — otherwise salsa has already memoized the fresh-parse result and setting cached_index now would only bump the revision without using the cache. In practice the workspace-scan path seeds immediately after mirror_text and before any query runs.

Returns false when uri was not mirrored (caller should mirror first); returns true on success.

pub fn evict_token_cache(&self, uri: &Uri)

Evict the semantic-tokens cache for uri. Called by Backend when a file is closed; diff-based tokens computed against the old revision are no longer meaningful.

pub fn ingest(&self, uri: Uri, text: &str)

Register a file in the salsa layer without marking it open.

Salsa’s parsed_doc query parses lazily on first read; diagnostics are populated by did_open when the editor actually opens the file.

pub fn ingest_from_doc(&self, uri: Uri, doc: &ParsedDoc)

Index a file using an already-parsed ParsedDoc, avoiding a second parse.

Prefer this over [ingest] when the caller already has a ParsedDoc (e.g. after running DefinitionCollector during workspace scan). Reuses the Arc<str> already owned by doc so that text_cache and SourceFile::text share the same pointer — enabling the Arc::ptr_eq fast path in get_parsed_cached on the first subsequent salsa query, without an extra Arc::from(source) allocation.

pub fn remove(&self, uri: &Uri)

pub fn get_doc_salsa(&self, uri: &Uri) -> Option<Arc<ParsedDoc>>

Salsa-backed parsed document.

Salsa-backed parsed document for any mirrored file (open or background-indexed). Returns None only when the file is not known to the store. Callers that want “only if open” should gate on Backend::open_files at the call site (see Backend::get_doc).

pub fn get_index_salsa(&self, uri: &Uri) -> Option<Arc<FileIndex>>

Salsa-backed compact symbol index.

pub fn get_symbol_map_salsa(&self, uri: &Uri) -> Option<Arc<SymbolMap>>

Salsa-backed pre-computed symbol map (name → Vec). Memoized per revision: stable files serve from cache in O(1).

pub fn other_symbol_maps( &self, uri: &Uri, open_urls: &[Uri], ) -> Vec<(Uri, Arc<SymbolMap>)>

Pre-computed symbol maps for every entry in open_urls except uri.

pub fn get_doc_snapshot_or_stale(&self, uri: &Uri) -> Option<Arc<ParsedDoc>>

Parsed doc for a cosmetic, cursor-triggered read (e.g. documentHighlight) that must stay responsive while the user types. Unlike Self::get_doc_salsa it never spins on the Cancelled retry loop: it tries the lock-free parsed_cache, then a bounded snapshot parse, and if a concurrent write stream keeps cancelling it, returns the last-good cached ParsedDoc (possibly one edit stale — invisible for a highlight, unlike a hang). None only when the file has never been parsed.

pub fn sync_workspace_files(&self)

Refresh workspace.files to mirror the current active file set.

Skips all work when workspace_files_dirty is false (the common case after the workspace scan completes — file-set changes are rare).

pub fn mark_workspace_files_dirty(&self)

Mark the workspace file set as dirty so the next sync_workspace_files call re-runs the collect/sort/compare path, and invalidate the workspace_file_paths() cache. Exposed for benchmarks that need to measure the dirty-path cost in isolation.

pub fn set_php_version(&self, version: PhpVersion) -> bool

Update the PHP version tracked by the workspace. Salsa will invalidate all semantic_issues queries so diagnostics are re-evaluated. Skips the setter when the version hasn’t changed to avoid spurious query invalidation. Returns true when the version actually changed — callers that scan the workspace at runtime (not just at init, before any file is mirrored) must re-scan every root when this is true, since drop_session_scoped_state below empties lsp_ws_files and nothing else repopulates it.

pub fn indexed_references( &self, symbol: &Name, files: &[Arc<str>], include_declaration: bool, cancel_rev: Option<u64>, ) -> Vec<(Arc<str>, u32, u32, u32)>

Inverted-index reference lookup scoped to files (the text-pre-filtered candidate set): a posting-list read for committed-fresh files plus an on-demand analyze+commit for stale/uncommitted candidates, so warm requests are O(results) instead of O(candidates).

Returns LSP-style 0-based line/column.

cancel_rev: when Some(rev), the loop throws salsa::Cancelled and returns empty if a concurrent write advances the write_revision counter past rev — preventing unbounded retries against a newly-invalidated db. Pass None to retain the original indefinite-retry behaviour (fast ops like single-file reads where a stale result is not a concern).

pub fn indexed_use_imports( &self, symbol: &Name, files: &[Arc<str>], ) -> Vec<(Arc<str>, u32, u32, u32)>

use-import lines referencing symbol, from mir’s use: postings. Read-only lookup with no freshness pass — run Self::indexed_references over the same files first so uncommitted candidates are analyzed. Returns (file_uri, line, col_start, col_end) tuples like Self::indexed_references; the range covers the whole import item.

pub fn warm_start_indexes(&self)

Replay disk-cached reference postings and subtype edges for the whole mirrored workspace (mir’s warm_start_files) — a no-op per file without a content-hash-matching cache entry from a previous run. Call once after the scan mirrors texts, before the analysis warm sweep, so a returning session starts index-warm.

pub fn workspace_file_paths(&self) -> Arc<Vec<Arc<str>>>

Every active workspace file as a mir path (Arc<str> of the URI). The candidate scope handed to mir’s queries — mir gates uncommitted candidates on symbol-name mention internally, so this is always safe.

Cached behind an Arc (invalidated by mark_workspace_files_dirty) so the ~15K-file walk + Arc<str> allocation per file only happens once per workspace-file-set change, not once per caller per request.

pub fn indexed_subtype_classes( &self, class_fqn: &str, include_trait_users: bool, ) -> Vec<SubtypeClassSite>

Transitive subtypes of class_fqn from mir’s maintained subtype edge index, with declaration sites. include_trait_users also counts use Trait; composition as a subtype edge (trait-usage lenses); leave it off for goto-implementation semantics (extends/implements only).

pub fn indexed_method_implementations( &self, class_fqn: &str, method: &str, ) -> Vec<(Arc<str>, Arc<str>, Range)>

Concrete implementations of class_fqn::method across its subtypes: (subtype fqcn, file, name range) from mir’s subtype edge index.

pub fn method_reference_scope( &self, owner_fqn: &str, method: &str, ) -> Option<Vec<Uri>>

The complete set of files a private method’s references can occur in, or None when the search must stay workspace-wide.

owner_fqn is the enclosing class at the cursor; narrowing applies only when that class directly declares method (so its MethodDef visibility is authoritative — inherited/call-site lookups fall through to None). A reference to Class::method is recorded only where analyze_file resolves an expression to that key, and analyze_file is per-source-file, so a private member — resolvable only inside the declaring class body, which lives in one file — is fully scoped to the declaring file at any indexing stage.

A protected member is reachable from the declaring class and its transitive subclasses ($this->m(), parent::m(), self::/static::), all of which live in the declaring file or a subtype file — never outside the hierarchy in valid PHP. Its scope is therefore the declaring file plus the transitive subtype files. The complete subtype set is only known once the workspace reference index finishes, so this narrowing applies only when Self::is_index_ready; before then it falls back to None (full workspace scope) so references are never under-reported.

Classes that compose traits or mixins are excluded — those inline external resolution context, so a reference could surface in another file.

pub fn fqn_reachable_files(&self, fqns: &[Arc<str>]) -> Option<Vec<Arc<str>>>

Files that could possibly reference any FQN in fqns, narrowed via PHP’s own name-resolution rules rather than bare-word text mention:

1. Namespace rule — the file’s namespace equals the target’s, or is a \-segment prefix of it: namespace Foo; reaches Foo\Bar\Baz through the relative-qualified Bar\Baz.
2. Import rule — a use of the target itself, an alias of it, or any namespace prefix of it (use Foo\Bar; Bar\Baz::x()), all matched on the import’s FQN so aliases come for free.
3. Text rule — the qualified path appears literally in the file (\App\Widget::class config arrays with no use line, or a leading-slash-free App\Widget from a no-namespace file, where qualified names resolve from the root). Matched ASCII-case-insensitively — PHP class names are case-insensitive.

These are the only ways PHP resolves a class-like or namespaced name, so this is exact narrowing grounded in the language’s own resolution order, not a heuristic — unlike mir’s own gate, which only sees bare short names and can’t distinguish this owner class from an unrelated class sharing its short name elsewhere in the workspace.

Callers must NOT use this for global-namespace functions/constants (unqualified calls fall back to the global namespace from any namespace, so no file can be excluded) or for instance members (a typed receiver can hide the class entirely).

Returns None (full workspace) when the boot scan hasn’t finished — same conservative discipline as the Protected branch above — so references are never under-reported at cold start.

pub fn get_workspace_index_salsa(&self) -> Arc<WorkspaceIndexData>

Phase J: salsa-memoized aggregate workspace index.

Returns the shared Arc<WorkspaceIndexData> with flat (Uri, Arc<FileIndex>) list plus pre-built classes_by_name and subtypes_of reverse maps. Used by workspace_symbols, prepare_type_hierarchy, supertypes_of, subtypes_of, and find_implementations so they don’t each rebuild the aggregate per request. Invalidates automatically when any file’s file_index changes.

pub fn parse_count(&self) -> u64

Total number of real ParsedDoc parses served so far (cache misses). Surfaced via $/php-lsp/debugStats so tests can assert the references read path doesn’t parse the whole workspace.

pub fn ref_index_lock_count(&self) -> u64

Times mir’s RefIndex was locked on the current session. Reads are per-key posting lookups and edits commit one file’s postings, so this grows by a small bounded amount per operation — never per candidate. Surfaced via $/php-lsp/debugStats for the stress-test guard.

pub fn workspace_symbol_index_ready(&self) -> bool

Whether mir’s workspace symbol index singleton is populated (warm-start seed or first sweep). See DebugStats::workspace_symbol_index_ready.

pub fn workspace_index_walks(&self) -> u64

Executions of mir’s tracked O(all-files) symbol-index walk.

pub fn source_text(&self, uri: &Uri) -> Option<Arc<str>>

Return the raw source text for uri if it has been mirrored into the salsa workspace. Used by the references handler to pre-filter session results by checking whether a file mentions the owning class name.

pub fn store_token_cache( &self, uri: &Uri, result_id: String, tokens: Arc<Vec<SemanticToken>>, )

Cache the semantic tokens computed for a delta response. result_id is an opaque string (a hash of the token data) returned to the client.

pub fn get_token_cache( &self, uri: &Uri, result_id: &str, ) -> Option<Arc<Vec<SemanticToken>>>

Return the cached tokens if result_id matches the stored one.

pub fn get_semantic_issues_salsa(&self, uri: &Uri) -> Option<Arc<[Issue]>>

Raw semantic issues for a file, computed via mir’s session-based FileAnalyzer. The session lazy-loads dependencies via PSR-4 so the LSP no longer needs to mirror vendor up-front. Callers apply their own DiagnosticsConfig filter via crate::semantic_diagnostics::issues_to_diagnostics.

pub fn cached_analysis_if_fresh(&self, uri: &Uri) -> Option<Arc<FileAnalysis>>

Run (or reuse) mir’s per-file body analysis, retaining the full mir_analyzer::FileAnalysis — issues and resolved symbols — across requests. Diagnostics read .issues; position features call .symbol_at(offset) for the resolved type at a cursor.

Cache hit when the entry’s captured source Arc is pointer-equal to the file’s current doc.source_arc(). A miss recomputes and overwrites, so the entry self-evicts on any content edit. Cache-hit-only variant of Self::cached_analysis: returns the cached analysis when the entry is current for the file’s text, never computes. Lets async handlers take the warm path synchronously and reserve spawn_blocking for the cold path (mir Pass 1 + Pass 2 can take hundreds of ms on large files).

pub fn cached_analysis(&self, uri: &Uri) -> Option<Arc<FileAnalysis>>

pub fn note_new_file_declarations(&self, uri: &Uri)

Register a newly-discovered file’s declarations so a consumer that was analyzed before this file existed doesn’t keep a stale cached analysis forever.

mirror_text/ingest_from_doc alone never bump decl_version — that only happens inside cached_analysis_cancellable’s own first-analysis check, which runs when a file undergoes its own full analysis. A file that is merely scanned or created as someone else’s dependency (what a workspace scan or a didChangeWatchedFiles CREATED/CHANGED event does) never goes through that path, so without this call, a consumer analyzed earlier keeps returning a stale UndefinedClass (or similar) even after the dependency shows up.

Call this after mirroring a file from one of those discovery paths — not from every mirror_text call, which would also fire on every keystroke edit to an already-open file and defeat the whole point of caching sibling files’ analyses across those edits.

pub fn cached_analysis_cancellable( &self, uri: &Uri, should_cancel: &(dyn Fn() -> bool + Sync), ) -> Option<Arc<FileAnalysis>>

Self::cached_analysis with an early exit: should_cancel is polled whenever a concurrent salsa write cancels the analysis attempt. A handler passes its write-revision staleness probe so a request made obsolete by newer typing stops burning a blocking-pool thread instead of retrying until the writer pauses — the editor re-requests anyway.

pub fn docs_for(&self, open_urls: &[Uri]) -> Vec<(Uri, Arc<ParsedDoc>)>

Returns (uri, doc) for files currently open in the editor.

Resolve open_urls (from Backend::open_urls()) to parsed docs. Files not mirrored in the salsa layer are filtered out silently.

pub fn other_docs( &self, uri: &Uri, open_urls: &[Uri], ) -> Vec<(Uri, Arc<ParsedDoc>)>

Parsed docs for every entry in open_urls except uri.

pub fn all_indexes(&self) -> Vec<(Uri, Arc<FileIndex>)>

Compact symbol index for every mirrored file.

pub fn with_all_indexes<R>( &self, f: impl FnOnce(&[(Uri, Arc<FileIndex>)]) -> R, ) -> R

Borrow-scoped alternative to all_indexes() for callers that only need the slice for the duration of one synchronous call — avoids cloning every Uri in the aggregate (get_workspace_index_salsa() itself is a cheap Arc clone; all_indexes()’s .files.clone() is the expensive part). Use all_indexes() instead when the result must be moved across an .await/spawn_blocking boundary.

pub fn cache_vendor_index(&self, uri: Uri, index: Arc<FileIndex>)

Store a lazily-loaded vendor FileIndex in the session cache. Only call this for files that are not part of the normal workspace scan (i.e. vendor files loaded on-demand by PSR-4 navigation).

pub fn get_vendor_index(&self, uri: &Uri) -> Option<Arc<FileIndex>>

Retrieve a previously cached vendor FileIndex.

pub fn other_indexes(&self, uri: &Uri) -> Vec<(Uri, Arc<FileIndex>)>

Same as all_indexes but excludes uri.

pub fn all_docs_for_scan(&self) -> Vec<(Uri, Arc<ParsedDoc>)>

Parsed documents for every mirrored file (open or background-indexed). Suitable for full-scan operations: find-references, rename, call_hierarchy, code_lens.

pub fn docs_for_scan_mentioning( &self, needles: &[String], ) -> Vec<(Uri, Arc<ParsedDoc>)>

Like Self::all_docs_for_scan, but only parses files whose raw text contains at least one of needles (ASCII-case-insensitive — PHP class names are case-insensitive, unlike the Laravel string-key prefilter’s exact-value match). Used by callers scanning for a class/interface declaration by name (e.g. “implement missing methods”), where the needle set is small and a miss guarantees the file declares none of them.

pub fn files_importing(&self, fqn: &str) -> Vec<Uri>

Files whose use imports include fqn (leading \ and ASCII case ignored — PHP names are case-insensitive), from the workspace symbol index — no parsing, no text scan. The candidate scope for use-line rewrites on file rename/delete: only importers can carry such a line.

Trait Implementations

impl Default for DocumentStore

fn default() -> Self

Returns the “default value” for a type.