Skip to content

feat(laravel): support custom Eloquent builders and improve LSP responsiveness#118

Merged
AJenbo merged 4 commits into
PHPantom-dev:mainfrom
MingJen:feat/laravel-custom-builder
May 17, 2026
Merged

feat(laravel): support custom Eloquent builders and improve LSP responsiveness#118
AJenbo merged 4 commits into
PHPantom-dev:mainfrom
MingJen:feat/laravel-custom-builder

Conversation

@MingJen
Copy link
Copy Markdown
Contributor

@MingJen MingJen commented May 13, 2026

Summary

This PR introduces comprehensive support for Laravel custom Eloquent builders (#[UseEloquentBuilder], HasBuilder trait) and significantly enhances LSP
responsiveness through background processing and intelligent completion caching. Editor users will now see accurate type information and completion for
forwarded builder methods, even when using complex inheritance patterns in their models.

Changes

  • Adds Laravel custom Eloquent builder support: Implements resolution for methods defined in custom builders specified via the #[UseEloquentBuilder]
    attribute or HasBuilder trait.
  • Improves LSP responsiveness: Offloads file parsing (update_ast) and diagnostic publishing to background tasks, preventing the main thread from blocking
    during heavy typing.
  • Implements member completion caching: Caches unfiltered member lists per-target to drastically reduce latency for subsequent completions while the user is
    typing a member name.
  • Adds Laravel background warming: Automatically indexes common Laravel builder classes in the background during startup to eliminate "first-access" latency
    in Eloquent projects.
  • Refines Find References logic: Scopes the hierarchy "walk-down" to only those classes that actually define the member, improving both the performance and
    accuracy of project-wide reference searches.

How It Works (Laravel Custom Builders)

  1. Extraction: During the parsing phase, src/symbol_map/extraction.rs identifies #[UseEloquentBuilder] attributes and stores the builder's FQN in the
    ClassInfo.
  2. Virtual Member Generation: When a Model's members are requested, virtual_members/laravel/builder.rs walks the inheritance chain to find the applicable
    custom builder and injects its instance methods as static "forwarded" methods on the Model.
  3. Bridge Resolution: The reference engine (src/references/mod.rs) implements a "bridge" in the hierarchy resolution. If a search is initiated for a Model
    method, the engine automatically includes the associated Builder in its search scope (and vice versa), ensuring that calls like User::active() resolve
    correctly to UserBuilder::active().

Why Core Library Was Modified

  • src/references/mod.rs & src/definition/member/mod.rs: Modified to implement the Model-Builder hierarchy bridge. This was necessary because the
    relationship between a Laravel Model and its Builder is a framework-specific inheritance pattern that isn't captured by standard PHP class hierarchies.
  • src/server.rs: Background task orchestration was added to the core LSP loop to ensure that state updates (AST, indices) remain consistent while processing
    concurrent interactive requests.

Tests

  • tests/integration/laravel_custom_builder.rs: Covers go-to-definition, completion, and type resolution for custom builders, including inherited builder
    attributes and model-generic substitution.
  • tests/integration/laravel_references.rs: Asserts that "Find References" correctly bridges between declarations in a custom builder and usages on the
    associated Model.
  • benches/custom_builder.rs: Benchmarks the overhead of custom builder resolution in large Model hierarchies.

@codecov-commenter
Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 87.74194% with 76 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.80%. Comparing base (6c35273) to head (24045c8).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/completion/handler.rs 79.16% 35 Missing ⚠️
src/parser/classes.rs 84.00% 8 Missing ⚠️
src/completion/builder.rs 80.55% 7 Missing ⚠️
src/references/mod.rs 94.21% 7 Missing ⚠️
src/virtual_members/laravel/builder.rs 93.91% 7 Missing ⚠️
src/virtual_members/mod.rs 88.37% 5 Missing ⚠️
src/completion/call_resolution.rs 72.72% 3 Missing ⚠️
src/lib.rs 75.00% 3 Missing ⚠️
src/definition/member/mod.rs 94.44% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #118      +/-   ##
==========================================
+ Coverage   86.71%   86.80%   +0.09%     
==========================================
  Files         170      170              
  Lines      108396   108888     +492     
==========================================
+ Hits        93996    94524     +528     
+ Misses      14400    14364      -36     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

MingJen and others added 4 commits May 17, 2026 17:34
- 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.
- Fix formatting across multiple files using 'cargo fmt'.
- Collapse nested 'if let' statements into single chains with 'and_then' or 'let_chains'.
- Remove redundant closures.
- Fix unused variable warning in 'src/references/mod.rs'.
@AJenbo AJenbo force-pushed the feat/laravel-custom-builder branch from 24045c8 to 8a49775 Compare May 17, 2026 18:44
@AJenbo AJenbo merged commit 18499a6 into PHPantom-dev:main May 17, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants