Log stub version and clean up stub handeling

Author: AJenbo

.github/workflows/ci.yml

@@ -58,7 +58,9 @@ jobs:
       - uses: shivammathur/setup-php@v2
         with:
           php-version: "8.4"
+          ini-values: zend.assertions=1
       - run: php -l example.php
+      - run: php -d zend.assertions=1 example.php
 
   benchmark:
     name: Benchmark

.github/workflows/release.yml

@@ -52,20 +52,6 @@ jobs:
         with:
           key: ${{ matrix.target }}
 
-      - uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.4'
-          tools: composer
-
-      - name: Cache Composer stubs
-        uses: actions/cache@v4
-        with:
-          path: stubs
-          key: composer-stubs-${{ hashFiles('composer.lock') }}
-          restore-keys: composer-stubs-
-
-      - run: composer install --no-interaction --prefer-dist
-
       - name: Build
         run: cargo build --release --target ${{ matrix.target }}
 

build.rs

@@ -76,11 +76,21 @@ fn main() {
         if let Err(e) = fetch_stubs(&manifest_dir) {
             eprintln!("cargo:warning=Failed to fetch stubs from GitHub: {}", e);
             eprintln!("cargo:warning=Building without stubs (network may be unavailable).");
+            println!("cargo:rustc-env=PHPANTOM_STUBS_VERSION=none");
             write_empty_stubs();
             return;
         }
     }
 
+    // Emit the stubs version so the binary can log it at runtime.
+    // fetch_stubs writes a `.version` file next to the extracted stubs.
+    let version_file = Path::new(&manifest_dir).join("stubs/.version");
+    let stubs_version = fs::read_to_string(&version_file)
+        .ok()
+        .map(|v| v.trim().to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+    println!("cargo:rustc-env=PHPANTOM_STUBS_VERSION={}", stubs_version);
+
     let map_content = match fs::read_to_string(&map_path) {
         Ok(c) => c,
         Err(e) => {
@@ -276,6 +286,11 @@ fn fetch_stubs(manifest_dir: &str) -> Result<(), Box<dyn std::error::Error>> {
         }
     }
 
+    // Record which version was fetched so subsequent builds (that skip
+    // the download because stubs/ already exists) can still read it.
+    let version_file = Path::new(manifest_dir).join("stubs/.version");
+    let _ = fs::write(&version_file, &release.tag_name);
+
     eprintln!(
         "cargo:warning=Successfully downloaded phpstorm-stubs {}",
         release.tag_name

docs/ARCHITECTURE.md

@@ -346,14 +346,15 @@ PHPantom bundles the [JetBrains phpstorm-stubs](https://github.com/JetBrains/php
 
 The `build.rs` script:
 
-1. Reads `stubs/jetbrains/phpstorm-stubs/PhpStormStubsMap.php` — a generated index mapping symbol names to file paths.
-2. Emits `stub_map_generated.rs` containing:
+1. If `stubs/jetbrains/phpstorm-stubs/` does not exist, fetches the latest release tarball from the JetBrains/phpstorm-stubs GitHub repository and extracts it. This makes `cargo install` and `cargo build` work without any prior setup.
+2. Reads `stubs/jetbrains/phpstorm-stubs/PhpStormStubsMap.php` — a generated index mapping symbol names to file paths.
+3. Emits `stub_map_generated.rs` containing:
    - `STUB_FILES`: an array of `include_str!(...)` calls embedding every referenced PHP file (~502 files, ~8.5MB of source).
    - `STUB_CLASS_MAP`: maps class/interface/trait names → index into `STUB_FILES`.
    - `STUB_FUNCTION_MAP`: maps function names → index into `STUB_FILES`.
    - `STUB_CONSTANT_MAP`: maps constant names → index into `STUB_FILES`.
 
-The build script watches `composer.lock` for changes, so running `composer update` followed by `cargo build` automatically picks up new stub versions.
+The stubs are cached in the `stubs/` directory (gitignored). To update to the latest version, delete `stubs/` and rebuild.
 
 ### Runtime Lookup — Classes
 
@@ -464,7 +465,7 @@ User code is never filtered. The `php_version` field in `DocblockCtx` is `None`
 
 ### Graceful Degradation
 
-If the stubs aren't installed (e.g. `composer install` hasn't been run), `build.rs` generates empty arrays and the build succeeds. The LSP just won't know about built-in PHP symbols.
+If the stubs can't be fetched (e.g. no network access during the build), `build.rs` generates empty arrays and the build succeeds. The LSP just won't know about built-in PHP symbols.
 
 ## Inheritance Resolution
 

docs/BUILDING.md

@@ -36,9 +36,10 @@ cargo clippy -- -D warnings
 cargo clippy --tests -- -D warnings
 cargo fmt --check
 php -l example.php
+php -d zend.assertions=1 example.php
 ```
 
-All five must pass with zero warnings and zero failures.
+All six must pass with zero warnings and zero failures.
 
 ### Manual LSP Testing
 

docs/CHANGELOG.md

@@ -53,6 +53,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Concurrent read access to shared state.** All read-heavy maps now use `parking_lot::RwLock` instead of `std::sync::Mutex`, allowing multiple requests to read in parallel.
 - **Parallel workspace indexing.** Find References and other workspace-wide operations now parse files across multiple CPU cores. The workspace walk respects `.gitignore` rules instead of hardcoding directory names to skip. Self-scan classmap building, PSR-4 directory scanning, and vendor package scanning now read and scan files in parallel across all CPU cores. The byte-level PHP scanner uses `memchr` SIMD acceleration to skip comments, strings, and heredocs instead of scanning byte-by-byte. Redundant `composer.json` reads during initialization have been eliminated.
 - **Merged classmap + self-scan pipeline.** The Composer classmap and the self-scanner are no longer mutually exclusive. PHPantom always loads the Composer classmap (when present) and then self-scans all PSR-4 and vendor directories, skipping files the classmap already covers. Stale or incomplete classmaps are no longer a problem: whatever Composer already knew about is a free performance win, and whatever it missed is discovered automatically. The fragile completeness heuristic that decided whether to trust the classmap has been removed. Monorepo subprojects use the same merged pipeline.
+- **Automatic stub fetching.** The build script now downloads phpstorm-stubs from GitHub automatically when the `stubs/` directory is missing. `cargo install` and `cargo build` work without any prior setup. Composer is no longer required to build PHPantom.
 
 ### Fixed
 

docs/SETUP.md

@@ -17,7 +17,6 @@ Download the latest binary for your platform from [GitHub Releases](https://gith
 See [BUILDING.md](BUILDING.md) for full instructions. Quick version:
 
 ```bash
-composer install
 cargo build --release
 # Binary is at target/release/phpantom_lsp
 ```

docs/todo/external-stubs.md

@@ -554,9 +554,8 @@ but it is not a priority.
 ### Building without embedded stubs
 
 The `build.rs` script already handles a missing `stubs/` directory
-gracefully by generating empty arrays. An IDE extension that wants
-to distribute PHPantom without embedded stubs simply skips
-`composer install` in the PHPantom build directory. The binary
+gracefully by generating empty arrays. If the automatic GitHub
+fetch fails (e.g. no network access during the build), the binary
 compiles and runs normally; it just has no built-in fallback for
 PHP standard library symbols.
 

src/server.rs

@@ -548,7 +548,6 @@ impl Backend {
         }
 
         let (mappings, vendor_dir) = composer::parse_composer_json(root);
-        let mapping_count = mappings.len();
 
         // Parse the raw composer.json once so that build_self_scan_composer
         // can reuse it without redundant I/O.
@@ -572,15 +571,10 @@ impl Backend {
                 .await;
         }
 
-        let (classmap, classmap_source) = match strategy {
+        let (classmap, source_label) = match strategy {
             IndexingStrategy::None => {
                 let cm = composer::parse_autoload_classmap(root, &vendor_dir);
-                let source = if cm.is_empty() {
-                    "none"
-                } else {
-                    "composer classmap"
-                };
-                (cm, source)
+                (cm, "composer")
             }
             IndexingStrategy::SelfScan | IndexingStrategy::Full => {
                 let skip_paths = HashSet::new();
@@ -595,11 +589,6 @@ impl Backend {
             }
             IndexingStrategy::Composer => {
                 // ── Merged classmap + self-scan pipeline ─────────────
-                // Always load the Composer classmap (if it exists) and
-                // then self-scan with a skip set built from the classmap
-                // file paths.  Whatever the classmap already covers is a
-                // free performance win; whatever it's missing, we find
-                // ourselves.  No completeness heuristic needed.
                 let composer_cm = composer::parse_autoload_classmap(root, &vendor_dir);
                 let skip_paths: HashSet<PathBuf> = composer_cm.values().cloned().collect();
                 let scan = self.build_self_scan_composer(
@@ -613,16 +602,11 @@ impl Backend {
                 for (fqcn, path) in scan.classmap {
                     merged.entry(fqcn).or_insert(path);
                 }
-                let source = if skip_paths.is_empty() {
-                    "self-scan"
-                } else {
-                    "composer classmap + self-scan"
-                };
-                (merged, source)
+                (merged, "composer+scan")
             }
         };
 
-        let classmap_count = classmap.len();
+        let symbol_count = classmap.len();
         *self.classmap.write() = classmap;
 
         // ── Autoload files ──────────────────────────────────────────
@@ -631,25 +615,20 @@ impl Backend {
                 .await;
         }
 
-        let autoload_count = self.scan_autoload_files(root, &vendor_dir);
+        self.scan_autoload_files(root, &vendor_dir);
 
-        let func_index_count = self.autoload_function_index.read().len();
-        let const_index_count = self.autoload_constant_index.read().len();
-
-        let index_suffix = if func_index_count > 0 || const_index_count > 0 {
-            format!(
-                ", {} indexed function(s), {} indexed constant(s)",
-                func_index_count, const_index_count
-            )
-        } else {
-            String::new()
-        };
+        let symbol_count = symbol_count
+            + self.autoload_function_index.read().len()
+            + self.autoload_constant_index.read().len();
 
         self.log(
             MessageType::INFO,
             format!(
-                "PHPantom initialized! PHP {}, {} PSR-4 mapping(s), {} classmap entries ({}), {} autoload file(s){}",
-                php_version, mapping_count, classmap_count, classmap_source, autoload_count, index_suffix
+                "PHPantom: PHP {}, {} symbols from {}, stubs {}",
+                php_version,
+                symbol_count,
+                source_label,
+                crate::stubs::STUBS_VERSION
             ),
         )
         .await;
@@ -690,8 +669,6 @@ impl Backend {
 
         // Collect subproject root paths for the skip set.
         let mut skip_dirs: HashSet<PathBuf> = HashSet::new();
-        let mut total_mapping_count = 0usize;
-        let mut total_autoload_count = 0usize;
         let sub_count = subprojects.len();
 
         for (sub_idx, (sub_root, vendor_dir)) in subprojects.iter().enumerate() {
@@ -720,7 +697,6 @@ impl Backend {
 
             // ── PSR-4 mappings ──────────────────────────────────────
             let (mappings, _) = composer::parse_composer_json(sub_root);
-            total_mapping_count += mappings.len();
 
             // Resolve base_path values to absolute paths so that
             // resolve_class_path works regardless of workspace_root.
@@ -744,7 +720,7 @@ impl Backend {
             self.add_vendor_dir(&vendor_path);
 
             // ── Autoload files ──────────────────────────────────────
-            total_autoload_count += self.scan_autoload_files(sub_root, vendor_dir);
+            self.scan_autoload_files(sub_root, vendor_dir);
 
             // ── Merged classmap + self-scan ──────────────────────────
             // Load the subproject's Composer classmap as a skip set,
@@ -789,24 +765,18 @@ impl Backend {
             }
         }
 
-        let classmap_count = self.classmap.read().len();
-        let func_index_count = self.autoload_function_index.read().len();
-        let const_index_count = self.autoload_constant_index.read().len();
-
-        let index_suffix = if func_index_count > 0 || const_index_count > 0 {
-            format!(
-                ", {} indexed function(s), {} indexed constant(s)",
-                func_index_count, const_index_count
-            )
-        } else {
-            String::new()
-        };
+        let symbol_count = self.classmap.read().len()
+            + self.autoload_function_index.read().len()
+            + self.autoload_constant_index.read().len();
 
         self.log(
             MessageType::INFO,
             format!(
-                "PHPantom initialized! PHP {}, {} subproject(s), {} PSR-4 mapping(s), {} classmap entries, {} autoload file(s){}",
-                php_version, subprojects.len(), total_mapping_count, classmap_count, total_autoload_count, index_suffix
+                "PHPantom: PHP {}, {} symbols from {} subprojects, stubs {}",
+                php_version,
+                symbol_count,
+                subprojects.len(),
+                crate::stubs::STUBS_VERSION
             ),
         )
         .await;
@@ -839,26 +809,20 @@ impl Backend {
         let scan = classmap_scanner::scan_workspace_fallback_full(root, &skip_dirs);
         self.populate_autoload_indices(&scan);
 
-        let classmap_count = scan.classmap.len();
+        let symbol_count = scan.classmap.len();
         *self.classmap.write() = scan.classmap;
 
-        let func_index_count = self.autoload_function_index.read().len();
-        let const_index_count = self.autoload_constant_index.read().len();
-
-        let index_suffix = if func_index_count > 0 || const_index_count > 0 {
-            format!(
-                ", {} indexed function(s), {} indexed constant(s)",
-                func_index_count, const_index_count
-            )
-        } else {
-            String::new()
-        };
+        let symbol_count = symbol_count
+            + self.autoload_function_index.read().len()
+            + self.autoload_constant_index.read().len();
 
         self.log(
             MessageType::INFO,
             format!(
-                "PHPantom initialized! PHP {}, {} classmap entries (workspace scan){}",
-                php_version, classmap_count, index_suffix
+                "PHPantom: PHP {}, {} symbols from workspace scan, stubs {}",
+                php_version,
+                symbol_count,
+                crate::stubs::STUBS_VERSION
             ),
         )
         .await;

src/stubs.rs

@@ -36,6 +36,13 @@ use std::collections::HashMap;
 // Pull in the generated static arrays.
 include!(concat!(env!("OUT_DIR"), "/stub_map_generated.rs"));
 
+/// The phpstorm-stubs version that was embedded at build time.
+///
+/// Set by `build.rs` via `cargo:rustc-env`.  Contains the GitHub release
+/// tag (e.g. `"v2025.3"`), `"unknown"` when stubs were present but the
+/// version file was missing, or `"none"` when stubs could not be fetched.
+pub const STUBS_VERSION: &str = env!("PHPANTOM_STUBS_VERSION");
+
 /// Build a lookup table mapping class/interface/trait short names to their
 /// embedded PHP source code.
 ///