What is interface segregation?

“many client-specific interfaces are better than one general-purpose interface.”

class MySQLi {
    function __construct($host, $username, $password,
        $dbname, $port) { ... }
}  

class S3Client { 
    static function factory(array $config) { ... }
}

class MySQLi {
  function __construct($host, $username, $password,
        $dbname, $port) {...}
}  
  
//oops - forget to set password, dbname and port
$db = new MySQLi('localhost', 'db_user');
  
  

class S3Client { 
    static function factory(array $config) { ... }
}
  
// Spelling is hard
$config['passwrod'] = '12345';
S3Client::factory($config);

We're going to refactor some code!

Mock objects allow easier testing

function testFoo()
{
   $mock = Mockery::mock(Request::class);
      ->shouldReceive('getUri')
      ->andReturn('/search')
      ->getMock();
  
    foo($mockObject);
    // If foo doesn't call '$mock->getUri()'
    // the test will fail
}

use Psr\Http\Message\ServerRequestInterface 
      as Request;
      
class SearchController
{
    function search(Request $request, ...)
    {
       ...
    }
}

interface ServerRequestInterface extends RequestInterface
{
    public function getServerParams();
    public function getCookieParams();
    public function withCookieParams(array $cookies);
    public function getQueryParams();
    public function withQueryParams(array $query);
    public function getUploadedFiles();
    public function withUploadedFiles(array $uploadedFiles);
    public function getParsedBody();
    public function withParsedBody($data);
    public function getAttributes();
    public function getAttribute($name, $default = null);
    public function withAttribute($name, $value);
    public function withoutAttribute($name);
}

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);
}

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);
}

Creating a mock ...?

function testSearchController()
{
    $request = \Mockery::mock(Request::class)
      ->shouldReceive(???)
      ->andReturn(???)
      ->getMock();
 
    ...
    ...
}

class SearchController
{
   function search(Request $request, DataSource $dataSource) 
   {
      $queryParams = $request->getQueryParams();
      if (!array_key_exists('searchTerms', $queryParams)) {
         throw new ParamsMissingException("...");
      }
      $searchTerms = $queryParams['searchTerms'];

      $searchOptions = [];
      $searchOptions['keywords'] = explode(',', $searchTerms);
      return $dataSource->searchForItems($searchOptions);
   }
}

//class SearchController
//{
// function search(Request $request, DataSource $dataSource) 
// {
      $queryParams = $request->getQueryParams();
      if (!array_key_exists('searchTerms', $queryParams)) {
         throw new ParamsMissingException("...");
      }
      $searchTerms = $queryParams['searchTerms'];

//    $searchOptions = [];
//    $searchOptions['keywords'] = explode(',', $searchTerms);
//    return $dataSource->searchForItems($searchOptions);
//  }
//}
  

Extracting a type

interface VariableMap
{
    /**
     * @throws ParamMissingException
     */
    public function getVariable(string $variableName) : string;
}

    class PSR7VariableMap implements VariableMap {
    /** @var ServerRequestInterface */
    private $serverRequest;

    public function __construct(ServerRequestInterface $serverRequest) {
        $this->serverRequest = $serverRequest;
    }

    public function getVariable(string $variableName) : string {
        $queryParams = $this->serverRequest->getQueryParams();
        if (array_key_exists($variableName, $queryParams) === false) {
            $message = "Parameter [$variableName] is not available";
            throw new ParamMissingException($message);
        }

        return $queryParams[$variableName];
    }
}

Controller is now simpler, and more reasonable

class SearchController
{
// function search(Request $request, DataSource $dataSource) 
   function search(VariableMap $variableMap, DataSource $dataSource)
   {
      $searchTerms = $variableMap->getVariable('searchTerms');
      // $queryParams = $request->getQueryParams();
      // if (!array_key_exists('searchTerms', $queryParams)) {
      //    throw new ParamsMissingException("...");
      // }
      // $searchTerms = $queryParams['searchTerms'];
      $searchOptions = [];
      $searchOptions['keywords'] = explode(',', $searchTerms);

      return $dataSource->searchForItems($searchOptions);
   }
}

I hate strongly dislike mocks

• Mocks should only be used when you have to test behaviour
• Stubs/fakes are much easier to use
• Stubs/fakes suffer from poor marketing...

Stub implementation of VariableMap

class ArrayVariableMap implements VariableMap {
  public function __construct(array $variables) {
    $this->variables = $variables;
  }

  public function getVariable(string $variableName) : string {
    if (!array_key_exists($variableName, $this->variables)) {
        $message = "Parameter [$variableName] is not available";
        throw new ParamMissingException($message);
    }

    return $this->variables[$variableName];
  }
}

Fake implementation of DataSource

 interface DataSource {
     function searchForItems(array $searchOptions);
 }

 class EchoDataSource implements DataSource {
     function searchForItems(array $searchOptions) {
         return $searchOptions;
     }
 }

Testing the controller, success case

  function testSearchControllerWorks()
{
    $varMap = new ArrayVariableMap(
        ['searchTerms' => 'foo,bar']
    );
    // EchoDataSource just returns the keywords searched
    $dataSource = new EchoDataSource(); 

    $controller = new SearchController();
    $result = $controller->search($varMap, $dataSource);
    $this->assertEquals(['foo', 'bar'], $result);
} 

Testing the controller, error case

  
function testSearchControllerException()
{
    $varMap = new ArrayVariableMap([]);
    $dataSource = new EchoDataSource();

    $controller = new SearchController();
    $this->setExpectedException('ParamMissingException');
    $controller->search($varMap, $dataSource);
}
  

We want to limit number of items

class SearchController
{
  function search(DataSource $dataSource, VariableMap $variableMap)
  {
    $searchTerms = $variableMap->getVariable('searchTerms');
    $searchOptions = [];
    $searchOptions['keywords'] = explode(',', $searchTerms);
    // limit added to $searchOptions
    $searchOptions['limite'] = 50;

    return $dataSource->searchForItems($searchOptions);
  }
}

Extracting a type

  
class SearchOptions
{
    public $keywords;
    public $limit;

    public function __construct(array $keywords, int $limit = 1000)
    {
        //@TODO - check $keywords are all strings
        $this->keywords = $keywords;
        $this->limit = $limit;
    }
}

class SearchController
{
    function search(VariableMap $variableMap, DataSource $dataSource)
    {
        $searchTermsString = $variableMap->getVariable('searchTerms');  
        // $searchOptions = [];
        // $searchOptions['keywords'] = explode(',', $searchTerms);
        // $searchOptions['limite'] = 50; // LIMIT added
        $searchTermsArray = explode(',', $searchTermsString);
        $searchOptions = new SearchOptions($searchTermsArray, 50);

        return $dataSource->searchForItems($searchOptions);
    }
}

Use semantically meaningful types

function writeTempFile(string $tmpPath) {
    ...
    file_put_contents($tmpPath.'/foo.txt', $data);
    ...
}
function writeImageTempFile(string $tmpPath) {
    ...
    file_put_contents($tmpPath.'/foo.png', $imageData);
    ...
}

class TmpPath
{
    private $path;

    public function __construct(string $tmpPath)
    {
        $this->path = $tmpPath;
    }

    public function getPath()
    {
        return $this->path;
    }
}

Use semantically meaningful types

function writeTempFile(TmpPath $tmpPath)
{
    ...
    file_put_contents($tmpPath->getPath().'/foo.txt', $data);
    ...
}

function writeImageTempFile(ImageTmpPath $tmpPath)
{
    ...
    file_put_contents($tmpPath->getPath().'/foo.png', $imageData);
    ...
}

Compare SOLID code

function badCode($userId)
{
    global $session;
    $userId = $session->getUserId();

    return User::find($userId);
}

function solidCode(Session $session, UserRepo $userRepo) 
{
    $userId = $session->getUserId();

    return $userRepo->find($session->getUserId());
}

Compare SOLID code

badCode(); // This is easy to call

$session = new FileSession("/var/php/sessions", $request);
$userRepo = new UserSqlRepo($pdo);

solidCode($logger, $userRepo); // This is harder to call

Designing good interfaces is hard

Business (aka domain) interfaces

• Emerge from your application.
• Probably not reusable.
• Provide a large amount of value.

Not just services - also data

$emailSender->send(
    $user->getName(),
    $user->getEmailAddress()
);

$emailSender->send(
    null,
    $signupFormData->getEmailAddress()
);

Extract a type

interface EmailRecipient {
  public function getName(): ?string;
  public function getEmailAddress(): string;
}

Extract a type

class UserEmailRecipient implements EmailRecipient {

  private $user;

  function __construct(User $user) {
    $this->user = $user;
  }

  public function getName(): ?string {
    return $this->user->getName();
  }

  public function getEmailAddress(): string {
    return $this->user->getEmailAddress();
  }
}

Extract a type

class SignupEmailRecipient implements EmailRecipient {

  private $formData;

  function __construct(SignupFormData $signupFormData) {
   $this->formData = $signupFormData;
  }

  public function getName(): ?string {
    return null;
  }

  public function getEmailAddress(): string {
    return $this->formData->getEmailAddress();
  }
};

Not just services - also data

$emailSender->send(
  new UserEmailRecipient($user)
);

$emailSender->send(
  new SignupEmailRecipient($signupFormData)
);

Avoid big interfaces

interface FileUploader {
    function upload($localFilename, $storageName);
}

Avoid big interfaces

interface FileTransfer {
    function upload($localFilename, $storageName);
    function download($localFilename, $storageName);
}
 

Avoid big interfaces

interface FileTransfer {
    function upload($localFilename, $storageName);
    function download($localFilename, $storageName);
    function fileExists($storageName);
}

And so it grows...

Breakup big interfaces

interface FileUploader {
    function upload($localFilename, $storageName);
}

interface FileDownloader {
    function download($localFilename, $storageName);
}

interface FileChecker {
    function fileExists($storageName);
}

interface FileTransfer extends FileUploader, FileDownloader { }

class S3FileManager implements 
    FileUploader, 
    FileDownloader, 
    FileChecker
{
   ...
}

function foo(FileTransfer $fileTransfer) {
  ...
}

class S3FileTransfer extends S3FileManager
    implements FileTransfer {
  // empty - just used for declaring interface
}
  
foo(new S3FileTransfer(...));

How does this code make you feel?

class ArrayVariableMap implements VariableMap
{
    public function __construct(array $variables)
    {
        $this->variables = $variables;
    }

    public function getVariable(string $variableName) : string
    {
        if (array_key_exists($variableName, $this->variables) === false) {
            $message = "Parameter [$variableName] is not available";
            throw new ParamMissingException($message);
        }

        return $this->variables[$variableName];
    }
}

Context objects

function backupDB(DB $liveDb, DB $archiveDb) {

}

When people give talks on the "S.O.L.I.D." design principles one of the letters that doesn't get enough attention is the "i" - the "interface segregation principle". This talk seeks to redress that imbalance by going into a bit more in-depth into:

• An introduction to interface segregation and an explanation of how it make your code easier to test.
• Why in PHP we need to apply the principle more broadly, to make types be more specific, so that code is more reasonable.
• Me babbling on about emotions, and how good code is boring. Which is good!

“For years there has been a theory that millions of monkeys typing at random on millions of typewriters would reproduce the entire works of Shakespeare. The Internet has proven this theory to be untrue.”

Object-oriented programming is an exceptionally bad idea which could only have originated in California — Edsger W. Dijkstra