Skip to content
Skills Library
Programming · Conversion & formats

upgrade-php

/upgrade-php

PHP Upgrade Assistant. Use when upgrading PHP version, fixing deprecations for a target PHP version, or scanning for PHP compatibility issues.

Licence
MIT
Last repository change
10.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

PHP Upgrade Assistant. Use when upgrading PHP version, fixing deprecations for a target PHP version, or scanning for PHP compatibility issues.

Original author description

PHP Upgrade Assistant. Use when upgrading PHP version, fixing deprecations for a target PHP version, or scanning for PHP compatibility issues.

How it works

  1. Activation and exit
  2. Phase 1: Pre-check
  3. Phase 2: Discovery (Scan)
  4. Phase 3: Fix
  5. Phase 4: Verify
  6. Edge cases
Original SKILL.md headings · 211 lines, 853 words
SKILL.md preview
---
name: upgrade-php
description: "PHP Upgrade Assistant. Use when upgrading PHP version, fixing deprecations for a target PHP version, or scanning for PHP compatibility issues."
---

# PHP Upgrade Assistant

Helps upgrade a PHP project to a target PHP version by scanning for deprecations,
reporting issues, applying automated fixes after confirmation, and verifying the result.

## Activation and exit

- **Enter** when the user asks to:
  - Upgrade to a specific PHP version (e.g., "upgrade to PHP 8.4")
  - Fix PHP deprecations or compatibility issues
  - Scan for PHP version-related problems
- **Exit** when all identified issues are resolved/triaged, or the user cancels.

## Phase 1: Pre-check

### 1. Confirm target version

Ask the user for the **target PHP version** if not already stated.

### 2. Detect current PHP configuration

```
get_php_project_config()
```

This returns the configured PHP language level, interpreter details (name, path, local/remote),
and runtime information (exact version, loaded extensions, debuggers). Use it to determine the
current PHP version the project is targeting.

### 3. Check Composer project

```
get_composer_dependencies()
```

If no packages are returned, warn: *"No composer.json found. Proceeding with code-only scan."*

### 4. Confirm PHP version constraint

```
get_file_text_by_path(pathInProject: "composer.json")
```

Look for `"require": { "php": "..." }` and `config.platform.php`.
Report to the user: **Current: PHP >=X.Y → Target: PHP Z.W**

## Phase 2: Discovery (Scan)

Scan the project to build a complete issue inventory. **Do not fix anything yet.**

### Step 1: Find PHP files

```
find_files_by_glob(globPattern: "**/*.php")
```

Exclude `vendor/` from scanning. For large projects (>200 files), scan `src/`, `app/` first, then `tests/` separately.

### Step 2: Run deprecation inspections on each file

```
get_inspections(
  filePath: "<relative-path>",
  minSeverity: "WEAK_WARNING"
)
```

Common deprecation-related problems will have descriptions mentioning:
- Deprecated function/method usage
- PHP version-specific language level issues
- Deprecated string interpolation syntax (`${}`)
- Deprecated partially-supported callables
- Deprecated `implode()` argument order
- Deprecated serializable usage
- Deprecated cast expressions

### Step 3: Supplementary structural search (optional)

For patterns inspections may miss, use structural search:

```
# Dynamic properties (deprecated in PHP 8.2)
search_structural(
  pattern: "$obj$->$prop$ = $val$",
  fileType: "PHP",
  maxResults: 50
)
```

**Pattern syntax**: Use `$name$` for template variables (e.g., `$a$->$b$()` matches any method
call on any object). Use `$a${2,5}` for count constraints, `$a$+` for one-or-more, `$a$*` for
zero-or-more.

### Step 4: Build and present inventory

Categorize all discovered issues:

| Priority | Category                            | Count | Auto-fixable |
|----------|-------------------------------------|-------|--------------|
| **P0**   | Errors (breaking in target version) | N     | Y/N          |
| **P1**   | Deprecations (removed in target)    | N     | Y/N          |
| **P2**   | Deprecations (warned in target)     | N     | Y/N          |

Present this table to the user. **Wait for explicit confirmation before proceeding to fixes.**

## Phase 3: Fix

Apply fixes only after user confirmation. Process in priority order: P0 → P1 → P2.

### Auto-fixes (quick fix available)

For each problem where `quickFixes` is non-empty:

```
apply_quick_fix(
  filePath: "<path>",
  line: <line>,
  column: <column>,
  quickFixName: "<quickFixes[0].name>"
)
```

**Strategy:**

1. Process one file at a time — apply all fixes for that file before moving on.
2. After all fixes in a file, re-scan it to verify fixes took effect:
   ```
   get_inspections(filePath: "<path>", minSeverity: "WEAK_WARNING")
   ```
3. If re-scan shows new issues, attempt to fix (max 3 iterations per file).

### Manual fixes (no quick fix available)

When `quickFixes` is empty:

1. Read the problem `description` — it usually names the replacement.
2. Read the file context with `get_file_text_by_path`.
3. Apply the fix with `replace_text_in_file`.

Common manual fix patterns:

| Deprecation                         | Before                       | After                         |
|-------------------------------------|------------------------------|-------------------------------|
| Implicitly nullable params (8.4)    | `function f(Type $p = null)` | `function f(?Type $p = null)` |
| `${}` interpolation (8.2)           | `"Hello ${name}"`            | `"Hello {$name}"`             |
| Partially-supported callables (8.2) | `$c = "self::method"`        | `$c = self::method(...)`      |

If no replacement is documented, add a `// TODO: PHP <target> - <description>` comment
and include in the "Remaining" report.

### Update composer.json

After code fixes, update the PHP version constraint:

```
replace_text_in_file(
  pathInProject: "composer.json",
  oldText: "\"php\": \">=8.1\"",
  newText: "\"php\": \">=8.4\""
)
```

**Do NOT run `composer update` automatically.** Advise the user to run it manually.

## Phase 4: Verify

### 1. Re-scan modified files

Re-run `get_inspections` on all modified files with `minSeverity: "WEAK_WARNING"`.
Confirm zero remaining deprecation issues.

### 2. Suggest test run

Check for available test configurations:

```
get_run_configurations()
```

Suggest the user run their test suite. Do not execute tests automatically unless
the user explicitly asks.

### 3. Final report

```
PHP Upgrade Summary: X.Y → Z.W
────────────────────────────────
Files scanned:    N
Issues found:     M
Auto-fixed:       A
Manually fixed:   B
Remaining:        C (needs manual review)
composer.json:    Updated / Not updated

Next steps:
1. Run `composer update` to validate dependency compatibility
2. Run your test suite
3. Review files listed under "Remaining"
```

## Edge cases

| Case                           | Handling                                                      |
|--------------------------------|---------------------------------------------------------------|
| **No quick fix available**     | Apply manual fix or add TODO comment                          |
| **Breaking changes (P0)**      | Fix these first — code will fail at runtime                   |
| **Inspection timeout**         | Re-run with longer `timeout` or narrow to subdirectory        |
| **Large project (>500 files)** | Scan in batches of 50; offer to scope to specific directories |
| **Multiple composer.json**     | Ask user which sub-project to upgrade                         |

Versions

The database has no other skills named upgrade-php.

Database snapshot: 13.11.2026 · package version 6aead3d2cdc7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 2 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100php-upgrade
    Step-by-step PHP upgrade playbook for hops from 7.4 to 8.5, with known traps per version, Rector rule sets, and a CI matrix. Use to upgrade PHP, fix deprecations, check compatibility, or plan a PHP migration.
  • 100php-code-review
    Review PHP code using PhpStorm inspections. Use when editing PHP files, reviewing code quality, fixing PHP issues, or when asked about PHP best practices.
  • 92write-script-php
    MUST use when writing PHP scripts.
  • 100programming-php
    PHP 8 practices: typed concise code, features through PHP 8.5, input validation, quality checks. Use when writing or reviewing PHP in Composer projects.
  • 85php-upcoming
    Check a Joomla extension or PHP project against the next, not-yet-released PHP version by executing its test suite on that PHP with full error reporting — the only method that works, since static analysis has no sniff data for an unreleased version. Use when preparing for an…
  • 100php
    PHP language conventions, modern idioms, and type system. Invoke whenever task involves any interaction with PHP code — writing, reviewing, refactoring, debugging, or understanding PHP projects.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.