PSR – Standardy programowania z przykładami

PHP Standards Recommendations (PSR) to zbiór wytycznych i standardów programowania dla języka PHP. Są tworzone i utrzymywane przez grupę programistów związanych z PHP Framework Interop Group (PHP-FIG). PHP-FIG to organizacja non-profit, składająca się z różnych grup programistów i firm, których celem jest rozwijanie i promowanie interoperacyjności między różnymi frameworkami i bibliotekami PHP.

W ramach PHP-FIG, członkowie zajmujący się PSR pracują nad opracowywaniem i aktualizowaniem standardów programowania dla języka PHP, aby ujednolicić praktyki i zachowania wśród różnych frameworków, bibliotek i projektów w PHP. PSR jest więc tworzony przez całą społeczność PHP-FIG, a poszczególne standardy opracowywane są przez różne grupy robocze, które reprezentują różne aspekty programowania w PHP.

Dlaczego warto używać PSR?

Używanie standardów PSR (PHP Standard Recommendations) jest korzystne z kilku powodów:

1. Ujednolicenie stylu kodowania – dzięki zastosowaniu standardów PSR, kodowanie staje się bardziej jednolite i przejrzyste, co ułatwia pracę programistom i zwiększa czytelność kodu.
2. Zwiększenie przenośności – stosowanie standardów PSR ułatwia przenoszenie kodu między różnymi projektami, bibliotekami i frameworkami, co jest szczególnie ważne w większych projektach.
3. Wspólna baza wiedzy – stosowanie standardów PSR umożliwia programistom korzystanie z wiedzy i doświadczenia innych członków społeczności PHP, co przyspiesza proces nauki i poprawia jakość kodu.

Jak nauczyć się PSR oraz jak pamiętać je stosować?

Aby nauczyć się standardów PSR, należy przede wszystkim zapoznać się z dokumentacją dotyczącą danego standardu i zastosować jego zasady w swoim kodzie. Warto również korzystać z narzędzi, takich jak codeSniffer, które pomagają weryfikować, czy kod spełnia wymagania standardów PSR. Kolejnym sposobem na nauczenie się standardów PSR jest analiza kodu źródłowego projektów, które je stosują.

Zaakceptowane zalecenia PSR od PHP-FIG

Ok, lećmy teraz po więcej szczegółów każdy standard:

PSR-1: Basic Coding Standard

PSR-1 (PHP Standard Recommendation) to standard dotyczący nazewnictwa klas, interfejsów, stałych i funkcji w języku PHP. Jego celem jest ujednolicenie stylu kodowania w projekcie oraz ułatwienie pracy programistom, którzy korzystają z różnych bibliotek i frameworków.

Poniżej znajdują się przykłady zastosowania standardu PSR-1 w PHP:

1. Nazewnictwo klas i interfejsów powinno być zgodne z camelCase, gdzie pierwsza litera każdego słowa jest wielka:

interface MyInterface
{
    // ...
}

class MyClass
{
    // ...
}

2. Nazwy stałych powinny być pisane wielkimi literami i oddzielone podkreślnikami:

const MY_CONSTANT = 'value';

3. Nazewnictwo funkcji powinno być zgodne z camelCase, gdzie pierwsza litera każdego słowa jest wielka:

function myFunction()
{
    // ...
}

4. Wszystkie pliki PHP powinny zaczynać się od znacznika <?php i nie powinny zawierać znacznika ?> na końcu:

<?php
// kod pliku

5. Wszystkie pliki PHP powinny używać jednego z trzech standardów końca linii: Unix (\n), Windows (\r\n) lub Macintosh (\r).

Standard PSR-1 dotyczy również innych kwestii, takich jak stosowanie wcięć, używanie spacji przed i po operatorach, itp. Jednak powyższe przykłady pokazują najważniejsze zasady dotyczące nazewnictwa w języku PHP.

PSR-3: Logger Interface

Standard PSR-3 dotyczy jednolitego interfejsu loggera w języku PHP. Standard ten określa sposoby, w jakie aplikacje powinny zapisywać i przetwarzać logi, aby były bardziej przejrzyste i łatwiejsze w analizie.

Głównym celem standardu PSR-3 jest ujednolicenie interfejsu loggera, tak aby kod napisany w jednym projekcie mógł korzystać z loggera zaimplementowanego w innym projekcie, co ułatwia przenoszenie i łączenie kodu.

Standard PSR-3 definiuje interfejs LoggerInterface, który zawiera 8 metod:

• emergency($message, array $context = array())
• alert($message, array $context = array())
• critical($message, array $context = array())
• error($message, array $context = array())
• warning($message, array $context = array())
• notice($message, array $context = array())
• info($message, array $context = array())
• debug($message, array $context = array())

Każda z tych metod przyjmuje dwa parametry: $message, który zawiera treść logowanego komunikatu, oraz opcjonalny parametr $context, który zawiera dodatkowe informacje, np. zmienne, nazwy plików itp.

Przykładowa implementacja interfejsu LoggerInterface w PHP może wyglądać następująco:

use Psr\Log\LoggerInterface;

class MyLogger implements LoggerInterface
{
    public function emergency($message, array $context = array())
    {
        // implementacja metody emergency
    }

    public function alert($message, array $context = array())
    {
        // implementacja metody alert
    }

    // implementacje pozostałych metod
}

W powyższym przykładzie klasa MyLogger implementuje interfejs LoggerInterface i definiuje implementacje wszystkich 8 metod zgodnie z wymaganiami standardu PSR-3.

PSR-4: Autoloader

Standard PSR-4 dotyczy autoloadingu klas w języku PHP. Autoloading klas polega na dynamicznym ładowaniu klas w trakcie działania aplikacji, co eliminuje potrzebę ręcznego importowania i ładowania plików z klasami typu include czy require.

Głównym celem standardu PSR-4 jest ujednolicenie sposobu, w jaki klasy są ładowane w aplikacjach PHP. Standard określa konwencję nazewnictwa plików i katalogów, co pozwala na automatyczne ładowanie klas bez konieczności ręcznego importowania.

Według standardu PSR-4, nazwa klasy jest równa nazwie pliku, a przestrzenie nazw odpowiadają katalogom. Na przykład klasa MyClass w przestrzeni nazw MyNamespace powinna znajdować się w pliku MyClass.php w katalogu MyNamespace/.

Przykładowa implementacja autoloadera zgodnego z PSR-4 w PHP może wyglądać następująco:

spl_autoload_register(function ($class) 
{
    // konwertowanie przestrzeni nazw na ścieżkę pliku
    $file = str_replace('\\', DIRECTORY_SEPARATOR, $class) . '.php';
    
    // szukanie pliku w katalogach zdefiniowanych przez PSR-4
    foreach ([
        'MyNamespace\\' => '/path/to/my/namespace',
        'AnotherNamespace\\' => '/path/to/another/namespace'
    ] as $prefix => $baseDir) {
        if (strpos($class, $prefix) === 0) {
            $path = $baseDir . DIRECTORY_SEPARATOR . substr($file, strlen($prefix));
            if (file_exists($path)) {
                require $path;
                return;
            }
        }
    }
});

W powyższym przykładzie autoloader przetwarza nazwę klasy i konwertuje ją na ścieżkę pliku, szuka pliku w katalogach zdefiniowanych przez PSR-4 i ładuje go, jeśli istnieje. Dzięki temu, zgodnie ze standardem PSR-4, klasy są ładowane automatycznie, bez potrzeby ręcznego importowania i ładowania plików.

PSR-6: Caching Interface

Standard PSR-6 określa interfejs dla implementacji Cache, czyli mechanizmu przechowywania danych w pamięci podręcznej w celu przyspieszenia dostępu do tych danych. PSR-6 definiuje interfejs i ogólne zachowanie dla obiektów Cache, umożliwiając w ten sposób programistom korzystanie z różnych implementacji Cache bez konieczności zmiany kodu aplikacji.

Główne cechy standardu PSR-6 to:

• Dostarczenie prostego, jednoznacznego interfejsu do przechowywania danych w pamięci podręcznej, który może być łatwo zaimplementowany w różnych środowiskach PHP.
• Określenie wspólnych zachowań dla wszystkich implementacji Cache, dzięki czemu kod aplikacji może być przenoszony między różnymi implementacjami Cache bez potrzeby zmiany kodu.
• Umożliwienie korzystania z zaawansowanych funkcji Cache, takich jak przestarzalność danych, ich usuwanie i wymuszanie aktualizacji.

Przykładowa implementacja interfejsu Cache zgodnego ze standardem PSR-6 w PHP może wyglądać następująco:

use Psr\Cache\CacheItemPoolInterface;
use Psr\Cache\CacheItemInterface;

class MyCache implements CacheItemPoolInterface
{
    private $cache = [];
    
    public function getItem($key)
    {
        if (!isset($this->cache[$key])) {
            return new CacheItem($key, false);
        }
        return $this->cache[$key];
    }
    
    public function getItems(array $keys = array())
    {
        $items = array();
        foreach ($keys as $key) {
            $items[] = $this->getItem($key);
        }
        return $items;
    }
    
    public function hasItem($key)
    {
        return isset($this->cache[$key]);
    }
    
    public function clear()
    {
        $this->cache = [];
        return true;
    }
    
    // inne metody interfejsu CacheItemPoolInterface
}

class CacheItem implements CacheItemInterface
{
    public function __construct(
    	private $key,
    	private $value,
    	private $isHit
    ) {
    }
    
    public function getKey()
    {
        return $this->key;
    }
    
    public function get()
    {
        return $this->value;
    }
    
    public function set($value)
    {
        $this->value = $value;
        return $this;
    }
    
    public function isHit()
    {
        return $this->isHit;
    }
    
    // inne metody interfejsu CacheItemInterface
}

W powyższym przykładzie MyCache implementuje interfejs CacheItemPoolInterface, który określa metody służące do pobierania i zapisywania danych w pamięci podręcznej. CacheItem implementuje interfejs CacheItemInterface, który określa metody służące do zarządzania pojedynczymi elementami pamięci podręcznej.

W implementacji MyCache, metoda getItem służy do pobierania pojedynczego elementu z pamięci podręcznej, getItems służy do pobierania wielu elementów naraz, hasItem służy do sprawdzania, czy element o podanym kluczu znajduje się w pamięci podręcznej, a clear służy do czyszczenia całej pamięci podręcznej.

Implementacja CacheItem przechowuje klucz, wartość i flagę isHit, która określa, czy element został znaleziony w pamięci podręcznej. Metoda get zwraca wartość elementu, a metoda set służy do zapisywania wartości do elementu.

Dzięki zastosowaniu standardu PSR-6, aplikacje napisane w PHP mogą korzystać z różnych implementacji Cache, bez konieczności zmiany kodu aplikacji. Standard ten ułatwia także pisanie testów jednostkowych i integracyjnych dla kodu korzystającego z mechanizmu Cache, ponieważ pozwala na łatwe zamiany różnych implementacji Cache w zależności od potrzeb.

PSR-7: HTTP Message Interface

Standard PSR-7 określa interfejsy dla obiektów reprezentujących zapytania i odpowiedzi HTTP w PHP. Interfejsy te pozwalają na tworzenie uniwersalnych narzędzi do obsługi żądań i odpowiedzi HTTP, które będą działać z różnymi frameworkami i bibliotekami.

Głównymi interfejsami w PSR-7 są Psr\Http\Message\RequestInterface i Psr\Http\Message\ResponseInterface. RequestInterface reprezentuje zapytanie HTTP, a ResponseInterface reprezentuje odpowiedź HTTP. Oba interfejsy posiadają wiele metod, takich jak getProtocolVersion(), getHeaders(), getBody(), withHeader(), itp., które umożliwiają operowanie na danych HTTP.

Standard PSR-7 zachęca do tworzenia niemodyfikowalnych obiektów reprezentujących zapytania i odpowiedzi HTTP. Oznacza to, że każda zmiana stanu obiektu powoduje utworzenie nowego obiektu, a nie modyfikację oryginału. Dzięki temu, obiekty te są bardziej przewidywalne i łatwiejsze do testowania.

Przykład implementacji PSR-7 w PHP to biblioteka Guzzle, która umożliwia tworzenie i wysyłanie zapytań HTTP zgodnie z tym standardem. Oto przykład kodu w PHP, który wykorzystuje interfejsy PSR-7 do tworzenia obiektu zapytania HTTP i przesyłania go z wykorzystaniem biblioteki Guzzle:

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

// Tworzenie obiektu URI
$uri = new Uri('https://api.example.com/path/to/resource');

// Tworzenie obiektu zapytania HTTP zgodnie z interfejsem PSR-7
$request = new Request('GET', $uri, ['User-Agent' => 'MyApp/1.0']);

// Tworzenie obiektu klienta HTTP
$client = new Client();

// Wysyłanie zapytania HTTP z wykorzystaniem biblioteki Guzzle
$response = $client->send($request);

// Odczytanie ciała odpowiedzi HTTP
$responseBody = $response->getBody()->getContents();

W powyższym przykładzie, obiekt zapytania Request i obiekt odpowiedzi Response są tworzone zgodnie z interfejsami PSR-7. Następnie, wykorzystując bibliotekę Guzzle, wysyłane jest zapytanie HTTP do serwera, a ciało odpowiedzi jest odczytywane z wykorzystaniem metody getBody().

PSR-11: Container Interface

Standard PSR-11 określa interfejs kontenera zależności w PHP. Kontenery zależności są narzędziami, które pozwalają na zarządzanie obiektami w aplikacji poprzez wstrzykiwanie ich w inne obiekty, co ułatwia tworzenie modułów i ułatwia testowanie.

Głównym interfejsem w PSR-11 jest Psr\Container\ContainerInterface. Ten interfejs definiuje metody takie jak get($id) i has($id), które pozwalają na pobieranie i sprawdzanie obiektów w kontenerze zależności.

Przykłady implementacji PSR-11 w PHP to biblioteki takie jak Symfony Dependency Injection, PHP-DI, czy Zend ServiceManager. Oto przykład kodu w PHP, który wykorzystuje interfejs PSR-11 do pobrania obiektu z kontenera zależności:

use Psr\Container\ContainerInterface;

class MyClass 
{
    private $dependency;
    
    public function __construct(ContainerInterface $container) 
    {
        // Pobieranie obiektu zależności z kontenera
        $this->dependency = $container->get('my_dependency');
    }
    
    public function doSomething() 
    {
        // Używanie obiektu zależności
        $this->dependency->someMethod();
    }
}

W powyższym przykładzie, klasa MyClass przyjmuje interfejs kontenera zależności ContainerInterface w swoim konstruktorze. Następnie, obiekt zależności o identyfikatorze my_dependency jest pobierany z kontenera w celu użycia w metodzie doSomething(). Dzięki takiemu podejściu, obiekt zależności może być łatwo zastąpiony przez inny, co ułatwia testowanie i rozwijanie aplikacji.

PSR-12: Extended Coding Style Guide

Najbardziej kojarzon standard PSR-12, określa zasady formatowania kodu w języku PHP. Określa on konkretne reguły dotyczące stylu pisania kodu, takie jak użycie białych znaków, nawiasów, wcięć, nazw zmiennych i funkcji, a także sposobu grupowania instrukcji.

Kilka przykładów zasad zdefiniowanych w PSR-12 to:

• Użyj czterech spacji do wcięcia bloków kodu.
• Używaj nawiasów klamrowych na nowej linii dla bloków kodu.
• Użyj camelCase dla nazw metod i pól.

Przykłady implementacji PSR-12 w PHP to biblioteki takie jak PHP_CodeSniffer, PHP-CS-Fixer, czy PHPMD. Oto przykład kodu PHP zgodny z zasadami PSR-12:

class ExampleClass
{
    public function exampleMethod($firstParameter, $secondParameter)
    {
        if ($firstParameter === $secondParameter) {
            $result = 'Parameters are equal.';
        } else {
            $result = 'Parameters are not equal.';
        }

        return $result;
    }
}

W powyższym przykładzie kodu, klasy i metody są napisane w stylu camelCase, a bloki kodu są wcięte za pomocą czterech spacji i używają nawiasów klamrowych na nowej linii. Ten kod jest zgodny z zasadami formatowania PSR-12.

WORK IN PROGRESS:

PSR-13: Hypermedia Links

PSR-14: Event Dispatcher

PSR-15: HTTP Handlers

PSR-16: Simple Cache

PSR-18: HTTP Client

Standard PSR-18: HTTP Client to zestaw interfejsów programistycznych (API) dla klientów HTTP w języku PHP. Celem jest umożliwienie zastępowania klientów HTTP zgodnie z zasadą zastępowania Liskov . Oznacza to, że wszyscy klienci MUSZĄ zachowywać się w ten sam sposób podczas wysyłania żądania. Zwiększy to możliwości wielokrotnego użytku bibliotek, ponieważ zmniejszy liczbę zależności i prawdopodobieństwo konfliktów wersji.

W skrócie, PSR-18 definiuje interfejs ClientInterface, który zawiera jedną metodę sendRequest(). Ta metoda przyjmuje obiekt Psr\Http\Message\RequestInterface reprezentujący żądanie HTTP i zwraca obiekt Psr\Http\Message\ResponseInterface reprezentujący odpowiedź HTTP.

Przykładowa implementacja klienta HTTP zgodna z PSR-18 może wyglądać tak:

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.
     *
     * @param RequestInterface $request
     *
     * @return ResponseInterface
     *
     * @throws \Psr\Http\Client\ClientExceptionInterface If an error happens while processing the request.
     */
    public function sendRequest(RequestInterface $request): ResponseInterface;
}

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

class MyHttpClient implements ClientInterface
{
    public function sendRequest(RequestInterface $request): ResponseInterface
    {
        // kod obsługi żądania HTTP
    }
}

Poniżej przykład użycia klienta HTTP zgodnego z PSR-18 do wykonania żądania GET na stronie internetowej:

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

// utworzenie klienta HTTP
$httpClient = new MyHttpClient();

// utworzenie fabryk żądań i URI
$requestFactory = new MyRequestFactory();
$uriFactory = new MyUriFactory();

// utworzenie obiektu URI reprezentującego adres strony
$uri = $uriFactory->createUri('http://example.com');

// utworzenie obiektu żądania GET z adresem strony
$request = $requestFactory->createRequest('GET', $uri);

// wysłanie żądania HTTP i pobranie odpowiedzi
$response = $httpClient->sendRequest($request);

// odczytanie zawartości odpowiedzi
echo $response->getBody()->getContents();

W powyższym przykładzie MyHttpClient to implementacja interfejsu ClientInterface, a MyRequestFactory i MyUriFactory to implementacje interfejsów RequestFactoryInterface i UriFactoryInterface odpowiednio. Metoda getContents() zwraca zawartość odpowiedzi HTTP jako ciąg znaków.

PSR-20: Clock

Standard PSR-20: Clock to zestaw interfejsów programistycznych (API) dla systemów zegarowych w języku PHP. Standard ten definiuje, jak programiści mogą używać zegarów systemowych lub symulowanych zegarów w swoich aplikacjach.

Interfejs Clock definiuje jedną metodę now(), która zwraca obiekt DateTimeImmutable reprezentujący aktualny czas zgodny z zegarem systemowym lub symulowanym. Można także użyć metody createFromTimestamp() do utworzenia obiektu DateTimeImmutable na podstawie znacznika czasu Unix.

Dzięki zastosowaniu interfejsu Clock w swoim kodzie, programiści mogą łatwo symulować czas w testach jednostkowych i uniknąć problemów związanych z manipulacją zegarem systemowym.

namespace Psr\Clock;

interface ClockInterface
{
    /**
     * Returns the current time as a DateTimeImmutable Object
     */
    public function now(): \DateTimeImmutable;

}