Annotate Attribute return types on models

2026-08-18 11:15:42 +00:00 · 2026-08-13 16:30:03 -07:00
parent af52d6c5b7
commit a76d4db36e
8 changed files with 124 additions and 18 deletions
--- a/app/Models/Asset.php
+++ b/app/Models/Asset.php
@ -30,13 +30,6 @@ use Watson\Validating\ValidatingTrait;
 * Model for Assets.
 *
 * @version v1.0
- * @property ?int $location_id
- * @property Carbon|string|null $next_audit_date
- * @property Carbon|string|null $last_audit_date
- * @property Carbon|string|null $asset_eol_date
- * @property ?int $company_id
- * @property Carbon|string|null $last_checkin
- * @property bool $requestable
 */
 class Asset extends Depreciable
 {
@ -125,6 +118,8 @@ class Asset extends Depreciable
     * NULL and 0 as different. `set` normalizes on write, `get`
     * normalizes on read so legacy rows already storing 0 present as
     * null at the model boundary until they're re-saved.
+     *
+     * @return Attribute<int|null, int|null>
     */
    protected function locationId(): Attribute
    {
@ -134,6 +129,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<int|null, int|null>
+     */
    protected function companyId(): Attribute
    {
        return Attribute::make(
@ -336,7 +334,7 @@ class Asset extends Depreciable
    /**
     * Returns the warranty expiration date as Carbon object
     *
-     * @return Carbon|null
+     * @return Attribute<Carbon|null, never>
     */
    protected function warrantyExpires(): Attribute
    {
@ -345,6 +343,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function warrantyExpiresFormattedDate(): Attribute
    {

@ -353,6 +354,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<float|null, never>
+     */
    protected function warrantyExpiresDiff(): Attribute
    {
        return Attribute::make(
@ -361,6 +365,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function warrantyExpiresDiffForHumans(): Attribute
    {
        return Attribute::make(
@ -369,6 +376,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function lastAuditFormattedDate(): Attribute
    {

@ -377,6 +387,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<float|null, never>
+     */
    protected function lastAuditDiff(): Attribute
    {
        return Attribute::make(
@ -385,6 +398,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function lastAuditDiffForHumans(): Attribute
    {
        return Attribute::make(
@ -393,6 +409,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function nextAuditFormattedDate(): Attribute
    {

@ -401,6 +420,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<float|null, never>
+     */
    protected function nextAuditDiffInDays(): Attribute
    {
        return Attribute::make(
@ -408,6 +430,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function nextAuditDiffForHumans(): Attribute
    {
        return Attribute::make(
@ -416,6 +441,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<Carbon|null, never>
+     */
    protected function eolDate(): Attribute
    {

@ -433,6 +461,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function eolFormattedDate(): Attribute
    {
        return Attribute::make(
@ -440,6 +471,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<float|null, never>
+     */
    protected function eolDiffInDays(): Attribute
    {
        return Attribute::make(
@ -448,6 +482,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function eolDiffForHumans(): Attribute
    {

@ -457,6 +494,9 @@ class Asset extends Depreciable

    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function expectedCheckinFormattedDate(): Attribute
    {
        return Attribute::make(
@ -464,6 +504,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function expectedCheckinDiffForHumans(): Attribute
    {
        return Attribute::make(
@ -1366,7 +1409,7 @@ class Asset extends Depreciable
     * in the database, but here we are.
     *
     * @param  $value
-     * @return void
+     * @return Attribute<string|null, string|null>
     */
    protected function nextAuditDate(): Attribute
    {
@ -1376,6 +1419,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, string|null>
+     */
    protected function lastAuditDate(): Attribute
    {
        return Attribute::make(
@ -1384,6 +1430,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, string|null>
+     */
    protected function lastCheckout(): Attribute
    {
        return Attribute::make(
@ -1392,6 +1441,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, string|null>
+     */
    protected function lastCheckin(): Attribute
    {
        return Attribute::make(
@ -1400,6 +1452,9 @@ class Asset extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, string|null>
+     */
    protected function assetEolDate(): Attribute
    {
        return Attribute::make(
@ -1415,7 +1470,7 @@ class Asset extends Depreciable
     * This will also correctly parse a 1/0 if "true"/"false" is passed.
     *
     * @param  $value
-     * @return void
+     * @return Attribute<int, mixed>
     */
    protected function requestable(): Attribute
    {
--- a/app/Models/CheckoutAcceptance.php
+++ b/app/Models/CheckoutAcceptance.php
@ -54,6 +54,8 @@ class CheckoutAcceptance extends Model

    /**
     * Accessor for the checkoutable item's category name.
+     *
+     * @return Attribute<string|null, never>
     */
    protected function checkoutableCategoryName(): Attribute
    {
@ -180,6 +182,9 @@ class CheckoutAcceptance extends Model
        return $query->whereNull('accepted_at')->whereNotNull('declined_at');
    }

+    /**
+     * @return Attribute<string, never>
+     */
    protected function displayCheckoutableType(): Attribute
    {
        return Attribute::make(
--- a/app/Models/Component.php
+++ b/app/Models/Component.php
@ -182,6 +182,8 @@ class Component extends SnipeModel
     * Per-pivot line cost for components-assets. Pulls the per-unit
     * price from the last acquisition (with the same default_* fallback
     * that lastOrderDefaults() applies) and multiplies by pivot qty.
+     *
+     * @return Attribute<float|null, never>
     */
    protected function calculatedPurchaseCost(): Attribute
    {
--- a/app/Models/License.php
+++ b/app/Models/License.php
@ -182,6 +182,9 @@ class License extends Depreciable
            && ($this->deleted_at == '');
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function terminatesFormattedDate(): Attribute
    {
        return Attribute::make(
@ -189,6 +192,9 @@ class License extends Depreciable
        );
    }

+    /**
+     * @return Attribute<float|null, never>
+     */
    protected function terminatesDiffInDays(): Attribute
    {
        return Attribute::make(
@ -196,6 +202,9 @@ class License extends Depreciable
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function terminatesDiffForHumans(): Attribute
    {
        return Attribute::make(
--- a/app/Models/LicenseSeat.php
+++ b/app/Models/LicenseSeat.php
@ -92,6 +92,9 @@ class LicenseSeat extends SnipeModel implements ICompanyableChild
        return $this->license->getEula();
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function name(): Attribute
    {
        return Attribute::make(
@ -99,6 +102,9 @@ class LicenseSeat extends SnipeModel implements ICompanyableChild
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function displayName(): Attribute
    {
        return Attribute::make(
--- a/app/Models/Setting.php
+++ b/app/Models/Setting.php
@ -209,9 +209,9 @@ class Setting extends Model
     *
     * Important: Do not remove the e() escaping here, as we output raw in the blade.
     *
-     * @return string escaped CSS
-     *
     * @author A. Gianotto <snipe@snipe.net>
+     *
+     * @return Attribute<string, mixed>
     */
    protected function headerColor(): Attribute
    {
@ -220,6 +220,9 @@ class Setting extends Model
        );
    }

+    /**
+     * @return Attribute<string, mixed>
+     */
    protected function linkLightColor(): Attribute
    {
        return Attribute::make(
@ -227,6 +230,9 @@ class Setting extends Model
        );
    }

+    /**
+     * @return Attribute<string, mixed>
+     */
    protected function linkDarkColor(): Attribute
    {
        return Attribute::make(
@ -234,6 +240,9 @@ class Setting extends Model
        );
    }

+    /**
+     * @return Attribute<string, mixed>
+     */
    protected function navLinkColor(): Attribute
    {
        return Attribute::make(
--- a/app/Models/SnipeModel.php
+++ b/app/Models/SnipeModel.php
@ -10,9 +10,6 @@ use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Support\Facades\Storage;

-/**
- * @property-read string $display_name
- */
 class SnipeModel extends Model
 {
    // Setters that are appropriate across multiple models.
@ -24,6 +21,9 @@ class SnipeModel extends Model
        $this->attributes['purchase_date'] = $value;
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function purchaseDateFormatted(): Attribute
    {
        return Attribute::make(
@ -31,6 +31,9 @@ class SnipeModel extends Model
        );
    }

+    /**
+     * @return Attribute<float|null, never>
+     */
    protected function expiresDiffInDays(): Attribute
    {
        return Attribute::make(
@ -38,6 +41,9 @@ class SnipeModel extends Model
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function expiresDiffForHumans(): Attribute
    {
        return Attribute::make(
@ -45,6 +51,9 @@ class SnipeModel extends Model
        );
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function expiresFormattedDate(): Attribute
    {
        return Attribute::make(
@ -200,6 +209,9 @@ class SnipeModel extends Model
        $query->skip($offset)->take($limit);
    }

+    /**
+     * @return Attribute<string|null, never>
+     */
    protected function displayName(): Attribute
    {
        return Attribute::make(
--- a/app/Models/User.php
+++ b/app/Models/User.php
@ -32,9 +32,6 @@ use Illuminate\Support\Str;
 use Laravel\Passport\HasApiTokens;
 use Watson\Validating\ValidatingTrait;

-/**
- * @property string $display_name
- */
 class User extends SnipeModel implements AuthenticatableContract, AuthorizableContract, CanResetPasswordContract, HasLocalePreference
 {
    use CompanyableTrait;
@ -328,6 +325,8 @@ class User extends SnipeModel implements AuthenticatableContract, AuthorizableCo
     * This overrides the SnipeModel displayName accessor to return the full name if display_name is not set
     *
     * @see SnipeModel::displayName()
+     *
+     * @return Attribute<string|null, mixed>
     */
    protected function displayName(): Attribute
    {
@ -909,6 +908,9 @@ class User extends SnipeModel implements AuthenticatableContract, AuthorizableCo
        return $this->last_name ? $this->first_name.' '.$this->last_name : $this->first_name;
    }

+    /**
+     * @return Attribute<string, never>
+     */
    protected function linkLightColor(): Attribute
    {
        return Attribute::make(
@ -928,6 +930,9 @@ class User extends SnipeModel implements AuthenticatableContract, AuthorizableCo
        );
    }

+    /**
+     * @return Attribute<string, never>
+     */
    protected function linkDarkColor(): Attribute
    {
        return Attribute::make(
@ -947,6 +952,9 @@ class User extends SnipeModel implements AuthenticatableContract, AuthorizableCo
        );
    }

+    /**
+     * @return Attribute<string, never>
+     */
    protected function navLinkColor(): Attribute
    {
        return Attribute::make(