PSR Standards and PHP-FIG: Writing Interoperable PHP

Imagine you're building a PHP application that needs to send emails, handle payments, and generate PDFs. You find great libraries for each task, but they all have different coding styles, autoloading methods, and ways of handling HTTP requests. Integrating them becomes a nightmare of manual adjustments and compatibility hacks. This is exactly the problem the PHP Framework Interoperability Group (PHP-FIG) set out to solve with PSR (PHP Standards Recommendations) standards.

PHP-FIG is a group of PHP project representatives who collaborate to define common standards. By following PSRs, your code becomes predictable and interoperable with thousands of other PHP packages. Whether you're using a micro-framework or a full-stack CMS, PSR compliance ensures your code plays nicely with others.

In this tutorial, you'll learn the most important PSR standards: PSR-1 (basic coding standard), PSR-4 (autoloading), PSR-7 (HTTP message interfaces), and PSR-12 (extended coding style guide). We'll explore real-world examples, a production incident caused by ignoring PSR-4, and debugging techniques. By the end, you'll be able to write PHP code that any PSR-compliant project can consume.

What is PHP-FIG and Why PSR Standards Matter

PHP-FIG (PHP Framework Interoperability Group) is a collective of PHP project leaders who collaborate to create standards that promote interoperability. PSR (PHP Standards Recommendation) documents define these standards. Adopting PSRs ensures your code can work seamlessly with other PHP libraries and frameworks, reducing integration friction.

Let's start with the foundational standards.

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

PSR-1: Basic Coding Standard

PSR-1 defines basic coding elements to ensure a high level of technical interoperability. Key rules: - Files MUST use only <?php and <?= tags. - Files MUST use UTF-8 without BOM. - Namespaces and classes MUST follow PSR-4 autoloading. - Class names MUST be declared in StudlyCaps. - Class constants MUST be declared in UPPER_CASE with underscores. - Method names MUST be declared in camelCase.

Example:

<?php

namespace App;

class UserManager
{
    const MAX_LOGIN_ATTEMPTS = 5;

    public function getUserById(int $id): ?User
    {
        // implementation
    }
}

PSR-4: Autoloading Standard

PSR-4 describes a specification for autoloading classes from file paths. It maps fully qualified class names to file paths based on namespace prefixes. This eliminates the need for manual require/include statements.

Composer autoload configuration:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "Monolog\\": "vendor/monolog/monolog/src/"
        }
    }
}

PSR-7: HTTP Message Interfaces

PSR-7 standardizes HTTP messages (requests and responses) as objects. It defines interfaces for: - Psr\Http\Message\RequestInterface - Psr\Http\Message\ResponseInterface - Psr\Http\Message\ServerRequestInterface - Psr\Http\Message\StreamInterface - Psr\Http\Message\UriInterface

These interfaces allow frameworks and libraries to exchange HTTP data without coupling to specific implementations. For example, a middleware can modify a request object regardless of the underlying framework.

Example using Guzzle (PSR-7 compatible):

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

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

echo $response->getStatusCode(); // 200
echo $response->getBody(); // JSON body

PSR-12: Extended Coding Style Guide

PSR-12 extends PSR-2 (now deprecated) with modern PHP features. It covers: - Indentation: 4 spaces, no tabs. - Line length: soft limit 120 chars, hard limit 80 chars recommended. - Keywords: lowercase (true, false, null). - Braces: opening brace on same line for classes/methods, on new line for control structures. - Use declarations: one per line, alphabetically ordered. - Traits: one per line. - Anonymous classes: same as regular classes.

Example:

<?php

declare(strict_types=1);

namespace App;

use App\Interface\SomeInterface;
use App\Trait\SomeTrait;

class Example implements SomeInterface
{
    use SomeTrait;

    public function doSomething(): void
    {
        if (true) {
            echo 'Hello';
        }
    }
}

Other Important PSRs

Beyond the core standards, several other PSRs address specific concerns: - PSR-3: Logger Interface – standardizes logging (e.g., Monolog implements it). - PSR-6: Caching Interface – defines cache pool and item interfaces. - PSR-11: Container Interface – standardizes dependency injection containers. - PSR-14: Event Dispatcher – standardizes event handling. - PSR-18: HTTP Client – defines a client interface for sending PSR-7 requests.

Adopting these PSRs makes your code compatible with a vast ecosystem of packages. For example, using PSR-3 allows you to swap logging libraries without changing your code.

<?php

use Psr\Log\LoggerInterface;

class UserService
{
    private LoggerInterface $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function registerUser(array $data): void
    {
        // ...
        $this->logger->info('User registered', ['email' => $data['email']]);
    }
}