Implement virtual properties for model created_at / updated_at with

rename and toggle support.

Author: AJenbo

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Eloquent timestamp properties.** Models extending `Illuminate\Database\Eloquent\Model` now automatically get `created_at` and `updated_at` virtual properties typed as `Carbon\Carbon`. Setting `$timestamps = false` suppresses both. Overriding `CREATED_AT` or `UPDATED_AT` constants changes the column name; setting either to `null` disables that column. Explicit `$casts` entries (e.g. `'created_at' => 'immutable_datetime'`) take priority over the timestamp defaults.
 - **`fix` CLI subcommand.** `phpantom_lsp fix` applies automated code fixes across a project, modeled after php-cs-fixer. Specify rules with `--rule unused_import` (multiple allowed) or omit to run all preferred native fixers. `--dry-run` reports what would change without writing files (exit code 2). `--with-phpstan` enables PHPStan-based fixers (not yet implemented). The first shipped rule, `unused_import`, removes all unused `use` statements project-wide, handling simple imports, group imports, and blank-line collapsing. Supports path filtering (`fix src/`) and single-file mode.
 - **Array element type extraction from property generics.** Bracket access on properties annotated with generic array types (e.g. `$this->cache[$key]->` where `cache` is `array<string, IntCollection>`, or `$this->translations[0]->` where `translations` is `Collection<int, Translation>`) now resolves the element type correctly. Previously the generic parameters were lost during property chain resolution, causing "subject type could not be resolved" on any member access after the bracket. Works for `$this->prop`, `$obj->prop`, nested chains like `$this->nested->prop[0]->`, string-literal keys, and method chains after the bracket access.
 - **Template binding from closure return types.** Methods like `Collection::reduce()` that declare a method-level `@template` parameter bound through a callable's return type now resolve correctly. When the closure or arrow function argument has a return type annotation (e.g. `fn(Decimal $carry, $item): Decimal => ...`), the return type binds the template parameter, so the method's own return type resolves to the concrete class. This works for `fn()` arrow functions, `function()` closures, and closures with `use()` clauses.

docs/todo.md

@@ -24,6 +24,9 @@ within the same impact tier.
 | #   | Item                                                                                                                                       | Impact | Effort     |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ---------- |
 | T18 | [Method-level template parameter resolution at call sites](todo/type-inference.md#t18-method-level-template-parameter-resolution-at-call-sites) | Medium | Medium     |
+| L3  | [`$dates` array (deprecated)](todo/laravel.md#l3-dates-array-deprecated)                                                                     | Low-Med | Low       |
+| L11 | [`$appends` array](todo/laravel.md#l11-appends-array)                                                                                        | Low    | Low        |
+| L13 | [`where{PropertyName}()` dynamic methods on Builder](todo/laravel.md#l13-wherepropertyname-dynamic-methods-on-builder)                        | High   | Medium     |
 | H17 | [`missingType.iterableValue` — add `@return` with inferred element type](todo/phpstan-actions.md#h17-missingtype-iterablevalue-return-type--add-return-with-iterable-type) | Medium | High       |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium | Medium     |
 | H6  | `return.type` — update return type to match actual returns                                                                                   | Medium | Medium     |

docs/todo/diagnostics.md

@@ -368,3 +368,39 @@ own diagnostics.
 `str-contains`/`str-starts-with` modernization,
 `prefer-arrow-function`, `constant-condition`, `no-self-assignment`,
 `explicit-nullable-param`, `valid-docblock`.
+
+## D13. Unify diagnostic subject resolution with completion/hover
+
+`unknown_members.rs` has two secondary resolvers that run their own
+independent type resolution when `resolve_target_classes_expr` returns
+empty:
+
+- `resolve_scalar_subject_type` (~130 lines) re-resolves variables,
+  property chains, and call expressions to detect scalar types.
+- `resolve_unresolvable_class_subject` (~80 lines) re-resolves
+  variables and call expressions to detect class names that can't be
+  loaded.
+
+Both duplicate logic from `resolver.rs` and
+`variable/resolution.rs` but can diverge, producing diagnostics for
+types that completion and hover cannot see (or vice versa).
+
+### Goal
+
+The diagnostic path should use the same resolution result that
+completion and hover use. All three consumers should see identical
+outcomes for the same subject text at the same cursor position.
+
+### Approach
+
+Extend the shared resolver's return type (or add a secondary result)
+to carry scalar type information and unresolvable class names
+alongside the resolved `ClassInfo` list. The diagnostic collector
+would then inspect this enriched result instead of running its own
+resolution. This eliminates the secondary resolvers entirely.
+
+### Files
+
+- `src/diagnostics/unknown_members.rs` — remove
+  `resolve_scalar_subject_type` and `resolve_unresolvable_class_subject`
+- `src/completion/resolver.rs` — enrich the resolution result

docs/todo/laravel.md

@@ -152,6 +152,46 @@ today and what is still missing.
 
 ---
 
+#### L13. `where{PropertyName}()` dynamic methods on Builder
+
+**Impact: High · Effort: Medium**
+
+**Depends on:** All model property gathering gaps being resolved first
+(L3, L11, and any others that feed into `column_names` or
+`casts_definitions`). The `where{PropertyName}` methods are derived
+from the model's known properties, so incomplete property lists produce
+incomplete method coverage.
+
+Eloquent's `Builder::__call()` translates calls like
+`whereLangCode($value)` into `where('lang_code', $value)` and returns
+`$this`. This is a dynamic convention based on the model's column
+names: `where` + StudlyCase column name.
+
+PHPantom currently has no knowledge of this pattern. The `__call`
+return type preservation (shipped in 0.5.0) keeps chains alive when
+`__call` exists, but the analyzer still reports `unknown_member` for
+each `where{PropertyName}` call because no actual method by that name
+exists on the Builder or Model.
+
+From the luxplus/shared triage, this pattern accounts for ~17
+diagnostics (29% of remaining errors): 11 direct `unknown_member`
+errors plus ~6 cascading `unresolved_member_access` failures.
+
+Affected examples: `whereBrandId()`, `whereSubcategoryId()`,
+`whereLangCode()`, `whereLanguage()`, `whereIsLuxury()`,
+`whereIsDerma()`, `whereIsProHairCare()`, `whereIsVisible()`.
+
+**Implementation approach:** In the `LaravelModelProvider` (or a new
+virtual-member pass), for each model that extends
+`Illuminate\Database\Eloquent\Model`, synthesize `where{StudlyCase}()`
+methods on the associated Builder class. Each method should accept one
+parameter (the value) and return `$this` (the Builder). The column
+names come from all property sources: `$casts`, `$attributes`,
+`$fillable`/`$guarded`/`$hidden`/`$visible`, `$dates`, timestamps,
+relationship `*_count`, and `@property` annotations.
+
+---
+
 #### L2. `morphedByMany` missing from relationship method map
 
 **Impact: Low-Medium · Effort: Low**

docs/todo/refactor.md

@@ -214,38 +214,4 @@ Each item must include:
 
 ## Outstanding items
 
-### Tighter `mago-type-syntax` integration
-
-The project already wraps `mago-type-syntax` via `PhpType` in
-`src/php_type.rs` and uses it for structured type operations (substitution,
-equivalence, display). Several areas still do manual string-level type
-manipulation that could be replaced or simplified by leaning on `PhpType`
-and the mago parser/lexer. See also
-`scratch/mago_type_syntax_integration.md` for completed items (#1, #2)
-and additional context.
-
-Grouped by size:
-
-#### Medium
-
-- **`ArrayShapeEntry.value_type: String` → `PhpType`.**
-  `src/types.rs` `ArrayShapeEntry` stores the value type as a `String`.
-  `src/docblock/shapes.rs` `shape_entries_to_array_entries()` converts
-  `PhpType::ShapeEntry` (which already has `value_type: PhpType`) back
-  to strings via `.to_string()`, and callers re-parse with
-  `PhpType::parse()`. Store `PhpType` directly to eliminate the
-  round-trip. Files: `src/types.rs`, `src/docblock/shapes.rs`,
-  `tests/integration/completion_array_shapes.rs`.
-
-#### Large
-
-- **`split_type_token()` → `mago_type_syntax::lexer::TypeLexer`.**
-  `src/docblock/type_strings.rs` L107-215 is a 108-line hand-rolled
-  tokenizer tracking `<>`, `{}`, `()` nesting, quoted strings, and
-  union/intersection suffixes. It is called from 24 sites across 7
-  files. The `TypeLexer` from `mago-type-syntax` is available but
-  unused. Replacing `split_type_token` with lexer-based boundary
-  detection would eliminate the largest piece of manual type parsing.
-  High risk due to the number of callers; should be done as a
-  standalone task with a parallel implementation and extensive
-  comparison testing.
+No outstanding items.

src/definition/member/mod.rs

@@ -198,6 +198,27 @@ impl Backend {
                 }
             }
 
+            // ── Timestamp constant redirect ─────────────────────────
+            // When the property name matches a timestamp column,
+            // jump straight to the CREATED_AT / UPDATED_AT constant.
+            if extends_eloquent_model(lookup_class, &class_loader)
+                && let Some(const_name) =
+                    Self::timestamp_property_to_constant(lookup_class, &effective_name)
+                && let Some((const_class, const_fqn)) =
+                    Self::find_declaring_class(lookup_class, const_name, &class_loader)
+                && let Some((class_uri, class_content)) =
+                    self.find_class_file_content(&const_fqn, uri, content)
+                && let Some(position) = Self::find_member_position(
+                    &class_content,
+                    const_name,
+                    MemberKind::Constant,
+                    const_class.member_name_offset(const_name, "constant"),
+                )
+                && let Ok(parsed_uri) = Url::parse(&class_uri)
+            {
+                return Some(point_location(parsed_uri, position));
+            }
+
             // ── Scope method mapping ────────────────────────────────
             // Laravel scope methods are defined as `scopeActive()` but
             // invoked as `active()`.  When the effective name doesn't
@@ -810,4 +831,34 @@ impl Backend {
         let (declaring, fqn) = Self::find_declaring_class(&model, member_name, class_loader)?;
         Some((declaring, fqn, member_name.to_string()))
     }
+
+    /// Map a timestamp virtual property name to its defining constant.
+    ///
+    /// Returns `Some("CREATED_AT")` or `Some("UPDATED_AT")` when the
+    /// property name matches the model's configured timestamp column,
+    /// or `None` when the property is not a timestamp.
+    fn timestamp_property_to_constant<'a>(
+        class: &ClassInfo,
+        property_name: &str,
+    ) -> Option<&'a str> {
+        if let Some(laravel) = class.laravel() {
+            let created_col = match &laravel.created_at_name {
+                Some(Some(name)) => Some(name.as_str()),
+                Some(None) => None,
+                None => Some("created_at"),
+            };
+            let updated_col = match &laravel.updated_at_name {
+                Some(Some(name)) => Some(name.as_str()),
+                Some(None) => None,
+                None => Some("updated_at"),
+            };
+            if created_col == Some(property_name) {
+                return Some("CREATED_AT");
+            }
+            if updated_col == Some(property_name) {
+                return Some("UPDATED_AT");
+            }
+        }
+        None
+    }
 }

src/parser/classes.rs

@@ -653,6 +653,80 @@ fn infer_type_from_literal(value: &str) -> Option<String> {
     None
 }
 
+/// Extract timestamp configuration from a model class.
+///
+/// Reads three sources:
+///
+/// - `$timestamps` property — `true` (default) or `false`.
+/// - `CREATED_AT` constant — column name string or `null`.
+/// - `UPDATED_AT` constant — column name string or `null`.
+///
+/// Returns `(timestamps, created_at_name, updated_at_name)` using the
+/// same `Option` semantics as `LaravelMetadata`: outer `None` means
+/// "not declared", `Some(None)` means "explicitly `null`".
+fn extract_timestamp_config<'a>(
+    members: impl Iterator<Item = &'a ClassLikeMember<'a>>,
+    content: &str,
+) -> (Option<bool>, Option<Option<String>>, Option<Option<String>>) {
+    let mut timestamps: Option<bool> = None;
+    let mut created_at: Option<Option<String>> = None;
+    let mut updated_at: Option<Option<String>> = None;
+
+    for member in members {
+        match member {
+            ClassLikeMember::Property(Property::Plain(plain)) => {
+                for item in plain.items.iter() {
+                    let var_name = item.variable().name.to_string();
+                    let stripped = var_name.strip_prefix('$').unwrap_or(&var_name);
+                    if stripped != "timestamps" {
+                        continue;
+                    }
+                    if let PropertyItem::Concrete(concrete) = item {
+                        let span = concrete.value.span();
+                        let start = span.start.offset as usize;
+                        let end = span.end.offset as usize;
+                        if let Some(text) = content.get(start..end) {
+                            let trimmed = text.trim();
+                            if trimmed == "false" {
+                                timestamps = Some(false);
+                            } else if trimmed == "true" {
+                                timestamps = Some(true);
+                            }
+                        }
+                    }
+                }
+            }
+            ClassLikeMember::Constant(constant) => {
+                for item in constant.items.iter() {
+                    let name = item.name.value.to_string();
+                    if name != "CREATED_AT" && name != "UPDATED_AT" {
+                        continue;
+                    }
+                    let span = item.value.span();
+                    let start = span.start.offset as usize;
+                    let end = span.end.offset as usize;
+                    let value = content.get(start..end).map(|t| t.trim());
+                    let parsed = match value {
+                        Some("null") | Some("NULL") => Some(None),
+                        Some(v) => extract_string_literal(v).map(Some),
+                        None => None,
+                    };
+                    if let Some(val) = parsed {
+                        if name == "CREATED_AT" {
+                            created_at = Some(val);
+                        } else {
+                            updated_at = Some(val);
+                        }
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
+    (timestamps, created_at, updated_at)
+}
+
 /// Extract column names from `$fillable`, `$guarded`, and `$hidden` arrays.
 ///
 /// These properties contain simple string lists of column names without
@@ -839,6 +913,9 @@ impl Backend {
 
                     let column_names = extract_column_names(class.members.iter(), content);
 
+                    let (timestamps, created_at_name, updated_at_name) =
+                        extract_timestamp_config(class.members.iter(), content);
+
                     let attr_targets = extract_attribute_targets(&class.attribute_lists, content);
 
                     let class_depr = merge_deprecation_info(
@@ -884,6 +961,9 @@ impl Backend {
                             casts_definitions,
                             attributes_definitions,
                             column_names,
+                            timestamps,
+                            created_at_name,
+                            updated_at_name,
                         })),
                     });
 

src/types.rs

@@ -1285,6 +1285,28 @@ pub struct LaravelMetadata {
     /// properties as a last-resort fallback when a column is not
     /// already covered by `$casts` or `$attributes`.
     pub column_names: Vec<String>,
+    /// Whether `$timestamps` is explicitly set on the model.
+    ///
+    /// - `None` — not declared (inherits the default, which is `true`
+    ///   on `Illuminate\Database\Eloquent\Model`).
+    /// - `Some(true)` — explicitly enabled.
+    /// - `Some(false)` — explicitly disabled; no timestamp properties
+    ///   should be synthesized.
+    pub timestamps: Option<bool>,
+    /// Override for the `CREATED_AT` column name constant.
+    ///
+    /// - `None` — not declared (inherits the default `"created_at"`).
+    /// - `Some(None)` — explicitly set to `null`; no created-at
+    ///   property should be synthesized.
+    /// - `Some(Some("created"))` — custom column name.
+    pub created_at_name: Option<Option<String>>,
+    /// Override for the `UPDATED_AT` column name constant.
+    ///
+    /// - `None` — not declared (inherits the default `"updated_at"`).
+    /// - `Some(None)` — explicitly set to `null`; no updated-at
+    ///   property should be synthesized.
+    /// - `Some(Some("modified"))` — custom column name.
+    pub updated_at_name: Option<Option<String>>,
 }
 
 /// Stores extracted class information from a parsed PHP file.

src/virtual_members/laravel/mod.rs

@@ -568,6 +568,32 @@ impl VirtualMemberProvider for LaravelModelProvider {
                 }
                 properties.push(PropertyInfo::virtual_property(column, Some("mixed")));
             }
+
+            // ── Timestamp properties ────────────────────────────────
+            // When $timestamps is true (the default), synthesize
+            // created_at and updated_at as Carbon\Carbon.  The column
+            // names can be overridden via CREATED_AT / UPDATED_AT
+            // constants, and either can be disabled by setting the
+            // constant to null.
+            let timestamps_enabled = laravel.timestamps.unwrap_or(true);
+            if timestamps_enabled {
+                let created_col = match &laravel.created_at_name {
+                    Some(Some(name)) => Some(name.as_str()),
+                    Some(None) => None,         // explicitly null
+                    None => Some("created_at"), // default
+                };
+                let updated_col = match &laravel.updated_at_name {
+                    Some(Some(name)) => Some(name.as_str()),
+                    Some(None) => None,         // explicitly null
+                    None => Some("updated_at"), // default
+                };
+                for col in [created_col, updated_col].into_iter().flatten() {
+                    if seen_props.insert(col.to_string()) {
+                        properties
+                            .push(PropertyInfo::virtual_property(col, Some("Carbon\\Carbon")));
+                    }
+                }
+            }
         }
 
         for method in &class.methods {