{"id":35478058,"url":"https://github.com/netresearch/php-modernization-skill","last_synced_at":"2026-01-31T04:08:30.968Z","repository":{"id":328481267,"uuid":"1115712425","full_name":"netresearch/php-modernization-skill","owner":"netresearch","description":"Agent Skill: PHP 8.x modernization patterns - typing, attributes, PHPStan | Claude Code compatible","archived":false,"fork":false,"pushed_at":"2026-01-11T22:29:35.000Z","size":100,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-14T00:03:09.771Z","etag":null,"topics":["agent-skills","ai-agent","open-standard"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netresearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-13T11:57:20.000Z","updated_at":"2026-01-11T22:29:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/netresearch/php-modernization-skill","commit_stats":null,"previous_names":["netresearch/php-modernization-skill"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/netresearch/php-modernization-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fphp-modernization-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fphp-modernization-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fphp-modernization-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fphp-modernization-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netresearch","download_url":"https://codeload.github.com/netresearch/php-modernization-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fphp-modernization-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28928895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T04:05:25.756Z","status":"ssl_error","status_checked_at":"2026-01-31T04:02:35.005Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agent","open-standard"],"created_at":"2026-01-03T13:13:06.811Z","updated_at":"2026-01-31T04:08:30.950Z","avatar_url":"https://github.com/netresearch.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Modernization Skill\n\nExpert patterns for modernizing PHP applications to PHP 8.x with type safety, PSR/PER compliance, static analysis tools, and Symfony best practices.\n\n## Compatibility\n\nThis is an **Agent Skill** following the [open standard](https://agentskills.io) originally developed by Anthropic and released for cross-platform use.\n\n**Supported Platforms:**\n- Claude Code (Anthropic)\n- Cursor\n- GitHub Copilot\n- Other skills-compatible AI agents\n\n\u003e Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.\n\n\n## Features\n\n- **PHP 8.x Features**: Constructor property promotion, readonly properties and classes, named arguments, enums and match expressions, attributes (replacing annotations), union and intersection types, nullsafe operator\n- **Static Analysis Tools**: PHPStan (level 9+), PHPat (architecture testing), Rector (automated refactoring), PHP-CS-Fixer (coding style)\n- **PSR/PER Compliance**: Enforces all active PHP-FIG standards (PSR-1, 3, 4, 6, 7, 11, 12, 13, 14, 15, 16, 17, 18, 20) and PER Coding Style\n- **Type Safety Patterns**: DTOs and Value Objects over arrays, generic collection typing via PHPDoc, strict typing enforcement, PHPStan level 10 compliance, runtime type validation\n- **Symfony Integration**: Dependency injection patterns, service configuration (YAML to PHP), event dispatcher and PSR-14, form handling modernization, security component updates\n\n## Installation\n\n### Option 1: Via Netresearch Marketplace (Recommended)\n\n```bash\n/plugin marketplace add netresearch/claude-code-marketplace\n```\n\n### Option 2: Download Release\n\nDownload the [latest release](https://github.com/netresearch/php-modernization-skill/releases/latest) and extract to `~/.claude/skills/php-modernization-skill/`\n\n### Option 3: Composer (PHP projects)\n\n```bash\ncomposer require netresearch/agent-php-modernization-skill\n```\n\n**Requires:** [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin)\n\n## Usage\n\nThis skill is automatically triggered when:\n\n- Modernizing PHP codebases to PHP 8.1/8.2/8.3/8.4/8.5\n- Implementing type safety and strict typing\n- Setting up static analysis tools (PHPStan, PHPat, Rector, PHP-CS-Fixer)\n- Ensuring PSR/PER compliance\n- Adopting Symfony best practices\n- Achieving PHPStan level 9+/10 compliance\n- Upgrading from older PHP versions\n- Implementing generic collection patterns\n\nExample queries:\n- \"Modernize this PHP class to PHP 8.2\"\n- \"Add strict type safety with PHPStan level 10\"\n- \"Set up PHPat architecture tests\"\n- \"Configure Rector for PHP 8.3 upgrade\"\n- \"Ensure this code follows PSR standards\"\n- \"Convert YAML service configuration to PHP\"\n- \"Implement readonly class with constructor promotion\"\n- \"Make this HTTP client PSR-18 compliant\"\n\n## Structure\n\n```\nphp-modernization-skill/\n├── SKILL.md                              # Skill metadata and core patterns\n├── references/\n│   ├── static-analysis-tools.md          # PHPStan, PHPat, Rector, PHP-CS-Fixer\n│   ├── psr-per-compliance.md             # Active PSR and PER standards\n│   ├── php8-features.md                  # PHP 8.0-8.5 feature adoption patterns\n│   ├── type-safety.md                    # Type system maximization strategies\n│   ├── symfony-patterns.md               # Modern Symfony architecture\n│   ├── phpstan-compliance.md             # PHPStan configuration details\n│   └── migration-strategies.md           # Version upgrade planning\n└── scripts/\n    └── verify-php-project.sh             # Verification script\n```\n\n## Expertise Areas\n\n### Required Static Analysis Tools\n\nAll modern PHP projects must use these tools:\n\n| Tool | Purpose | Requirement |\n|------|---------|-------------|\n| [PHPStan](https://phpstan.org/) | Type checking, bug detection | **Level 9 minimum**, level 10 recommended |\n| [PHPat](https://www.phpat.dev/) | Architecture testing | **Required** for projects with defined architecture |\n| [Rector](https://getrector.com/) | Automated refactoring | **Required** for modernization |\n| [PHP-CS-Fixer](https://cs.symfony.com/) | Coding style | **Required** with `@PER-CS` |\n\n### PSR/PER Compliance\n\nAll modern PHP code must follow active PHP-FIG standards:\n\n| Standard | Purpose | Requirement |\n|----------|---------|-------------|\n| PSR-1 | Basic Coding | **Required** |\n| PSR-4 | Autoloading | **Required** |\n| PER Coding Style | Coding Style | **Required** (supersedes PSR-12) |\n| PSR-3 | Logger | Use when logging |\n| PSR-6/16 | Cache | Use when caching |\n| PSR-7/17/18 | HTTP | Use for HTTP clients |\n| PSR-11 | Container | Use for DI containers |\n| PSR-14 | Events | Use for event dispatching |\n| PSR-15 | Middleware | Use for HTTP middleware |\n| PSR-20 | Clock | Use for time-dependent code |\n\n**Source of truth:** https://www.php-fig.org/psr/ and https://www.php-fig.org/per/\n\n### PHP 8.x Features\n- Constructor property promotion\n- Readonly properties and classes\n- Named arguments\n- Enums and match expressions\n- Attributes (replacing annotations)\n- Union and intersection types\n- Nullsafe operator\n\n### Type Safety Patterns\n- **DTOs and Value Objects over arrays** (see below)\n- Generic collection typing via PHPDoc\n- Strict typing enforcement\n- PHPStan level 9+/10 compliance\n- Runtime type validation\n\n### DTOs and Value Objects (Required)\n\n**Never pass or return raw arrays** for structured data. Use typed objects instead:\n\n| Instead of | Use |\n|------------|-----|\n| `array $userData` | `UserDTO $user` |\n| `array{email: string, name: string}` | `readonly class UserDTO` |\n| `array $config` | `readonly class Config` or Value Object |\n| `array $request` | `RequestDTO::fromRequest($request)` |\n| `return ['success' =\u003e true, 'data' =\u003e $x]` | `return new ResultDTO($x)` |\n\n**Why:**\n- Arrays lack type safety at runtime\n- No IDE autocompletion for array keys\n- PHPStan cannot verify array shapes across boundaries\n- Refactoring arrays is error-prone\n\n**Pattern:**\n```php\n// ❌ Bad: Array passing\npublic function createUser(array $data): array\n\n// ✅ Good: DTO pattern\npublic function createUser(CreateUserDTO $dto): UserDTO\n```\n\nSee `references/request-dtos.md` for complete patterns including Request DTOs, Command/Query DTOs, and Value Objects\n\n### Enums (Required)\n\n**Never use string/integer constants or arrays** for fixed sets of values. Use PHP 8.1+ backed enums instead:\n\n| Instead of | Use |\n|------------|-----|\n| `const STATUS_DRAFT = 'draft'` | `enum Status: string { case Draft = 'draft'; }` |\n| `['draft', 'published', 'archived']` | `Status::cases()` |\n| `string $status` parameter | `Status $status` parameter |\n| `switch ($status)` | `match($status)` with enum |\n\n**Why enums are required:**\n- Compile-time type checking (invalid values caught before runtime)\n- IDE autocompletion for all valid values\n- Exhaustive `match()` enforcement (compiler ensures all cases handled)\n- Methods encapsulate related logic (labels, colors, validation)\n- Self-documenting API with clear valid options\n\n**Pattern:**\n```php\n// ❌ Bad: String constants\nclass Order {\n    public const STATUS_DRAFT = 'draft';\n    public const STATUS_PENDING = 'pending';\n    public const STATUS_COMPLETED = 'completed';\n\n    public function setStatus(string $status): void // Any string accepted!\n}\n\n// ✅ Good: Backed enum\nenum OrderStatus: string {\n    case Draft = 'draft';\n    case Pending = 'pending';\n    case Completed = 'completed';\n\n    public function label(): string {\n        return match($this) {\n            self::Draft =\u003e 'Draft Order',\n            self::Pending =\u003e 'Awaiting Payment',\n            self::Completed =\u003e 'Order Complete',\n        };\n    }\n}\n\nclass Order {\n    public function setStatus(OrderStatus $status): void // Only valid statuses!\n}\n```\n\nSee `references/php8-features.md` for complete enum patterns including methods, validation, and database integration.\n\n### Symfony Integration\n- Dependency injection patterns\n- Service configuration (YAML to PHP)\n- Event dispatcher and PSR-14\n- Form handling modernization\n- Security component updates\n\n## Migration Checklist\n\n### Static Analysis Setup\n- PHPStan at level 9+ (level 10 for new projects)\n- PHPat architecture tests for layer dependencies\n- Rector with `LevelSetList::UP_TO_PHP_83` and `SetList::CODE_QUALITY`\n- PHP-CS-Fixer with `@PER-CS` ruleset\n\n### PHP Version Upgrade\n- Update composer.json PHP requirement\n- Enable strict_types in all files\n- Replace annotations with attributes\n- Convert to constructor property promotion\n- Use readonly where applicable\n- Replace switch with match expressions\n- **Replace string/int constants with backed enums**\n- **Use enums for all status, type, and option values**\n\n### PSR/PER Compliance\n- Configure PSR-4 autoloading in composer.json\n- Enforce PER Coding Style via PHP-CS-Fixer (`@PER-CS`)\n- Type-hint against PSR interfaces (not implementations)\n- Use PSR-3 for logging\n- Use PSR-14 for event dispatching\n- Use PSR-18/17 for HTTP clients\n- Use PSR-20 for time-dependent code\n\n### Type Safety Enhancement\n- Add return types to all methods\n- Add parameter types to all methods\n- Use union types instead of mixed\n- **Replace array parameters with DTOs**\n- **Replace array returns with typed objects**\n- **Use Value Objects for domain concepts (Email, Money, etc.)**\n- **Use backed enums for all fixed value sets (status, type, options)**\n- Add @template annotations for generics\n- Remove @var annotations where inferrable\n\n## Related Skills\n\n- **security-audit-skill**: Security patterns for PHP applications\n- **typo3-testing-skill**: PHPUnit patterns (applicable to any PHP project)\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n## Credits\n\nDeveloped and maintained by [Netresearch DTT GmbH](https://www.netresearch.de/).\n\n---\n\n**Made with love for Open Source by [Netresearch](https://www.netresearch.de/)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetresearch%2Fphp-modernization-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetresearch%2Fphp-modernization-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetresearch%2Fphp-modernization-skill/lists"}