📦 deps(thirdparty): update snapshots

2026-06-18 16:04:36 +00:00
parent 71b421806e
commit dd4c084042
416 changed files with 35467 additions and 3065 deletions
@@ -0,0 +1,316 @@
+---
+name: php
+description: "Language-specific super-code guidelines for php."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# PHP: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [Arrays & Collections](#arrays)
+2. [Type Safety](#types)
+3. [Error Handling](#errors)
+4. [String Handling](#strings)
+5. [OOP & Modern PHP](#oop)
+6. [Functions & Closures](#functions)
+7. [Anti-patterns specific to PHP](#antipatterns)
+
+---
+
+## 1. Arrays & Collections {#arrays}
+
+```php
+// ❌ Manual accumulation
+$result = [];
+foreach ($items as $item) {
+    if ($item->isActive()) {
+        $result[] = strtoupper($item->getName());
+    }
+}
+
+// ✅
+$result = array_map(
+    fn($i) => strtoupper($i->getName()),
+    array_filter($items, fn($i) => $i->isActive())
+);
+```
+
+```php
+// ❌ Manual key-value grouping
+$grouped = [];
+foreach ($items as $item) {
+    $grouped[$item->getCategory()][] = $item;
+}
+
+// ✅ (PHP 8.1+) — or use the loop above; PHP lacks a built-in groupBy
+// The foreach is actually idiomatic PHP for grouping. No need to force array_* here.
+```
+
+```php
+// ❌ Checking isset then accessing
+if (isset($data['key'])) {
+    $value = $data['key'];
+} else {
+    $value = 'default';
+}
+
+// ✅
+$value = $data['key'] ?? 'default';
+```
+
+```php
+// ❌ array_push for single element
+array_push($items, $newItem);
+
+// ✅
+$items[] = $newItem;
+```
+
+**Use `array_map`/`array_filter` for transforms. The `foreach` loop is fine when array functions would be less readable.**
+
+---
+
+## 2. Type Safety {#types}
+
+```php
+// ❌ No type declarations
+function process($items) {
+    return $items;
+}
+
+// ✅ (PHP 8.0+)
+function process(array $items): array {
+    return $items;
+}
+```
+
+```php
+// ❌ Union type for nullable
+function find(string $key): string|null { ... }
+
+// ✅
+function find(string $key): ?string { ... }
+```
+
+```php
+// ❌ Loose comparison
+if ($value == '0') { ... } // true for 0, '', false, null
+
+// ✅
+if ($value === '0') { ... }
+```
+
+```php
+// ❌ Type checking with gettype()
+if (gettype($x) === 'integer') { ... }
+
+// ✅
+if (is_int($x)) { ... }
+// or with union types, avoid checks entirely
+```
+
+**Enable `declare(strict_types=1)` at the top of every file.**
+
+---
+
+## 3. Error Handling {#errors}
+
+```php
+// ❌ Suppressing errors with @
+$data = @file_get_contents($path);
+
+// ✅
+$data = file_get_contents($path);
+if ($data === false) {
+    throw new RuntimeException("Failed to read: $path");
+}
+```
+
+```php
+// ❌ Catching \Exception and swallowing
+try { process(); }
+catch (\Exception $e) { /* silence */ }
+
+// ✅
+try {
+    process();
+} catch (SpecificException $e) {
+    $this->logger->error($e->getMessage(), ['exception' => $e]);
+    throw new AppException('Processing failed', previous: $e);
+}
+```
+
+```php
+// ❌ Returning mixed types for error indication
+function divide(int $a, int $b): int|false {
+    if ($b === 0) return false;
+    return intdiv($a, $b);
+}
+
+// ✅ — throw exception for exceptional cases
+function divide(int $a, int $b): int {
+    if ($b === 0) throw new \DivisionByZeroError();
+    return intdiv($a, $b);
+}
+```
+
+---
+
+## 4. String Handling {#strings}
+
+```php
+// ❌ Concatenation for variable interpolation
+$msg = 'Hello, ' . $name . '! You have ' . $count . ' messages.';
+
+// ✅
+$msg = "Hello, {$name}! You have {$count} messages.";
+```
+
+```php
+// ❌ Manual string contains check
+if (strpos($haystack, $needle) !== false) { ... }
+
+// ✅ (PHP 8.0+)
+if (str_contains($haystack, $needle)) { ... }
+```
+
+```php
+// ❌ substr for prefix/suffix check
+if (substr($str, 0, 4) === 'http') { ... }
+if (substr($str, -4) === '.php') { ... }
+
+// ✅ (PHP 8.0+)
+if (str_starts_with($str, 'http')) { ... }
+if (str_ends_with($str, '.php')) { ... }
+```
+
+---
+
+## 5. OOP & Modern PHP {#oop}
+
+```php
+// ❌ Manual constructor property assignment
+class User {
+    private string $name;
+    private int $age;
+    public function __construct(string $name, int $age) {
+        $this->name = $name;
+        $this->age = $age;
+    }
+}
+
+// ✅ (PHP 8.0+)
+class User {
+    public function __construct(
+        private readonly string $name,
+        private readonly int $age,
+    ) {}
+}
+```
+
+```php
+// ❌ Constants as class properties
+class Status {
+    const ACTIVE = 'active';
+    const INACTIVE = 'inactive';
+}
+
+// ✅ (PHP 8.1+)
+enum Status: string {
+    case Active = 'active';
+    case Inactive = 'inactive';
+}
+```
+
+```php
+// ❌ instanceof chains
+if ($shape instanceof Circle) { ... }
+elseif ($shape instanceof Rectangle) { ... }
+
+// ✅ (PHP 8.0+)
+$area = match(true) {
+    $shape instanceof Circle => $shape->radius ** 2 * M_PI,
+    $shape instanceof Rectangle => $shape->width * $shape->height,
+    default => throw new \InvalidArgumentException("Unknown shape"),
+};
+```
+
+```php
+// ❌ Named constructor via static method returning new self()
+class Money {
+    public static function fromCents(int $cents): self {
+        $m = new self();
+        $m->cents = $cents;
+        return $m;
+    }
+}
+
+// ✅ (PHP 8.0+) — constructor promotion + named arguments
+class Money {
+    public function __construct(
+        public readonly int $cents,
+    ) {}
+}
+$m = new Money(cents: 500);
+```
+
+---
+
+## 6. Functions & Closures {#functions}
+
+```php
+// ❌ Verbose closure for simple operation
+$doubled = array_map(function ($x) { return $x * 2; }, $numbers);
+
+// ✅ (PHP 7.4+)
+$doubled = array_map(fn($x) => $x * 2, $numbers);
+```
+
+```php
+// ❌ Passing globals or using `global` keyword
+global $db;
+function getUser(int $id) {
+    global $db;
+    return $db->find($id);
+}
+
+// ✅ — dependency injection
+function getUser(int $id, PDO $db): ?User {
+    return $db->find($id);
+}
+```
+
+```php
+// ❌ Named arguments abused for every call
+str_pad(string: $s, length: 10, pad_string: ' ', pad_type: STR_PAD_LEFT);
+
+// ✅ — named args are useful for readability on ambiguous params; don't force
+str_pad($s, 10, ' ', STR_PAD_LEFT);
+// but named args shine for: new User(name: 'Alice', age: 30)
+```
+
+---
+
+## 7. Anti-patterns specific to PHP {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `==` for comparison | `===` (strict equality) |
+| `@` error suppression | explicit error handling |
+| `global` keyword | dependency injection |
+| `extract()` on user input | access keys explicitly |
+| `die()` / `exit()` in library code | throw exception |
+| `strpos !== false` for contains | `str_contains()` (PHP 8.0) |
+| Manual constructor assignment | constructor promotion (PHP 8.0) |
+| Class constants for enums | `enum` (PHP 8.1) |
+| `mixed` return types | specific typed returns |
+| `array` for everything | typed classes / DTOs |
+| `var_dump` / `print_r` debugging | proper logging (PSR-3) |
+| Not using `declare(strict_types=1)` | always enable |
+
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.