cursorrules / rules

---
description: PHP memory optimisation standards and actionable checks
globs: *.php, *.ini
---
# PHP Memory Optimisation Standards

Guidance and automated checks to reduce peak memory usage in PHP applications. Based on widely accepted practices and the article "PHP Memory Optimization Tips" by Khouloud Haddad.

<rule>
name: php_memory_optimisation
description: Detect memory-heavy patterns and suggest streaming, generators, and better data handling
filters:
  - type: file_extension
    pattern: "\\.php$"

actions:
  - type: enforce
    conditions:
      # Avoid loading entire DB result sets into memory.
      - pattern: "->fetchAll\\("
        message: "Avoid fetchAll() on large result sets; iterate with fetch() in a loop or wrap with a generator (yield)."

      - pattern: "\\bmysqli_fetch_all\\("
        message: "Avoid mysqli_fetch_all() for large queries; prefer streaming fetch (e.g., mysqli_fetch_assoc in a loop)."

      # Avoid repeated full-file loads inside loops.
      - pattern: "foreach\\s*\\([^)]*\\)\\s*\\{[^}]*file_get_contents\\("
        message: "Avoid file_get_contents() inside loops; stream with SplFileObject or read once and reuse."

      # Avoid array_merge in tight loops as it copies arrays.
      - pattern: "foreach\\s*\\([^)]*\\)\\s*\\{[^}]*=\\s*array_merge\\("
        message: "Avoid array_merge() inside loops; append elements directly or preallocate arrays."

      # Use caution with range() on large ranges (allocates full array).
      - pattern: "\\brange\\s*\\("
        message: "range() allocates full arrays; for large ranges consider generators (yield) to avoid high memory."

  - type: suggest
    message: |
      **PHP memory optimisation recommendations:**

      - **Stream database results:** Prefer `$stmt->fetch(PDO::FETCH_ASSOC)` in a `while` loop or use generators instead of `fetchAll()`.
      - **Use generators (yield):** Iterate large datasets without allocating full arrays.
      - **Stream files:** Use `SplFileObject` or chunked reads instead of `file_get_contents()` for large files.
      - **Minimise array copying:** Avoid `array_merge()` in loops; push items directly or pre-size with known capacity (e.g., `SplFixedArray`).
      - **Free memory explicitly:** `unset($var)` after large data is no longer needed; consider `gc_collect_cycles()` for long-running scripts.
      - **Profile memory:** Use `memory_get_usage()` and tools like Xdebug/Blackfire to spot peaks.
      - **OPcache:** Ensure OPcache is enabled and sized appropriately in production.

  - type: validate
    conditions:
      # Detect full-file reads that likely could be streamed.
      - pattern: "\\bfile\\s*\\("
        message: "file() reads entire files into memory; prefer SplFileObject for line-by-line streaming."

metadata:
  priority: high
  version: 1.0
</rule>

<rule>
name: php_ini_opcache_recommendations
description: Recommend enabling OPcache for lower memory and better performance when editing php.ini
filters:
  - type: file_extension
    pattern: "\\.ini$"

actions:
  - type: suggest
    message: |
      **OPcache recommendations (php.ini):**
      - Set `opcache.enable=1` and `opcache.enable_cli=1` for CLI scripts that process large datasets.
      - Size memory pool appropriately, e.g., `opcache.memory_consumption=128` (adjust to your project).
      - Consider `opcache.interned_strings_buffer` and `opcache.max_accelerated_files` for larger codebases.

  - type: enforce
    conditions:
      - pattern: "(?mi)^opcache\\.enable\\s*=\\s*0"
        message: "Enable OPcache in production (set opcache.enable=1) to reduce memory and CPU overhead."

metadata:
  priority: medium
  version: 1.0
</rule>

More agent context in ivangrynenko/cursorrules

70 other files this repository gives its agents, the first 60 shown.