Web Developer Blog

Start developing with Laravel on Ubuntu 24.04 LTS

Sun, 22 Feb 2026 00:00:00 +0000

Ahnii!

Ubuntu 24.04 LTS is a solid base for learning web development. The Laravel docs recommend PHP, Composer, and the Laravel installer on your machine. This post follows that official path first, then shows the DDEV option if you prefer a container-based stack.

Prerequisites

Ubuntu 24.04 LTS (desktop or server)
For the official method: no PHP/Composer required yet — the install script adds them.
For the DDEV method: Docker and Docker Compose.

Official method: PHP, Composer, and Laravel installer

The Laravel 12 installation guide uses php.new to install PHP 8.4, Composer, and the Laravel installer in one go. On Linux you run:

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

Restart your terminal after it finishes. That gives you PHP, Composer, and the laravel CLI. You also need Node.js and npm (or Bun) to build frontend assets; install them via your package manager if needed (e.g. sudo apt install nodejs npm on Ubuntu).

Create the application

Create a new Laravel app. The installer will prompt you for testing framework, database, and starter kit:

laravel new my-laravel-app
cd my-laravel-app

Then install frontend dependencies, build assets, and start the dev server:

npm install && npm run build
composer run dev

The app runs at http://localhost:8000. The composer run dev script starts Laravel’s HTTP server plus the Vite dev server and queue worker.

Verify it works

Open http://localhost:8000 in your browser. You should see the default Laravel welcome page.

Alternatively: DDEV method

If you prefer to keep PHP and the database in containers, use DDEV. Follow the DDEV installation guide for Linux, then use the Laravel quickstart: create the project directory, configure DDEV for Laravel, start the containers, and install Laravel via Composer:

mkdir my-laravel-site && cd my-laravel-site
ddev config --project-type=laravel --docroot=public
ddev start
ddev composer create-project "laravel/laravel:^12"
ddev launch

ddev config sets the project type and document root. ddev start brings up the web and database containers. ddev composer create-project installs Laravel 12 inside the web container. The Laravel project type in DDEV automatically updates or creates the .env file with the database host, user, and password (db), so you don’t run key:generate or edit .env by hand. ddev launch opens the app in your browser.

Baamaapii

coaudit: AI-Powered Code Audits with GitHub Copilot CLI

Sun, 15 Feb 2026 00:00:00 +0000

Ahnii!

This is a submission for the GitHub Copilot CLI Challenge

What I Built

coaudit is a command-line tool that performs structured code audits on any repository using GitHub Copilot CLI. Instead of implementing static analyzers, it orchestrates Copilot to analyze codebases across 6 critical dimensions:

Dead Code – Unused functions, variables, imports, unreachable code
Architectural Leaks – Layer violations, cyclic dependencies, improper coupling
Selector Fragility – Brittle CSS/DOM selectors prone to breaking with HTML changes
Routing Inconsistencies – Mismatched or missing route handlers, parameter naming mismatches
Missing Tests – Untested functions, uncovered error paths, integration gaps
Observability Gaps – Missing logging, error context, unmonitored operations

How It Works

# Audit any local project
coaudit ~/my-project

# Or audit directly from GitHub
coaudit owner/repo

# Full GitHub URL also works
coaudit https://github.com/owner/repo

The tool:

Collects source files from the target repository (multi-language support: JS, TS, Python, PHP, Go, Java, Rust)
Loads dimension-specific audit prompts from curated markdown templates
Chunks code context intelligently to stay within token limits
Invokes GitHub Copilot CLI in batch mode with prompt + context
Generates a structured Markdown report with findings across all dimensions

Why This Matters

Code audits typically require:

Static analyzers – Language-specific, limited to syntactic rules
Code review tools – Expensive, require human reviewers
Manual analysis – Time-consuming, inconsistent

coaudit combines the intelligence of Copilot with the automation of batch processing. It provides semantic analysis that static tools can’t do, at the speed of automation.

Demo

Repository: https://github.com/jonesrussell/coaudit

Quick Start

# Install
npm install
npm start

# Run audit on coaudit itself (meta!)
node bin/coaudit .

# Audit an external GitHub repo
node bin/coaudit facebook/react

Example Output

When you run coaudit on a repository, you get a Markdown report like:

# Copilot Pipeline Audit Report

**Repository:** facebook/react
**Timestamp:** 2026-02-16T01:45:59.842Z

## Summary
| Status | Count |
|--------|-------|
| Completed | 6 |
| Skipped | 0 |
| Errors | 0 |

## Findings

### Dead Code
**Status:** ✅ Completed
- Unused exports in `src/utils.js`
- Unreachable branches in error handling
- Deprecated function still exported...

### Architectural Leaks
**Status:** ✅ Completed
- Direct imports violating layer boundaries
- Cyclic dependency between modules A and B...

### Missing Tests
**Status:** ✅ Completed
- 14 functions with zero test coverage
- Error paths not tested...

Real Copilot Integration

This is not a mock – the tool makes real calls to Copilot CLI in batch mode:

// From src/runner.js
const output = execSync(
  `copilot -p '${prompt + context}' --allow-all --add-dir '${targetDir}'`,
  { encoding: 'utf8', timeout: 180000 }
);

Each audit dimension spawns a full Copilot analysis, giving you genuine semantic insights across your entire codebase.

My Experience with GitHub Copilot CLI

Why Copilot CLI Was Essential

Building coaudit was only possible because of Copilot CLI’s non-interactive mode (-p flag). Here’s why:

Problem: I needed to automate code analysis without manually running Copilot for each repo.

Solution: Copilot CLI’s -p, --prompt flag enables batch execution:

copilot -p "analyze this code" --allow-all

This unlocked the entire project. Without it, coaudit would require:

Manual prompt copying/pasting
Interactive terminal sessions per repo
No way to orchestrate 6 sequential analyses

The Development Journey

Initial Approach – Started with static analyzer rules. Too limiting – couldn’t detect architectural patterns or semantic issues.
Pivot to Copilot – Realized Copilot CLI could do semantic analysis. But how to automate it?
Discovered Batch Mode – The -p flag was the breakthrough. Suddenly, I could:
- Pass full code context as a single prompt
- Run 6 audit dimensions in sequence
- Parse Copilot’s responses into structured reports
- All without user interaction
Real-World Testing – Ran coaudit on itself (meta!). The 6 audit dimensions identified:
- Architectural issue: Copilot integration logic duplicated in runner.js
- Test coverage gap: No test framework yet
- Observability gap: Silent failures in repo cloning
- Dead code: Unused exports in integration module

These insights came from Copilot, not linters.

Key Features Enabled by Copilot CLI

Feature	Why It Works
Semantic Analysis	Copilot understands code intent, not just syntax
Multi-Language	One prompt works for JS, Python, PHP, Go, Java, Rust
Contextual	Can analyze architectural patterns across files
Extensible	Adding audit dimensions is just adding a markdown prompt
Batch Processing	Non-interactive mode enables automation

What I Learned

Copilot CLI is a powerful automation engine – Not just for chat, but for building agentic workflows
Prompts-as-code is elegant – Audit rules live in markdown, easy to version and modify
Context windows are the lever – Intelligently chunking code context is more important than prompt engineering
Batch mode is underrated – The -p flag transforms Copilot from interactive tool to orchestration platform

Challenges & Solutions

Challenge: Large codebases exceed token limits Solution: Implemented smart chunking – limit context to 50KB per audit dimension, prioritize relevant files

Challenge: Copilot takes 30-180 seconds per dimension Solution: Added progress indicators and timeout handling; parallel audits planned for v1

Challenge: Structuring Copilot’s free-text output Solution: Request JSON format in prompts; parse responses programmatically

The Meta Moment

I ran coaudit on coaudit itself. Copilot found legitimate issues that I missed:

Unused exports in copilot-integration.js
Architectural leak: Should use dedicated integration module instead of duplicating logic in runner.js
Missing tests and observability logging

This validated the tool’s value – even the author benefits from automated analysis.

Why coaudit Matters for Teams

Speed – Get insights from a full codebase audit in minutes, not days
Consistency – Same audit rules applied to every dimension
Scale – Works on any size repo, any language
Feedback Loop – Iterate on audit prompts to improve analysis
Learning – Copilot’s findings teach you architectural patterns you might miss

What’s Next

Real-time audit feedback in GitHub PR comments
Configurable audit dimensions via .copilot-audit.json
JSON/HTML report formats for CI/CD integration
Severity levels and risk scoring
Parallel dimension audits for faster results

Thanks to GitHub Copilot CLI

This project wouldn’t exist without the -p batch execution mode. Copilot CLI transformed from a chat interface into a powerful automation platform. Excited to see what else the community builds!

Try coaudit: https://github.com/jonesrussell/coaudit

Baamaapii 👋

Using Laravel Boost With DDEV

Tue, 10 Feb 2026 00:00:00 +0000

Ahnii!

Laravel Boost is an official MCP server that gives AI coding agents deep context about your Laravel application — routes, schema, logs, config, and more. If you develop with DDEV, Boost runs inside the container, and your editor just needs to know how to reach it.

This post covers the standard DDEV setup and the extra step needed for WSL.

Prerequisites

A Laravel project running in DDEV
An editor that supports MCP (Cursor, VS Code with Copilot, Claude Code, etc.)

Install Boost

From your project root:

ddev composer require laravel/boost --dev
ddev artisan boost:install

The install command generates guideline and skill files for your chosen AI agent. You can add these generated files to .gitignore since boost:install recreates them.

Configure the MCP Server

Standard Setup (Linux / macOS)

Create a .mcp.json in your project root:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "ddev",
            "args": [
                "artisan",
                "boost:mcp"
            ]
        }
    }
}

That’s it. DDEV provides ddev artisan as a shorthand for ddev exec php artisan, so the config stays minimal. It runs boost:mcp inside the container and exposes it over stdio to your editor.

WSL Setup (Windows)

If your editor runs on Windows but your DDEV project lives in WSL, the editor can’t call ddev directly. Wrap the command with wsl.exe and point cwd to the WSL project path:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "wsl.exe",
            "args": [
                "ddev",
                "artisan",
                "boost:mcp"
            ],
            "cwd": "/home/your-user/dev/your-project"
        }
    }
}

wsl.exe bridges from Windows into your default WSL distro, where ddev is available on the PATH. The cwd tells it which directory to run from so DDEV picks up the right project.

If you use a non-default distro, add -d your-distro before ddev in the args array.

Verify It Works

Open your editor and ask the AI agent something project-specific, like “What routes does this app have?” or “Show me the database schema.” If Boost is connected, the agent will use its tools to answer from your actual application state instead of guessing.

You can also check the available tools directly. In Claude Code:

claude mcp list

You should see laravel-boost with its 15+ tools listed.

Keeping Boost Updated

When you update Laravel or your dependencies:

ddev composer update laravel/boost
ddev artisan boost:update

Or add boost:update to your Composer post-update-cmd scripts to automate it.

Baamaapii

Drift in Cursor AI Rules

Thu, 19 Jun 2025 00:00:00 +0000

Ahnii! As codebases evolve, Cursor AI rules quietly fall behind. Rules that once provided helpful suggestions now generate irrelevant completions. Patterns that worked for your initial architecture become counterproductive as your project grows. This is drift—and it’s undermining your AI-assisted development workflow.

Problem

Drift happens because we treat Cursor rules as set-and-forget configurations. But they’re not static—they’re living instructions that must evolve with our code. When they don’t, the AI starts offering suggestions that feel more like obstacles than assistance.

The cost compounds over time: ignoring unhelpful completions, fighting against outdated patterns, and ultimately, losing trust in AI-powered development tools.

Example

Your project moved from JavaScript to TypeScript, but your Cursor rules still generate untyped code.

Outdated /cursor/.rules:

# Component Guidelines
- Use functional components with useState hooks
- Export default components
- Use PropTypes for validation

const Button = ({ onClick, children }) => {
  return ;
};

Updated rules:

# Component Guidelines  
- Use TypeScript functional components
- Define proper interfaces for props
- Export default components

interface ButtonProps {
  onClick: () => void;
  children: React.ReactNode;
}

const Button: React.FC = ({ onClick, children }) => {
  return ;
};

The AI now suggests properly typed components instead of outdated JavaScript patterns.

Solution

Treat your Cursor rules like code. They need active maintenance, not neglect.

Audit your rules, all the time. Which ones generate irrelevant suggestions? What new patterns aren’t captured?

Usage monitoring: Pay attention to which AI suggestions you consistently reject or modify. These are signals of drift.

Incremental updates: Refine rules based on how your codebase actually evolves, not how you thought it would.

Team alignment: Ensure rules reflect current team practices and architectural decisions.

Payoff

When you prevent drift, Cursor transforms from a sometimes-helpful tool into a reliable coding partner. The AI understands your current patterns and provides genuinely useful suggestions that accelerate development.

Maintaining alignment between your rules and reality ensures that AI assistance enhances rather than interrupts your flow. In a world where AI coding tools are becoming essential, keeping them accurate and relevant isn’t optional—it’s critical for productivity.

Baamaapii!

CORS: Understanding Cross-Origin Resource Sharing

Fri, 16 May 2025 00:00:00 +0000

Update - June 16, 2025: This post has been updated to better explain CORS as a security feature rather than a problem to be “fixed.” The content is now language-agnostic and emphasizes why CORS is essential for web security.

Ahnii!

CORS (Cross-Origin Resource Sharing) is a crucial web security mechanism that controls how web pages from one domain can access resources from another domain. Rather than being a problem to solve, CORS is actually a security feature that protects users while enabling legitimate cross-origin communication.

Why CORS Exists

Browsers enforce the same-origin policy by default, which prevents scripts from one origin from accessing resources on another origin. This security measure protects users from malicious websites that might try to access sensitive data from other sites you’re logged into.

Without CORS, a malicious website could potentially:

Read your emails from Gmail if you’re logged in
Access your banking information from another tab
Make unauthorized requests on your behalf

CORS provides a controlled way for servers to explicitly permit cross-origin requests while maintaining security. Learn more about CORS on MDN.

Understanding Origins

An origin consists of three parts: protocol, host, and port. These are considered different origins:

http://localhost:3000 and http://localhost:8080 (different ports)
https://api.example.com and http://api.example.com (different protocols)
https://app.example.com and https://api.example.com (different subdomains)

Implementing CORS

When you need to allow cross-origin requests, you configure CORS headers on your server. Here’s a basic implementation:

// Node.js/Express example
app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', 'https://yourdomain.com');
    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    next();
});

# Python/Flask example
from flask_cors import CORS

app = Flask(__name__)
CORS(app, origins=['https://yourdomain.com'])

// Java/Spring example
@CrossOrigin(origins = "https://yourdomain.com")
@RestController
public class ApiController {
    // Your endpoints here
}

Security Best Practices

Never use wildcards in production:

// DON'T do this in production
res.header('Access-Control-Allow-Origin', '*');

// DO this instead
res.header('Access-Control-Allow-Origin', 'https://yourdomain.com');

Be specific with allowed methods and headers:

res.header('Access-Control-Allow-Methods', 'GET, POST'); // Only what you need
res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');

Key Takeaways

CORS is not a barrier to overcome but a security feature that enables safe cross-origin communication. When implementing CORS:

Understand the why: CORS protects users from malicious cross-origin requests
Be restrictive: Only allow the origins, methods, and headers you actually need
Use libraries: Leverage well-tested CORS implementations rather than rolling your own
Test thoroughly: Verify your CORS configuration works with your frontend applications
Monitor: Keep track of CORS errors in production to catch configuration issues

Additional Resources:

Got questions about CORS implementation? Drop a comment below!

Baamaapii 👋

PSR-20: Clock Interface in PHP

Sun, 20 Apr 2025 00:00:00 +0000

Ahnii!

Here’s a question that’s tripped up every developer: how do you test code that depends on “right now”? PSR-20 has the answer.

Prerequisites: PHP OOP, basic testing concepts. No specific PSR prerequisites – this is a standalone utility standard.

What Problem Does PSR-20 Solve? (3 minutes)

Every time you write new \DateTime('now') or time(), you’ve made your code untestable.

Think about it. Your test says “check if this event was created in the last 5 minutes.” But when is “now”? During CI at 3am? When the developer runs it at noon? On a server in a different timezone? The answer changes every time the test runs, and that’s the problem.

Time is a hidden dependency, just like a database connection or a file path. When you call new \DateTime('now') inside a method, you’ve hardcoded a dependency on the system clock. You can’t control it, you can’t predict it, and you can’t freeze it for testing.

PSR-20 makes that dependency explicit. Instead of asking PHP for the time, you ask a Clock object. In production, the clock returns the real time. In tests, you freeze it to whatever moment you need. The code under test doesn’t know the difference – it just calls $clock->now() and gets a DateTimeImmutable back.

No more flaky tests. No more “it passed on my machine.” No more race conditions between the time a test creates data and the time it checks it.

Core Interface (3 minutes)

PSR-20 is the simplest PSR of all – one interface, one method:

php

namespace Psr\Clock;

interface ClockInterface
{
    public function now(): \DateTimeImmutable;
}

That’s the entire specification. Call now(), get back the current time as a DateTimeImmutable. No exceptions to handle, no configuration to pass, no edge cases to consider.

The power is in the implementations. You need two:

SystemClock

The production implementation. Returns the real current time:

php

namespace App\Clock;

use Psr\Clock\ClockInterface;

class SystemClock implements ClockInterface
{
    public function now(): \DateTimeImmutable
    {
        return new \DateTimeImmutable('now');
    }
}

FrozenClock

The testing implementation. Returns a fixed time that never changes:

php

namespace App\Clock;

use Psr\Clock\ClockInterface;

class FrozenClock implements ClockInterface
{
    public function __construct(private \DateTimeImmutable $frozenAt) {}

    public function now(): \DateTimeImmutable
    {
        return $this->frozenAt;
    }
}

In production, your service container wires up SystemClock. In tests, you create a FrozenClock with whatever time you need. The code that depends on ClockInterface works identically in both cases.

Real-World Implementation (10 minutes)

Let’s build practical examples using the blog API. Each one demonstrates a different reason you’d want testable time.

Publishing a Post with Testable Time

When a post is published, it needs a timestamp. With PSR-20, that timestamp comes from the clock:

php

namespace App\Blog;

use Psr\Clock\ClockInterface;

class PostPublisher
{
    public function __construct(
        private PostRepository $posts,
        private ClockInterface $clock,
    ) {}

    public function publish(Post $post): void
    {
        $post->setPublishedAt($this->clock->now());
        $this->posts->save($post);
    }
}

No new \DateTime() hidden inside the method. The time comes from an injected dependency you can control.

Cache TTL with Testable Time

Cache expiration depends on time. Without a clock, you can’t test whether expired entries are properly evicted:

php

namespace App\Blog;

use Psr\Clock\ClockInterface;

class CachedPostRepository
{
    /** @var array */
    private array $cache = [];

    public function __construct(
        private PostRepository $inner,
        private ClockInterface $clock,
        private int $ttlSeconds = 300,
    ) {}

    public function find(int $id): ?Post
    {
        $key = "post.$id";

        if (isset($this->cache[$key]) && $this->cache[$key]['expires'] > $this->clock->now()) {
            return $this->cache[$key]['post'];
        }

        $post = $this->inner->find($id);

        if ($post !== null) {
            $this->cache[$key] = [
                'post'    => $post,
                'expires' => $this->clock->now()->modify("+{$this->ttlSeconds} seconds"),
            ];
        }

        return $post;
    }
}

With a FrozenClock, you can test cache expiration by setting the clock to a time after the TTL – no waiting, no sleep() calls, no timing-dependent failures.

Scheduled Publishing

Check if a post’s scheduled date has arrived and publish all pending posts:

php

namespace App\Blog;

use Psr\Clock\ClockInterface;

class ScheduledPostPublisher
{
    public function __construct(
        private PostRepository $posts,
        private ClockInterface $clock,
    ) {}

    public function publishScheduledPosts(): int
    {
        $now = $this->clock->now();
        $pending = $this->posts->findScheduledBefore($now);

        foreach ($pending as $post) {
            $post->setPublishedAt($now);
            $this->posts->save($post);
        }

        return count($pending);
    }
}

In tests, you set the frozen clock to 2025-03-15 10:00:00 and schedule a post for 2025-03-15 09:00:00. The test deterministically verifies the post gets published. No ambiguity, no flakiness.

Common Mistakes and Fixes

1. Using `new \DateTime()` Instead of the Clock

The whole point of PSR-20 is to eliminate direct time construction. If you’re still calling new \DateTime() inside your methods, the clock can’t help you.

// Bad -- hardcoded time, untestable
public function publish(Post $post): void
{
    $post->setPublishedAt(new \DateTimeImmutable('now'));
    $this->posts->save($post);
}

// Good -- time comes from the clock
public function publish(Post $post): void
{
    $post->setPublishedAt($this->clock->now());
    $this->posts->save($post);
}

2. Making the Clock Optional

Don’t make the clock a nullable parameter with a fallback to real time. This defeats the purpose entirely – if tests don’t provide a clock, they silently use real time and become flaky.

// Bad -- optional clock means tests might skip it
public function __construct(
    private PostRepository $posts,
    private ?ClockInterface $clock = null,
) {
    $this->clock = $clock ?? new SystemClock();
}

// Good -- always require the clock
public function __construct(
    private PostRepository $posts,
    private ClockInterface $clock,
) {}

3. Using `time()` or `date()` Functions

The global time() and date() functions have the same problem as new \DateTime(). All time access should go through the clock.

// Bad -- global function, same untestable problem
if (time() - $cachedAt > 300) {
    $this->refreshCache();
}

// Good -- clock-based comparison
if ($this->clock->now()->getTimestamp() - $cachedAt > 300) {
    $this->refreshCache();
}

Testing with PSR-20 (5 minutes)

Testing is PSR-20’s entire reason for existing. Let’s write a complete PHPUnit test that demonstrates why this standard matters:

php

namespace Tests\Blog;

use App\Blog\Post;
use App\Blog\PostPublisher;
use App\Blog\PostRepository;
use App\Clock\FrozenClock;
use PHPUnit\Framework\TestCase;

class PostPublisherTest extends TestCase
{
    public function testPublishSetsTimestamp(): void
    {
        $frozenTime = new \DateTimeImmutable('2025-03-15 10:00:00');
        $clock = new FrozenClock($frozenTime);

        $post = new Post('My Blog Post');
        $repository = $this->createMock(PostRepository::class);
        $repository->expects($this->once())->method('save')->with($post);

        $publisher = new PostPublisher($repository, $clock);
        $publisher->publish($post);

        $this->assertEquals($frozenTime, $post->getPublishedAt());
        // This test ALWAYS passes, regardless of when it runs
    }

    public function testPublishScheduledPostsOnlyPublishesPastDue(): void
    {
        $frozenTime = new \DateTimeImmutable('2025-03-15 10:00:00');
        $clock = new FrozenClock($frozenTime);

        // A post scheduled for 9am should be published at 10am
        $scheduledPost = new Post('Scheduled Post');
        $scheduledPost->setScheduledAt(new \DateTimeImmutable('2025-03-15 09:00:00'));

        $repository = $this->createMock(PostRepository::class);
        $repository->method('findScheduledBefore')
            ->with($frozenTime)
            ->willReturn([$scheduledPost]);

        $publisher = new ScheduledPostPublisher($repository, $clock);
        $count = $publisher->publishScheduledPosts();

        $this->assertSame(1, $count);
        $this->assertEquals($frozenTime, $scheduledPost->getPublishedAt());
    }
}

Notice what’s happening: the tests don’t depend on the real clock at all. They freeze time at a known moment and assert against that moment. Run them at midnight, noon, or during a leap second – the result is always the same.

Symfony’s Clock Component

If you don’t want to write your own implementations, symfony/clock provides a full PSR-20 package:

composer require symfony/clock

It includes NativeClock (production), MockClock (testing with the ability to advance time), and a Clock::now() static helper. The MockClock is particularly useful because you can advance time during a test to simulate the passage of time without waiting.

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=Clock

See src/Clock/ for the SystemClock and FrozenClock implementations.

Series Wrap-Up

This is the final post in the PHP-FIG Standards series, and what a journey it’s been.

We’ve covered all 14 accepted PSRs – from the foundational coding standards of PSR-1 and PSR-12, through the logging, caching, and dependency injection interfaces, across the entire HTTP stack (PSR-7, PSR-15, PSR-17, PSR-18), and now ending with PSR-20’s elegantly simple approach to testable time.

Each standard solves a specific interoperability problem, but they truly shine when used together. The companion repository ties every PSR into a working blog API – a logger that follows PSR-3, a container that implements PSR-11, HTTP handling with PSR-7/15/17/18, caching with PSR-6/16, events with PSR-14, and time with PSR-20. Clone the repo and experiment with it. Change an implementation, swap a library, write a test. That’s the best way to internalize these standards.

The PHP-FIG standards aren’t just rules to follow – they’re contracts that let your code play well with the entire PHP ecosystem. When you type-hint against ClockInterface instead of calling time(), you’re making a promise: this code is testable, this code is swappable, this code is ready for whatever comes next.

If you’re just discovering this series, start from the beginning and work through each post. If you’ve been following along from PSR-1 to PSR-20 – thank you for sticking with it. Now go build something great.

Resources

Baamaapii 👋

PSR-18: HTTP Client in PHP

Sun, 06 Apr 2025 00:00:00 +0000

Ahnii!

We can define HTTP messages (PSR-7), create them with factories (PSR-17), and handle incoming requests (PSR-15). But what about sending requests to other services? PSR-18 completes the HTTP picture.

Prerequisites: PHP OOP. Required: Read PSR-7 and PSR-17 first. PSR-18 sends PSR-7 requests and receives PSR-7 responses.

What Problem Does PSR-18 Solve? (3 minutes)

Here’s the analogy that ties the HTTP stack together:

PSR-7 is the letter – it defines the shape of the message (headers, body, status code).
PSR-17 is the envelope factory – it creates those messages without coupling you to a specific brand.
PSR-18 is the postal service – it delivers the letter and brings back the reply.

Your code writes a letter and hands it to the postal service. You don’t care if it goes by FedEx (Guzzle), UPS (Symfony HttpClient), or carrier pigeon (cURL wrapper). PSR-18 defines the contract: give me a request, I’ll give you a response.

Without PSR-18, your code calls $guzzle->get('/api/feeds') – tightly coupled to Guzzle. Want to switch to Symfony’s HttpClient? You’d rewrite every HTTP call across your codebase.

With PSR-18, you call $client->sendRequest($request) and the implementation behind it can be anything. One interface, any HTTP library.

Core Interface (5 minutes)

PSR-18 is the simplest PSR you’ll encounter. It defines a single interface with a single method:

php

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

interface ClientInterface
{
    /**
     * Sends a PSR-7 request and returns a PSR-7 response.
     */
    public function sendRequest(RequestInterface $request): ResponseInterface;
}

That’s it. One method. Give it a PSR-7 request, get back a PSR-7 response.

Exception Interfaces

PSR-18 also defines three exception interfaces for when things go wrong:

php

namespace Psr\Http\Client;

// Base exception -- all PSR-18 exceptions extend this
interface ClientExceptionInterface extends \Throwable {}

// The request itself was malformed (bad URI, invalid method, etc.)
interface RequestExceptionInterface extends ClientExceptionInterface
{
    public function getRequest(): RequestInterface;
}

// Couldn't reach the server (DNS failure, connection timeout, etc.)
interface NetworkExceptionInterface extends ClientExceptionInterface
{
    public function getRequest(): RequestInterface;
}

Here’s the key insight that trips people up: PSR-18 does NOT throw exceptions for 4xx or 5xx responses. A 404 Not Found or a 500 Internal Server Error is a perfectly valid HTTP response – the server received your request and replied. Your code should check the status code, not rely on exceptions for error handling.

Exceptions are only thrown when the request can’t be sent at all – a malformed URI, a DNS failure, a connection timeout. These are transport-level failures, not application-level errors.

Real-World Implementation (10 minutes)

Let’s build something practical: an RssFeedFetcher that pulls external RSS feeds for the blog. This is a real use case – aggregating content from other sites.

The Decoupled Fetcher

php

namespace App\Blog;

use Psr\Http\Client\ClientInterface;
use Psr\Http\Client\NetworkExceptionInterface;
use Psr\Http\Message\RequestFactoryInterface;

class RssFeedFetcher
{
    public function __construct(
        private ClientInterface $client,
        private RequestFactoryInterface $requestFactory,
    ) {}

    /**
     * Fetches and parses an RSS feed from the given URL.
     *
     * @return array
     */
    public function fetch(string $feedUrl): array
    {
        $request = $this->requestFactory->createRequest('GET', $feedUrl);

        try {
            $response = $this->client->sendRequest($request);
        } catch (NetworkExceptionInterface $e) {
            throw new \RuntimeException(
                "Could not reach feed at {$feedUrl}: {$e->getMessage()}"
            );
        }

        if ($response->getStatusCode() !== 200) {
            throw new \RuntimeException(
                "Feed returned HTTP {$response->getStatusCode()}"
            );
        }

        return $this->parseFeed($response->getBody()->getContents());
    }

    /**
     * @return array
     */
    private function parseFeed(string $xml): array
    {
        $feed = new \SimpleXMLElement($xml);
        $items = [];

        foreach ($feed->channel->item as $item) {
            $items[] = [
                'title'   => (string) $item->title,
                'link'    => (string) $item->link,
                'pubDate' => (string) $item->pubDate,
            ];
        }

        return $items;
    }
}

Notice what this class depends on: ClientInterface and RequestFactoryInterface – both PSR interfaces. It knows nothing about Guzzle, Symfony, or cURL.

Swapping Implementations

Here’s the power of PSR-18. The same RssFeedFetcher works with any compliant HTTP client:

php

// With Guzzle (implements PSR-18 natively since v7)
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$fetcher = new RssFeedFetcher(
    new Client(),
    new HttpFactory()
);

// With Symfony HttpClient (via PSR-18 adapter)
use Symfony\Component\HttpClient\Psr18Client;

$fetcher = new RssFeedFetcher(
    new Psr18Client(),
    new Psr18Client() // Psr18Client also implements RequestFactoryInterface
);

Same RssFeedFetcher, different postal services. Zero code changes inside the class.

Testing with a Mock Client

PSR-18 makes testing trivial. Create a mock client that returns predetermined responses:

php

use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

class MockHttpClient implements ClientInterface
{
    public function __construct(
        private ResponseInterface $response
    ) {}

    public function sendRequest(RequestInterface $request): ResponseInterface
    {
        return $this->response;
    }
}

Now test the fetcher without making any real HTTP calls:

php

use Nyholm\Psr7\Factory\Psr17Factory;

class RssFeedFetcherTest extends TestCase
{
    public function testFetchParsesRssItems(): void
    {
        $factory = new Psr17Factory();

        $xml = <<<XML
        
        
            
                Test Post
                https://example.com/test
                Mon, 01 Jan 2024 00:00:00 GMT
            
        
        XML;

        $mockResponse = $factory->createResponse(200)
            ->withBody($factory->createStream($xml));

        $fetcher = new RssFeedFetcher(
            new MockHttpClient($mockResponse),
            $factory
        );

        $items = $fetcher->fetch('https://example.com/feed.xml');

        $this->assertCount(1, $items);
        $this->assertEquals('Test Post', $items[0]['title']);
    }

    public function testFetchThrowsOnServerError(): void
    {
        $factory = new Psr17Factory();

        $mockResponse = $factory->createResponse(500);

        $fetcher = new RssFeedFetcher(
            new MockHttpClient($mockResponse),
            $factory
        );

        $this->expectException(\RuntimeException::class);
        $this->expectExceptionMessage('Feed returned HTTP 500');

        $fetcher->fetch('https://example.com/feed.xml');
    }
}

No HTTP mocking libraries needed. No spinning up fake servers. Just inject a different implementation – that’s the whole point of coding to interfaces.

Common Mistakes and Fixes

1. Catching \Exception Instead of PSR-18 Exceptions

PSR-18 defines specific exception types for a reason. Use them to handle failures appropriately.

// Bad -- catches everything, can't distinguish failure types
try {
    $response = $client->sendRequest($request);
} catch (\Exception $e) {
    echo "Something went wrong";
}

// Good -- handle each failure type differently
try {
    $response = $client->sendRequest($request);
} catch (NetworkExceptionInterface $e) {
    // Server unreachable -- retry or use cached data
    $this->logger->warning("Network error: {$e->getMessage()}");
    return $this->getCachedResponse($request);
} catch (RequestExceptionInterface $e) {
    // Request itself is broken -- fix it, don't retry
    throw new \InvalidArgumentException("Bad request: {$e->getMessage()}");
}

2. Not Using PSR-17 to Create Requests

If you’re using PSR-18 but creating requests with concrete classes, you’ve decoupled the delivery but not the envelope. Half-decoupled code is still coupled code.

// Bad -- coupled to Guzzle's Request class
use GuzzleHttp\Psr7\Request;

$request = new Request('GET', 'https://api.example.com/data');
$response = $client->sendRequest($request);

// Good -- use PSR-17 factory for full decoupling
$request = $this->requestFactory->createRequest('GET', 'https://api.example.com/data');
$response = $client->sendRequest($request);

3. Ignoring Response Status Codes

PSR-18 doesn’t throw on 4xx/5xx. Assuming sendRequest() returned successfully means “200 OK” is a common bug.

// Bad -- assumes success means 200
$response = $client->sendRequest($request);
$data = json_decode($response->getBody()->getContents(), true);
// What if the response was a 404 with an HTML error page?

// Good -- always check the status code
$response = $client->sendRequest($request);

if ($response->getStatusCode() >= 400) {
    throw new \RuntimeException(
        "API returned HTTP {$response->getStatusCode()}"
    );
}

$data = json_decode($response->getBody()->getContents(), true);

Framework Integration

Guzzle

Guzzle implements PSR-18 natively since version 7. The Client class implements ClientInterface out of the box – no adapters needed:

use GuzzleHttp\Client;

$client = new Client(['timeout' => 5]);
// $client is a PSR-18 ClientInterface -- use it directly
$response = $client->sendRequest($request);

Symfony HttpClient

Symfony provides the Psr18Client adapter that wraps Symfony’s native HttpClient with a PSR-18 interface:

use Symfony\Component\HttpClient\Psr18Client;

$client = new Psr18Client();
// Also implements RequestFactoryInterface, StreamFactoryInterface
$response = $client->sendRequest($request);

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR18

See src/Http/Client/ for the HTTP client implementation and src/Blog/RssFeedFetcher.php for a practical example.

What’s Next

We’ve completed the HTTP stack! Next: PSR-6: Caching Interface – making your application faster with standardized caching.

Resources

Baamaapii 👋

PSR-17: HTTP Factories in PHP

Sun, 23 Mar 2025 00:00:00 +0000

Ahnii!

We’ve seen how PSR-7 defines what HTTP messages look like. But how do you create them without tying your code to a specific library? That’s where PSR-17 comes in.

Prerequisites: PHP OOP. Required: Read PSR-7 first – PSR-17 creates the objects PSR-7 defines.

What Problem Does PSR-17 Solve? (3 minutes)

PSR-7 defines what a “car” is – the interfaces: wheels, engine, steering. PSR-17 is the factory that builds them.

Without factories, your code must say new GuzzleHttp\Psr7\Request('GET', '/posts') – coupling you directly to Guzzle. What if you want to switch to Laminas Diactoros? You’d need to find and replace every new GuzzleHttp\Psr7\... call across your entire codebase.

And what about testing? How do you create a fake request without pulling in a full HTTP library?

With PSR-17 factories, you say $factory->createRequest('GET', '/posts') and the factory decides which implementation to use. Your code stays portable. Swap the factory, and every object it creates changes with it – no other code needs to change.

Core Interfaces (5 minutes)

PSR-17 defines six factory interfaces, one for each type of PSR-7 object. Let’s walk through them.

RequestFactoryInterface

php

namespace Psr\Http\Message;

interface RequestFactoryInterface
{
    public function createRequest(string $method, $uri): RequestInterface;
}

Creates outgoing HTTP requests. The $uri parameter accepts either a string or a UriInterface instance.

ResponseFactoryInterface

php

namespace Psr\Http\Message;

interface ResponseFactoryInterface
{
    public function createResponse(int $code = 200, string $reasonPhrase = ''): ResponseInterface;
}

Creates HTTP responses. The reason phrase defaults to the standard one for the given status code (e.g., “OK” for 200, “Not Found” for 404).

ServerRequestFactoryInterface

php

namespace Psr\Http\Message;

interface ServerRequestFactoryInterface
{
    public function createServerRequest(
        string $method,
        $uri,
        array $serverParams = []
    ): ServerRequestInterface;
}

Creates server-side requests – the kind your application receives from a web server. The $serverParams array maps to $_SERVER.

StreamFactoryInterface

php

namespace Psr\Http\Message;

interface StreamFactoryInterface
{
    public function createStream(string $content = ''): StreamInterface;
    public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface;
    public function createStreamFromResource($resource): StreamInterface;
}

Three ways to create a stream: from a string, from a file path, or from an existing PHP resource. You’ll use createStream() most often for JSON response bodies.

UploadedFileFactoryInterface

php

namespace Psr\Http\Message;

interface UploadedFileFactoryInterface
{
    public function createUploadedFile(
        StreamInterface $stream,
        ?int $size = null,
        int $error = UPLOAD_ERR_OK,
        ?string $clientFilename = null,
        ?string $clientMediaType = null
    ): UploadedFileInterface;
}

Creates uploaded file representations. Useful for testing file upload handlers without actual file uploads.

UriFactoryInterface

php

namespace Psr\Http\Message;

interface UriFactoryInterface
{
    public function createUri(string $uri = ''): UriInterface;
}

Creates URI objects from strings. The factory parses the URI and gives you a structured object with methods like getHost(), getPath(), and getQuery().

Which Ones Matter Most?

The two you’ll use most are RequestFactoryInterface and ResponseFactoryInterface – they cover the vast majority of use cases. StreamFactoryInterface comes up when you need to set response bodies. The others are for specialized cases like testing file uploads or building URIs programmatically.

Real-World Implementation (10 minutes)

Let’s see the difference factories make in a blog API handler.

The Coupled Version (Bad)

php

use GuzzleHttp\Psr7\Response;

class BlogPostHandler
{
    public function handle($request): Response
    {
        $posts = $this->fetchPosts();
        $json = json_encode($posts);

        // Coupled to Guzzle's concrete Response class
        return new Response(
            200,
            ['Content-Type' => 'application/json'],
            $json
        );
    }
}

This works, but you’ve hardcoded GuzzleHttp\Psr7\Response into your handler. Want to switch to Nyholm or Laminas? You need to change this class and every other class that creates HTTP objects.

The Decoupled Version (Good)

php

use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamFactoryInterface;

class BlogPostHandler
{
    public function __construct(
        private ResponseFactoryInterface $responseFactory,
        private StreamFactoryInterface $streamFactory,
    ) {}

    public function handle($request): ResponseInterface
    {
        $posts = $this->fetchPosts();
        $body = $this->streamFactory->createStream(json_encode($posts));

        return $this->responseFactory->createResponse(200)
            ->withHeader('Content-Type', 'application/json')
            ->withBody($body);
    }
}

Now the handler depends only on interfaces. The concrete implementation is injected at construction time – the handler doesn’t care whether it’s Guzzle, Nyholm, or Laminas under the hood.

Testing Becomes Trivial

php

use Nyholm\Psr7\Factory\Psr17Factory;

class BlogPostHandlerTest extends TestCase
{
    public function testReturnsJsonResponse(): void
    {
        // Nyholm provides a single class that implements all 6 factory interfaces
        $factory = new Psr17Factory();

        $handler = new BlogPostHandler($factory, $factory);
        $response = $handler->handle($factory->createServerRequest('GET', '/posts'));

        $this->assertEquals(200, $response->getStatusCode());
        $this->assertEquals('application/json', $response->getHeaderLine('Content-Type'));
    }
}

Swap the factory, and the entire implementation changes. No mocking needed for the HTTP layer – just inject a different factory.

Common Mistakes and Fixes

1. Newing Up PSR-7 Objects Directly

If your application code contains new Response(...) or new Request(...), you’ve bypassed the factory pattern and re-introduced coupling.

// Bad -- coupled to a specific implementation
use GuzzleHttp\Psr7\Response;

$response = new Response(200, [], 'Hello');

// Good -- use the injected factory
$response = $this->responseFactory->createResponse(200);
$body = $this->streamFactory->createStream('Hello');
$response = $response->withBody($body);

2. Not Type-Hinting Factory Interfaces

Accepting a concrete factory class defeats the purpose. Always type-hint the PSR-17 interface.

// Bad -- tied to Guzzle's factory
use GuzzleHttp\Psr7\HttpFactory;

public function __construct(HttpFactory $factory) {}

// Good -- any PSR-17 compliant factory works
use Psr\Http\Message\ResponseFactoryInterface;

public function __construct(ResponseFactoryInterface $responseFactory) {}

Framework Integration

Slim 4

Slim 4 uses PSR-17 natively. When you create a Slim app, it auto-discovers available PSR-17 factories from your installed packages:

php

use Slim\Factory\AppFactory;

// Slim auto-discovers PSR-17 factories from installed packages
// (e.g., nyholm/psr7, slim/psr7, or guzzlehttp/psr7)
$app = AppFactory::create();

$app->get('/posts', function ($request, $response) {
    $response->getBody()->write(json_encode(['title' => 'Hello']));
    return $response->withHeader('Content-Type', 'application/json');
});

$app->run();

You can also set a specific factory explicitly:

use Nyholm\Psr7\Factory\Psr17Factory;

AppFactory::setResponseFactory(new Psr17Factory());
$app = AppFactory::create();

Laminas Diactoros

Laminas Diactoros provides all six factory implementations out of the box:

php

use Laminas\Diactoros\RequestFactory;
use Laminas\Diactoros\ResponseFactory;
use Laminas\Diactoros\ServerRequestFactory;
use Laminas\Diactoros\StreamFactory;
use Laminas\Diactoros\UploadedFileFactory;
use Laminas\Diactoros\UriFactory;

// Each factory implements its corresponding PSR-17 interface
$responseFactory = new ResponseFactory();
$response = $responseFactory->createResponse(200, 'OK');

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR17

See src/Http/Factory/ for the factory implementations used in the blog API.

What’s Next

Now that we can create requests and responses, let’s process them: PSR-15: HTTP Handlers and Middleware – building a middleware pipeline.

Resources

Baamaapii 👋

PSR-16: Simple Cache in PHP

Sun, 16 Mar 2025 00:00:00 +0000

Ahnii!

Remember PSR-6’s cache pools and cache items? Sometimes that’s more machinery than you need. PSR-16 is the simpler alternative.

This post is part of our PSR Standards in PHP series.

Prerequisites: PHP OOP. Recommended: Read PSR-6 first for comparison.

What Problem Does PSR-16 Solve? (3 minutes)

PSR-6 is a full warehouse management system. You get items, check if they’re hits, set values, then save them back to the pool. That’s five lines of code just to cache a single value. Sometimes you just need a shelf: put something on it, take something off.

PSR-16 is that shelf — a simple get/set key-value interface for when PSR-6’s ceremony is overkill.

Both standards are valid. PSR-6 gives you fine-grained control with item metadata, deferred saves, and pool management. PSR-16 is for the common case where you just need basic caching without the extra layers.

Core Interface (5 minutes)

PSR-16 defines a single CacheInterface with eight methods. That’s it — no pools, no items, no wrappers:

php

namespace Psr\SimpleCache;

interface CacheInterface
{
    // Returns the cached value, or $default on a miss — no exceptions for misses!
    public function get(string $key, mixed $default = null): mixed;

    // Stores a value under $key, with an optional TTL in seconds (or DateInterval)
    public function set(string $key, mixed $value, null|int|\DateInterval $ttl = null): bool;

    // Removes a single cached item by key
    public function delete(string $key): bool;

    // Wipes the entire cache — use with care
    public function clear(): bool;

    // Batch get: returns an iterable of key => value pairs, using $default for misses
    public function getMultiple(iterable $keys, mixed $default = null): iterable;

    // Batch set: $values is an iterable of key => value pairs, all with the same TTL
    public function setMultiple(iterable $values, null|int|\DateInterval $ttl = null): bool;

    // Batch delete: removes multiple items at once
    public function deleteMultiple(iterable $keys): bool;

    // Checks if a key exists — but prefer get() with a default instead!
    public function has(string $key): bool;
}

Notice how every method either returns the cached value directly or a simple bool. No intermediate objects, no two-step save process. Call get(), get your data. Call set(), you’re done.

PSR-6 vs PSR-16: Which Should You Use? (3 minutes)

The best way to see the difference is to compare the same operation side by side. Let’s cache a user object.

PSR-6 — cache a user:

php

// PSR-6: Five steps to cache one value
$item = $pool->getItem('user.1');
if (!$item->isHit()) {
    $item->set($user);
    $item->expiresAfter(3600);
    $pool->save($item);
}
$user = $item->get();

PSR-16 — cache a user:

php

// PSR-16: One line to cache, one line to retrieve
$cache->set('user.1', $user, 3600);
$user = $cache->get('user.1');

That’s the core trade-off. PSR-6 gives you an item object you can inspect and manipulate. PSR-16 gives you direct access.

Decision Table

Scenario	PSR-16	PSR-6
Simple key-value storage	Yes	Overkill
Small to medium apps	Yes	Yes
Need item metadata (hit/miss status, expiry info)	No	Yes
Deferred/batched saves	No	Yes
Cache tags or complex invalidation	No	Yes
Minimal API surface, quick integration	Yes	No
Direct cache access without pooling	Yes	No

Rule of thumb: Start with PSR-16. Move to PSR-6 when you need the extra control.

Real-World Implementation (10 minutes)

Let’s build a practical FileCache that implements CacheInterface. This stores each cached value as a serialized file on disk:

php

namespace App\Cache;

use Psr\SimpleCache\CacheInterface;

class FileCache implements CacheInterface
{
    private string $cacheDir;

    public function __construct(string $cacheDir)
    {
        if (!is_dir($cacheDir)) {
            mkdir($cacheDir, 0775, true);
        }
        $this->cacheDir = rtrim($cacheDir, '/');
    }

    public function get(string $key, mixed $default = null): mixed
    {
        $path = $this->path($key);

        if (!file_exists($path)) {
            return $default;
        }

        $data = unserialize(file_get_contents($path));

        // Check if the entry has expired
        if ($data['expiry'] !== null && $data['expiry'] < time()) {
            $this->delete($key);
            return $default;
        }

        return $data['value'];
    }

    public function set(string $key, mixed $value, null|int|\DateInterval $ttl = null): bool
    {
        $expiry = null;
        if ($ttl instanceof \DateInterval) {
            $expiry = (new \DateTime())->add($ttl)->getTimestamp();
        } elseif (is_int($ttl)) {
            $expiry = time() + $ttl;
        }

        $data = serialize(['value' => $value, 'expiry' => $expiry]);
        return file_put_contents($this->path($key), $data) !== false;
    }

    public function delete(string $key): bool
    {
        $path = $this->path($key);
        return file_exists($path) && unlink($path);
    }

    public function clear(): bool
    {
        $files = glob($this->cacheDir . '/*.cache');
        foreach ($files as $file) {
            unlink($file);
        }
        return true;
    }

    public function has(string $key): bool
    {
        return $this->get($key, $this) !== $this;
    }

    public function getMultiple(iterable $keys, mixed $default = null): iterable
    {
        $results = [];
        foreach ($keys as $key) {
            $results[$key] = $this->get($key, $default);
        }
        return $results;
    }

    public function setMultiple(iterable $values, null|int|\DateInterval $ttl = null): bool
    {
        $success = true;
        foreach ($values as $key => $value) {
            if (!$this->set($key, $value, $ttl)) {
                $success = false;
            }
        }
        return $success;
    }

    public function deleteMultiple(iterable $keys): bool
    {
        $success = true;
        foreach ($keys as $key) {
            if (!$this->delete($key)) {
                $success = false;
            }
        }
        return $success;
    }

    private function path(string $key): string
    {
        return $this->cacheDir . '/' . md5($key) . '.cache';
    }
}

Using It With the Blog API

php

$cache = new FileCache('/tmp/blog-cache');

// Cache a blog post for 1 hour
$post = $database->fetchPost($slug);
$cache->set("post.{$slug}", $post, 3600);

// Retrieve it later — returns null if expired
$post = $cache->get("post.{$slug}");

// Cache configuration values with no expiry
$cache->set('config.site_name', 'My Blog');
$cache->set('config.posts_per_page', 10);

// Batch operations — cache multiple posts at once
$posts = $database->fetchRecentPosts(5);
$cacheEntries = [];
foreach ($posts as $post) {
    $cacheEntries["post.{$post['slug']}"] = $post;
}
$cache->setMultiple($cacheEntries, 3600);

// Retrieve multiple posts in one call
$cached = $cache->getMultiple(['post.first-post', 'post.second-post']);
foreach ($cached as $key => $post) {
    if ($post !== null) {
        echo $post['title'] . "\n";
    }
}

Common Mistakes and Fixes

1. Using `has()` Then `get()` (Race Condition)

Between checking and getting, the cache entry could expire. This is a classic time-of-check to time-of-use bug:

php

// Bad — race condition between has() and get()
if ($cache->has('key')) {
    $value = $cache->get('key'); // Could be null if expired between calls!
}

// Good — use get() with a meaningful default
$value = $cache->get('key', false);
if ($value !== false) {
    // Cache hit — use $value
}

// Also good — just use get() and check for null
$value = $cache->get('user.profile');
if ($value !== null) {
    // Cache hit
}

2. Storing Non-Serializable Values

Closures, database connections, and file handles can’t be serialized. Trying to cache them will fail silently or throw errors:

php

// Bad — closures can't be serialized
$cache->set('callback', function() { return 'hello'; });

// Bad — resource handles can't be cached
$cache->set('db', $pdoConnection);

// Good — cache the data, not the objects that produce it
$cache->set('query.result', $pdoConnection->query($sql)->fetchAll());

// Good — cache serializable DTOs or arrays
$cache->set('user.1', [
    'id' => 1,
    'name' => 'Russell',
    'email' => 'russell@example.com',
]);

3. Key Naming Collisions

Without namespacing, user.1 in one part of your app could clash with user.1 in another:

php

// Bad — ambiguous keys that could collide
$cache->set('user.1', $userData);    // Is this from auth? profiles? admin?
$cache->set('user.1', $permissions); // Overwrites the previous value!

// Good — prefix keys with a namespace
$cache->set('profiles.user.1', $userData);
$cache->set('auth.user.1', $permissions);

// Even better — use a helper to enforce consistent prefixes
function cacheKey(string $namespace, string $key): string
{
    return "{$namespace}.{$key}";
}

$cache->set(cacheKey('profiles', 'user.1'), $userData);
$cache->set(cacheKey('auth', 'user.1'), $permissions);

Framework Integration

Laravel

Laravel’s Cache facade uses a PSR-16-like API — the method names will feel instantly familiar:

php

use Illuminate\Support\Facades\Cache;

// Store a value for 1 hour (seconds)
Cache::put('user.1', $user, 3600);

// Retrieve with a default
$user = Cache::get('user.1', null);

// Remember pattern — fetch from cache or compute and store
$user = Cache::remember('user.1', 3600, function () {
    return User::find(1);
});

Symfony

Symfony provides a Psr16Cache adapter that wraps any PSR-6 pool as a PSR-16 interface:

php

use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

// Wrap a PSR-6 adapter as PSR-16
$psr6Cache = new FilesystemAdapter();
$cache = new Psr16Cache($psr6Cache);

// Now use the simple PSR-16 API
$cache->set('user.1', $user, 3600);
$user = $cache->get('user.1');

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR16

See src/Cache/SimpleCache/ for the blog API’s simple cache implementation.

What’s Next?

Next: PSR-13: Hypermedia Links — making your REST APIs self-documenting with standardized link relations.

Baamaapii 👋

PSR-15: HTTP Handlers and Middleware in PHP

Sun, 02 Mar 2025 00:00:00 +0000

Ahnii!

We’ve seen how PSR-7 defines HTTP messages and PSR-17 creates them. Now, how do we actually process a request and produce a response? That’s PSR-15.

Prerequisites: PHP OOP. Required: Read PSR-7 first – PSR-15 builds directly on it.

What Problem Does PSR-15 Solve? (3 minutes)

Think of your HTTP request as a traveler going through an airport. Each checkpoint (middleware) can inspect your boarding pass (headers), check your luggage (body), add a stamp to your passport (modify the request), or turn you away entirely (return an error response). The final gate (the handler) is your destination – it’s where the actual work happens and you get your response.

Without a standard, every framework’s middleware is incompatible. Middleware written for Slim can’t be used in Laravel. Middleware from Mezzio won’t work in Symfony. PSR-15 fixes this by defining two simple interfaces that every framework can agree on.

The result? You can write an authentication middleware once and use it in any PSR-15 compliant application. Just like PSR-7 gave us a standard “shape” for HTTP messages, PSR-15 gives us a standard “shape” for processing them.

Core Interfaces (5 minutes)

PSR-15 defines just two interfaces. That’s it – two interfaces that power every middleware pipeline.

RequestHandlerInterface

php

namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

interface RequestHandlerInterface
{
    /**
     * Handles a request and produces a response.
     */
    public function handle(ServerRequestInterface $request): ResponseInterface;
}

This is the final destination. A handler takes a request and returns a response – no delegation, no chain. Think of it as the gate at the end of the airport.

MiddlewareInterface

php

namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

interface MiddlewareInterface
{
    /**
     * Process a request and delegate to the next handler.
     */
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

Here’s the key insight: middleware receives both the request AND the next handler in the chain. This means middleware can:

Modify the request before passing it along
Call the next handler with $handler->handle($request) to continue the chain
Modify the response that comes back
Short-circuit by returning a response without calling the handler at all

That $handler->handle($request) call is the delegation pattern – it passes control to the next layer in the pipeline.

Real-World Implementation (10 minutes)

Let’s build a middleware pipeline for a blog API. We’ll create four middleware/handler classes, then wire them into a pipeline.

LoggingMiddleware

php

namespace App\Http\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Log\LoggerInterface;

class LoggingMiddleware implements MiddlewareInterface
{
    public function __construct(
        private LoggerInterface $logger
    ) {}

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // Log the incoming request
        $this->logger->info('Request', [
            'method' => $request->getMethod(),
            'uri'    => (string) $request->getUri(),
        ]);

        // Delegate to the next handler
        $response = $handler->handle($request);

        // Log the outgoing response
        $this->logger->info('Response', [
            'status' => $response->getStatusCode(),
        ]);

        return $response;
    }
}

Notice how we log before and after delegating. The request flows in, passes through to the next layer, and the response bubbles back up.

AuthMiddleware

php

namespace App\Http\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Nyholm\Psr7\Response;

class AuthMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        $token = $request->getHeaderLine('Authorization');

        if (empty($token) || !$this->validateToken($token)) {
            // Short-circuit -- return 401 without calling the handler
            return new Response(
                401,
                ['Content-Type' => 'application/json'],
                json_encode(['error' => 'Unauthorized'])
            );
        }

        // Token is valid -- attach user data to the request
        $request = $request->withAttribute('user', $this->getUserFromToken($token));

        return $handler->handle($request);
    }

    private function validateToken(string $token): bool
    {
        return str_starts_with($token, 'Bearer ') && strlen($token) > 10;
    }

    private function getUserFromToken(string $token): array
    {
        return ['id' => 1, 'name' => 'Blog Author'];
    }
}

If the token is missing or invalid, the pipeline stops right here – no further middleware or handler runs. If the token is valid, the middleware attaches user data to the request using withAttribute() so downstream code can access it.

CorsMiddleware

php

namespace App\Http\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class CorsMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // Delegate first, then modify the response
        $response = $handler->handle($request);

        return $response
            ->withHeader('Access-Control-Allow-Origin', '*')
            ->withHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')
            ->withHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    }
}

CORS middleware modifies the response, so it delegates first and then adds the headers on the way back out.

BlogPostHandler

php

namespace App\Http\Handler;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Nyholm\Psr7\Response;

class BlogPostHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        // Access user data set by AuthMiddleware
        $user = $request->getAttribute('user');

        $posts = [
            ['id' => 1, 'title' => 'Getting Started with PSR-15', 'author' => $user['name']],
            ['id' => 2, 'title' => 'Middleware Pipelines in PHP', 'author' => $user['name']],
        ];

        return new Response(
            200,
            ['Content-Type' => 'application/json'],
            json_encode($posts)
        );
    }
}

This is the final destination – no delegation, just produce a response.

MiddlewarePipeline

php

namespace App\Http;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class MiddlewarePipeline implements RequestHandlerInterface
{
    /** @var MiddlewareInterface[] */
    private array $middleware;
    private int $index = 0;

    public function __construct(
        array $middleware,
        private RequestHandlerInterface $handler
    ) {
        $this->middleware = $middleware;
    }

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        // If we've run through all middleware, call the final handler
        if ($this->index >= count($this->middleware)) {
            return $this->handler->handle($request);
        }

        // Get the next middleware and advance the index
        $next = $this->middleware[$this->index];
        $this->index++;

        // Process the middleware, passing $this as the next handler
        return $next->process($request, $this);
    }
}

Wiring It All Together

php

use App\Http\MiddlewarePipeline;
use App\Http\Middleware\{LoggingMiddleware, AuthMiddleware, CorsMiddleware};
use App\Http\Handler\BlogPostHandler;

$pipeline = new MiddlewarePipeline(
    [new LoggingMiddleware($logger), new AuthMiddleware(), new CorsMiddleware()],
    new BlogPostHandler()
);

$response = $pipeline->handle($serverRequest);

Here’s how a request flows through the pipeline:

Request → Logging → Auth → CORS → BlogPostHandler
                                        ↓
Response ← Logging ← Auth ← CORS ← Response

Each middleware wraps the next layer. Logging sees the request first and the response last. Auth can stop the chain entirely. CORS adds headers on the way out.

Common Mistakes and Fixes

1. Forgetting to Call `$handler->handle()`

If middleware doesn’t delegate, the chain breaks and no downstream middleware or handler ever runs.

// Bad -- returns a response without delegating
public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler
): ResponseInterface {
    return new Response(200, [], 'Handled!');
}

// Good -- delegates, then modifies the response
public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler
): ResponseInterface {
    $response = $handler->handle($request);
    return $response->withHeader('X-Custom', 'value');
}

2. Modifying Request State Directly

Don’t use globals or superglobals to pass data between middleware. Use the request’s attributes instead.

// Bad -- storing data in globals
public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler
): ResponseInterface {
    $_SESSION['user'] = $this->getUser($request);
    return $handler->handle($request);
}

// Good -- using request attributes
public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler
): ResponseInterface {
    $user = $this->getUser($request);
    $request = $request->withAttribute('user', $user);
    return $handler->handle($request);
}

3. Doing Too Much in One Middleware

Each middleware should have one job. If your middleware is handling auth, logging, AND CORS, split it up.

// Bad -- one middleware doing three jobs
class KitchenSinkMiddleware implements MiddlewareInterface
{
    public function process($request, $handler): ResponseInterface
    {
        $this->logger->info($request->getMethod()); // logging
        if (!$this->checkAuth($request)) { return new Response(401); } // auth
        $response = $handler->handle($request);
        return $response->withHeader('Access-Control-Allow-Origin', '*'); // CORS
    }
}

// Good -- three focused middleware classes
$pipeline = new MiddlewarePipeline(
    [new LoggingMiddleware($logger), new AuthMiddleware(), new CorsMiddleware()],
    new BlogPostHandler()
);

Framework Integration

Laravel

Laravel middleware uses the same concept but its own interface. PSR-15 packages work via a bridge:

php artisan make:middleware CheckAge

// Laravel's middleware signature (not PSR-15, but same pattern)
public function handle(Request $request, Closure $next): Response
{
    if ($request->age < 18) {
        return redirect('home');
    }
    return $next($request);
}

Slim

Slim is built on PSR-15 natively – any PSR-15 middleware works out of the box:

$app->add(new LoggingMiddleware($logger));
$app->add(new AuthMiddleware());
$app->add(new CorsMiddleware());

Mezzio (Laminas)

Mezzio provides a full PSR-15 pipeline with declarative configuration:

$app->pipe(LoggingMiddleware::class);
$app->pipe(AuthMiddleware::class);
$app->pipe(CorsMiddleware::class);
$app->pipe(BlogPostHandler::class);

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR15

See src/Http/Middleware/ for the blog API’s middleware stack.

What’s Next

Next up: PSR-18: HTTP Client – how to send HTTP requests the standard way, completing our HTTP stack.

Resources

Baamaapii 👋

PSR-13: Hypermedia Links in PHP

Mon, 24 Feb 2025 00:00:00 +0000

Ahnii!

Prerequisites: PHP OOP, REST API basics. Recommended: Read PSR-7 first.

What Problem Does PSR-13 Solve? (3 minutes)

Have you ever used a website where you had to manually construct URLs to navigate? Neither have your API consumers — they shouldn’t have to either. PSR-13 lets your API tell clients “here’s where to go next,” like how a website has navigation links.

This is the heart of HATEOAS (Hypermedia as the Engine of Application State) — a REST principle where API responses include links to related actions and resources. Instead of hardcoding /api/users/123/posts in your frontend, the API response itself says “here’s the link to this user’s posts.”

When Would You Actually Use This?

Pagination: Include next, prev, first, last links in list responses
Related resources: A blog post response includes links to its author, comments, and category
Available actions: A draft post includes a publish link; a published post includes unpublish

Today we’ll explore PSR-13, which defines interfaces for creating and managing hypermedia links in PHP applications. This standard is particularly useful for building REST APIs that follow HATEOAS (Hypermedia as the Engine of Application State) principles, enabling self-documenting and discoverable APIs.

Core Interfaces (5 minutes)

PSR-13 defines three main interfaces that work together to create a flexible hypermedia linking system.

1. LinkInterface

php

namespace Psr\Link;

interface LinkInterface
{
    public function getHref();
    public function isTemplated();
    public function getRels();
    public function getAttributes();
}

2. EvolvableLinkInterface

php

namespace Psr\Link;

interface EvolvableLinkInterface extends LinkInterface
{
    public function withHref($href);
    public function withRel($rel);
    public function withoutRel($rel);
    public function withAttribute($attribute, $value);
    public function withoutAttribute($attribute);
}

3. LinkProviderInterface

php

namespace Psr\Link;

interface LinkProviderInterface
{
    public function getLinks();
    public function getLinksByRel($rel);
}

Usage Examples (15 minutes)

1. Basic Link Creation

php

// Create a simple link to a user profile
$link = new HypermediaLink('/users/123')
    ->withRel('self')
    ->withAttribute('title', 'User Profile');

// Create a templated link for user resources
$link = new HypermediaLink('/users/{id}')
    ->withRel('user')
    ->withAttribute('templated', true);

// Create a link collection and add links to it
$provider = new HypermediaLinkProvider();
$provider->addLink($link);

2. REST API Implementation

php

class UserController
{
    public function show($id): array
    {
        $user = $this->repository->find($id);
        $links = new HypermediaLinkProvider();
        
        // Add self-referential link
        $links->addLink(
            (new HypermediaLink("/users/$id"))
                ->withRel('self')
        );
        
        // Add link to related posts
        $links->addLink(
            (new HypermediaLink("/users/$id/posts"))
                ->withRel('posts')
        );
        
        return [
            'data' => $user,
            '_links' => $this->serializeLinks($links)
        ];
    }
}

Best Practices

1. Link Relations

// Bad - Using arbitrary relation names
$link->withRel('get-user-stuff');

// Good - Using standard IANA relations
$link->withRel('self')
     ->withRel('next')
     ->withRel('prev');

2. Template Parameters

// Bad - Hardcoded IDs in URLs
$link = new HypermediaLink("/users/123/posts");

// Good - Templated links
$link = (new HypermediaLink("/users/{id}/posts"))
    ->withTemplated(true);

Next Steps (5 minutes)

In our next article, we’ll explore PSR-14, which defines interfaces for event handling in PHP applications.

Framework Integration

Symfony

Symfony’s WebLink component implements PSR-13 for HTTP/2 server push and preloading:

php

use Symfony\Component\WebLink\Link;

// Add a preload link for a CSS file
$link = (new Link('preload', '/styles/app.css'))
    ->withAttribute('as', 'style');

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR13

See src/Link/ for how the blog API adds hypermedia links to post responses.

Resources (5 minutes)

Baamaapii 👋

How We Got DDEV, Laravel, and a Go API Talking: The Sidecar Approach

Tue, 18 Feb 2025 00:00:00 +0000

Ahnii!

Our stack splits responsibilities: Laravel (DDEV) handles auth and the UI; a Go service serves the API. We needed the Laravel app inside DDEV to call the Go API reliably. Here’s how we did it.

The Problem

Laravel runs in a DDEV web container.
Go was either on the host or in its own Docker Compose.
From inside the web container, localhost:8090 points at the container itself, not the host.
Using host.docker.internal:8090 led to timeouts (routing/WSL2) or required the Go app to listen on 0.0.0.0.
When we did get a response, we often saw 401 Unauthorized: the shared secret for signed requests didn’t match between Laravel and Go.

We wanted one predictable setup: Laravel and Go on the same network, with a single place to configure the shared secret.

The Solution: Go as a DDEV Sidecar

We added the Go service (and its Postgres) as custom Docker Compose services in DDEV so they share the same Docker network as the web container and can talk by service name.

Custom compose file
Add a file like .ddev/docker-compose.go-api.yaml that defines:
- go-api-db: Postgres for the Go app (data in a named volume).
- go-api: Builds from your Go repo (e.g. a sibling directory), mounts it for live reload if you use something like air. It depends on go-api-db and uses APP_HOST=0.0.0.0 so the app is reachable on the network.
- web: Extend the web service to set your API URL, e.g. API_URL=http://go-api:8090, so Laravel always targets the sidecar.
Paths
Compose paths are relative to the compose file. If the file lives in .ddev/ and your Go repo is a sibling of the Laravel project, use ../../your-go-project for build context and volume mount.
Shared secret
Both sides must use the same value for signed requests (e.g. X-Signature). In the Go service, set something like SHARED_SECRET: ${SHARED_SECRET:-ddev-sidecar-secret} so the container always has a non-empty default. In Laravel’s .env, set the same value (e.g. SHARED_SECRET=ddev-sidecar-secret) so Laravel signs with the same secret.
Healthcheck
Give the Go service a healthcheck that hits something like /health with a long start_period so DDEV waits for the first build before considering the stack ready.

Result

Laravel calls the sidecar by service name (e.g. http://go-api:8090); no host networking or host.docker.internal.
One .env (Laravel’s) controls both the API URL and the shared secret for DDEV.
ddev restart brings up web, db, and your sidecar services together.
Same pattern works for any “Laravel in DDEV + internal Go (or other) service”: add a custom compose file, put the service on the default network, and point Laravel at the service name.

If you run into 401s, double-check that the shared secret env var is identical in Laravel’s .env and in the Go container.

Baamaapii

PSR-14: Event Dispatcher in PHP

Mon, 17 Feb 2025 00:00:00 +0000

Ahnii!

Prerequisites: PHP OOP (classes, interfaces). Recommended: Read PSR-11 first.

Now that we’ve seen how PSR-11 wires services together, what if those services need to communicate without knowing about each other? That’s where events come in. PSR-14 defines a standard interface for event dispatching in PHP, enabling loose coupling and better extensibility across your entire application.

What Problem Does PSR-14 Solve? (3 minutes)

Think of your application as a radio station. When something happens – a user registers, a post gets published, an order is placed – the station broadcasts it. Listeners are tuned-in radios: they hear the broadcasts they care about and react accordingly.

The key insight is decoupling. The radio station doesn’t need to know who’s listening, and listeners don’t need to know about each other. A registration broadcast might trigger a welcome email, update analytics, and create a default profile – all without the registration code knowing any of that exists.

Without a standard, every framework invents its own event system. Symfony has its EventDispatcher, Laravel has its Events facade, and smaller libraries roll their own. PSR-14 standardizes the pattern so event systems become interchangeable – just like PSR-3 did for logging and PSR-11 did for containers.

Core Interfaces (5 minutes)

PSR-14 defines three interfaces. Let’s look at each one.

EventDispatcherInterface

php

namespace Psr\EventDispatcher;

interface EventDispatcherInterface
{
    /**
     * Dispatches an event to all registered listeners.
     *
     * @param object $event The event to dispatch
     * @return object The same event object, possibly modified by listeners
     */
    public function dispatch(object $event): object;
}

One method, one job: take any object as an event, pass it to listeners, and return it. The event object is returned so listeners can modify it – for example, a validation listener might mark an event as invalid.

ListenerProviderInterface

php

namespace Psr\EventDispatcher;

interface ListenerProviderInterface
{
    /**
     * Returns all listeners applicable to the given event.
     *
     * @param object $event The event to find listeners for
     * @return iterable Listeners for this event
     */
    public function getListenersForEvent(object $event): iterable;
}

This is the registry. When an event is dispatched, the dispatcher asks the provider: “Who wants to hear about this?” The provider returns all matching listeners. This separation means you can swap out how listeners are discovered without changing the dispatcher.

StoppableEventInterface

php

namespace Psr\EventDispatcher;

interface StoppableEventInterface
{
    /**
     * Has propagation been stopped?
     *
     * @return bool True if no further listeners should be called
     */
    public function isPropagationStopped(): bool;
}

Sometimes you need to short-circuit. If a validation listener finds a problem, there’s no point running the rest. Events that implement this interface can signal the dispatcher to stop calling listeners.

Real-World Implementation (10 minutes)

Let’s build a working event system for a blog application. We’ll create events, listeners, a provider, and a dispatcher.

Event Classes

php

namespace App\Event;

class PostCreatedEvent
{
    public function __construct(
        private object $post,
        private \DateTimeImmutable $createdAt = new \DateTimeImmutable()
    ) {}

    public function getPost(): object
    {
        return $this->post;
    }

    public function getCreatedAt(): \DateTimeImmutable
    {
        return $this->createdAt;
    }
}

class PostPublishedEvent
{
    public function __construct(
        private object $post
    ) {}

    public function getPost(): object
    {
        return $this->post;
    }
}

Events are simple data carriers. They hold information about what happened – nothing more.

Listener Provider

php

namespace App\Event;

use Psr\EventDispatcher\ListenerProviderInterface;

class SimpleListenerProvider implements ListenerProviderInterface
{
    /** @var array> */
    private array $listeners = [];

    /**
     * Register a listener for a specific event class.
     */
    public function addListener(string $eventClass, callable $listener): void
    {
        $this->listeners[$eventClass][] = $listener;
    }

    /**
     * Returns all listeners registered for this event's class.
     */
    public function getListenersForEvent(object $event): iterable
    {
        $eventClass = get_class($event);
        return $this->listeners[$eventClass] ?? [];
    }
}

The provider maps event class names to arrays of callables. When the dispatcher asks for listeners, it looks up the event’s class and returns any registered listeners.

Event Dispatcher

php

namespace App\Event;

use Psr\EventDispatcher\EventDispatcherInterface;
use Psr\EventDispatcher\ListenerProviderInterface;
use Psr\EventDispatcher\StoppableEventInterface;

class SimpleEventDispatcher implements EventDispatcherInterface
{
    public function __construct(
        private ListenerProviderInterface $listenerProvider
    ) {}

    public function dispatch(object $event): object
    {
        // If the event is already stopped, return immediately
        if ($event instanceof StoppableEventInterface && $event->isPropagationStopped()) {
            return $event;
        }

        foreach ($this->listenerProvider->getListenersForEvent($event) as $listener) {
            // Check before each listener call
            if ($event instanceof StoppableEventInterface && $event->isPropagationStopped()) {
                break;
            }
            $listener($event);
        }

        return $event;
    }
}

The dispatcher gets listeners from the provider and calls each one. It respects StoppableEventInterface by checking before each call.

Wiring It All Together

php

// Create the provider and register listeners
$provider = new SimpleListenerProvider();

// When a post is created, send a notification
$provider->addListener(PostCreatedEvent::class, function (PostCreatedEvent $event) {
    $post = $event->getPost();
    echo "Notification: New post '{$post->title}' created!\n";
});

// When a post is created, update the search index
$provider->addListener(PostCreatedEvent::class, function (PostCreatedEvent $event) {
    $post = $event->getPost();
    echo "Search index updated for post #{$post->id}\n";
});

// When a post is published, notify subscribers
$provider->addListener(PostPublishedEvent::class, function (PostPublishedEvent $event) {
    $post = $event->getPost();
    echo "Email sent to subscribers about '{$post->title}'\n";
});

// Create the dispatcher
$dispatcher = new SimpleEventDispatcher($provider);

// Dispatch events
$post = (object) ['id' => 1, 'title' => 'Getting Started with PSR-14'];
$dispatcher->dispatch(new PostCreatedEvent($post));
$dispatcher->dispatch(new PostPublishedEvent($post));

// Output:
// Notification: New post 'Getting Started with PSR-14' created!
// Search index updated for post #1
// Email sent to subscribers about 'Getting Started with PSR-14'

Notice how the code that creates the post doesn’t know about notifications, search indexing, or emails. It just dispatches an event and moves on. That’s the power of event-driven architecture.

Common Mistakes and Fixes

1. Fat Events That Do Too Much

Events should carry data, not business logic. They describe what happened – they don’t decide what to do about it.

// Bad -- the event does the processing
class PostCreatedEvent
{
    public function process(): void
    {
        $this->sendEmail();
        $this->updateIndex();
        $this->logCreation();
    }
}

// Good -- the event carries data, listeners do the work
class PostCreatedEvent
{
    public function __construct(private object $post) {}
    public function getPost(): object { return $this->post; }
}

2. Relying on Listener Order

Don’t write listeners that assume they’ll run in a specific order. If order matters, use a single listener that orchestrates the steps explicitly.

// Bad -- second listener assumes the first already ran
$provider->addListener(PostCreatedEvent::class, function ($event) {
    $event->getPost()->slug = generateSlug($event->getPost()->title);
});
$provider->addListener(PostCreatedEvent::class, function ($event) {
    // Assumes slug is already set -- fragile!
    saveToDatabase($event->getPost());
});

// Good -- one listener handles the ordered workflow
$provider->addListener(PostCreatedEvent::class, function ($event) {
    $post = $event->getPost();
    $post->slug = generateSlug($post->title);
    saveToDatabase($post);
});

3. Not Using Stoppable Events

When you want to short-circuit processing – like validation where one failure should stop everything – use StoppableEventInterface.

class ValidationEvent implements StoppableEventInterface
{
    private array $errors = [];

    public function addError(string $error): void
    {
        $this->errors[] = $error;
    }

    public function isPropagationStopped(): bool
    {
        // Stop as soon as we find any error
        return count($this->errors) > 0;
    }

    public function getErrors(): array
    {
        return $this->errors;
    }
}

Framework Integration

Laravel

Laravel’s event system follows the same pattern, though it predates PSR-14:

// Dispatch an event
Event::dispatch(new PostCreated($post));

// Register a listener in EventServiceProvider
protected $listen = [
    PostCreated::class => [
        SendNotification::class,
        UpdateSearchIndex::class,
    ],
];

Symfony

Symfony’s EventDispatcher component is PSR-14 compliant. You can register listeners with PHP attributes:

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: PostCreatedEvent::class)]
class SendNotificationListener
{
    public function __invoke(PostCreatedEvent $event): void
    {
        // Send notification for the new post
    }
}

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR14

See src/Event/ for the blog API’s event dispatcher implementation.

What’s Next

Next, we’ll dive into the HTTP stack, starting with PSR-7: HTTP Message Interfaces – the standard that defines how PHP represents HTTP requests and responses.

Resources

Baamaapii 👋

PSR-12: Extended Coding Style Guide in PHP

Sun, 16 Feb 2025 00:00:00 +0000

Ahnii!

Prerequisites: Read PSR-1 first — PSR-12 extends it.

Remember PSR-1’s “house rules” for PHP code? PSR-12 is like the detailed home manual. It extends PSR-1 and replaces the deprecated PSR-2 to provide a comprehensive coding style guide for modern PHP.

Why PSR-12 Matters (2 minutes)

You might think coding style is superficial. But imagine reading a book where every chapter uses different indentation, different quote marks, and different paragraph spacing. It’s exhausting. PSR-12 eliminates these distractions so you can focus on what the code does rather than how it looks.

PSR-12 replaces PSR-2 (now deprecated) and works alongside PSR-1. If PSR-1 covers the “what” (naming, file structure), PSR-12 covers the “how” (formatting, spacing, braces).

Key Style Rules

1. General Code Layout

Files MUST use Unix LF line endings.
Files MUST end with a single blank line.
The closing ?> tag MUST be omitted from files containing only PHP.
Lines SHOULD be 80 characters or less.
There MUST be one blank line after namespace declarations.
Opening braces MUST be on the same line as the statement.

2. Class Structure

Here’s an example of a properly structured class:

php

declare(strict_types=1);

namespace Vendor\Package;

use Vendor\Package\SomeClass;
use Vendor\Package\AnotherClass as AClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    private const VERSION = '1.0';
    
    public function methodName(int $arg1, ?string $arg2): string
    {
        // method body
    }
}

3. Control Structures

Examples of control structures formatted according to PSR-12:

php

if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body
}

switch ($expr) {
    case 0:
        echo 'First case';
        break;
    default:
        echo 'Default case';
        break;
}

try {
    // try body
} catch (FirstThrowableType $e) {
    // catch body
} finally {
    // finally body
}

Modern PHP Features

1. Type Declarations

Example of using type declarations in method signatures:

php

public function processUser(
    User $user,
    ?array $options = null
): ?Response {
    // Implementation
}

2. Attribute Syntax

Example of using attribute syntax in PHP 8:

php

#[Route("/api/posts/{id}", methods: ["GET"])]
public function show(#[EntityId] int $id): Response
{
    // Implementation
}

Tools for PSR-12 Compliance

PHP_CodeSniffer Configuration
PHP-CS-Fixer Setup
IDE Integration
- PhpStorm
- VS Code with PHP Intelephense

Common Issues and Solutions

Mixed Line Endings

# Check for mixed line endings
$ find . -name "*.php" -exec file {} \;

# Fix with dos2unix
$ find . -name "*.php" -exec dos2unix {} \;

Incorrect Indentation

// Bad
class Foo {
    function bar() {
return true;
    }
}

// Good
class Foo
{
    public function bar(): bool
    {
        return true;
    }
}

Next Steps

In our next post, we’ll explore PSR-13, which defines standards for HTTP message interfaces in PHP. Check out our example repository for the implementation of these standards.

Try It Yourself

Clone the companion repository — the entire project follows PSR-12:

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install

# Check if code follows PSR-12
composer check-style

# Auto-fix style violations
composer fix-style

See phpcs.xml for the PSR-12 configuration used across the project.

Resources

Baamaapii 👋

PSR-11: Container Interface in PHP

Mon, 03 Feb 2025 00:00:00 +0000

Ahnii!

Prerequisites: PHP OOP (classes, interfaces, constructors). Recommended: Read PSR-4 and PSR-3 first.

Ever created an object that needs five other objects to work, and each of those needs three more? That’s the dependency puzzle. PSR-11 defines a common interface for dependency injection containers in PHP — the tool that solves this puzzle automatically.

What Problem Does PSR-11 Solve? (3 minutes)

Imagine building a car by hand: you need an engine, which needs a fuel system, which needs a fuel pump, which needs… it goes on forever. A dependency injection container is like a car factory — you tell it the blueprint, and it builds everything in the right order.

Without a standard container interface, libraries that need to look up services (like a router finding controllers) must be written for a specific container. PSR-11 lets any library work with any container — PHP-DI, Symfony’s container, Laravel’s container, or your own simple one.

Understanding Dependency Injection Containers

A dependency injection container (DIC) is responsible for:

Managing service definitions
Creating service instances
Resolving dependencies
Managing object lifecycle

The Container Interface

php

namespace JonesRussell\PhpFigGuide\PSR11;

interface ContainerInterface
{
    /**
     * Finds an entry of the container by its identifier and returns it.
     *
     * @param string $id
     * @return mixed
     * @throws NotFoundExceptionInterface
     * @throws ContainerExceptionInterface
     */
    public function get($id);

    /**
     * Returns true if the container can return an entry for the given identifier.
     *
     * @param string $id
     * @return bool
     */
    public function has($id);
}

Basic Implementation

Here’s a simple implementation of a dependency injection container that adheres to PSR-11:

php

namespace JonesRussell\PhpFigGuide\PSR11;

class SimpleContainer implements ContainerInterface
{
    private array $services = [];

    public function set(string $id, $service): void
    {
        $this->services[$id] = $service;
    }

    public function get($id)
    {
        if (!$this->has($id)) {
            throw new class extends \Exception implements NotFoundExceptionInterface {};
        }

        return $this->services[$id];
    }

    public function has($id): bool
    {
        return isset($this->services[$id]);
    }
}

// Example usage
$container = new SimpleContainer();
$container->set('database', new DatabaseConnection());
$database = $container->get('database');

Best Practices

Service Resolution

// Bad - Service locator pattern
class UserService
{
    public function __construct(private ContainerInterface $container) {}
    
    public function doSomething()
    {
        $dep = $this->container->get('some.service');
    }
}

// Good - Explicit dependency injection
class UserService
{
    public function __construct(
        private SomeServiceInterface $someService
    ) {}
}

Container Configuration

// Bad - Runtime service definition
if ($condition) {
    $container->set('service', new ServiceA());
} else {
    $container->set('service', new ServiceB());
}

// Good - Configuration-driven definition
$container->set('service', function (ContainerInterface $c) {
    return $c->get('config')->get('use_service_a')
        ? new ServiceA()
        : new ServiceB();
});

Common Mistakes and Fixes

1. Using the Container as a Service Locator

// Bad — passing the container everywhere defeats the purpose of DI
class OrderService
{
    public function __construct(private ContainerInterface $container) {}

    public function process(int $orderId): void
    {
        $db = $this->container->get('database');
        $logger = $this->container->get('logger');
        // Now OrderService depends on EVERYTHING
    }
}

// Good — inject only what you need
class OrderService
{
    public function __construct(
        private DatabaseConnection $db,
        private LoggerInterface $logger
    ) {}

    public function process(int $orderId): void
    {
        // Dependencies are clear from the constructor
    }
}

2. Forgetting to Handle Missing Services

// Bad — crashes with an unhelpful error
$service = $container->get('nonexistent.service');

// Good — check first, or catch the exception
if ($container->has('optional.service')) {
    $service = $container->get('optional.service');
}

Framework Integration

Laravel

Laravel’s service container is PSR-11 compliant. You usually don’t call it directly — Laravel auto-injects dependencies:

php

// Laravel resolves LoggerInterface automatically from the container
class PostController extends Controller
{
    public function __construct(
        private LoggerInterface $logger,
        private PostRepository $posts
    ) {}
}

Symfony

Symfony’s DependencyInjection component is PSR-11 compliant. You define services in YAML or PHP:

# config/services.yaml
services:
    App\Service\PostService:
        arguments:
            $logger: '@Psr\Log\LoggerInterface'
            $cache: '@Psr\SimpleCache\CacheInterface'

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR11

See src/Container/ for the blog API’s container implementation.

Next Steps

In our next post, we’ll explore PSR-14, which defines a standard event dispatcher interface. Check out our example repository for the implementation of these standards.

Resources

Baamaapii 👋

PSR-7: HTTP Message Interfaces in PHP

Fri, 24 Jan 2025 00:00:00 +0000

Ahnii!

Prerequisites: PHP OOP, Composer. Recommended: Read PSR-4 first. Pairs with: PSR-15 (middleware) and PSR-17 (factories).

Ever wondered how frameworks like Laravel and Slim handle HTTP requests behind the scenes? PSR-7 defines common interfaces for representing HTTP messages in PHP. These interfaces enable framework-agnostic HTTP message handling, making it easier to create interoperable HTTP clients, servers, and middleware.

What Problem Does PSR-7 Solve? (3 minutes)

Imagine every restaurant in town used different-shaped plates. Chefs couldn’t share recipes because “put it on the plate” meant something different everywhere. PSR-7 gives PHP a standard “plate” for HTTP messages — every framework and library agrees on what a request and response look like.

Before PSR-7, switching from Guzzle to Buzz or from Laravel to Slim meant learning entirely new objects for the same HTTP concepts. PSR-7 lets you write code that works with any compliant library.

Why Immutability?

PSR-7 messages are immutable — you can’t change them after creation. Instead, methods like withHeader() return a new object with the change applied. Think of it like editing a Google Doc with “suggestion mode” on: the original stays intact, and each change creates a new version.

This matters because HTTP messages often pass through multiple middleware layers. If one middleware could modify the request object directly, another middleware downstream might get unexpected data. Immutability prevents these bugs.

Core Interfaces

1. Message Interface

php

namespace Psr\Http\Message;

interface MessageInterface
{
    public function getProtocolVersion();
    public function withProtocolVersion($version);
    public function getHeaders();
    public function hasHeader($name);
    public function getHeader($name);
    public function getHeaderLine($name);
    public function withHeader($name, $value);
    public function withAddedHeader($name, $value);
    public function withoutHeader($name);
    public function getBody();
    public function withBody(StreamInterface $body);
}

2. Request Interface

php

namespace Psr\Http\Message;

interface RequestInterface extends MessageInterface
{
    public function getRequestTarget();
    public function withRequestTarget($requestTarget);
    public function getMethod();
    public function withMethod($method);
    public function getUri();
    public function withUri(UriInterface $uri, $preserveHost = false);
}

3. Response Interface

php

namespace Psr\Http\Message;

interface ResponseInterface extends MessageInterface
{
    public function getStatusCode();
    public function withStatus($code, $reasonPhrase = '');
    public function getReasonPhrase();
}

Basic Implementation

1. Creating Requests

php

use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Uri;

// Simple GET request
$request = new Request(
    'GET',
    'https://api.example.com/users'
);

// POST request with JSON body
$request = new Request(
    'POST',
    'https://api.example.com/users',
    [
        'Content-Type' => 'application/json'
    ],
    json_encode(['name' => 'John Doe'])
);

2. Handling Responses

php

use GuzzleHttp\Psr7\Response;

$response = new Response(
    200,
    ['Content-Type' => 'application/json'],
    json_encode(['status' => 'success'])
);

// Working with responses
$status = $response->getStatusCode();
$body = $response->getBody()->getContents();
$contentType = $response->getHeaderLine('Content-Type');

Best Practices

Immutability

// Bad - Modifying message directly
$request->method = 'POST';

// Good - Using withers
$newRequest = $request->withMethod('POST');

Stream Handling

// Bad - Loading entire body into memory
$content = $request->getBody()->getContents();

// Good - Streaming large responses
$body = $response->getBody();
while (!$body->eof()) {
    echo $body->read(8192);
}

Framework Integration

Laravel

Laravel uses PSR-7 under the hood via Symfony’s HttpFoundation. You can access PSR-7 objects directly:

php

use Psr\Http\Message\ServerRequestInterface;

// In a controller — Laravel auto-injects the PSR-7 request
public function store(ServerRequestInterface $request)
{
    $body = $request->getParsedBody();
    // $body contains the form data
}

Slim Framework

Slim is built entirely on PSR-7:

php

$app->get('/posts/{id}', function ($request, $response, $args) {
    $data = ['id' => $args['id'], 'title' => 'My Post'];
    $response->getBody()->write(json_encode($data));
    return $response->withHeader('Content-Type', 'application/json');
});

Try It Yourself

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR7

See src/Http/ for the PSR-7 implementation in the blog API.

Next Steps

In our next post, we’ll explore PSR-15, which builds upon PSR-7 to define HTTP server request handlers and middleware. Check out our example repository for the implementation of these standards.

Resources

Baamaapii 👋

PSR-6: Caching Interface in PHP

Fri, 10 Jan 2025 00:00:00 +0000

Ahnii!

Ever had your application slow to a crawl because of repeated database queries? Or struggled to switch between different caching libraries? Let’s dive into PSR-6, the standard that makes caching in PHP predictable and swappable!

This post is part of our PSR Standards in PHP series. If you’re new here, you might want to start with PSR-1 for the basics.

Prerequisites: PHP OOP (classes, interfaces). Recommended: Read PSR-4 first. See also: PSR-16 for simpler caching needs.

What Problem Does PSR-6 Solve? (2 minutes)

Before PSR-6, every caching library had its own way of doing things. Want to switch from Memcached to Redis? Rewrite your code. Moving from one framework to another? Learn a new caching API. PSR-6 fixes this by providing a common interface that all caching libraries can implement.

Core Interfaces (5 minutes)

Let’s look at the two main players:

1. CacheItemPoolInterface

This is your cache manager. Think of it as a warehouse where you store and retrieve items:

php

namespace Psr\Cache;

interface CacheItemPoolInterface
{
    public function getItem($key);
    public function getItems(array $keys = array());
    public function hasItem($key);
    public function clear();
    public function deleteItem($key);
    public function deleteItems(array $keys);
    public function save(CacheItemInterface $item);
    public function saveDeferred(CacheItemInterface $item);
    public function commit();
}

2. CacheItemInterface

This represents a single item in your cache:

php

namespace Psr\Cache;

interface CacheItemInterface
{
    public function getKey();
    public function get();
    public function isHit();
    public function set($value);
    public function expiresAt($expiration);
    public function expiresAfter($time);
}

Practical Usage (5 minutes)

Let’s see how to use this in real code:

php

// Basic usage
$pool = new FileCachePool('/path/to/cache');

try {
    // Store a value
    $item = $pool->getItem('user.1');
    if (!$item->isHit()) {
        $userData = $database->fetchUser(1); // Your database call
        $item->set($userData)
             ->expiresAfter(3600); // 1 hour
        $pool->save($item);
    }
    $user = $item->get();
} catch (\Exception $e) {
    // Handle errors gracefully
    log_error('Cache operation failed: ' . $e->getMessage());
    $user = $database->fetchUser(1); // Fallback to database
}

Common Pitfalls (3 minutes)

Key Validation

// Don't do this - using invalid characters
$key = 'user@email.com';

// Do this instead
$key = 'user.' . md5('user@email.com');

Error Handling

// Always handle cache failures gracefully
try {
    $pool->save($item);
} catch (CacheException $e) {
    // Log and continue with a cache miss
}

Cache Stampede

When a popular cache key expires, every request hits the database simultaneously:

// Bad - All requests hit the database when cache expires
$item = $pool->getItem('popular-posts');
if (!$item->isHit()) {
    $data = $database->getPopularPosts(); // Hundreds of requests run this at once
    $item->set($data)->expiresAfter(60);
    $pool->save($item);
}

// Good - Stagger expiration with random jitter
$item = $pool->getItem('popular-posts');
if (!$item->isHit()) {
    $data = $database->getPopularPosts();
    $jitter = random_int(0, 30);
    $item->set($data)->expiresAfter(60 + $jitter);
    $pool->save($item);
}

Framework Integration

Laravel

Laravel’s cache system supports PSR-6 through a bridge package:

php

use Illuminate\Support\Facades\Cache;

// Laravel's cache can be accessed as a PSR-6 pool
$pool = app('cache.psr6');
$item = $pool->getItem('user.1');

if (!$item->isHit()) {
    $item->set($user);
    $item->expiresAfter(3600);
    $pool->save($item);
}

Symfony

Symfony’s Cache component is a native PSR-6 implementation — no bridge needed:

php

use Symfony\Component\Cache\Adapter\FilesystemAdapter;

// Symfony's adapters implement PSR-6 directly
$cache = new FilesystemAdapter();
$item = $cache->getItem('user.1');

if (!$item->isHit()) {
    $item->set($user);
    $item->expiresAfter(3600);
    $cache->save($item);
}

What’s Next?

Tomorrow, we’ll look at PSR-7 (HTTP Message Interfaces). If you’re interested in simpler caching, stay tuned for our upcoming PSR-16 (Simple Cache) article, which offers a more straightforward alternative to PSR-6.

Try It Yourself

Clone the companion repository and explore the caching examples:

git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
composer test -- --filter=PSR6

See src/Cache/ for the PSR-6 implementation used in the blog API.

Resources

Official PSR-6 Specification
Our Example Repository (v0.6.0 - PSR-6 Implementation)
Symfony Cache Component
PHP Cache

PSR-4: Autoloading Standard in PHP

Wed, 08 Jan 2025 00:00:00 +0000

Ahnii!

Prerequisites: Basic PHP OOP, Composer installed. Recommended: Read PSR-1 first.

Remember the old days of PHP when we had to manually require every single file? Last week, I was helping a team modernize their legacy application that had 50+ require statements at the top of each file. Let me show you how PSR-4 autoloading makes this a problem of the past!

Understanding PSR-4 (5 minutes)

Think of PSR-4 as your code’s GPS system - it helps PHP find the right files automatically. Just like how a GPS uses addresses to find locations, PSR-4 uses namespaces to locate classes.

Key Concepts (2 minutes)

Fully Qualified Class Name (FQCN)
- Vendor namespace (like your brand)
- Package namespace (like your project)
- Class name (the actual file)
Directory Structure
- Base directory (where everything starts)
- Namespace mapping (your GPS coordinates)
- File location rules (the actual addresses)

Real-World Example (10 minutes)

Here’s how I structure my projects:

vendor/
└── jonesrussell/
    └── blog/
        ├── composer.json
        └── src/
            └── Post/
                ├── PostController.php
                └── PostRepository.php

1. Setting Up Composer (3 minutes)

{
    "name": "jonesrussell/blog",
    "autoload": {
        "psr-4": {
            "JonesRussell\\Blog\\": "src/"
        }
    }
}

2. Creating Classes (2 minutes)

php

namespace JonesRussell\Blog\Post;

class PostController
{
    public function index()
    {
        return ['status' => 'Ready to blog!'];
    }
}

Common Patterns I Use (5 minutes)

1. Multiple Namespace Roots

{
    "autoload": {
        "psr-4": {
            "JonesRussell\\Blog\\": "src/",
            "JonesRussell\\Blog\\Tests\\": "tests/"
        }
    }
}

2. Nested Namespaces

php

namespace JonesRussell\Blog\Core\Database;

class Connection
{
    private $config;
    
    public function __construct(array $config)
    {
        $this->config = $config;
    }
}

// File location: src/Core/Database/Connection.php

Framework Examples (5 minutes)

If you’re using Laravel or Symfony (like I do), they follow PSR-4 out of the box:

Laravel

php

namespace App\Http\Controllers;

class BlogController extends Controller
{
    public function index()
    {
        return view('blog.index');
    }
}

Symfony

php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class BlogController extends AbstractController
{
    public function index(): Response
    {
        return $this->render('blog/index.html.twig');
    }
}

Quick Fixes for Common Issues (3 minutes)

“Class Not Found” Errors

# When things go wrong, this is your friend:
composer dump-autoload

Directory Structure Mistakes

# Don't do this
src/
└── controllers/  # lowercase = bad
    └── PostController.php

# Do this instead
src/
└── Controller/  # Matches namespace case
    └── PostController.php

Testing Your Setup (2 minutes)

Drop this in test-autoload.php:

php

require 'vendor/autoload.php';

// If this works, your autoloading is set up correctly!
$controller = new \JonesRussell\Blog\Post\PostController();
var_dump($controller->index()); // Should show "Ready to blog!"

Next Steps

Tomorrow, we’ll explore PSR-6 and see how it standardizes caching in PHP applications. This post is part of our PSR Standards in PHP series.

Resources

Official PSR-4 Specification
Composer Autoloading Documentation
Series Example Repository (v0.3.0 - PSR-4 Implementation)

Baamaapii 👋

PSR-3: Logger Interface in PHP

Tue, 07 Jan 2025 00:00:00 +0000

Updated on Jan 10, 2025: Fixed markdown formatting and removed emojis for consistency.
Updated on Feb 16, 2025: Added additional comments and clarifications.

Ahnii!

Prerequisites: Basic PHP OOP (classes, interfaces). Recommended: Read PSR-1 first.

Recently, I was helping a team migrate from Monolog to a custom logging solution, and guess what? They had to change code in dozens of files because their logging wasn’t standardized. That’s exactly the problem PSR-3 solves. Let me show you how!

Understanding PSR-3 (5 minutes)

Think of PSR-3 as a contract for logging in PHP. Just like how every car has a steering wheel and pedals in roughly the same place (making it easy to switch between cars), PSR-3 ensures all logging libraries work in a similar way.

1. The Logger Interface

Here’s what this contract looks like:

php

namespace Psr\Log;

/**
 * LoggerInterface defines the contract for logging implementations.
 *
 * This interface provides methods for logging messages at different levels
 * of severity, allowing for a consistent logging approach across applications.
 */
interface LoggerInterface
{
    public function emergency($message, array $context = array());
    public function alert($message, array $context = array());
    public function critical($message, array $context = array());
    public function error($message, array $context = array());
    public function warning($message, array $context = array());
    public function notice($message, array $context = array());
    public function info($message, array $context = array());
    public function debug($message, array $context = array());
    public function log($level, $message, array $context = array());
}

2. Log Levels (3 minutes)

Think of these levels as a severity scale, from “everything’s on fire” to “just FYI”:

Emergency: The house is burning down (system is completely broken).
Alert: Wake up, we need to fix this now!
Critical: Major component is broken.
Error: Something failed, but the app is still running.
Warning: Heads up, something’s not right.
Notice: Something normal but noteworthy happened.
Info: Just keeping you in the loop.
Debug: For the curious developers.

Real-World Implementation (10 minutes)

Let’s build something practical - a logger that writes to files and sends critical errors to Slack:

php

namespace App\Logging;

use Psr\Log\AbstractLogger;
use Psr\Log\LogLevel;

/**
 * SmartLogger is an implementation of the PSR-3 Logger Interface.
 *
 * This logger writes log messages to a file and sends critical messages
 * to a Slack channel for immediate attention.
 */
class SmartLogger extends AbstractLogger
{
    private string $logFile;
    private string $slackWebhook;

    /**
     * Initialize the logger with file and Slack configuration.
     *
     * @param string $logFile      Path to the log file
     * @param string $slackWebhook Slack webhook URL
     */
    public function __construct(string $logFile, string $slackWebhook)
    {
        $this->logFile = $logFile;
        $this->slackWebhook = $slackWebhook;
    }

    /**
     * Logs with an arbitrary level.
     *
     * This method formats the log message and writes it to the log file.
     * It also sends critical and emergency messages to Slack.
     *
     * @param  mixed              $level   Log level
     * @param  string|\Stringable $message Message to log
     * @param  array              $context Context data for interpolation
     * @return void
     */
    public function log($level, string|\Stringable $message, array $context = []): void
    {
        // Format the message
        $timestamp = date('Y-m-d H:i:s');
        $message = $this->interpolate((string)$message, $context);
        $logLine = "[$timestamp] [$level] $message" . PHP_EOL;
        
        // Always write to file
        file_put_contents($this->logFile, $logLine, FILE_APPEND);
        
        // Send critical and emergency messages to Slack
        if (in_array($level, [LogLevel::CRITICAL, LogLevel::EMERGENCY])) {
            $this->notifySlack($level, $message);
        }
    }

    /**
     * Interpolates context values into message placeholders.
     *
     * @param  string $message Message with placeholders
     * @param  array  $context Values to replace placeholders
     * @return string Interpolated message
     */
    private function interpolate($message, array $context = array()): string
    {
        $replace = array();
        foreach ($context as $key => $val) {
            $replace['{' . $key . '}'] = $val;
        }
        return strtr($message, $replace);
    }
}

Using It In Your Project (5 minutes)

Here’s how I use this in my projects:

$logger = new SmartLogger(
    '/var/log/app.log',
    'https://hooks.slack.com/services/YOUR/WEBHOOK/HERE'
);

// Regular info logging
$logger->info('User {user} logged in from {ip}', [
    'user' => 'jonesrussell',
    'ip' => '192.168.1.1'
]);

// Critical error - this will go to both file and Slack
$logger->critical('Payment gateway {gateway} is down!', [
    'gateway' => 'Stripe',
    'error_code' => 500
]);

Framework Integration (5 minutes)

If you’re using Laravel or Symfony, they’ve already done the heavy lifting:

Laravel

// In a service
public function processOrder($orderId)
{
    try {
        // Process order
        Log::info('Order processed', ['order_id' => $orderId]);
    } catch (\Exception $e) {
        Log::error('Order failed', [
            'order_id' => $orderId,
            'error' => $e->getMessage()
        ]);
        throw $e;
    }
}

Symfony

class OrderController extends AbstractController
{
    public function process(LoggerInterface $logger, string $orderId)
    {
        $logger->info('Starting order process', ['order_id' => $orderId]);
        // Your code here
    }
}

Quick Tips (2 minutes)

Be Specific: Include relevant context in your logs

// Instead of this
$logger->error('Database error');

// Do this
$logger->error('Database connection failed', [
    'host' => $dbHost,
    'error' => $e->getMessage(),
    'retry_attempt' => $attempt
]);

Use the Right Level: Don’t cry wolf!

// Don't do this
$logger->emergency('User not found');

// Do this
$logger->notice('User not found', ['username' => $username]);

Next Steps

Tomorrow, we’ll dive into PSR-4 and see how it makes autoloading a breeze. This post is part of our PSR Standards in PHP series.

Resources

For more information:

Baamaapii 👋

PSR-1: Basic Coding Standard in PHP

Mon, 06 Jan 2025 00:00:00 +0000

Updated on Jan 7, 2025: Improved writing style and examples for better clarity. Updated on Jan 10, 2025: Removed emojis and simplified language for consistency. Updated on Feb 16, 2025: Added additional comments and clarifications.

Ahnii!

Prerequisites: Basic PHP syntax, a code editor. No prior PSR knowledge needed — this is where we start!

Have you ever pulled down a PHP project and felt like you were reading five different coding styles at once? That’s exactly what happened to me last week while helping a team with their legacy codebase. Let me show you how PSR-1 can save you from this headache.

Understanding PSR-1 (5 minutes)

Think of PSR-1 as the “house rules” for PHP code. Just like how every house has basic rules (shoes off at the door, close the fridge, turn off lights), PSR-1 sets the foundation for writing clean PHP code that everyone can understand.

Files and Namespaces (2 minutes)

Here are the ground rules:

Only use and tags (forget about those old-school short tags).


Always use UTF-8 without BOM (it prevents weird encoding issues).
Keep your files focused - either declare stuff OR do stuff, not both.


Naming Things Right (3 minutes)
Let’s make it clear:

Classes use StudlyCaps (like UserManager, OrderProcessor).
Constants should be in UPPER_CASE (like MAX_ATTEMPTS, API_VERSION).
Methods use camelCase (like getUserById, processOrder).

Real-World Example (10 minutes)
Here’s a practical example from our repository:
php

namespace JonesRussell\PhpFigGuide\PSR1;

/**
 * User management class following PSR-1 standards.
 *
 * This class provides methods to manage user-related operations, including
 * retrieving user information by ID and defining constants for versioning
 * and error types.
 */
class UserManager
{
    /**
     * Version number of the implementation.
     *
     * @var string
     */
    public const VERSION = '1.0.0';

    /**
     * Error type constant for not found errors.
     *
     * @var string
     */
    public const ERROR_TYPE_NOT_FOUND = 'not_found';

    /**
     * Get user information by ID.
     *
     * This method retrieves user data based on the provided user ID.
     * It returns an associative array containing the user's ID and name.
     *
     * @param  int $id The user ID to retrieve.
     * @return array User data with 'id' and 'name' keys.
     */
    public function getUserById(int $id): array
    {
        // Implementation
        return ['id' => $id, 'name' => 'John Doe'];
    }
}
Let’s break down what makes this code PSR-1 compliant:

Proper namespace using StudlyCaps.
Class name in StudlyCaps.
Constants in UPPERCASE_WITH_UNDERSCORES.
Method in camelCase.

Common Mistakes and Fixes (5 minutes)
The Kitchen Sink File
php
// Don't do this - mixing declarations and side effects
echo "Hello World";
class Foo {}

// Do this instead - separate files
// config.php
echo "Hello World";

// Foo.php
class Foo {}
Name Things Right
php
// Incorrect
class user_manager {}

// Correct
class UserManager {}
Tools to Help You (3 minutes)
I use these tools in all my projects:

PHP_CodeSniffer: composer check-style to spot issues.
Auto-fixing: composer fix-style to fix common mistakes.
IDE Integration: Let your editor help you stay compliant.
Git hooks: Catch issues before they hit your repo.

Next Steps
Tomorrow, we’ll explore PSR-3 and see how it makes logging consistent across your applications. This post is part of our PSR Standards in PHP series.
Resources (5 minutes)
For more information:

Official PSR-1 Specification
PHP-FIG Website

Baamaapii 👋



PSR Standards in PHP: A Practical Guide for Developers
Sun, 05 Jan 2025 00:00:00 +0000
Are you tired of wrestling with inconsistent PHP codebases or struggling to make different packages work together? You’re not alone! In this series, we’ll explore how PHP-FIG’s PSR standards can transform your development experience.
What is PHP-FIG?
PHP-FIG is a group of PHP project representatives working together to advance the PHP ecosystem. Their primary contribution is the PSR system, which defines coding standards and interfaces that enable better interoperability between PHP packages and frameworks.
Why PSRs Matter
PSRs solve several critical challenges in PHP development:

Code Consistency: Standardized coding styles make code more readable
Interoperability: Common interfaces allow different packages to work together seamlessly
Best Practices: Established patterns improve code quality and maintainability

Recommended Reading Path
New to PSRs? Follow this order — it builds knowledge progressively:
Foundation (Start Here)

PSR-1: Basic Coding Standard — The “house rules” for PHP code
PSR-12: Extended Coding Style — Detailed formatting rules (extends PSR-1)
PSR-4: Autoloading Standard — How PHP finds your classes automatically

Core Infrastructure

PSR-3: Logger Interface — Standardized logging across your application
PSR-11: Container Interface — Dependency injection made interoperable
PSR-14: Event Dispatcher — Decoupled communication between components

HTTP Stack (Read in Sequence)

PSR-7: HTTP Message Interfaces — The standard “shape” of HTTP requests and responses
PSR-17: HTTP Factories — Creating PSR-7 objects without coupling to implementations
PSR-15: HTTP Handlers and Middleware — Processing HTTP requests through a middleware pipeline
PSR-18: HTTP Client — Sending HTTP requests the standard way

Data and Caching

PSR-6: Caching Interface — Full-featured cache pools and items
PSR-16: Simple Cache — Lightweight key-value caching

Specialized

PSR-13: Hypermedia Links — Self-documenting REST APIs with HATEOAS
PSR-20: Clock Interface — Testable time handling

Quick Reference (by PSR Number)

  
      
          PSR
          Topic
          Post
      
  
  
      
          1
          Basic Coding Standard
          Read
      
      
          3
          Logger Interface
          Read
      
      
          4
          Autoloading Standard
          Read
      
      
          6
          Caching Interface
          Read
      
      
          7
          HTTP Messages
          Read
      
      
          11
          Container Interface
          Read
      
      
          12
          Extended Coding Style
          Read
      
      
          13
          Hypermedia Links
          Read
      
      
          14
          Event Dispatcher
          Read
      
      
          15
          HTTP Handlers
          Read
      
      
          16
          Simple Cache
          Read
      
      
          17
          HTTP Factories
          Read
      
      
          18
          HTTP Client
          Read
      
      
          20
          Clock
          Read
      
  

Practical Learning
Each post includes:

A relatable analogy explaining what the standard solves
The actual PSR interface with commentary
A working implementation from our blog API companion project
Common mistakes with before/after fixes
Framework integration examples (Laravel, Symfony, Slim)
A “Try It Yourself” section with exact commands to run

Getting Started
To follow along, clone our companion repository — a blog API that uses all 14 PSRs:
git clone https://github.com/jonesrussell/php-fig-guide.git
cd php-fig-guide
composer install
The blog API demonstrates every PSR in a real project context. Each PSR has:

Implementation code under src/
PHPUnit tests under tests/

# Run all tests
composer test

# Run tests for a specific PSR
composer test -- --filter=PSR7

# Check coding standards (PSR-1 + PSR-12)
composer check-style
Resources

PHP-FIG Website
PSR Index
Our Example Repository

Baamaapii 👋



Debugging Bubbletea Command Comparisons: A Learning Experience
Sat, 28 Dec 2024 00:00:00 +0000
Disclaimer: This is entirely AI generated.
When building test utilities for Bubbletea applications, I recently encountered an interesting issue around command handling. Here’s what I learned about the proper way to handle Bubbletea’s command system.
The Initial Problem
The code started with what seemed like a straightforward comparison:
if cmd == tea.Quit {
    // Handle quit...
}
This triggered a compiler error:
invalid operation: cmd == tea.Quit (func can only be compared to nil)
The Misguided Fix
My first attempt at fixing this used reflection to compare function pointers:
if reflect.ValueOf(cmd).Pointer() == reflect.ValueOf(tea.Quit).Pointer() {
    // Handle quit...
}
While this compiled, it was fundamentally misunderstanding Bubbletea’s design. Commands in Bubbletea aren’t meant to be compared - they’re functions that produce messages.
The Correct Solution
The proper way to handle command checking in Bubbletea is to:

Execute the command to get its message
Use type assertion to check the message type

if cmd != nil {
    if msg := cmd(); msg != nil {
        if _, ok := msg.(tea.QuitMsg); ok {
            // Handle quit...
        }
    }
}
Key Takeaways

Commands are producers: In Bubbletea, commands are functions that produce messages, not values to be compared
Type assertions over comparisons: Use Go’s type system to check message types
Message-passing design: Bubbletea follows a message-passing architecture where commands produce messages that drive the application state

This experience reinforces the importance of understanding the underlying design patterns of the libraries we use, rather than trying to force familiar patterns that might not fit.



Python Virtual Environments for Beginners
Fri, 29 Nov 2024 00:00:00 +0000
If you’re new to Python, you might have heard about virtual environments but aren’t sure what they are or why you need them. Let’s break it down in simple terms!
What’s a Virtual Environment?
Think of a virtual environment like a clean room for your Python project. It’s an isolated space where you can install packages and dependencies without affecting your computer’s main Python installation or other projects.
Why Do You Need One?
Imagine you’re working on two Python projects:

Project A needs version 1.0 of a package
Project B needs version 2.0 of the same package

Without virtual environments, you’d have a conflict! Virtual environments solve this by giving each project its own separate space with its own packages.
How to Create a Virtual Environment
It’s surprisingly simple! You only need two commands:
# Create the virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate
Let’s break down that first command:

python3 - runs Python 3
-m venv - tells Python to run the venv module
The last venv - is just the name of the directory (you can name it anything)

How to Know It’s Working
When your virtual environment is active, you’ll see (venv) at the start of your terminal prompt:
(venv) username@computer:~/project$
Installing Packages
Once your virtual environment is active, you can install packages using pip:
pip install requests
These packages will only be installed in your virtual environment, keeping your system Python clean.
Common Commands
# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install packages
pip install requests
pip install -r requirements.txt  # install from a requirements file

# See what's installed
pip list

# Deactivate when you're done
deactivate
Best Practices

Create a virtual environment for each Python project
Add venv/ to your .gitignore file
Keep a requirements.txt file listing your project dependencies
Activate the virtual environment before working on your project

Wrapping Up
Virtual environments might seem like extra work at first, but they’re a crucial tool for Python development. They keep your projects isolated, make them more portable, and help avoid dependency conflicts.
Remember: if you’re starting a new Python project, creating a virtual environment should be your first step!



Suspend and Resume Processes in Linux
Tue, 27 Aug 2024 00:00:00 +0000
Managing processes in Linux is an essential skill for any user. This post covers how to suspend, resume, and manage jobs using simple commands.
Suspending a Process

Ctrl+Z: This command suspends the current foreground process, stopping its execution and putting it in the background. This is useful if you need to temporarily halt a process to free up the terminal for other tasks without terminating the process.

Background and Foreground Jobs

jobs: This command lists all the jobs that are currently running or suspended in the background. It helps you keep track of the processes you have suspended or are running in the background.
bg %n: This command resumes the suspended job n in the background, allowing it to continue running while you can still use the terminal. This is useful if you want a process to continue running without occupying the terminal.
fg %n: This command brings the job n to the foreground, making it the active process in the terminal. This is useful when you need to interact with a process that was running in the background.

Example


Start a process:
sleep 100
This command starts a process that will sleep for 100 seconds.


Suspend the process:
Ctrl+Z
This suspends the sleep process and puts it in the background.


Check jobs:
$ jobs
[1]+  Stopped                 sleep 100
This lists the jobs, showing that the sleep process is stopped.


Resume in background:
$ bg %1
[1]+ sleep 100 &
This resumes the sleep process in the background.


Bring to foreground:
$ fg %1
sleep 100
This brings the sleep process back to the foreground.


Summary

Ctrl+Z: Suspend the current process.
jobs: List all jobs.
bg %n: Resume a job in the background.
fg %n: Bring a job to the foreground.




Understanding Go Interfaces: A Practical Guide
Mon, 12 Aug 2024 00:00:00 +0000
Ahnii,
Interfaces in Go might seem simple at first, but they’re incredibly powerful. Let’s explore how to use them effectively and avoid common pitfalls.
What Makes Go Interfaces Special? (2 minutes)
Unlike other languages, Go interfaces are:

Implicitly implemented
Small by convention
Composable
Type-safe

Basic Interface Usage (5 minutes)
Here’s a simple example:
// Define a simple interface
type Writer interface {
    Write([]byte) (int, error)
}

// Concrete implementation
type FileWriter struct {
    file *os.File
}

// Implement the Writer interface
func (fw *FileWriter) Write(data []byte) (int, error) {
    return fw.file.Write(data)
}
Interface Best Practices

Keep Interfaces Small

// Good
type Reader interface {
    Read(p []byte) (n int, err error)
}

// Too big
type BigInterface interface {
    Read(p []byte) (n int, err error)
    Write(p []byte) (n int, err error)
    Close() error
    Flush() error
    // ... many more methods
}

Accept Interfaces, Return Structs

// Good
func ProcessData(r Reader) error {
    // ...
}

// Not as flexible
func ProcessData(f *os.File) error {
    // ...
}
Common Interface Patterns

The io.Reader/Writer Family

type ReadWriter interface {
    Reader
    Writer
}

The Stringer Interface

type Stringer interface {
    String() string
}
Testing with Interfaces
Interfaces make testing easier:
type MockWriter struct {
    WrittenData []byte
}

func (m *MockWriter) Write(data []byte) (int, error) {
    m.WrittenData = append(m.WrittenData, data...)
    return len(data), nil
}
Real-World Examples
Here’s how interfaces solve common problems:

Database Abstraction

type Storage interface {
    Save(data interface{}) error
    Find(id string) (interface{}, error)
}

Logging

type Logger interface {
    Info(msg string)
    Error(msg string)
}
Wrapping Up
Interfaces are one of Go’s most powerful features for writing flexible, testable code. Start small, focus on behavior, and let interfaces emerge from your code naturally.
What’s your favorite use of interfaces in Go? Have you discovered any interesting patterns? Share in the comments!
Baamaapii 👋



Testing Cobra CLI Apps in Go: A DI Approach
Wed, 24 Jul 2024 00:00:00 +0000
Ahnii,
Ever struggled with testing your Cobra CLI applications? I recently refactored one of my projects to use dependency injection, and it made testing so much easier. Let me show you how!
Why Dependency Injection? (2 minutes)
Key benefits for CLI apps:

Easier to mock dependencies
More testable code
Cleaner separation of concerns
Flexible configuration

Basic Setup (5 minutes)
Here’s our basic CLI structure with DI:
type AppDependencies struct {
    Logger  Logger
    Config  Config
    Client  HTTPClient
}

func NewRootCmd(deps *AppDependencies) *cobra.Command {
    cmd := &cobra.Command{
        Use:   "mycli",
        Short: "My CLI application",
        RunE: func(cmd *cobra.Command, args []string) error {
            return runRoot(deps, args)
        },
    }
    return cmd
}
Testing Strategy (10 minutes)

Mock Dependencies

type MockLogger struct {
    mock.Mock
}

func TestRootCommand(t *testing.T) {
    mockLogger := &MockLogger{}
    deps := &AppDependencies{
        Logger: mockLogger,
    }
    
    cmd := NewRootCmd(deps)
    assert.NotNil(t, cmd)
}

Test Command Execution

func TestCommandExecution(t *testing.T) {
    deps := setupTestDependencies()
    cmd := NewRootCmd(deps)
    
    output, err := executeCommand(cmd, "arg1", "--flag=value")
    assert.NoError(t, err)
    assert.Contains(t, output, "expected output")
}
Best Practices

Keep dependencies minimal and focused
Use interfaces for flexibility
Test edge cases thoroughly
Mock external services

Common Patterns

Configuration Injection

func NewConfig() *Config {
    return &Config{
        // Default values
    }
}

Logger Injection

type Logger interface {
    Info(msg string, args ...interface{})
    Error(msg string, args ...interface{})
}
Wrapping Up
Dependency injection might seem like overhead at first, but it pays off in testability and maintainability. Start small and refactor as needed.
How do you handle testing in your CLI applications? Have you tried dependency injection? Share your experiences below!
Baamaapii 👋



Setting Up a Dev Container in VS Code
Sat, 29 Jun 2024 00:00:00 +0000
Ahnii,
Tired of “it works on my machine” syndrome? Let’s fix that with VS Code Dev Containers! I recently switched to using them for all my projects, and it’s been a game-changer.
What are Dev Containers? (2 minutes)
Dev Containers provide:

Isolated development environments
Consistent tooling across team members
Project-specific configurations
Easy onboarding for new developers

Quick Setup (5 minutes)


Prerequisites

Install Docker Desktop
Install VS Code
Add “Dev Containers” extension



Basic Configuration
{
    "name": "Your Project",
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "customizations": {
        "vscode": {
            "extensions": [
                "dbaeumer.vscode-eslint",
                "esbenp.prettier-vscode"
            ]
        }
    }
}


Pro Tips

Use multi-stage builds for smaller images
Share your Docker cache between containers
Mount your SSH keys safely
Configure Git settings properly

Common Issues and Solutions


Performance

Use volume mounts wisely
Enable BuildKit
Optimize your Dockerfile



Security

Never expose sensitive data in images
Use COPY instead of ADD
Keep base images updated



Wrapping Up
Dev Containers have transformed how I work with different projects. They’re worth the initial setup time for the consistency and reliability they provide.
What’s your development environment setup like? Have you tried Dev Containers? Share your experiences below!
Baamaapii 👋



Quickly View Project Dependencies on the CLI
Sat, 21 Nov 2020 00:00:00 +0000

Update (2025): This article has been revised to reflect modern npm capabilities. The original custom tool is no longer necessary as npm now provides these features out of the box.

Ahnii!
I frequently find myself wanting to check package.json dependencies while working in the terminal. Here are the modern ways to do this using npm’s built-in commands.
Built-in NPM Commands (2 minutes)
List All Dependencies
npm list
# or shorter
npm ls
List Only Direct Dependencies
npm ls --depth=0
List Production Dependencies Only
npm ls --prod --depth=0
List Development Dependencies Only
npm ls --dev --depth=0
Search for Specific Package
npm ls package-name
View Outdated Packages
npm outdated
Enhanced Features with npm@7+ (2 minutes)
Newer versions of npm include additional helpful commands:
# View package details
npm view package-name

# View all package versions
npm view package-name versions

# Check for security vulnerabilities
npm audit
Legacy Custom Tool

Note: The custom CLI tool from the original post is no longer necessary with modern npm versions, but you can still find it in the GitHub repository if interested.

Wrapping Up
npm’s built-in commands now provide robust dependency management features right out of the box. What’s your favorite npm command for managing dependencies? Share below!
Baamaapii 👋

PSR	Topic	Post
1	Basic Coding Standard	Read
3	Logger Interface	Read
4	Autoloading Standard	Read
6	Caching Interface	Read
7	HTTP Messages	Read
11	Container Interface	Read
12	Extended Coding Style	Read
13	Hypermedia Links	Read
14	Event Dispatcher	Read
15	HTTP Handlers	Read
16	Simple Cache	Read
17	HTTP Factories	Read
18	HTTP Client	Read
20	Clock	Read

Web Developer Blog

Start developing with Laravel on Ubuntu 24.04 LTS

Prerequisites

Official method: PHP, Composer, and Laravel installer

Create the application

Verify it works

Alternatively: DDEV method

coaudit: AI-Powered Code Audits with GitHub Copilot CLI

What I Built

How It Works

Why This Matters

Demo

Quick Start

Example Output

Real Copilot Integration

My Experience with GitHub Copilot CLI

Why Copilot CLI Was Essential

The Development Journey

Key Features Enabled by Copilot CLI

What I Learned

Challenges & Solutions

The Meta Moment

Why coaudit Matters for Teams

What’s Next

Thanks to GitHub Copilot CLI

Using Laravel Boost With DDEV

Prerequisites

Install Boost

Configure the MCP Server

Standard Setup (Linux / macOS)

WSL Setup (Windows)

Verify It Works

Keeping Boost Updated

Drift in Cursor AI Rules

Problem

Example

Solution

Payoff

CORS: Understanding Cross-Origin Resource Sharing

Why CORS Exists

Understanding Origins

Implementing CORS

Security Best Practices

Key Takeaways

PSR-20: Clock Interface in PHP

What Problem Does PSR-20 Solve? (3 minutes)

Core Interface (3 minutes)

SystemClock

FrozenClock

Real-World Implementation (10 minutes)

Publishing a Post with Testable Time

Cache TTL with Testable Time

Scheduled Publishing

Common Mistakes and Fixes

1. Using new \DateTime() Instead of the Clock

2. Making the Clock Optional

3. Using time() or date() Functions

Testing with PSR-20 (5 minutes)

Symfony’s Clock Component

Try It Yourself

Series Wrap-Up

Resources

PSR-18: HTTP Client in PHP

What Problem Does PSR-18 Solve? (3 minutes)

Core Interface (5 minutes)

Exception Interfaces

Real-World Implementation (10 minutes)

The Decoupled Fetcher

Swapping Implementations

Testing with a Mock Client

Common Mistakes and Fixes

1. Catching \Exception Instead of PSR-18 Exceptions

2. Not Using PSR-17 to Create Requests

3. Ignoring Response Status Codes

Framework Integration

Guzzle

Symfony HttpClient

Try It Yourself

What’s Next

Resources

1. Using `new \DateTime()` Instead of the Clock

3. Using `time()` or `date()` Functions

1. Using `has()` Then `get()` (Race Condition)

1. Forgetting to Call `$handler->handle()`

Blog

Stay Updated