feat(laravel): support custom Eloquent builders and optimize references

- Implement support for #[UseEloquentBuilder] and HasBuilder trait.
- Support inherited custom builder attributes by walking the Model parent chain.
- Fix Go-to-Definition and Completion for forwarded methods on inherited custom builders.
- Fix 'Find References' for forwarded builder methods by bridging Model/Builder hierarchies.
- Improve reference accuracy by scoping hierarchy 'walk-down' to classes defining the member.
- Relax is_static check for Laravel-related member references.
- Optimize LSP responsiveness with background parsing and completion caching.
- Add comprehensive integration tests for Laravel custom builder resolution and references.

Author: MingJen

Cargo.toml

@@ -59,3 +59,11 @@ harness = false
 [[bench]]
 name = "references"
 harness = false
+
+[[bench]]
+name = "laravel_completion"
+harness = false
+
+[[bench]]
+name = "custom_builder"
+harness = false

benches/custom_builder.rs

@@ -0,0 +1,121 @@
+use criterion::{Criterion, black_box, criterion_group, criterion_main};
+use phpantom_lsp::Backend;
+use std::collections::HashMap;
+use tower_lsp::LanguageServer;
+use tower_lsp::lsp_types::*;
+
+fn rt() -> tokio::runtime::Runtime {
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+}
+
+fn leak_str(s: String) -> &'static str {
+    Box::leak(s.into_boxed_str())
+}
+
+async fn setup_laravel_backend() -> Backend {
+    let mut stubs = HashMap::new();
+    stubs.insert("Illuminate\\Database\\Eloquent\\Model", "<?php namespace Illuminate\\Database\\Eloquent; class Model { public static function query(): CustomBuilder {} }");
+    stubs.insert("Illuminate\\Database\\Eloquent\\Builder", "<?php namespace Illuminate\\Database\\Eloquent; class Builder { public function where($column): self {} }");
+
+    let mut user_src = String::from(
+        "<?php namespace App\\Models; class User extends \\Illuminate\\Database\\Eloquent\\Model {\n",
+    );
+    for i in 0..200 {
+        user_src.push_str(&format!(
+            "    public function scopeActive{}($query) {{}}\n",
+            i
+        ));
+        user_src.push_str(&format!("    public $prop{};\n", i));
+    }
+    user_src.push('}');
+    stubs.insert("App\\Models\\User", leak_str(user_src));
+
+    // Deep inheritance for the builder
+    for i in 0..10 {
+        let parent = if i == 0 {
+            "Illuminate\\Database\\Eloquent\\Builder"
+        } else {
+            leak_str(format!("App\\QueryBuilders\\BaseBuilder{}", i - 1))
+        };
+        let current = leak_str(format!("App\\QueryBuilders\\BaseBuilder{}", i));
+        let src = leak_str(format!(
+            "<?php namespace App\\QueryBuilders; class BaseBuilder{} extends {} {{ public function m{}(): void {{}} }}",
+            i, parent, i
+        ));
+        stubs.insert(current, src);
+    }
+
+    stubs.insert("App\\QueryBuilders\\CustomBuilder", "<?php namespace App\\QueryBuilders; use App\\QueryBuilders\\BaseBuilder9; class CustomBuilder extends BaseBuilder9 { public function customMethod(): void {} }");
+
+    Backend::new_test_with_stubs(stubs)
+}
+
+async fn open_file(backend: &Backend, uri_str: &str, content: &str) -> Url {
+    let uri = Url::parse(uri_str).unwrap();
+    let params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: content.to_string(),
+        },
+    };
+    backend.did_open(params).await;
+    uri
+}
+
+fn generate_source() -> String {
+    r#"<?php
+namespace App\Models;
+use App\QueryBuilders\CustomBuilder;
+
+/** @var CustomBuilder<\App\Models\User> $query */
+$query->wher
+"#
+    .to_string()
+}
+
+fn bench_custom_builder_completion(c: &mut Criterion) {
+    let runtime = rt();
+    let backend = runtime.block_on(setup_laravel_backend());
+    let source = generate_source();
+    let uri = runtime.block_on(open_file(&backend, "file:///app/Models/User.php", &source));
+    let lines: Vec<&str> = source.lines().collect();
+    let line = lines.len() as u32 - 1;
+    let last_line = lines.last().unwrap();
+    let col = last_line.len() as u32;
+
+    let mut group = c.benchmark_group("custom_builder_completion");
+
+    group.bench_function("custom_builder_deep_inheritance", |b| {
+        b.iter(|| {
+            runtime.block_on(async {
+                backend.clear_completion_cache();
+                let params = CompletionParams {
+                    text_document_position: TextDocumentPositionParams {
+                        text_document: TextDocumentIdentifier { uri: uri.clone() },
+                        position: Position {
+                            line,
+                            character: col,
+                        },
+                    },
+                    work_done_progress_params: WorkDoneProgressParams::default(),
+                    partial_result_params: PartialResultParams::default(),
+                    context: Some(CompletionContext {
+                        trigger_kind: CompletionTriggerKind::INVOKED,
+                        trigger_character: None,
+                    }),
+                };
+                let _ = black_box(backend.completion(params).await);
+            })
+        })
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_custom_builder_completion);
+criterion_main!(benches);

benches/laravel_completion.rs

@@ -0,0 +1,119 @@
+use criterion::{Criterion, black_box, criterion_group, criterion_main};
+use phpantom_lsp::Backend;
+use std::collections::HashMap;
+use tower_lsp::LanguageServer;
+use tower_lsp::lsp_types::*;
+
+fn rt() -> tokio::runtime::Runtime {
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+}
+
+async fn setup_laravel_backend() -> Backend {
+    let mut stubs = HashMap::new();
+    stubs.insert("Illuminate\\Database\\Eloquent\\Model", "<?php namespace Illuminate\\Database\\Eloquent; class Model { public static function query(): Builder {} }");
+    stubs.insert("Illuminate\\Database\\Eloquent\\Builder", "<?php namespace Illuminate\\Database\\Eloquent; class Builder { public function where($column): self {} public function whereIn($column, $values): self {} public function orWhere($column): self {} }");
+
+    Backend::new_test_with_stubs(stubs)
+}
+
+async fn open_file(backend: &Backend, uri_str: &str, content: &str) -> Url {
+    let uri = Url::parse(uri_str).unwrap();
+    let params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: content.to_string(),
+        },
+    };
+    backend.did_open(params).await;
+    uri
+}
+
+fn generate_laravel_model_source() -> String {
+    r#"<?php
+namespace App\Models;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * @property string $name
+ * @property string $email
+ */
+class User extends Model {}
+
+$user = new User();
+$user->wher
+"#
+    .to_string()
+}
+
+fn bench_laravel_model_completion(c: &mut Criterion) {
+    let runtime = rt();
+    let backend = runtime.block_on(setup_laravel_backend());
+    let source = generate_laravel_model_source();
+    let uri = runtime.block_on(open_file(&backend, "file:///app/Models/User.php", &source));
+    let lines: Vec<&str> = source.lines().collect();
+    let line = lines.len() as u32 - 1;
+    let last_line = lines.last().unwrap();
+    let col = last_line.len() as u32; // After 'wher'
+
+    let mut group = c.benchmark_group("laravel_completion");
+
+    group.bench_function("model_where_prefix", |b| {
+        b.iter(|| {
+            runtime.block_on(async {
+                let params = CompletionParams {
+                    text_document_position: TextDocumentPositionParams {
+                        text_document: TextDocumentIdentifier { uri: uri.clone() },
+                        position: Position {
+                            line,
+                            character: col,
+                        },
+                    },
+                    work_done_progress_params: WorkDoneProgressParams::default(),
+                    partial_result_params: PartialResultParams::default(),
+                    context: Some(CompletionContext {
+                        trigger_kind: CompletionTriggerKind::INVOKED,
+                        trigger_character: None,
+                    }),
+                };
+                let _ = black_box(backend.completion(params).await);
+            })
+        })
+    });
+
+    // Simulate typing: Model::w -> Model::wh -> Model::whe -> Model::wher
+    group.bench_function("model_typing_sequence", |b| {
+        b.iter(|| {
+            runtime.block_on(async {
+                for i in 1..=4 {
+                    let current_col = col - 4 + i;
+                    let params = CompletionParams {
+                        text_document_position: TextDocumentPositionParams {
+                            text_document: TextDocumentIdentifier { uri: uri.clone() },
+                            position: Position {
+                                line,
+                                character: current_col,
+                            },
+                        },
+                        work_done_progress_params: WorkDoneProgressParams::default(),
+                        partial_result_params: PartialResultParams::default(),
+                        context: Some(CompletionContext {
+                            trigger_kind: CompletionTriggerKind::INVOKED,
+                            trigger_character: None,
+                        }),
+                    };
+                    let _ = black_box(backend.completion(params).await);
+                }
+            })
+        })
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_laravel_model_completion);
+criterion_main!(benches);

examples/laravel/app/Models/Baker.php

@@ -3,7 +3,9 @@
 namespace App\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
 
+#[UseEloquentBuilder(BakerBuilder::class)]
 class Baker extends Model
 {
     public function getName(): string { return ''; }

examples/laravel/app/Models/BakerBuilder.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+
+/**
+ * @template TModel of \App\Models\Baker
+ * @extends Builder<TModel>
+ */
+class BakerBuilder extends Builder
+{
+    /**
+     * @return $this
+     */
+    public function active()
+    {
+        return $this->where('active', true);
+    }
+}

src/completion/builder.rs

@@ -22,6 +22,7 @@ use std::sync::Arc;
 use tower_lsp::lsp_types::*;
 
 use super::resolve::CompletionItemData;
+use crate::hover::{MemberKindForOrigin, find_declaring_class};
 use crate::types::Visibility;
 use crate::types::*;
 
@@ -658,7 +659,8 @@ pub(crate) fn build_union_completion_items(
             uri,
         );
 
-        for item in items {
+        for mut item in items {
+            apply_declaring_class_label(&mut item, &merged, class_loader);
             if let Some(existing) = all_items
                 .iter_mut()
                 .find(|existing| existing.label == item.label)
@@ -679,6 +681,47 @@ pub(crate) fn build_union_completion_items(
     merge_union_completion_items(all_items, occurrence_count, num_candidates)
 }
 
+fn apply_declaring_class_label(
+    item: &mut CompletionItem,
+    owner: &ClassInfo,
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) {
+    let Some(data_value) = item.data.as_ref() else {
+        return;
+    };
+    let Ok(mut data) = serde_json::from_value::<CompletionItemData>(data_value.clone()) else {
+        return;
+    };
+    let member_kind = match data.kind.as_str() {
+        "method" => MemberKindForOrigin::Method,
+        "property" => MemberKindForOrigin::Property,
+        "constant" => MemberKindForOrigin::Constant,
+        _ => return,
+    };
+
+    let declaring = find_declaring_class(owner, &data.member_name, &member_kind, class_loader);
+    let declaring_name = declaring.name.to_string();
+    if declaring_name == data.class_name {
+        return;
+    }
+
+    data.class_name = declaring_name.clone();
+    data.extra_class_names.clear();
+    if let Ok(value) = serde_json::to_value(&data) {
+        item.data = Some(value);
+    }
+
+    let description = Some(display_class_name(&declaring_name).to_string());
+    if let Some(ref mut label_details) = item.label_details {
+        label_details.description = description;
+    } else {
+        item.label_details = Some(CompletionItemLabelDetails {
+            detail: None,
+            description,
+        });
+    }
+}
+
 /// Merge the class name from a new item's `data` into the existing item's
 /// `data.extra_class_names` so that `completionItem/resolve` can iterate
 /// all union branches when building hover documentation.