Most Claude Code skills fail silently — they either never trigger, produce generic output, or break the moment something unexpected happens. Here’s how to build ones that actually work.
A skill is a set of instructions that teaches Claude Code how to handle a specific type of task. Think of it as a recipe — it tells Claude what steps to follow, what to look for in the codebase, and how to produce consistent, high-quality output.
A skill lives as a SKILL.md file in your project (usually under .claude/skills/), and Claude reads it whenever it detects a relevant request. The file contains markdown instructions, and optionally references additional files for detailed guidance.
This article shares practical patterns for building skills that trigger reliably, research code thoroughly, handle failures gracefully, and produce output developers actually want. The examples come from real skills we built and open-sourced at github.com/axitdev/skills — feel free to reference them, but the patterns here apply to any skill you’re building.
After iterating on several skills, we found a consistent three-layer structure works best:
skill-name/\n├── SKILL.md (under 500 lines — main instructions)\n├── references/\n│ └── detailed-reference.md (loaded on demand — syntax, patterns, etc.)\n└── .skill-config.yaml (optional — user-customizable settings)\nThe key insight is progressive disclosure. Claude loads skill metadata (name + description) for every message to decide whether to activate a skill. The SKILL.md body loads when the skill triggers. Reference files load only when needed during execution.
This isn’t just about organization — it directly affects output quality. Every token in a bloated SKILL.md competes with the actual code research and generation for space in Claude’s context window. A 700-line SKILL.md stuffed with syntax examples means less room for Claude to think about your actual codebase. Extract reference material, and Claude has more headroom for the work that matters.
SKILL.md (under 500 lines) — the brain of the skill:
name and description (the trigger mechanism)Reference files — the knowledge base, loaded on demand:
## References\n\n- `references/syntax-guide.md` — Syntax examples for all supported formats.\n **Read this before generating output.** Do not generate from memory.\nThe bold instruction is important — it prevents Claude from “winging it” with training data that might be outdated.
Config files — user-customizable settings:
.yaml file letting users tune behavior without editing SKILL.mdHere’s what a skill looks like when you don’t follow this structure vs. when you do.
Before (everything in SKILL.md, ~700 lines):
---\nname: my-diagrammer\ndescription: Creates diagrams.\n---\n\n# Diagrammer\n\n## Workflow\n1. Ask what to diagram\n2. Generate diagram\n\n## Mermaid Syntax Reference\n### Sequence diagrams\n(50 lines of syntax examples)\n### Class diagrams\n(40 lines of syntax examples)\n### ERD\n(40 lines of syntax examples)\n### State diagrams\n(30 lines)\n### Flowcharts\n(30 lines)\n... (8 more diagram types, 200+ more lines)\n\n## Common Patterns\n(100 lines of reusable patterns)\nProblems: description is too vague to trigger reliably, syntax reference bloats the file, no failure handling, no config, no principles.
After (structured, ~300 lines SKILL.md + reference files):
---\nname: my-diagrammer\ndescription: >\n Generate diagrams from codebases by researching actual project code. Use this\n skill whenever the user asks to create, generate, or update diagrams. Trigger\n on phrases like "diagram the flow", "visualize the schema", "show me how X\n works". Also trigger when the user says "how does X connect to Y" — this\n implies a visual would help.\n---\n\n# Diagrammer\n\n## References\n- `references/syntax.md` — **Read before generating.** Don't use from memory.\n\n## Configuration\n(config table with defaults)\n\n## Workflow\n### Step 0: Load config\n### Step 1: Check for existing diagrams\n### Step 2: Ask what to diagram (skip if already specified)\n### Step 3: Research the code (the most important step)\n### Step 4: Generate\n### Step 5: Save and confirm\n\n## Handling Failures\n(what to do when code isn't found, MCP fails, etc.)\n\n## Principles\n1. Accuracy over aesthetics\n2. Research thoroughly\n3. Never lose work\nThe second version triggers more reliably, researches code before generating, handles failures, and keeps the heavy syntax reference out of the main file.
The description is the most important part of your skill. It’s the only thing Claude sees when deciding whether to activate it. A bad description means the skill never triggers — or triggers for the wrong things.
Be pushy. The skill-creator documentation explicitly recommends this because Claude tends to “under-trigger” — to not use skills when they’d be helpful.
A good description follows this pattern:
description: >\n {What the skill does in one sentence}. Use this skill whenever {explicit \n triggers}. Trigger on phrases like "{keyword 1}", "{keyword 2}", "{keyword 3}".\n Also trigger when the user {describes the intent without using the keywords} — \n e.g. "{natural language example 1}", "{natural language example 2}".\n Even if the user just {edge case trigger} — use this skill.\nThe four layers:
Don’t be shy about listing trigger phrases. Better to over-trigger and handle gracefully than to never trigger at all.
Most good skills follow the same general workflow:
The golden rule: ask the user at every decision point, but don’t over-ask. If the user already specified what they want in their initial message, skip the questions.
Before creating anything, check if it already exists. If your skill produces files, maintain an index and search it before generating:
> I found an existing {thing} that might be what you're looking for:\n> - [{Name}](./path/to/file.md) — short description\n>\n> Would you like to:\n> 1. View this existing one\n> 2. Update/regenerate it\n> 3. Create a new, separate one\nThis prevents the frustrating experience of Claude creating a second version of something that already exists. One of our skills initially lacked this check, and Claude would happily create duplicate output for the same request.
This is where code-aware skills add their real value. If your skill operates on a codebase, tell Claude to research deeply:
The key instruction that makes this work:
This is the most important step. Thoroughly research the actual codebase \nbefore producing output. Spend more time reading code than writing output.\nWithout this emphasis, Claude tends to rush to generation based on partial understanding.
If your skill targets a specific language or ecosystem, consider adding environment detection so it adapts automatically. For example, a PHP skill might detect which framework is in use and adjust its research paths accordingly — looking for controllers in app/Http/Controllers/ for one framework but src/Controller/ for another. A Python skill might detect Django vs. Flask vs. FastAPI.
The pattern is: auto-detect by default, let the user override via config for edge cases.
Things will go wrong — code doesn’t match expectations, MCP servers disconnect, searches find nothing. Plan for every failure mode explicitly.
If your skill researches code and the requested feature/flow isn’t there, don’t invent or guess:
> I searched the codebase but couldn't find an implementation for "{request}".\n> Here's what I found related to this area: {list what you did find}.\n>\n> Would you like me to:\n> 1. Look again — point me to the right files\n> 2. Create a draft showing a proposed design (marked as DRAFT)\n> 3. Try something else instead\nThe first time we didn’t handle this, Claude invented a plausible-looking but completely fictional flow diagram. Adding explicit “if nothing found” instructions fixed it completely.
If your skill depends on an MCP server or external tool, always have a fallback:
If the external service fails mid-creation (after research is done), don't \nlose the work. Immediately save the output in a local format. Then offer \nto retry the external service.\nPrinciple: never lose completed research. The user’s time waiting for code analysis is valuable. If the final rendering step fails, save what you have.
For any skill that depends on MCP servers, don’t hardcode tool names:
Before doing anything, list the available MCP tools to discover what the \nserver provides. Tool names, parameters, and capabilities change between \nversions. **Never assume a fixed API.** Always discover first.\nWe learned this the hard way — an MCP skill that assumed a specific tool name broke when the server updated. Making it discovery-first (introspect tools → adapt) made it resilient to any API change.
Every skill that produces files should maintain an index — a markdown file listing everything it has created:
# Generated Output\n\n> Index. Last updated: 2025-12-15\n\n### {Category}\n- [{Title}](./{category}/{name}.md) — {short description}\nBuild the index dynamically — only include section headers for categories that actually have entries. Our first version had a static template listing all possible categories, most of them empty. Much better to generate sections on the fly.
Rules every index should follow:
[DRAFT] {Title}Last updated dateAfter building several config files, these patterns emerged:
# Detail level:\n# overview — high-level, no method names\n# standard — class/method names, happy + key error paths\n# detailed — every call, all error paths, middleware, events\ndetail: standard\n.yaml file has the full documentation.Every skill should end with a principles section — these are the tiebreakers when instructions are ambiguous. Order them by priority.
The best principles we’ve found across multiple skills:
These aren’t just nice-to-haves. Each principle exists because we hit a real problem that it solves. “Never lose work” came from an MCP failure that discarded 5 minutes of code analysis. “Real names always” came from Claude generating output with generic labels instead of actual class names.
Don’t just read your skill and imagine how it would work. Run it. The gap between “looks correct when read” and “works correctly when used” is always wider than you expect.
Write 3-5 realistic test prompts — the kind of thing a real user would actually say. Not “test the diagram feature” but “diagram the payment flow in this project” or “explain how user authentication works.” Run each prompt with the skill installed and evaluate:
1. Putting reference content in SKILL.md. Syntax examples, cheat sheets, and pattern libraries belong in references/ files. Your SKILL.md should be the workflow, not the encyclopedia. This also wastes context window — Claude has less room to think about your code when the SKILL.md is bloated.
2. Static index templates. Listing all possible sections in the index template creates bloat. Build it dynamically — only sections with actual entries.
3. Assuming one framework/environment. If your skill targets a language with multiple frameworks, detect the environment and provide parallel paths. Let the user override via config.
4. No failure handling for “nothing found.” Without explicit instructions, Claude will invent plausible-looking but fictional output. Always handle the “I found nothing” case.
5. Hardcoded MCP tool names. MCP servers evolve. Tools get renamed, parameters change. Discover tools at runtime, don’t assume they’ll stay the same.
6. No duplicate checking. Without checking existing work first, Claude happily creates a second version of something that already exists. Always search before creating.
7. Over-asking questions. If the user already specified what they want in their initial message, don’t ask them again. Parse their intent from what they said and start working. One clarifying question max.
references/ filesThe patterns in this post come from building and iterating on real skills. You can see full working examples at github.com/axitdev/skills — use them as reference or as a starting point for your own.
", "author": { "name": "Oleksii Ivanov" }, "tags": [ "Tutorial", "Prompt Engineering", "Coding assistants", "Claude Code", "AI Skills", "AI" ], "date_published": "2026-04-04T02:00:00+02:00", "date_modified": "2026-04-04T02:05:38+02:00" }, { "id": "https://ddd.wtf/post/the-hidden-power-of-php-generators-for-large-datasets/", "url": "https://ddd.wtf/post/the-hidden-power-of-php-generators-for-large-datasets/", "title": "The Hidden Power of PHP Generators for Large Datasets", "summary": "TL;DR: PHP generators let you process million-row CSVs, paginated APIs, and massive database exports without running out of memory. This article goes beyond the yield…", "content_html": "TL;DR: PHP generators let you process million-row CSVs, paginated APIs, and massive database exports without running out of memory. This article goes beyond the yield basics — covering generator pipelines, yield from delegation, bidirectional communication, and real memory comparisons that show why generators should be your default tool for any dataset that doesn’t fit comfortably in RAM.
yield. Here’s Why You’re Not Using It Enough.Most PHP developers learn generators from a tutorial that shows yield inside a range() replacement and think “cool, but I’ll never need that.” Then they write a queue worker that loads 200K rows into an array, blows through memory_limit, and spend an afternoon debugging it.
Generators are not a niche feature. They’re the right default for any data pipeline that processes more than a few hundred items. The problem is that most content stops at the basics. Let’s go further.
A generator function uses yield instead of return. Instead of building a complete array and returning it, it produces values one at a time, only when asked:
function naturalNumbers(): Generator\n{\n $i = 1;\n while (true) {\n yield $i++;\n }\n}\n\n// This doesn't consume infinite memory — it produces one number at a time\n$numbers = naturalNumbers();\necho $numbers->current(); // 1\n$numbers->next();\necho $numbers->current(); // 2\nThe key insight: between yields, the generator is suspended. It doesn’t use CPU cycles. It holds only its local variables in memory — not the entire dataset.
In practice, you almost never call ->current() and ->next() directly. You iterate with foreach:
foreach (naturalNumbers() as $n) {\n if ($n > 1000000) break;\n // Process each number without storing the full sequence\n}\nThe most common use case I hit in production. Clients upload CSV exports ranging from 10K to 5M rows. Processing them with file() or fgetcsv() in a loop that collects into an array is a ticking time bomb.
/**\n * Read a CSV file row by row, yielding associative arrays.\n * Memory usage is constant regardless of file size.\n */\nfunction readCsv(string $path, string $separator = ','): Generator\n{\n $handle = fopen($path, 'r');\n\n if ($handle === false) {\n throw new \\RuntimeException("Cannot open file: {$path}");\n }\n\n try {\n // First row is the header\n $headers = fgetcsv($handle, 0, $separator);\n\n if ($headers === false) {\n return; // Empty file\n }\n\n // Trim BOM and whitespace from headers\n $headers = array_map(fn ($h) => trim($h, "\\xEF\\xBB\\xBF \\t\\n\\r"), $headers);\n $columnCount = count($headers);\n\n $lineNumber = 1;\n while (($row = fgetcsv($handle, 0, $separator)) !== false) {\n $lineNumber++;\n\n // Skip rows with wrong column count (malformed data)\n if (count($row) !== $columnCount) {\n // Log and skip rather than crash\n error_log("CSV line {$lineNumber}: expected {$columnCount} columns, got " . count($row));\n continue;\n }\n\n yield $lineNumber => array_combine($headers, $row);\n }\n } finally {\n fclose($handle);\n }\n}\nUsage is dead simple:
foreach (readCsv('/imports/customers-2026.csv') as $lineNum => $row) {\n $this->upsertCustomer(\n email: $row['email'],\n name: $row['full_name'],\n region: $row['region'],\n );\n}\nLet’s put numbers on this:
| File size | \nRows | \nfile() + array | \nGenerator | \n
|---|---|---|---|
| 5 MB | \n10K | \n18 MB | \n2 MB | \n
| 50 MB | \n100K | \n165 MB | \n2 MB | \n
| 500 MB | \n1M | \nOOM (>512 MB) | \n2 MB | \n
| 2 GB | \n5M | \nOOM | \n2 MB | \n
The generator column is always ~2 MB because it only holds one row plus the headers in memory at any time. The file handle is buffered by the OS. You could process a 50 GB file on a server with 128 MB memory_limit and it would work fine.
External APIs paginate their responses. The naive approach loads all pages into an array before processing:
// ❌ Accumulates all pages in memory\nfunction getAllProducts(ApiClient $api): array\n{\n $all = [];\n $page = 1;\n\n do {\n $response = $api->get('/products', ['page' => $page, 'per_page' => 100]);\n $all = array_merge($all, $response['data']);\n $page++;\n } while ($response['has_more']);\n\n return $all; // Could be 50K+ items\n}\nWith a generator, each page is fetched on demand and each item is yielded individually:
// ✅ Fetches and yields one page at a time\nfunction allProducts(ApiClient $api, int $perPage = 100): Generator\n{\n $page = 1;\n\n do {\n $response = $api->get('/products', [\n 'page' => $page,\n 'per_page' => $perPage,\n ]);\n\n foreach ($response['data'] as $product) {\n yield $product;\n }\n\n $page++;\n } while ($response['has_more']);\n}\n\n// Consumer doesn't know or care about pagination\nforeach (allProducts($api) as $product) {\n $this->syncProduct($product);\n}\nThis pattern is even more powerful when the API uses cursor-based pagination:
function allOrders(ApiClient $api): Generator\n{\n $cursor = null;\n\n do {\n $params = ['limit' => 100];\n if ($cursor !== null) {\n $params['after'] = $cursor;\n }\n\n $response = $api->get('/orders', $params);\n\n foreach ($response['data'] as $order) {\n yield $order;\n }\n\n $cursor = $response['next_cursor'];\n } while ($cursor !== null);\n}\nThe consumer sees a flat stream of orders. The pagination complexity is entirely encapsulated in the generator.
PDO can fetch rows one at a time, but most code calls fetchAll() out of habit. For large result sets, use a generator:
function queryStream(PDO $pdo, string $sql, array $params = []): Generator\n{\n $stmt = $pdo->prepare($sql);\n $stmt->execute($params);\n\n while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {\n yield $row;\n }\n\n $stmt->closeCursor();\n}\n\n// Process 500K orders without loading them all\nforeach (queryStream($pdo, 'SELECT * FROM orders WHERE year = ?', [2025]) as $order) {\n $this->archiveOrder($order);\n}\nImportant MySQL note: By default, PHP’s MySQL driver buffers the entire result set in memory on the client side (even with fetch()). To truly stream results, you need unbuffered queries:
function mysqlStream(PDO $pdo, string $sql, array $params = []): Generator\n{\n // Switch to unbuffered mode for this query\n $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);\n\n try {\n $stmt = $pdo->prepare($sql);\n $stmt->execute($params);\n\n while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {\n yield $row;\n }\n\n $stmt->closeCursor();\n } finally {\n // Restore buffered mode for subsequent queries\n $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, true);\n }\n}\nWith unbuffered queries, the memory profile drops from “entire result set” to “one row” — the difference between OOM and success for large exports.
One caveat: with unbuffered queries, you cannot run other queries on the same PDO connection until the cursor is fully consumed or closeCursor() is called. If your pipeline needs to do lookups mid-stream — like the enrichWithCustomer stage below — use a separate PDO connection for those secondary queries.
This is where generators go from “useful” to “architectural pattern.” You can chain generators to build data pipelines where each stage transforms or filters the stream:
// Stage 1: Read raw data\nfunction readOrders(PDO $pdo): Generator\n{\n yield from queryStream($pdo, 'SELECT * FROM orders WHERE status = ?', ['completed']);\n}\n\n// Stage 2: Enrich with customer data\nfunction enrichWithCustomer(Generator $orders, PDO $pdo): Generator\n{\n // Batch customer lookups for efficiency\n $customerCache = [];\n\n foreach ($orders as $order) {\n $customerId = $order['customer_id'];\n\n if (!isset($customerCache[$customerId])) {\n $stmt = $pdo->prepare('SELECT name, email, tier FROM customers WHERE id = ?');\n $stmt->execute([$customerId]);\n $customerCache[$customerId] = $stmt->fetch(PDO::FETCH_ASSOC);\n\n // Keep cache bounded — evict old entries\n if (count($customerCache) > 1000) {\n $customerCache = array_slice($customerCache, -500, null, true);\n }\n }\n\n $order['customer'] = $customerCache[$customerId];\n yield $order;\n }\n}\n\n// Stage 3: Filter high-value orders\nfunction filterHighValue(Generator $orders, float $threshold = 500.0): Generator\n{\n foreach ($orders as $order) {\n if ((float) $order['total'] >= $threshold) {\n yield $order;\n }\n }\n}\n\n// Stage 4: Format for export\nfunction formatForExport(Generator $orders): Generator\n{\n foreach ($orders as $order) {\n yield [\n 'order_id' => $order['id'],\n 'date' => date('Y-m-d', strtotime($order['created_at'])),\n 'customer_name' => $order['customer']['name'],\n 'customer_tier' => $order['customer']['tier'],\n 'total' => number_format((float) $order['total'], 2),\n ];\n }\n}\n\n// Compose the pipeline\n$pipeline = formatForExport(\n filterHighValue(\n enrichWithCustomer(\n readOrders($pdo),\n $pdo,\n ),\n threshold: 1000.0,\n )\n);\n\n// Write to CSV — the entire pipeline processes one row at a time\n$out = fopen('high-value-orders.csv', 'w');\n$headerWritten = false;\n\nforeach ($pipeline as $row) {\n if (!$headerWritten) {\n fputcsv($out, array_keys($row));\n $headerWritten = true;\n }\n fputcsv($out, $row);\n}\n\nfclose($out);\nThis pipeline reads from the database, enriches with customer data (with a bounded cache), filters, formats, and writes to CSV — all in constant memory. A 500K-row export uses the same ~5 MB of RAM as a 5K-row export.
The nested function calls above compose right-to-left, which can be hard to follow. A thin wrapper flips the composition to read left-to-right:
final class Pipeline\n{\n private Generator $source;\n\n public function __construct(Generator $source)\n {\n $this->source = $source;\n }\n\n public function pipe(callable $stage): self\n {\n $this->source = $stage($this->source);\n return $this;\n }\n\n public function filter(callable $predicate): self\n {\n return $this->pipe(function (Generator $input) use ($predicate): Generator {\n foreach ($input as $key => $item) {\n if ($predicate($item)) {\n yield $key => $item;\n }\n }\n });\n }\n\n public function map(callable $transform): self\n {\n return $this->pipe(function (Generator $input) use ($transform): Generator {\n foreach ($input as $key => $item) {\n yield $key => $transform($item);\n }\n });\n }\n\n public function each(callable $callback): void\n {\n foreach ($this->source as $item) {\n $callback($item);\n }\n }\n\n public function toArray(): array\n {\n return iterator_to_array($this->source);\n }\n\n public function reduce(callable $callback, mixed $initial = null): mixed\n {\n $carry = $initial;\n foreach ($this->source as $item) {\n $carry = $callback($carry, $item);\n }\n return $carry;\n }\n}\n\n// Now the same pipeline reads left to right:\n(new Pipeline(readOrders($pdo)))\n ->pipe(fn ($g) => enrichWithCustomer($g, $pdo))\n ->filter(fn ($order) => (float) $order['total'] >= 1000.0)\n ->map(fn ($order) => [\n 'order_id' => $order['id'],\n 'customer' => $order['customer']['name'],\n 'total' => number_format((float) $order['total'], 2),\n ])\n ->each(fn ($row) => fputcsv($out, $row));\nyield from: Delegation and Flatteningyield from delegates to another generator (or any iterable), flattening nested sequences:
function allTransactions(PDO $pdo): Generator\n{\n // Combine multiple sources into one stream\n yield from queryStream($pdo, 'SELECT *, "sale" as type FROM sales');\n yield from queryStream($pdo, 'SELECT *, "refund" as type FROM refunds');\n yield from queryStream($pdo, 'SELECT *, "chargeback" as type FROM chargebacks');\n}\n\n// Consumer sees a single flat stream of transactions\nforeach (allTransactions($pdo) as $txn) {\n $this->ledger->record($txn);\n}\nThis is powerful for combining data from multiple tables, files, or APIs into one unified stream without loading any of them fully into memory.
A practical use case — multi-file import:
function importDirectory(string $dir): Generator\n{\n $files = glob("{$dir}/*.csv");\n\n foreach ($files as $file) {\n echo "Processing: {$file}\\n";\n yield from readCsv($file);\n }\n}\n\n// Process all CSVs in a directory as one stream\nforeach (importDirectory('/imports/2026-03') as $lineNum => $row) {\n $this->importRow($row);\n}\nsend() and BackpressureGenerators can receive values via send(), which becomes the return value of the yield expression. This enables backpressure patterns — the consumer can signal the producer:
function controllableProducer(PDO $pdo): Generator\n{\n $offset = 0;\n $batchSize = 1000;\n\n while (true) {\n $stmt = $pdo->prepare("SELECT * FROM events LIMIT ? OFFSET ?");\n $stmt->execute([$batchSize, $offset]);\n $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);\n\n if (empty($rows)) {\n return; // No more data\n }\n\n foreach ($rows as $row) {\n $signal = yield $row;\n\n // Consumer can send signals back\n if ($signal === 'skip_batch') {\n break; // Skip rest of this batch\n }\n if ($signal === 'stop') {\n return; // Stop entirely\n }\n }\n\n $offset += $batchSize;\n }\n}\n\n// Usage\n$producer = controllableProducer($pdo);\n\nforeach ($producer as $event) {\n $result = $this->processEvent($event);\n\n if ($result === 'rate_limited') {\n // Tell the producer to stop — we'll resume later\n $producer->send('stop');\n }\n}\nI’ll be honest: I use send() rarely. In most cases, you can achieve the same result with a simple break or by tracking state outside the generator. But for complex producer-consumer patterns where the producer needs to adapt its behavior, send() is the clean tool.
Let’s settle this with numbers. Processing 100K items through a filter + map + reduce:
| Approach | \nPeak memory | \nTime | \nNotes | \n
|---|---|---|---|
array_filter + array_map + array_reduce | \n82 MB | \n95ms | \nCreates 3 intermediate arrays | \n
| Raw generator pipeline | \n2 MB | \n88ms | \nMinimal overhead | \n
The time difference is negligible. The memory difference is not. When you’re running 10 queue workers, each processing large datasets, the difference between 82 MB and 2 MB per worker is the difference between needing 820 MB and 20 MB of total memory. That’s real money on your hosting bill.
iterator_to_array() Too Early// ❌ Defeats the entire purpose of the generator\n$allRows = iterator_to_array(readCsv('huge-file.csv'));\n// You just loaded the entire file into an array\n\n// ✅ Consume lazily\nforeach (readCsv('huge-file.csv') as $row) {\n process($row);\n}\n$gen = readCsv('data.csv');\n\nforeach ($gen as $row) { /* first pass */ }\nforeach ($gen as $row) { /* nothing happens — generator is exhausted */ }\n\n// If you need multiple passes, either:\n// a) Create a new generator for each pass\n// b) Collect into an array (if it fits in memory)\n// c) Restructure to do everything in one pass\nIf a consumer breaks out of a generator early, the finally block runs — use it for cleanup:
function readFile(string $path): Generator\n{\n $handle = fopen($path, 'r');\n\n try {\n while (($line = fgets($handle)) !== false) {\n yield trim($line);\n }\n } finally {\n // This runs even if the consumer breaks early\n fclose($handle);\n }\n}\n\n// The file handle is properly closed even though we break early\nforeach (readFile('log.txt') as $line) {\n if (str_contains($line, 'FATAL')) {\n $this->alert($line);\n break; // finally block still runs, file is closed\n }\n}\nGenerators can return a final value (accessible via getReturn()), but it’s rarely useful and often confusing:
function countedRead(string $path): Generator\n{\n $count = 0;\n $handle = fopen($path, 'r');\n\n while (($line = fgets($handle)) !== false) {\n yield trim($line);\n $count++;\n }\n\n fclose($handle);\n return $count; // Accessible after generator completes\n}\n\n$gen = countedRead('data.txt');\nforeach ($gen as $line) {\n process($line);\n}\necho "Processed {$gen->getReturn()} lines"; // Works, but a counter variable is simpler\nMy advice: avoid return in generators. Track metadata with a separate counter or wrapper object. It’s clearer.
My personal heuristic is simple:
yield from.usort, array_unique, or random access? Use an array — generators can’t do that.Generators are not a premature optimization. They’re a better default. An array is the special case — you use it when you need random access or the dataset is small enough that it doesn’t matter.
Start yielding.
", "author": { "name": "Oleksii Ivanov" }, "tags": [ "Tutorial", "Performance", "PHP", "Database" ], "date_published": "2026-03-28T10:00:00+01:00", "date_modified": "2026-03-28T11:01:40+01:00" }, { "id": "https://ddd.wtf/post/the-state-of-php-in-2026-whats-changed-and-whats-coming/", "url": "https://ddd.wtf/post/the-state-of-php-in-2026-whats-changed-and-whats-coming/", "title": "The State of PHP in 2026: What's Changed and What's Coming", "summary": "TL;DR: PHP is thriving in 2026. The 8.x series has transformed the language with property hooks, generics-adjacent features, and performance improvements that rival compiled languages…", "content_html": "TL;DR: PHP is thriving in 2026. The 8.x series has transformed the language with property hooks, generics-adjacent features, and performance improvements that rival compiled languages for web workloads. The ecosystem is mature, hiring is stable, and the “PHP is dead” narrative looks more ridiculous than ever. Here’s your comprehensive roundup of where PHP stands and where it’s headed.
Let’s start with the data that makes PHP haters uncomfortable.
As of early 2026, PHP powers roughly 75-77% of websites with a known server-side language. While that number has gradually declined from its peak of 80%+, the absolute number of PHP-powered sites continues to grow. WordPress alone accounts for over 40% of all websites, and it’s not going anywhere.
But raw market share tells only part of the story. The more interesting metrics are:
Framework Ecosystem Health (GitHub activity, 2025)\n──────────────────────────────────────────────────\nLaravel ████████████████████████████ 100K+ ★\nSymfony ██████████████████ 30K+ ★\nSlim ███████████ 12K+ ★\nAPI Platform ████████ 8K+ ★\nPHP 8.0 through 8.4 represent the most significant evolution of the language since PHP 7.0’s performance overhaul. Let’s recap what landed and what it means for daily development.
Enums and fibers laid groundwork that took years to fully appreciate. Readonly properties started the immutability push. Intersection types gave us composability.
Readonly classes, true/false/null as standalone types, and DNF (Disjunctive Normal Form) types. The deprecation of dynamic properties was controversial but correct — it pushed codebases toward explicit, analyzable structures.
Typed class constants, json_validate(), the #[Override] attribute, and deep-cloning improvements. Each small on its own, together they made strict typing feel natural rather than burdensome.
Property hooks are the headline feature, but the full picture is bigger:
class Money\n{\n public readonly string $formatted {\n get => number_format($this->amount / 100, 2) . ' ' . $this->currency;\n }\n\n public function __construct(\n private int $amount,\n private string $currency = 'USD',\n ) {}\n}\n\n$price = new Money(4999);\necho $price->formatted; // "49.99 USD"\nProperty hooks eliminate the getter/setter boilerplate that made PHP feel verbose compared to Kotlin or C#. Combined with asymmetric visibility (public private(set)), PHP’s object model is now genuinely expressive.
Other 8.4 highlights:
ReflectionClass::newLazyProxy() — massive DI container optimization potential#[Deprecated] attribute for userland code — finally, proper deprecation notices without docblock hacksnew without parentheses — new Foo->bar() chains cleanlyThe RFCs in discussion paint an exciting picture:
$result = $input |> trim(...) |> strtolower(...) |> sanitize(...) would make functional-style PHP beautifulLaravel’s dominance is undeniable. With Reverb (WebSockets), Volt (single-file Livewire components), and continued investment in the first-party ecosystem (Forge, Vapor, Envoyer, Nova, Pulse), it’s become a full platform rather than just a framework.
The critique that Laravel is “too magical” has softened as the framework embraced explicit typing, better IDE support, and first-class static analysis integration. Laravel Pint, Herd, and the official PHPStan extension (larastan) show a commitment to developer tooling that’s hard to match.
Symfony 7.x continued its tradition of reliability and flexibility. The Messenger component is arguably the best queue/message bus implementation in any PHP framework. Symfony UX with Turbo and Stimulus provides a pragmatic approach to frontend interactivity without the SPA complexity.
Where Symfony truly shines in 2026: API Platform. Building a standards-compliant, documented, and performant API has never been easier. If you’re building APIs that need to last 5+ years, Symfony’s stability guarantees are unmatched.
The developer experience in PHP has improved dramatically:
PHPStan and Psalm matured to the point where running without them feels reckless. PHPStan’s popularity exploded — most major open-source packages now ship with level 8+ CI checks. The combination of PHP’s gradual typing and PHPStan’s inference means you get TypeScript-like safety without a compile step.
Automated refactoring became mainstream. Upgrading PHP versions, modernizing code patterns, and enforcing architectural rules programmatically — Rector made large-scale codebase modernization feasible for teams that couldn’t afford a manual rewrite.
PhpStorm 2025.x releases brought AI-assisted refactoring, better generics support (even for PHPDoc-based generics), and first-class property hooks support. The VS Code + Intelephense combination closed the gap significantly, making PHP development accessible regardless of IDE budget.
Pest continued to grow as a PHPUnit wrapper that developers actually enjoy writing tests in. The combination of Pest’s expressive syntax with Laravel’s testing utilities created what is arguably the best testing DX in any backend language:
it('processes payments correctly', function () {\n $order = Order::factory()->withItems(3)->create();\n\n $result = $order->processPayment(\n new FakePaymentGateway()\n );\n\n expect($result)\n ->toBeSuccessful()\n ->and($order->refresh())\n ->status->toBe(OrderStatus::Paid)\n ->paid_at->not->toBeNull();\n});\nThe PHP community is in its most professional era:
It’s not all sunshine. Here’s what still needs work:
Every year we say “generics might come soon,” and every year it doesn’t happen. PHPDoc generics via PHPStan work remarkably well as a stopgap, but the lack of runtime generics means PHP can’t express certain patterns cleanly. The erased generics RFC is the most promising approach, but consensus is slow.
Fibers provided the building blocks, but there’s no standard async library in the way JavaScript has native promises. RevoltPHP is the closest thing to a standard event loop, but the ecosystem is fragmented. Most PHP developers still use synchronous code with queue workers, and that’s fine for 95% of use cases.
PHP’s identity is still heavily tied to WordPress in the public consciousness. While WordPress is a testament to PHP’s durability, it doesn’t represent modern PHP development. The gap between “WordPress PHP” and “Laravel/Symfony PHP” is wider than the gap between Java and Kotlin.
Junior developers increasingly learn JavaScript or Python first. PHP’s onboarding pipeline relies heavily on WordPress and legacy projects, which gives newcomers a skewed view of the language. More modern PHP educational content is needed.
Based on RFC discussions and Foundation roadmap:
|>), clone with syntax for readonly classes, a built-in URI extension replacing the aging parse_url(), #[\\NoDiscard] attribute for safer APIs, array_first() / array_last(), and fatal error backtraces. A solid, focused release.? placeholder syntax, completing the functional programming trifecta with first-class callables and the pipe operator. Native clamp() joins the standard library. Pattern matching and true async (spawn/await/coroutines) are under active RFC discussion but not guaranteed.After a decade of writing PHP professionally, I’ve never been more optimistic. The language has evolved faster than its reputation, the ecosystem is mature without being stagnant, and the developer experience rivals anything in the JavaScript or Python worlds.
Is PHP the best choice for every project? Of course not. But for web applications, APIs, and the vast majority of backend work, PHP in 2026 is a genuinely excellent choice. The developers who dismiss it are working from outdated information — or they never gave modern PHP a fair shot.
The boring truth is that PHP lets you ship fast, maintain easily, and hire affordably. In a world chasing the next shiny framework, that’s a superpower.