landing-api/app/Models/Call.php

<?php

declare(strict_types=1);

namespace App\Models;

use App\Enums\CallStatus;
use App\Models\Concerns\BumpsContentVersion;
use App\Models\Concerns\HasContentViews;
use App\Models\Concerns\HasRevisions;
use App\Models\Concerns\RecordsSlugChanges;
use Database\Factories\CallFactory;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Spatie\Translatable\HasTranslations;

/**
 * A call for contributors.
 *
 * The `hours_per_week` / `duration_weeks` pair is the point of this model. In
 * a hobby collective the scarce resource is time, not money: "~4h/week for 8
 * weeks" lets someone decide in ten seconds, where "we're looking for a
 * frontend dev" tells them nothing.
 */
#[Fillable([
    'project_id', 'title', 'slug', 'description', 'what_you_get', 'status',
    'hours_per_week', 'duration_weeks', 'seniority', 'opens_at', 'closes_at',
])]
class Call extends Model
{
    /** @use HasFactory<CallFactory> */
    use BumpsContentVersion, HasContentViews, HasFactory, HasRevisions, HasTranslations, RecordsSlugChanges;

    /** @var array<int, string> */
    public array $translatable = ['title', 'slug', 'description', 'what_you_get'];

    /** @var array<string, mixed> */
    protected $attributes = [
        'status' => CallStatus::Open->value,
    ];

    protected function casts(): array
    {
        return [
            'status' => CallStatus::class,
            'hours_per_week' => 'integer',
            'duration_weeks' => 'integer',
            'opens_at' => 'date',
            'closes_at' => 'date',
        ];
    }

    /**
     * The `site.paths` key this model publishes under, so a slug change knows
     * which URL it just broke.
     */
    public function publicPathType(): string
    {
        return 'call';
    }

    /**
     * @return BelongsTo<Project, $this>
     */
    public function project(): BelongsTo
    {
        return $this->belongsTo(Project::class);
    }

    /**
     * @return BelongsToMany<Technology, $this>
     */
    public function technologies(): BelongsToMany
    {
        return $this->belongsToMany(Technology::class);
    }

    /**
     * The people who answered this call.
     *
     * @return HasMany<Application, $this>
     */
    public function applications(): HasMany
    {
        return $this->hasMany(Application::class);
    }

    /**
     * Open, within its window, and — when tied to a project — only while that
     * project is itself published.
     *
     * @param  Builder<$this>  $query
     * @return Builder<$this>
     */
    public function scopeOpen(Builder $query): Builder
    {
        return $query
            ->where('status', CallStatus::Open)
            ->where(fn (Builder $q) => $q->whereNull('opens_at')->orWhere('opens_at', '<=', now()))
            ->where(fn (Builder $q) => $q->whereNull('closes_at')->orWhere('closes_at', '>=', now()));
    }

    /**
     * Total time being asked for, which is what a prospective contributor is
     * really weighing up.
     */
    public function totalHours(): ?int
    {
        if ($this->hours_per_week === null || $this->duration_weeks === null) {
            return null;
        }

        return $this->hours_per_week * $this->duration_weeks;
    }

    /**
     * @param  Builder<$this>  $query
     * @return Builder<$this>
     */
    public function scopeWhereSlug(Builder $query, string $slug, ?string $locale = null): Builder
    {
        $locale ??= app()->getLocale();

        return $query->where("slug->{$locale}", $slug);
    }
}