Struct AnalysisSession 

pub struct AnalysisSession { /* private fields */ }

Long-lived analysis context. Owns the salsa database and tracks which stubs have been loaded.

Cheap to clone the inner db for parallel reads; writes funnel through Self::ingest_file, Self::invalidate_file, and the crate-internal [Self::with_db_mut].

Implementations

impl AnalysisSession

pub fn new(php_version: PhpVersion) -> Self

Create a session targeting the given PHP language version.

pub fn with_cache(self, cache: Arc<AnalysisCache>) -> Self

pub fn with_psr4(self, map: Arc<Psr4Map>) -> Self

pub fn with_user_stubs(self, files: Vec<PathBuf>, dirs: Vec<PathBuf>) -> Self

pub fn php_version(&self) -> PhpVersion

pub fn cache(&self) -> Option<&AnalysisCache>

pub fn psr4(&self) -> Option<&Psr4Map>

pub fn ensure_stubs_loaded(&self)

Load every PHP built-in stub plus any configured user stubs. Idempotent. Equivalent to the legacy “load everything” behavior; use Self::ensure_essential_stubs_loaded in incremental scenarios where cold-start latency matters more than comprehensive stub coverage.

pub fn ensure_essential_stubs_loaded(&self)

Load only the curated set of essential stubs (Core, standard, SPL, date) plus any configured user stubs. About 25 of 120 stub files; covers types and functions used by virtually all PHP code.

Other extension stubs (Reflection, gd, openssl, …) can be brought in on demand via [Self::ensure_stubs_for_symbol] when user code references them. Idempotent — already-loaded stubs are skipped.

pub fn ensure_all_stubs_loaded(&self)

Load every embedded PHP stub plus any configured user stubs. Use for batch tools (CLI, full project analysis) where comprehensive symbol coverage matters more than cold-start latency.

pub fn ensure_stub_for_function(&self, name: &str) -> bool

Ensure the embedded stub that defines name (a function) is ingested. Returns true when a matching stub exists (whether or not it was already loaded), false when name isn’t a known PHP built-in.

pub fn ensure_stub_for_class(&self, fqcn: &str) -> bool

Ensure the embedded stub that defines fqcn (a class / interface / trait / enum) is ingested. Case-insensitive lookup with optional leading backslash.

pub fn ensure_stub_for_constant(&self, name: &str) -> bool

Ensure the embedded stub that defines name (a constant) is ingested.

pub fn loaded_stub_count(&self) -> usize

Number of distinct embedded stubs currently ingested into the session. Useful for diagnostics and bench reporting.

pub fn ensure_stubs_for_source(&self, source: &str)

Auto-discover and ingest the embedded stubs needed to cover every built-in PHP function / class / constant referenced by source.

Used by crate::FileAnalyzer::analyze to keep essentials-only mode correct without forcing callers to enumerate which stubs they need. Idempotent — already-loaded stubs are skipped via Self::loaded_stubs.

The discovery scan is a coarse identifier sweep (see [crate::stubs::collect_referenced_builtin_paths]) — it may pull in a slightly larger set than the file strictly needs, but never misses a referenced built-in. Cost is sub-millisecond per file.

Fast path: if every embedded stub is already loaded (e.g. after a batch tool called Self::ensure_all_stubs_loaded), the source scan is skipped entirely.

pub fn snapshot_db(&self) -> MirDb

Cheap clone of the salsa db for a read-only query. The lock is held only for the duration of the clone, so concurrent readers never serialize on each other or on writes for longer than the clone itself.

pub fn read<R>(&self, f: impl FnOnce(&dyn MirDatabase) -> R) -> R

Run a closure with read access to a database snapshot. The snapshot is taken under a brief lock, then the closure runs without holding it.

pub fn ingest_file(&self, file: Arc<str>, source: Arc<str>) -> FileDefinitions

Pass 1 ingestion. Updates the file’s source text in the salsa db, runs definition collection, and ingests the resulting stub slice. Triggers stub loading on first call. Also updates the cache’s reverse- dependency graph for file so cross-file invalidation stays correct across incremental edits — without rebuilding the graph from scratch.

If file was previously ingested, its old definitions and reference locations are removed first so renames / deletions don’t leave stale state in the codebase. (Without this, long-running sessions would accumulate dead reference-location entries indefinitely.)

pub fn invalidate_file(&self, file: &str)

Drop a file’s contribution to the session: codebase definitions, reference locations, salsa input handle, cache entry, and outgoing reverse-dependency edges. Cache entries of dependent files are also evicted (cross-file invalidation).

Use this when a file is closed by the consumer, or before a re-ingest of substantially changed content. (Plain re-ingest via Self::ingest_file also drops old definitions, but does not remove the salsa input handle — call this for full cleanup.)

pub fn tracked_file_count(&self) -> usize

Number of files currently tracked in this session’s salsa input set. Stable across reads; useful for diagnostics and memory bounds checks.

pub fn definition_of(&self, symbol: &str) -> Option<Location>

Resolve symbol (a class FQCN or function FQN) to its declaration location. Powers go-to-definition for top-level symbols. Returns None if the symbol isn’t known to the codebase or has no recorded source span (e.g. some stub-only declarations).

pub fn member_definition( &self, fqcn: &str, member_name: &str, ) -> Option<Location>

Resolve a class member (method / property / class constant / enum case) to its declaration location, walking the inheritance chain.

pub fn references_to(&self, symbol: &str) -> Vec<(Arc<str>, u32, u16, u16)>

Every recorded reference to symbol (as (file, line, col_start, col_end)). Use crate::symbol::ResolvedSymbol::codebase_key to build the lookup key from a ResolvedSymbol returned by crate::FileAnalysis::symbol_at.

pub fn document_symbols(&self, file: &str) -> Vec<DocumentSymbol>

All declarations defined in file (classes, interfaces, traits, enums, functions, constants). Powers outline / document-symbols views and any other consumer that needs the file’s top-level symbol set. Returns an empty Vec if file hasn’t been ingested.

pub fn run_inference_sweep(&self, files: &[(Arc<str>, Arc<str>)])

Cross-file inference sweep. For each (file, source) pair, runs the Pass 2 inference-only mode on a cloned db (parallel via rayon), then commits the collected inferred return types to the canonical db.

Call this on idle / save / explicit user request, not on every keystroke — crate::FileAnalyzer::analyze deliberately skips inference sweep on the hot path. Files whose source contains parse errors are silently skipped.