state-comparison_skill

Overview

This skill provides a set of model helper patterns to replace verbose Spatie Model States comparisons with concise, testable methods and query scopes. It reduces boilerplate, improves readability, and centralizes state logic so changes are made in one place. The result is clearer conditional logic, safer refactors, and about 63% less code for common state checks.

How this skill works

Add generic state-check methods, convenience boolean helpers for each state, and query scopes on models. Helpers like isCardQualityCheck() or isCompleted() call a single isState(state) method, while scopeWhereState and scopeWhereStateIn allow efficient database filtering. Use hasStateIn([...]) for multiple-state checks and specialized helpers like isTerminalState() where appropriate.

When to use it

• Replace repeated Spatie Model States equals(...) expressions in business logic
• Write conditional view or controller logic that depends on model state
• Filter queries by one or more states in repositories or controllers
• Refactor legacy code to remove magic strings and reduce typos
• Provide IDE-friendly, discoverable helpers for developer experience

Best practices

• Implement a single generic check (isXState) and build convenience methods on top
• Add scopeWhereState and scopeWhereStateIn for database-level filtering
• Name helpers explicitly (isCardQualityCheck) — avoid ambiguous abbreviations
• Use hasStateIn([...]) or a terminal-state helper instead of multiple OR checks
• Write tests that assert helper behavior so refactors remain safe

Example use cases

• Replace (new ($card->card_state)($card))->equals(...) with $card->isCardQualityCheck() in controllers
• Use Submission::whereSubmissionStateIn([...])->get() to load submissions in multiple states efficiently
• Use $submission->isTerminalState() to guard side effects like notifications
• Render badges in views with @if($submission->isCompleted()) instead of verbose state builds
• Refactor nested ternaries to a match expression driven by helper methods