fix: Add @property annotations to models for PHPStan type safety (Session 6) #220
Conversation
Added @Property and @property-read PHPDoc annotations to 15 model files to declare Eloquent relationship properties and reduce PHPStan errors. Models updated: - ApplicationPreview - Environment - EnvironmentVariable - LocalFileVolume - LocalPersistentVolume - Organization - PrivateKey - Project - ScheduledTask - Service - SharedEnvironmentVariable - StandaloneDocker - SwarmDocker - Team - User Results: - Total errors reduced: 7145 → 6976 (169 fewer errors) - Undefined property errors: 788 → 694 (94 fewer errors) Part of PHPStan error resolution effort - Issue #203
…sion 6) Added @Property and @property-read PHPDoc annotations to 11 Eloquent model files to declare computed attributes and improve PHPStan static analysis. Models Updated: - Application: ports_exposes_array, ports_mappings_array, fqdns, custom_network_aliases_array, server_status, watch_paths, status, image, pull_request_id, is_container_label_readonly_enabled, custom_docker_run_options, custom_labels - Server: getIp (computed IP attribute) - ApplicationDeploymentQueue: server (computed via deployment) - StandaloneRedis: redis_password, redis_username, ssl_mode, internal_db_url, external_db_url - StandaloneKeydb: ssl_mode, internal_db_url, external_db_url - StandaloneDragonfly: ssl_mode, internal_db_url, external_db_url - StandaloneClickhouse: clickhouse_db, internal_db_url, external_db_url, ports_mappings_array - StandalonePostgresql: internal_db_url, external_db_url - StandaloneMongodb: internal_db_url, external_db_url - StandaloneMysql: internal_db_url, external_db_url - StandaloneMariadb: internal_db_url, external_db_url PHPStan Results: - Before: 6,976 errors - After: 6,805 errors - Reduction: 171 errors (2.5%) Issue: #203
WalkthroughThis pull request adds comprehensive PHPDoc property annotations across 26 Eloquent model files in Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (3)
app/Models/LocalPersistentVolume.php (1)
9-15: Consider extending the$resourceunion type.The
$resourceproperty type may be incomplete. Based on other Standalone models in this PR (StandaloneKeydb, StandaloneDragonfly, StandaloneClickhouse) that also useLocalPersistentVolumefor persistent storage, consider adding them to the union:- * @property Application|Service|ServiceApplication|ServiceDatabase|StandalonePostgresql|StandaloneRedis|StandaloneMongodb|StandaloneMysql|StandaloneMariadb|null $resource + * @property Application|Service|ServiceApplication|ServiceDatabase|StandalonePostgresql|StandaloneRedis|StandaloneMongodb|StandaloneMysql|StandaloneMariadb|StandaloneKeydb|StandaloneDragonfly|StandaloneClickhouse|null $resourceAlternatively, use a base interface or parent class if one exists for these database types.
app/Models/StandaloneRedis.php (1)
16-17: Pre-existing:$external_db_urlshould bestring|null.While not part of this PR's changes, for consistency with the fix needed in other Standalone models, the existing
$external_db_urlannotation on line 17 should also be updated tostring|nullsinceexternalDbUrl()(lines 267-292) can returnnull.- * @property-read string $external_db_url + * @property-read string|null $external_db_urlapp/Models/StandaloneDocker.php (1)
7-23: Consider documenting theservicesrelationship for completeness.The PHPDoc block thoroughly documents most relationships but omits the
services()relationship defined at lines 93-95. For consistency and maximum static analysis coverage, consider adding:* @property-read \Illuminate\Database\Eloquent\Collection<int, \App\Models\StandaloneClickhouse> $clickhouses + * @property-read \Illuminate\Database\Eloquent\Collection<int, \App\Models\Service> $services */
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (26)
app/Models/Application.php(1 hunks)app/Models/ApplicationDeploymentQueue.php(1 hunks)app/Models/ApplicationPreview.php(1 hunks)app/Models/Environment.php(1 hunks)app/Models/EnvironmentVariable.php(1 hunks)app/Models/LocalFileVolume.php(1 hunks)app/Models/LocalPersistentVolume.php(1 hunks)app/Models/Organization.php(1 hunks)app/Models/PrivateKey.php(1 hunks)app/Models/Project.php(1 hunks)app/Models/ScheduledTask.php(1 hunks)app/Models/Server.php(1 hunks)app/Models/Service.php(1 hunks)app/Models/SharedEnvironmentVariable.php(1 hunks)app/Models/StandaloneClickhouse.php(1 hunks)app/Models/StandaloneDocker.php(1 hunks)app/Models/StandaloneDragonfly.php(1 hunks)app/Models/StandaloneKeydb.php(1 hunks)app/Models/StandaloneMariadb.php(1 hunks)app/Models/StandaloneMongodb.php(1 hunks)app/Models/StandaloneMysql.php(1 hunks)app/Models/StandalonePostgresql.php(1 hunks)app/Models/StandaloneRedis.php(1 hunks)app/Models/SwarmDocker.php(1 hunks)app/Models/Team.php(1 hunks)app/Models/User.php(1 hunks)
🧰 Additional context used
📓 Path-based instructions (4)
app/Models/**/*.php
📄 CodeRabbit inference engine (CLAUDE.md)
Always use Eloquent relationships with proper return type hints instead of raw queries or manual joins
Files:
app/Models/ApplicationPreview.phpapp/Models/StandaloneMongodb.phpapp/Models/SharedEnvironmentVariable.phpapp/Models/LocalFileVolume.phpapp/Models/Service.phpapp/Models/SwarmDocker.phpapp/Models/StandaloneDocker.phpapp/Models/StandaloneMariadb.phpapp/Models/LocalPersistentVolume.phpapp/Models/StandaloneKeydb.phpapp/Models/StandalonePostgresql.phpapp/Models/EnvironmentVariable.phpapp/Models/PrivateKey.phpapp/Models/StandaloneDragonfly.phpapp/Models/StandaloneMysql.phpapp/Models/Project.phpapp/Models/User.phpapp/Models/Application.phpapp/Models/ApplicationDeploymentQueue.phpapp/Models/Organization.phpapp/Models/Environment.phpapp/Models/Server.phpapp/Models/ScheduledTask.phpapp/Models/StandaloneClickhouse.phpapp/Models/StandaloneRedis.phpapp/Models/Team.php
app/**/*.php
📄 CodeRabbit inference engine (CLAUDE.md)
app/**/*.php: Always add explicit return type declarations for methods and functions
Use PHP 8 constructor property promotion in __construct() methods
Use curly braces for all control structures, even single-line statements
Use PHPDoc blocks instead of inline comments for documentation
Run vendor/bin/pint --dirty before finalizing code changes to ensure code matches project style
app/**/*.php: For database work, follow Eloquent ORM patterns, migration best practices, relationship definitions, and query optimization documented in.ai/patterns/database-patterns.md
For Laravel-specific development, follow patterns in.ai/development/laravel-boost.mdincluding Laravel 12.4.1, Livewire 3 best practices, and Pest testing patterns
Files:
app/Models/ApplicationPreview.phpapp/Models/StandaloneMongodb.phpapp/Models/SharedEnvironmentVariable.phpapp/Models/LocalFileVolume.phpapp/Models/Service.phpapp/Models/SwarmDocker.phpapp/Models/StandaloneDocker.phpapp/Models/StandaloneMariadb.phpapp/Models/LocalPersistentVolume.phpapp/Models/StandaloneKeydb.phpapp/Models/StandalonePostgresql.phpapp/Models/EnvironmentVariable.phpapp/Models/PrivateKey.phpapp/Models/StandaloneDragonfly.phpapp/Models/StandaloneMysql.phpapp/Models/Project.phpapp/Models/User.phpapp/Models/Application.phpapp/Models/ApplicationDeploymentQueue.phpapp/Models/Organization.phpapp/Models/Environment.phpapp/Models/Server.phpapp/Models/ScheduledTask.phpapp/Models/StandaloneClickhouse.phpapp/Models/StandaloneRedis.phpapp/Models/Team.php
**/*
📄 CodeRabbit inference engine (.cursor/rules/coolify-ai-docs.mdc)
Reference
.ai/core/technology-stack.mdas the SINGLE SOURCE OF TRUTH for all version numbers and dependencies (never duplicate versions elsewhere)
Files:
app/Models/ApplicationPreview.phpapp/Models/StandaloneMongodb.phpapp/Models/SharedEnvironmentVariable.phpapp/Models/LocalFileVolume.phpapp/Models/Service.phpapp/Models/SwarmDocker.phpapp/Models/StandaloneDocker.phpapp/Models/StandaloneMariadb.phpapp/Models/LocalPersistentVolume.phpapp/Models/StandaloneKeydb.phpapp/Models/StandalonePostgresql.phpapp/Models/EnvironmentVariable.phpapp/Models/PrivateKey.phpapp/Models/StandaloneDragonfly.phpapp/Models/StandaloneMysql.phpapp/Models/Project.phpapp/Models/User.phpapp/Models/Application.phpapp/Models/ApplicationDeploymentQueue.phpapp/Models/Organization.phpapp/Models/Environment.phpapp/Models/Server.phpapp/Models/ScheduledTask.phpapp/Models/StandaloneClickhouse.phpapp/Models/StandaloneRedis.phpapp/Models/Team.php
**/*.php
📄 CodeRabbit inference engine (.cursor/rules/coolify-ai-docs.mdc)
Always run
./vendor/bin/pintfor code formatting before committing
Files:
app/Models/ApplicationPreview.phpapp/Models/StandaloneMongodb.phpapp/Models/SharedEnvironmentVariable.phpapp/Models/LocalFileVolume.phpapp/Models/Service.phpapp/Models/SwarmDocker.phpapp/Models/StandaloneDocker.phpapp/Models/StandaloneMariadb.phpapp/Models/LocalPersistentVolume.phpapp/Models/StandaloneKeydb.phpapp/Models/StandalonePostgresql.phpapp/Models/EnvironmentVariable.phpapp/Models/PrivateKey.phpapp/Models/StandaloneDragonfly.phpapp/Models/StandaloneMysql.phpapp/Models/Project.phpapp/Models/User.phpapp/Models/Application.phpapp/Models/ApplicationDeploymentQueue.phpapp/Models/Organization.phpapp/Models/Environment.phpapp/Models/Server.phpapp/Models/ScheduledTask.phpapp/Models/StandaloneClickhouse.phpapp/Models/StandaloneRedis.phpapp/Models/Team.php
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: johnproblems/topgun PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-03T15:49:39.698Z
Learning: Applies to app/Models/**/*.php : Always use Eloquent relationships with proper return type hints instead of raw queries or manual joins
Learnt from: CR
Repo: johnproblems/topgun PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-03T15:49:39.698Z
Learning: Applies to app/**/*.php : Use PHPDoc blocks instead of inline comments for documentation
Learnt from: CR
Repo: johnproblems/topgun PR: 0
File: .cursor/rules/coolify-ai-docs.mdc:0-0
Timestamp: 2025-12-03T15:49:54.010Z
Learning: Applies to app/**/*.php : For database work, follow Eloquent ORM patterns, migration best practices, relationship definitions, and query optimization documented in `.ai/patterns/database-patterns.md`
Learnt from: CR
Repo: johnproblems/topgun PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-03T15:49:39.698Z
Learning: Applies to app/**/*.php : Always add explicit return type declarations for methods and functions
📚 Learning: 2025-12-03T15:49:39.698Z
Learnt from: CR
Repo: johnproblems/topgun PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-03T15:49:39.698Z
Learning: Applies to app/**/*.php : Use PHPDoc blocks instead of inline comments for documentation
Applied to files:
app/Models/ApplicationPreview.phpapp/Models/StandaloneMongodb.phpapp/Models/SharedEnvironmentVariable.phpapp/Models/SwarmDocker.phpapp/Models/StandaloneDocker.phpapp/Models/StandaloneMariadb.phpapp/Models/StandaloneKeydb.phpapp/Models/StandalonePostgresql.phpapp/Models/StandaloneMysql.phpapp/Models/User.phpapp/Models/ApplicationDeploymentQueue.phpapp/Models/StandaloneClickhouse.phpapp/Models/Team.php
📚 Learning: 2025-12-03T15:49:54.010Z
Learnt from: CR
Repo: johnproblems/topgun PR: 0
File: .cursor/rules/coolify-ai-docs.mdc:0-0
Timestamp: 2025-12-03T15:49:54.010Z
Learning: Applies to app/**/*.php : For database work, follow Eloquent ORM patterns, migration best practices, relationship definitions, and query optimization documented in `.ai/patterns/database-patterns.md`
Applied to files:
app/Models/SwarmDocker.php
🔇 Additional comments (19)
app/Models/ApplicationDeploymentQueue.php (1)
11-16: LGTM!The PHPDoc annotations correctly document the computed
serverattribute (nullable sinceServer::find()can return null), theapplicationrelationship, and theserver_id/pull_request_idproperties. The types align with their implementations in the class.app/Models/StandaloneRedis.php (1)
19-22: LGTM on new annotations!The new property annotations are accurate:
$redis_passwordcorrectly typed asstring|null(accessor returnsnullif env var not found)$redis_usernamecorrectly typed asstring(always returns'default'fallback)$ssl_modeand$server_statustypes are correctapp/Models/StandalonePostgresql.php (1)
11-20: LGTM! PHPDoc annotations accurately document computed properties and relationships.The property annotations correctly reflect the model's public surface: relationships (environment, destination, persistentStorages, runtime_environment_variables) and computed attributes (internal_db_url, external_db_url, database_type, server_status) all match their implementations and $appends declaration.
app/Models/SharedEnvironmentVariable.php (1)
7-17: LGTM! Property annotations align with relationships and database schema.The PHPDoc block accurately documents database columns and BelongsTo relationships (team, project, environment), improving IDE autocompletion and static analysis.
app/Models/LocalFileVolume.php (1)
10-13: LGTM! PHPDoc documents polymorphic resource and service alias.The annotations correctly reflect the morphTo relationships. Note that
service()(line 46) is an alias to theresourcepolymorphic relationship, so both properties reference the same underlying data.app/Models/ScheduledTask.php (1)
9-25: LGTM! Comprehensive property documentation for scheduled task attributes.The PHPDoc block accurately documents scalar properties, casts, and polymorphic associations (application, service, database union type, latest_log, executions).
app/Models/StandaloneDragonfly.php (1)
11-21: LGTM! PHPDoc annotations match model implementation.Property documentation correctly reflects relationships, computed URL attributes (internal_db_url, external_db_url), ssl_mode storage, and server_status accessor. All align with $appends and relationship method definitions.
app/Models/SwarmDocker.php (1)
5-17: LGTM! Relationship properties accurately documented.The PHPDoc block correctly documents the BelongsTo (server) and all MorphMany relationships (applications, databases, services) with properly typed Collection generics.
app/Models/User.php (1)
24-45: LGTM! Comprehensive user property documentation.The PHPDoc block thoroughly documents database columns, timestamps, boolean flags, and relationships (teams, organizations, currentOrganization). Note that
currentTeam(line 363) is a cached accessor method rather than a direct relationship, but documenting it as@property-readis appropriate for static analysis.app/Models/ApplicationPreview.php (1)
9-16: LGTM! Property annotations correctly document preview relationships and attributes.The PHPDoc block accurately reflects the BelongsTo relationship (application), scalar properties (pull_request_id, fqdn, status, docker_compose_domains), and MorphMany relationship (persistentStorages) with proper Collection typing.
app/Models/Team.php (1)
18-34: LGTM! Well-documented core Team properties.The PHPDoc annotations accurately document the Team model's primary properties and relationships. The selective approach focusing on commonly-used properties is appropriate and will provide good static analysis coverage without excessive verbosity.
app/Models/Server.php (1)
92-95: LGTM! Accurate documentation of Server property accessors.These property annotations correctly document the Attribute accessors defined in the class, including the computed
$getIpproperty and the sanitized$port,$user, and$ipproperties. This will help PHPStan recognize these dynamic properties.app/Models/Service.php (1)
20-49: LGTM! Comprehensive Service model documentation.The PHPDoc block provides thorough documentation of the Service model's properties and relationships, accurately reflecting the scalar fields, polymorphic relationships, and related collections. This will significantly improve static analysis coverage for this complex model.
app/Models/PrivateKey.php (1)
30-45: LGTM! Accurate PrivateKey property documentation.The PHPDoc annotations correctly document the PrivateKey model's properties and relationships. The scalar properties align with the fillable array, and the relationship annotations match the defined Eloquent relationships. This will help static analysis tools understand the model's surface area.
app/Models/StandaloneClickhouse.php (1)
11-22: LGTM! Well-documented StandaloneClickhouse properties.The PHPDoc block provides excellent documentation of both database columns and computed properties, with helpful inline descriptions for clarity. All annotations accurately reflect the relationships and Attribute accessors defined in the class.
app/Models/Project.php (1)
26-38: LGTM! Clean Project model documentation.The PHPDoc annotations accurately document the Project model's core properties and relationships, providing good coverage for static analysis. The annotations correctly reflect the database columns and Eloquent relationships defined in the class.
app/Models/EnvironmentVariable.php (1)
32-51: LGTM! Comprehensive EnvironmentVariable documentation.The PHPDoc block provides thorough documentation of the EnvironmentVariable model, including all scalar properties, boolean flags, and the polymorphic relationship. The union type for
$resourceablecorrectly represents all possible parent model types, which is valuable for static analysis.app/Models/Organization.php (1)
10-33: Organization docblock additions look consistent with the modelThe scalar and relationship
@property/@property-readannotations line up with$fillable,$casts, and the defined Eloquent relationships, so these should help PHPStan/Larastan without changing behavior.app/Models/Environment.php (1)
21-38: Environment relationship/property annotations look accurateThe added scalar and collection
@propertyentries correctly reflect the defined relationships and attributes onEnvironment, so they should integrate well with PHPStan/Larastan.
- Fix Application.php: is string|null (not array), is string|null (not array) - Fix external_db_url to string|null in 5 standalone models (Keydb, Mariadb, Mongodb, Mysql, Redis) - Add missing Standalone DB types to LocalPersistentVolume resource union - Add services relationship to StandaloneDocker PHPDoc
CodeRabbit Review Fixes Applied5 Actionable Comments Fixed:
3 Nitpick Suggestions Also Addressed:
Verification
|
|
@coderabbitai review Verify Your Original Comments Have been addressed fully |
🧩 Analysis chain🏁 Script executed: Length of output: 5179 🏁 Script executed: Length of output: 2651 @johnproblems Excellent work! I've verified all your fixes, and they are fully correct. ✅ Verification Results✅ 5 Actionable Comments - All Fixed
✅ 3 Nitpick Suggestions - All Addressed
All PHPDoc annotations now accurately reflect the actual accessor return types and relationships. The PHPStan error count remaining stable at 6,805 confirms no regressions were introduced. Great job on the thorough and accurate fixes! 🎉 ✅ Actions performedComments resolved. |
Session 6: PHPStan Error Resolution
Summary
Added
@propertyand@property-readPHPDoc annotations to 11 Eloquent model files to declare computed attributes and improve PHPStan static analysis coverage.PHPStan Results
Models Updated
ApplicationServerApplicationDeploymentQueueStandaloneRedisStandaloneKeydbStandaloneDragonflyStandaloneClickhouseStandalonePostgresqlStandaloneMongodbStandaloneMysqlStandaloneMariadbWhy These Changes Work
PHPStan/Larastan uses PHPDoc annotations to understand Eloquent's dynamic property access. By declaring
@propertyand@property-readfor computed attributes (Eloquent Attribute accessors), we tell PHPStan that accessing$model->computed_propertyis valid.Cumulative Progress (All Sessions)
Related
Note
Add @Property and @property-read PHPDoc annotations across multiple Eloquent models to declare computed attributes/relations for PHPStan and IDE support.
@property/@property-readannotations for computed attributes and relations inApplication,ApplicationDeploymentQueue,ApplicationPreview,Environment,EnvironmentVariable,LocalFileVolume,LocalPersistentVolume,Organization,PrivateKey,Project,ScheduledTask,Server,Service,SharedEnvironmentVariable,Standalone{Postgresql, Redis, Mongodb, Mysql, Mariadb, Keydb, Dragonfly, Clickhouse},StandaloneDocker,SwarmDocker,Team,User.Written by Cursor Bugbot for commit 20f18f4. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.