Understanding and Implementing PSR Workshop

Understanding
and
Implementing
PSR
Workshop

Mon 22 Aug 2016

Housekeeping

Wi-Fi (SSID and password)
PHP >= 5.5, preferrably 7.0 :)
Composer - https://getcomposer.org
Web server (optional)
- Apache
- XAMPP, MAMP, EasyPHP
No laptop?? Pen and paper!

Notes on installing PHP for Windows/Mac/Ubuntu:
bit.ly/zn-psr

Workshop Agenda

What is PSR?
PSR-0: Autoloading Standard
PSR-1: Basic Coding Standard
PSR-2: Coding Style Guide
PSR-4: Autoloading Standard (again?)
PSR-7: HTTP Message Interface

What is PSR?

PHP Standards Recommendation
proposed by the PHP Framework Interoperability Group (FIG)
http://www.php-fig.org/

Credits: https://xkcd.com/927

Common terminology in PSRs

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

PSR-0: Autoloading Standard

In the beginning

<?php // login.php
$conn = new mysqli('localhost', 'username', 'password'); // Database connection
if (!$conn) { die('Connection failed: ' . mysqli_connect_error()); }

if (isset($_POST['submit'])) { // Check form submit
    $user = $_POST['user'];
    $pass = $_POST['pass'];
    $result = $conn->query(
        "SELECT * FROM user WHERE username='{$user}' AND password='{$pass}'"
    );
    header('Location:' . (mysqli_num_rows($result) > 0 ? 'ok.php' : 'fail.php'));
    exit;
}
?>
<form method="POST">
  Username: <input type="text" name="user"><br />
  Password: <input type="password" name="pass"><br />
  <input type="submit" />
</form>

Later, include files with common functions

<?php // login.php
include 'connection.php';
include 'functions.php';

if (isset($_POST['submit'])) { // Check form submit
    $user = $_POST['user'];
    $pass = $_POST['pass'];
    header('Location: ' . (isLoginValid($user, $pass) ? 'ok.php' : 'fail.php'));
    exit;
}
?>
<form>
  Username: <input type="text" name="user"><br />
  Password: <input type="password" name="pass"><br />
  <input type="submit" />
</form>

Classes and Namespaces

<?php // Foo.php
class Foo {}

<?php // libraries/Foo/Bar.php
namespace Foo;

class Bar {}

<?php // libraries/Baz/Qux.php
namespace Baz;

use Foo\Bar;

class Qux {
    function __construct() { $bar = new Bar; }
}

spl_autoload_register('autoload');

Mandatory

A fully-qualified namespace and class must have the following structure
```
\<Vendor Name>$<Namespace>$*<Class Name>
```
Each namespace must have a top-level namespace ("Vendor Name").
Each namespace can have as many sub-namespaces as it wishes.

$object = new Foo\Bar\Baz\Qux;

Mandatory

Each namespace separator is converted to a
```
DIRECTORY_SEPARATOR
```
when loading from the file system.
Each
```
_
```
character in the CLASS NAME is converted to a
```
DIRECTORY_SEPARATOR
```
. The
```
_
```
character has no special meaning in the namespace.
The fully-qualified namespace and class is suffixed with
```
.php
```
when loading from the file system.
Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case.

Examples

\Doctrine\Common\IsolatedClassLoader

/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php

\Symfony\Core\Request

/path/to/project/lib/vendor/Symfony/Core/Request.php

\Zend\Acl

/path/to/project/lib/vendor/Zend/Acl.php

\Zend\Mail\Message

/path/to/project/lib/vendor/Zend/Mail/Message.php

Underscores in Namespaces and Class Names

\namespace\package\Class_Name

/path/to/project/lib/vendor/namespace/package/Class/Name.php

\namespace\package_name\Class_Name

/path/to/project/lib/vendor/namespace/package_name/Class/Name.php

Demo

Lab Practice

<?php // vendor/autoload.php

function autoload($className)
{
    // Resolve filename for $className based on PSR-0
    // Load the class file
}

spl_autoload_register('autoload');

bit.ly/zn-psr0

PSR-1: Basic Coding Standard

Method Names

function foobar()
function foo_bar()
function fooBar()
function Foobar()
function FooBar()
function FOOBAR()

Files

Files MUST use only
```
<?php
```
and
```
<?=
```
tags.
Files MUST use only UTF-8 without BOM for PHP code.
Files SHOULD either declare symbols or cause side-effects but SHOULD NOT do both.

<?php // example to avoid
ini_set('error_reporting', E_ALL); // side effect: change ini settings
include "file.php"; // side effect: loads a file
echo "<html>\n"; // side effect: generates output

// declaration
function foo()
{
    // function body
}

Namespaces and Class Names

Namespaces and classes MUST follow an "autoloading" PSR: [PSR-0, PSR-4].
Class names MUST be declared in
```
StudlyCaps
```
.

<?php // PHP 5.3 and later
namespace Vendor\Model;

class Foo
{
}

<?php // PHP 5.2.x and earlier
class Vendor_Model_Foo
{
}

Class Constants, Properties, and Methods

Class constants MUST be declared in all upper case with underscore separators.
Method names MUST be declared in
```
camelCase
```
.

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';

    public function myMethodName()
    {
        // method body
    }
}

PSR-2: Coding Style Guide

Extends PSR-1
A lot of opinions...
Survey results available

<?php
namespace Vendor\Package;

use FooInterface;
use OtherVendor\OtherPackage\BazClass as Bar;

class Foo extends Bar implements FooInterface
{
    public function sampleFunction($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
    }
}

http://www.php-fig.org/psr/psr-2/#a-2-survey-legend

indent_type:
    tab: 7
    2: 1
    4: 14
line_length_limit_soft:
    ?: 2
    no: 3
    75: 4
    80: 6
    85: 1
    100: 1
    120: 4
    150: 1
line_length_limit_hard:
    ?: 2
    no: 11
    85: 4
    100: 3
    120: 2
class_names:
    ?: 1
    lower: 1
    lower_under: 1
    studly: 19
class_brace_line:
    next: 16
    same: 6

constant_names:
    upper: 22
true_false_null:
    lower: 19
    upper: 3
method_names:
    camel: 21
    lower_under: 1
method_brace_line:
    next: 15
    same: 7
control_brace_line:
    next: 4
    same: 18
control_space_after:
    no: 2
    yes: 20
always_use_control_braces:
    no: 3
    yes: 19
else_elseif_line:
    next: 6
    same: 16
case_break_indent_from_switch:
    0/1: 4
    1/1: 4
    1/2: 14

function_space_after:
    no: 22
closing_php_tag_required:
    no: 19
    yes: 3
line_endings:
    ?: 5
    LF: 17
static_or_visibility_first:
    ?: 5
    either: 7
    static: 4
    visibility: 6
control_space_parens:
    ?: 1
    no: 19
    yes: 2
blank_line_after_php:
    ?: 1
    no: 13
    yes: 8
class_method_control_brace:
    next/next/next: 4
    next/next/same: 11
    next/same/same: 1
    same/same/same: 6

Lab Practice!

<?php // check.php

function check($filename)
{
    // Given a PHP file, check that it complies with PSR-2
    // For each error, output the line number and simple error message
    // You can use the shortcodes in the survey results
}

bit.ly/zn-psr2

CS Fixers out there

PHP Coding Standards Fixer by SensioLabs
PHP CodeSniffer
Integrate Travis CI for GitHub repository - see repo status and .travis.yml

PSR-4: Autoloading Standard (again??)

Why bother?

PSR-0 was based on Horde/PEAR convention under the constraints of PHP 5.2 and previous
The PEAR installer moved source files from PEAR packages into 1 central directory
With Composer, package sources are used from their installed location, no moving around, no central directory

http://www.php-fig.org/psr/psr-4/meta/

vendor/
    vendor_name/
        package_name/
            src/
                Vendor_Name/
                    Package_Name/
                        ClassName.php     # Vendor_Name\Package_Name\ClassName
            tests/
                Vendor_Name/
                    Package_Name/
                        ClassNameTest.php # Vendor_Name\Package_Name\ClassNameTest

vendor/
    vendor_name/
        package_name/
            src/
                ClassName.php     # Vendor_Name\Package_Name\ClassName
            tests/
                ClassNameTest.php # Vendor_Name\Package_Name\ClassNameTest

Examples

PSR-7: HTTP Message Interface

The most exciting PSR!
The Future of PHP!

Credits to talk by Matthew Weier O'Phinney on
PSR-7 And Middleware

<?php // test.php?city=SG
if (isset($_POST['submit'])) {
    echo 'You typed: ' . $_POST['myText'];
}
?>
City: <?php echo ($_GET['city'] ?? 'None'); ?><br />
<form method="POST">
  Text: <input type="text" name="myText"><br />
  <input type="submit" />
</form>

<?php // localhost/city/SG
class TestController extends AbstractActionController
{
    public function indexAction()
    {
        $request = $this->getRequest();
        $usertext = $request->isPost() ? $request->getPost()['myText'] : '';
        return new ViewModel([
            'city' => $this->params('city', 'None'),
            'form' => new TestForm(),
            'usertext' => $usertext,
        ]);
    }
}

Guzzle, Buzz and more...

Abstract what?

Form post
Access $_SERVER variables
Extract request uri for routing purposes
Handle file uploads
Input and output streams
Returning of response

Credits: http://code.tutsplus.com/tutorials/http-the-protocol-every-web-developer-must-know-part-1--net-31177

Credits: http://wiki.hashphp.org/HttpPrimer

Every HTTP request message has a specific form:

POST /path HTTP/1.1
Host: example.com

foo=bar&baz=bat

HTTP response messages have a similar structure:

HTTP/1.1 200 OK
Content-Type: text/plain

This is the response body

MessageInterface

$headers = $message->getHeaders(); // [<headerName> => <array>]

$headerValues = $message->getHeader('Cookie'); // array, may be more than 1

$headerLine = $message->getHeaderLine('Accept'); // string

$body = $message->getBody(); // StreamInterface

$newMessage = $message->withHeader('Content-Type', 'application/json');

$newerMessage = $newMessage->withBody($body->getContents() . 'appended content');

RequestInterface

$method = $request->getMethod(); // GET, POST, etc.

$uri = $request->getUri(); // UriInterface

$body = new Stream();
$body->write('{"id":1}');

$newRequest = $request
              ->withMethod('GET')
              ->withUri('http://example.com/api/v1/users')
              ->withHeader('Accept', 'application/json')
              ->withBody($body);

ResponseInterface

$status = $response->getStatusCode(); // 200, 404, 500

$reason = $response->getReasonPhrase(); // OK, Not Found, Server Error

$data = json_decode((string) $response->getBody(), true);
$data['timestamp'] = gmdate('c');

$newResponse = $response->withBody(json_encode($data));
$newerResponse = $newResponse->withStatus(200);

ServerRequestInterface

$queryParams = $request->getQueryParams();

$parsedBody = $request->getParsedBody(); // deserialized body params

$uploadedFiles = $request->getUploadedFiles(); // array of UploadedFileInterface

// Get `id` passed from route, eg. localhost/user/100.
// Application must parse route and inject into request attributes
$id = $request->getAttribute('id'); // 100

StreamInterface

interface StreamInterface
{
    public function __toString(); // important
    public function close();
    public function detach();
    public function getSize();
    public function tell();
    public function eof();
    public function isSeekable();
    public function seek($offset, $whence = SEEK_SET);
    public function rewind();
    public function isWritable();
    public function write($string);
    public function isReadable();
    public function read($length);
    public function getContents();
    public function getMetadata($key = null);
}

File Uploads with $_FILES

[
    'files' => [
        0 => [
            'name' => 'file0.txt',
            'type' => 'text/plain',
            /* etc. */
        ],
        1 => [
            'name' => 'file1.html',
            'type' => 'text/html',
            /* etc. */
        ],
    ],
];

File Uploads with $_FILES

[ // This is what $_FILES in PHP gives us :P
    'files' => [
        'name' => [
            0 => 'file0.txt',
            1 => 'file1.html',
        ],
        'type' => [
            0 => 'text/plain',
            1 => 'text/html',
        ],
        /* etc. */
    ],
];

UploadedFileInterface

$uploadedFiles = $request->getUploadedFiles(); // array of UploadedFileInterface

foreach ($uploadedFiles as $file) {
    echo $file->getClientFilename() . ', ' . $file->getClientMediaType();
    $size = $file->getSize();
    $contents = $file->getStream(); // StreamInterface
    $file->moveTo($newFilePath);
}

// Printout:
//   file0.txt, text/plain
//   file1.txt, text/html

What's in an URI?

                    authority               path
        ┌───────────────┴───────────────┐┌───┴────┐
 http://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
 └─┬┘   └───────┬───────┘ └────┬────┘ └┬┘           └─────────┬─────────┘ └──┬──┘
scheme  user information     host     port                  query         fragment

Credits: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Examples

Trying to compose a URI via $_SERVER

array( // not all variables shown here
  'HTTP_HOST' => 'localhost',
  'HTTP_ACCEPT' => 'text/html,application/xhtml+xml',
  'SERVER_NAME' => 'localhost',
  'SERVER_ADDR' => '127.0.0.1',
  'SERVER_PORT' => '80',
  'REMOTE_ADDR' => '127.0.0.1',
  'REQUEST_SCHEME' => 'http',
  'REMOTE_PORT' => '53746',
  'SERVER_PROTOCOL' => 'HTTP/1.1',
  'REQUEST_METHOD' => 'GET',
  'QUERY_STRING' => 'key1=value1',
  'REQUEST_URI' => '/test.php?key1=value1',
  'SCRIPT_NAME' => '/test.php',
  'PHP_SELF' => '/test.php',
  'REQUEST_TIME' => 1470751673,
)

UriInterface

$uri = $request->getUri();
$scheme   = $uri->getScheme();
$userInfo = $uri->getUserInfo();
$host     = $uri->getHost();
$port     = $uri->getPort();
$path     = $uri->getPath();
$query    = $uri->getQuery();
$fragment = $uri->getFragment();
$newUri   = $uri->withHost('example.com');

Lab Practice!

bit.ly/zn-psr7

Middleware

Zend Expressive

PSR-7 Middleware in Minutes
Try it today!