Add basic Phar support

Author: AJenbo

docs/CHANGELOG.md

@@ -42,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Phar archive class resolution.** Classes inside `.phar` archives (e.g. PHPStan's `phpstan.phar`) are now discovered and indexed automatically. During Composer autoload scanning, bootstrap files that reference a phar are detected, the archive is parsed in-process (no PHP runtime needed), and all PHP classes inside are registered for completion, hover, go-to-definition, and diagnostics. Anyone writing PHPStan extensions, custom rules, or dynamic return type extensions now gets full IDE support for the PHPStan API. Only uncompressed phars are supported (the format used by PHPStan and most other phar-distributed tools).
 - **Analyze command.** `phpantom_lsp analyze` scans a Composer project and reports PHPantom's own diagnostics in a PHPStan-like table format. Useful for measuring type coverage across an entire codebase without opening files one by one. Accepts an optional path argument to limit the scan to a single file or directory. Only native diagnostics are reported (no PHPStan, no external tools). Output includes diagnostic identifiers and supports `--severity` filtering and `--no-colour` for CI.
 - **Add @throws.** New code action triggered by PHPStan's `missingType.checkedException` diagnostic. When PHPStan reports that a method or function throws a checked exception not documented in `@throws`, the quick-fix inserts a `@throws ShortName` tag into the existing docblock (or creates a new docblock) and adds a `use` import for the exception class when needed. Handles methods, standalone functions, and property hooks. Skips the action when the exception is already documented, already imported, or in the same namespace.
 - **Remove @throws.** New code action triggered by PHPStan's `throws.unusedType` (a `@throws` tag for a type that is never thrown) and `throws.notThrowable` (a `@throws` tag for a type that is not a subtype of `Throwable`). The quick-fix removes the offending `@throws` line from the docblock, cleans up orphaned blank separator lines, and removes the entire docblock when it would be empty after removal. Handles FQN, short-name, and leading-backslash variants, as well as single-line docblocks.

docs/todo.md

@@ -208,7 +208,6 @@ unlikely to move the needle for most users.
 | X2  | Parallel file processing — remaining work                                                                                                                    | Low-Medium | Medium      |
 | X5  | Granular progress reporting for indexing, GTI, and Find References                                                                                           | Low-Medium | Medium      |
 | X4  | Full background indexing (`strategy = "full"`)                                                                                                               | Medium     | High        |
-| X8  | [Phar archive class resolution](todo/indexing.md#x8-phar-archive-class-resolution)                                                                           | Medium     | Medium      |
 | X6  | Disk cache (evaluate later)                                                                                                                                  | Medium     | High        |
 |     | **[Inline Completion](todo/inline-completion.md)**                                                                                                           |            |             |
 | N1  | Template engine (type-aware snippets)                                                                                                                        | Medium     | High        |

docs/todo/indexing.md

@@ -552,61 +552,4 @@ the implicit signal is sufficient and no explicit tracking is needed.
    not essential; the affinity table already provides a good cold-start
    ordering.
 
----
-
-## X8. Phar archive class resolution
-
-**Impact: Medium · Effort: Medium**
 
-Many PHP tools distribute as phar archives even when installed via
-Composer. PHPStan is the most prominent example: `composer require
-phpstan/phpstan` installs a `phpstan.phar` file, not extracted PHP
-source files. Classes like `PHPStan\Type\Type`,
-`PHPStan\Reflection\MethodReflection`, and `PHPStan\Analyser\Scope`
-are inside the phar and invisible to PHPantom's file-based class
-scanner.
-
-This blocks anyone writing PHPStan extensions (custom rules, type
-specifying extensions, dynamic return type extensions) from getting
-completion, hover, and go-to-definition for the PHPStan API they
-are implementing against. It also produces `unknown_class` diagnostics
-for every PHPStan type reference.
-
-### What a phar contains
-
-A phar archive is a single file containing a virtual filesystem of
-PHP files, accessible at runtime via the `phar://` stream wrapper.
-The internal structure mirrors a normal directory tree with
-`vendor/autoload.php`, namespaced source files, etc.
-
-### Implementation
-
-1. **Detection.** During Composer autoload scanning, detect when a
-   PSR-4 or classmap entry points into a `.phar` file (either
-   directly or via a `bootstrap.php` that includes one). Also scan
-   `autoload.files` entries that `require` a phar.
-
-2. **Extraction.** Read the phar's file index and extract PHP source
-   files into an in-memory or temporary directory. The phar format
-   is documented and relatively simple to parse: a manifest section
-   lists all files with offsets and sizes, followed by the
-   concatenated file contents (optionally compressed with gzip or
-   bzip2).
-
-3. **Indexing.** Feed the extracted PHP files through the existing
-   class scanner (`find_classes` / `find_symbols`) and add them to
-   the class index. The source path should use a `phar://` prefix
-   so go-to-definition can distinguish phar-sourced classes.
-
-4. **Staleness.** Check the phar file's mtime. Re-extract only when
-   the phar has changed (e.g. after `composer update`).
-
-### Scope
-
-The initial implementation only needs to support uncompressed phars
-(which is what PHPStan uses). Compressed phar support (gzip, bzip2)
-can be added later if needed.
-
-**Observed:** 13 `unknown_class` diagnostics in `shared` for PHPStan
-types, plus 6 cascading `unknown_member` diagnostics from unresolved
-PHPStan classes. A user request for this feature also exists.

src/composer.rs

@@ -433,6 +433,72 @@ pub fn extract_require_once_paths(content: &str) -> Vec<String> {
     paths
 }
 
+/// Detect `.phar` archive references in a PHP bootstrap file.
+///
+/// Scans the file content for patterns like:
+///
+/// ```text
+/// require 'phar://' . __DIR__ . '/phpstan.phar/vendor/autoload.php';
+/// $filepath = 'phar://' . __DIR__ . '/phpstan.phar/src/' . $filename . '.php';
+/// ```
+///
+/// Returns the absolute paths of all `.phar` files referenced in the
+/// content, resolved relative to `file_dir` (the directory containing
+/// the bootstrap file).
+///
+/// This is intentionally lenient: it looks for any `__DIR__` + string
+/// concatenation that mentions a `.phar` file, regardless of the
+/// surrounding PHP structure.  False positives are harmless (the phar
+/// parser will reject non-phar files), and false negatives are
+/// acceptable (users can always extract the phar manually).
+pub fn detect_phar_references(content: &str, file_dir: &Path) -> Vec<PathBuf> {
+    let mut phars = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+
+    for line in content.lines() {
+        // Look for lines containing both `__DIR__` and `.phar`.
+        if !line.contains("__DIR__") || !line.contains(".phar") {
+            continue;
+        }
+
+        // Extract the phar filename from string fragments like:
+        //   '/phpstan.phar/vendor/autoload.php'
+        //   '/phpstan.phar/src/'
+        // We look for quoted strings containing `.phar` and extract
+        // the path up to (and including) the `.phar` extension.
+        for quote in [b'\'', b'"'] {
+            let bytes = line.as_bytes();
+            let mut i = 0;
+            while i < bytes.len() {
+                if bytes[i] == quote {
+                    // Find the closing quote.
+                    if let Some(end) = bytes[i + 1..].iter().position(|&b| b == quote) {
+                        let fragment = &line[i + 1..i + 1 + end];
+                        if let Some(phar_end) = fragment.find(".phar") {
+                            // Extract the relative path: e.g. "/phpstan.phar"
+                            let rel = &fragment[..phar_end + 5]; // +5 for ".phar"
+                            let rel = rel.trim_start_matches('/');
+                            if !rel.is_empty() {
+                                let phar_path = file_dir.join(rel);
+                                if phar_path.is_file() && seen.insert(phar_path.clone()) {
+                                    phars.push(phar_path);
+                                }
+                            }
+                        }
+                        i += 1 + end + 1;
+                    } else {
+                        i += 1;
+                    }
+                } else {
+                    i += 1;
+                }
+            }
+        }
+    }
+
+    phars
+}
+
 /// Discover PHP subproject roots inside a workspace directory.
 ///
 /// When the workspace root itself has no `composer.json`, this function

src/lib.rs

@@ -109,6 +109,7 @@ mod hover;
 pub(crate) mod inheritance;
 mod inlay_hints;
 mod parser;
+pub(crate) mod phar;
 mod phpstan;
 mod references;
 mod rename;
@@ -303,6 +304,15 @@ pub struct Backend {
     /// Consulted by `find_or_load_class` as a resolution step between
     /// the ast_map scan (Phase 1) and PSR-4 resolution (Phase 2).
     pub(crate) classmap: Arc<RwLock<HashMap<String, PathBuf>>>,
+    /// Parsed phar archives keyed by the phar file's absolute path.
+    ///
+    /// Populated during Composer autoload scanning when a bootstrap file
+    /// references a `.phar` archive (e.g. PHPStan's `bootstrap.php`).
+    /// Used by [`parse_and_cache_file`](Self::parse_and_cache_file) to
+    /// extract PHP source files from inside the archive when the
+    /// classmap contains a phar-based path (detected by a `!` separator,
+    /// e.g. `/path/to/phpstan.phar!src/Type/Type.php`).
+    pub(crate) phar_archives: Arc<RwLock<HashMap<PathBuf, phar::PharArchive>>>,
     /// Embedded PHP stubs for built-in classes/interfaces (e.g. `UnitEnum`,
     /// `BackedEnum`, `Iterator`, `Countable`, …).
     /// Maps class short name → raw PHP source code.
@@ -511,6 +521,7 @@ impl Backend {
             fqn_index: Arc::new(RwLock::new(HashMap::new())),
             class_not_found_cache: Arc::new(RwLock::new(HashSet::new())),
             classmap: Arc::new(RwLock::new(HashMap::new())),
+            phar_archives: Arc::new(RwLock::new(HashMap::new())),
             stub_index: stubs::build_stub_class_index(),
             stub_function_index: stubs::build_stub_function_index(),
             stub_constant_index: stubs::build_stub_constant_index(),
@@ -712,6 +723,7 @@ impl Backend {
             class_index: Arc::clone(&self.class_index),
             fqn_index: Arc::clone(&self.fqn_index),
             classmap: Arc::clone(&self.classmap),
+            phar_archives: Arc::clone(&self.phar_archives),
             class_not_found_cache: Arc::clone(&self.class_not_found_cache),
             stub_index: self.stub_index.clone(),
             resolved_class_cache: Arc::clone(&self.resolved_class_cache),

src/resolution.rs

@@ -174,14 +174,39 @@ impl Backend {
         None
     }
 
-    /// Parse a PHP file from disk, cache the results, and return the
-    /// extracted classes.
+    /// Parse a PHP file from disk (or from a phar archive), cache the
+    /// results, and return the extracted classes.
     ///
     /// Convenience wrapper around [`parse_and_cache_content`] that reads
-    /// the file and derives a `file://` URI from the path.  Used by
+    /// the file and derives a URI from the path.  Used by
     /// [`find_or_load_class`] (Phases 1.5 and 2) and by the
     /// go-to-implementation scanner.
+    ///
+    /// **Phar support:** when `file_path` contains a `!` separator
+    /// (e.g. `/path/to/phpstan.phar!src/Type/Type.php`), the left side
+    /// is the phar archive path and the right side is the internal file
+    /// path.  The content is extracted from the in-memory
+    /// [`phar_archives`](crate::Backend::phar_archives) cache instead
+    /// of reading from disk.  The URI uses a `phar://` scheme so that
+    /// go-to-definition can distinguish phar-sourced classes.
     pub(crate) fn parse_and_cache_file(&self, file_path: &Path) -> Option<Vec<Arc<ClassInfo>>> {
+        let path_str = file_path.to_str().unwrap_or_default();
+
+        // ── Phar path: "archive.phar!internal/path.php" ─────────
+        if let Some(sep) = path_str.find('!') {
+            let phar_path = Path::new(&path_str[..sep]);
+            let internal_path = &path_str[sep + 1..];
+
+            let archives = self.phar_archives.read();
+            let archive = archives.get(phar_path)?;
+            let bytes = archive.read_file(internal_path)?;
+            let content = std::str::from_utf8(bytes).ok()?;
+
+            let uri = format!("phar://{}/{}", phar_path.display(), internal_path);
+            return self.parse_and_cache_content(content, &uri);
+        }
+
+        // ── Regular file path ───────────────────────────────────
         let content = std::fs::read_to_string(file_path).ok()?;
         let uri = crate::util::path_to_uri(file_path);
         self.parse_and_cache_content(&content, &uri)

src/server.rs

@@ -21,7 +21,7 @@
 ///   version counter; the worker waits for a quiet period before
 ///   publishing.
 use std::collections::{HashMap, HashSet};
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use std::sync::atomic::Ordering;
 
@@ -38,6 +38,7 @@ use crate::classmap_scanner::{self, WorkspaceScanResult};
 use crate::composer;
 use crate::config::IndexingStrategy;
 use crate::formatting;
+use crate::phar;
 
 #[tower_lsp::async_trait]
 impl LanguageServer for Backend {
@@ -1365,8 +1366,19 @@ impl Backend {
                     }
                 }
 
-                // Follow require_once statements to discover more files.
                 let content_str = String::from_utf8_lossy(&content);
+
+                // ── Phar detection ──────────────────────────────────
+                // If this autoload file references a .phar archive,
+                // parse the phar and scan its PHP files for classes.
+                if let Some(file_dir) = canonical.parent() {
+                    let phar_paths = composer::detect_phar_references(&content_str, file_dir);
+                    for phar_path in phar_paths {
+                        self.scan_phar_archive(&phar_path);
+                    }
+                }
+
+                // Follow require_once statements to discover more files.
                 let require_paths = composer::extract_require_once_paths(&content_str);
                 if let Some(file_dir) = canonical.parent() {
                     for rel_path in require_paths {
@@ -1389,6 +1401,102 @@ impl Backend {
         autoload_count
     }
 
+    /// Parse a `.phar` archive and register its PHP classes in the
+    /// classmap and class index for lazy loading.
+    ///
+    /// The phar's raw bytes are read from disk, parsed by
+    /// [`phar::PharArchive`], and stored in
+    /// [`phar_archives`](crate::Backend::phar_archives).  Each `.php`
+    /// file inside the archive is scanned with the lightweight
+    /// [`find_classes`](classmap_scanner::find_classes) byte scanner,
+    /// and discovered classes are registered in:
+    ///
+    /// - `classmap` — with a sentinel path like
+    ///   `/path/to/phpstan.phar!src/Type/Type.php` (the `!` separator
+    ///   tells [`parse_and_cache_file`](crate::Backend::parse_and_cache_file)
+    ///   to extract content from the phar instead of reading from disk)
+    /// - `class_index` — with a `phar://` URI for completions and
+    ///   workspace symbols
+    fn scan_phar_archive(&self, phar_path: &Path) {
+        // Avoid scanning the same phar twice.
+        if self.phar_archives.read().contains_key(phar_path) {
+            return;
+        }
+
+        let data = match std::fs::read(phar_path) {
+            Ok(d) => d,
+            Err(_) => return,
+        };
+
+        let archive = match phar::PharArchive::parse(data) {
+            Some(a) => a,
+            None => {
+                tracing::warn!("failed to parse phar archive: {}", phar_path.display());
+                return;
+            }
+        };
+
+        // Collect PHP file paths first so we can iterate while
+        // holding the archive reference.
+        let php_files: Vec<String> = archive
+            .file_paths()
+            .filter(|p| p.ends_with(".php"))
+            .map(String::from)
+            .collect();
+
+        let mut classmap_entries: Vec<(String, PathBuf)> = Vec::new();
+        let mut class_index_entries: Vec<(String, String)> = Vec::new();
+
+        for internal_path in &php_files {
+            if let Some(content) = archive.read_file(internal_path) {
+                let classes = classmap_scanner::find_classes(content);
+                for fqn in classes {
+                    // Sentinel path: "archive.phar!internal/path.php"
+                    let sentinel =
+                        PathBuf::from(format!("{}!{}", phar_path.display(), internal_path));
+                    let phar_uri = format!("phar://{}/{}", phar_path.display(), internal_path);
+                    classmap_entries.push((fqn.clone(), sentinel));
+                    class_index_entries.push((fqn, phar_uri));
+                }
+            }
+        }
+
+        let class_count = classmap_entries.len();
+
+        // Register classes in the classmap and class_index.
+        {
+            let mut cm = self.classmap.write();
+            for (fqn, path) in classmap_entries {
+                cm.entry(fqn).or_insert(path);
+            }
+        }
+        {
+            let mut idx = self.class_index.write();
+            for (fqn, uri) in class_index_entries {
+                idx.entry(fqn).or_insert(uri);
+            }
+        }
+
+        // Clear the negative class cache so that classes previously
+        // looked up (and cached as "not found") before the phar was
+        // scanned can now be resolved.
+        if class_count > 0 {
+            self.class_not_found_cache.write().clear();
+        }
+
+        tracing::info!(
+            "scanned phar {}: {} PHP files, {} classes",
+            phar_path.display(),
+            php_files.len(),
+            class_count,
+        );
+
+        // Store the parsed archive for lazy content extraction.
+        self.phar_archives
+            .write()
+            .insert(phar_path.to_owned(), archive);
+    }
+
     /// Build a workspace scan by self-scanning a Composer project's
     /// autoload directories (PSR-4 + classmap + vendor packages).
     ///