# Class Refactoring > Use when refactoring PHP classes following Laravel best practices and SOLID principles. Ensures code quality, maintains functionality, improves testability, and achieves 100% code coverage. Focuses on single responsibility, DRY principle, and clean code structure. - Skill: `tomevault-io/class-refactoring-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/class-refactoring-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/class-refactoring-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/class-refactoring-2 --- **Constraint:** - Read project.mdc file - First, load all the rules for the cursor editor (.cursor/rules/.*mdc). - Always apply @.cursor/skills/smartest-project-addition/SKILL.md to select the single highest-impact refactoring direction before implementing changes. **Steps:** - Analyze the class and complete the TODO list tasks. - Verify code coverage after refactoring. - For all changes in the current branch, analyze code coverage and ensure that all changes are covered by tests. Add any missing tests to ensure 100% coverage. - If new database migrations were created during the changes, run them (`php artisan migrate`) before running tests or creating a PR. - Preserve functionality — change how, not what. - Focus on recently modified code unless instructed otherwise. - No increase in public API surface without strong justification - Clean, modern, optimized code. - Stateless PHP classes. - Collections over `foreach` where appropriate. - PHPDoc for PHPStan analysis. PHPDoc content: describe business logic and general purpose; avoid listing method calls or implementation steps. - Complex logic commented - No magic numbers - No deep nesting - Prefer small, focused functions. - English comments only. - Spatie DTOs (Spatie Laravel Data) instead of arrays (except Job constructors). Use PHP attributes for property mapping — never override `from()` manually. Apply `#[MapInputName(SnakeCaseMapper::class)]` at class level for snake_case-to-camelCase input mapping, or `#[MapName(SnakeCaseMapper::class)]` when the DTO is also serialized to output. - **`?array` is forbidden:** Any use of `?array` as a type hint must be replaced with a typed collection, DTO, or explicit `array|null`. Vague nullable arrays hide structure and break static analysis. - **PHP array key type safety:** When refactoring associative arrays with dynamic keys, apply safe key strategies: use stable prefixed keys (`'user:' . $id`, `'postal:' . $postalCode`, `'ext:' . $externalReference`); prefer a dedicated collection or value object when the key is domain-significant; prefer `list` when the structure is a list, not a map; prefer explicit validation or normalization before using external values as array keys; where relevant, prefer `array` over misleading `array`. - Laravel helpers over native PHP when appropriate. - When changing Eloquent models, migrations, or factories, do not duplicate column defaults that already exist in the database schema; see `@.cursor/rules/laravel/architecture.mdc` (Schema defaults, Migrations). - When changing Laravel tests that queue jobs, dispatch only via `JobClass::dispatch(...)` per `@.cursor/rules/laravel/architecture.mdc` Testing. - DRY principle — eliminate duplicates. - **Validation rules as traits:** Extract reusable validation rules into traits in `App\Concerns` (e.g. `PasswordValidationRules`). Use these traits in FormRequest classes instead of duplicating rule arrays. - Remove obvious comments; keep PHPStan-relevant docs. - Single Responsibility Principle. - Extract private methods if body exceeds ~30 lines. - No single-use variables. - Extract intention-revealing private methods - **All business logic is allowed only in classes that follow the action pattern!** - **Invokeable call convention:** When calling Action classes, always use direct invocation `$action($params)` — never `$action->__invoke($params)`. - **Action pattern (only when `vendor/pekral/arch-app-services` exists):** Apply @.cursor/skills/refactor-entry-point-to-action/SKILL.md when the refactored class is a controller, job, command, listener, or **Livewire component** that contains orchestration logic. - **Invokeable controller rule:** Any controller method that is not a standard CRUD method (`index`, `create`, `store`, `show`, `edit`, `update`, `destroy`) must be extracted into a dedicated single-action invokeable controller with only `__invoke()`. Resource controllers must only contain CRUD methods. - **BaseModelService pattern (only when `vendor/pekral/arch-app-services` exists):** All services that primarily work with a specific Eloquent Model must extend `BaseModelService` and implement `getModelManager()`, `getRepository()`, and `getModelClass()` (see `vendor/pekral/arch-app-services/examples/Services/User/UserModelService.php`). Services that do not primarily serve a single model must be refactored into Action pattern classes. - **Data Validator extraction (only when `vendor/pekral/arch-app-services` exists):** If an Action class contains inline validation logic (throwing `ValidationException` directly or calling `Validator::make()`), extract it into a dedicated Data Validator class under `app/DataValidators/{Domain}/`. - **Livewire components (only in Livewire projects):** Livewire components are entry points — they must not contain business logic. Split every component into a PHP class (`app/Livewire/`) and a Blade view (`resources/views/livewire/`). Never use single-file (Volt) components. Delegate all business logic to Action classes following the mandatory flow: `Livewire Component -> Action -> ModelService -> Repository/ModelManager`. - Separate orchestration layer from business logic - Split by responsibility - Centralize business rules - Business logic duplication is not allowed. - Method signatures must remain expressive and minimal. - Match test variable names to actual use cases. - New tests must cover relevant code. - After generating or modifying tests, verify that all new tests comply with the testing rules in `@.cursor/rules/php/standards.mdc`. Check mock usage specifically: mock only external services (HTTP clients) or to simulate exceptions; remove any constructor mocks, unnecessary mocks, or mocks that can be replaced with real service logic. - Remove coverage files after verification. **Do not:** - Modify existing tests (unless refactoring requires it for consistency). **After completing the tasks** - If according to @.cursor/skills/test-like-human/SKILL.md the changes can be tested, do it! ## Output Humanization - Use [blader/humanizer](https://github.com/blader/humanizer) for all skill outputs to keep the text natural and human-friendly. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/pekral) — claim your Tome and manage your conversions.