The quest for global design principles (SymfonyLive Berlin 2015)
5 likes3,841 views
The document discusses principles for designing stable and effective inter-object and inter-application communication, emphasizing stability, information integrity, and the importance of keeping implementation details hidden. Key topics include API backward compatibility, semantic versioning, knowledge management, immutability, and the design of discoverable APIs. The overall aim is to enhance system communication and reduce the risks associated with unstable dependencies and duplication of knowledge.
![$uri ='/accounts/deposit/';
$data = json_encode([
'accountId' => 123
'currency' => 'EUR',
'amount' => 20000
]);
$httpClient
->createRequest('PUT', $uri, $data)
->send();
Translation
Prepare the
message
Send the message](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-18-320.jpg)
![/** @Route("/accounts/deposit") */
function depositAction(Request $request)
{
$request = json_decode($request->getContent());
$money = new Money(
$request['amount'],
$request['currency']
);
$this->get('account_service')->deposit(
$request['accountId'],
$money
);
return new Response(null, 200);
}
Translation
Prepare the
message
Send the message](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-19-320.jpg)
![// calculate the width of the nameplate
$nameplate = deserialize($xml);
$name = $nameplate['name'];
$width = strlen($name);
$widthPerCharacterInCm = 12;
$widthInCm = $width * $widthPerCharacterInCm;
// configure the nameplate machine ;)
Accepting messages
Duplication of knowledge](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-46-320.jpg)
![$nameplate = deserialize($xml);
$width = $nameplate['width'];
Accepting messages
No duplicate knowledge
anymore](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-48-320.jpg)
![class Person
{
/**
* @return PhoneNumber[]
*/
public function getPhoneNumbers() {
return $this->phoneNumbers;
}
}
Initial implementation](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-70-320.jpg)
![class Person
{
/**
* @return PhoneNumber[]
*/
public function getPhoneNumbers() {
return $this->phoneNumbers->toArray();
}
}
Hiding implementation](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-72-320.jpg)
![class NameplateController
{
function getAction($id) {
$nameplate = $this
->getDoctrine()
->getManager()
->getRepository(Nameplate::class)
->findOneBy(['id' => $id]);
if ($nameplate === null) {
throw new NotFoundHttpException();
}
...
}
}
More implementation hiding
Actual field names!
null or false?
"find"?](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-73-320.jpg)
![class NameplateRepository
{
function byId($id) {
$nameplate = $this
->findOneBy(['id' => $id]);
if ($nameplate === null) {
throw new NameplateNotFound($id);
}
return $nameplate;
}
}
Push it out of sight
Domain-specific exception
Hide specific return value
No "find"](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-74-320.jpg)
![[
'salt' => '...'
'cost' => 10
]
Options for bcrypt hashing](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-151015133538-lva1-app6892/85/The-quest-for-global-design-principles-SymfonyLive-Berlin-2015-86-320.jpg)
The quest for global design principles (SymfonyLive Berlin 2015)
- 3. Stability versus change • Backwards compatibility of APIs • Semantic versioning • HTTP status codes • XML schemas
- 6. The key is in the concept of communication ReceiverSender
- 7. What's being communicated? Message Type ("BookHotel") Value (“Golden Tulip", “15-10-2015", “16-10-2015”)
- 10. Sender Construct the message Message Translate Construct (Prepare for transport)
- 12. Global design principles can be discovered if we recognise the fact that communication between objects and applications are (more or less) equal
- 13. Communication between objects • Calling a function is like sending a message • The function and its parameters are the message type • The arguments constitute the value of the message
- 14. class AccountService { public function deposit($accountId, Money $amount) { ... } } Opportunity for sending a message Inter-object communication
- 15. $money = new Money(20000, 'EUR'); $userId = 123; $accountService->deposit( $userId, $money ); Translation The sender prepares the message for the receiver Prepare the message Send the message
- 16. Communication between applications • An HTTP request is a message • The HTTP method and URI are the type of the message • The HTTP request body constitutes the value of the message Or AMQP, Stomp, Gearman, ...
- 17. PUT /accounts/deposit/ HTTP/1.1 Host: localhost { "accountId": "123", "currency": "EUR", "amount": 20000 } Inter-application communication Opportunity for sending a message
- 18. $uri ='/accounts/deposit/'; $data = json_encode([ 'accountId' => 123 'currency' => 'EUR', 'amount' => 20000 ]); $httpClient ->createRequest('PUT', $uri, $data) ->send(); Translation Prepare the message Send the message
- 19. /** @Route("/accounts/deposit") */ function depositAction(Request $request) { $request = json_decode($request->getContent()); $money = new Money( $request['amount'], $request['currency'] ); $this->get('account_service')->deposit( $request['accountId'], $money ); return new Response(null, 200); } Translation Prepare the message Send the message
- 20. Global design principles Should be applicable to both inter-object and inter-application communication
- 21. Part I Stability III Implementation II Information
- 23. Stable Unstable What is safer? Unstable Stable OR
- 24. To be stable "Steady in position or balance; firm"
- 25. Irresponsible What makes something unstable? 1. Nothing depends on it It doesn't need to stay the same for anyone
- 26. Dependent What makes something unstable? 2. It depends on many things Any of the dependencies could change at any time
- 27. Stability is not a quality of one thing It emerges from the environment of that thing
- 28. Responsible What makes something stable? 1. Many things depend on it It has to stay the same, because change would break dependents
- 29. Independent What makes something stable? 2. It depends on nothing It is not affected by changes in anything
- 30. –The Stable dependencies principle Depend in the direction of stability
- 31. Stable package Unstable package What to do when this happens?
- 32. Stable package Depend on something that you own Unstable package Stable package
- 33. –The Dependency inversion principle Always depend on abstractions, not on concretions
- 34. Dependency inversion for objects • Depend on an interface instead of a class • Separate a task from its implementation
- 38. Dependency inversion for systems • Depend on your own (messaging) system • Communicate with other applications through a message queue
- 39. Part II Information I Stability III Implementation
- 41. Nameplate order system Nameplate machine Business automation for creating nameplates
- 42. <h1>You are about to order a nameplate!</h1> <p>Name on the plate: {{ name }}<br/> Width of the plate: {{ 12*(name|length) }} cm.</p> Calculating the width of a nameplate Knowledge
- 43. class Nameplate { private $name; function __construct($name) { $this->name = $name; } function widthInCm() { return strlen($this->name) * 12; } } Data object Knowledge is close to the subject
- 44. <h1>You are about to order a nameplate!</h1> <p>Name on the plate: {{ nameplate.name }}<br/> Width of the plate: {{ nameplate.widthInCm) }} cm.</p> No knowledge in the template
- 46. // calculate the width of the nameplate $nameplate = deserialize($xml); $name = $nameplate['name']; $width = strlen($name); $widthPerCharacterInCm = 12; $widthInCm = $width * $widthPerCharacterInCm; // configure the nameplate machine ;) Accepting messages Duplication of knowledge
- 47. <nameplate> <name>Ibuildings</name> <width>120</width> </nameplate> Deduplication Knowledge is in one place, facts can be everywhere
- 48. $nameplate = deserialize($xml); $width = $nameplate['width']; Accepting messages No duplicate knowledge anymore
- 49. –The Don't repeat yourself principle “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.” Even across applications!
- 50. "Don't repeat yourself" • Doesn't mean you can't repeat data • It means you can't have knowledge in multiple locations
- 51. Mutability
- 52. What's the difference between... class Money { private $amount; private $currency; public function setAmount($amount) { $this->amount = $amount; } public function getAmount() { return $this->amount; } ... }
- 53. ... and this class Money { public $amount; public $currency; }
- 54. Inconsistent data $savings = new Money(); $savings->setAmount(1000); // what's the currency at this point? $savings->setCurrency('USD'); // only now do we have consistent data $savings->setCurrency('EUR'); // we have a lot more money now! $savings->setAmount('Amsterdam');
- 55. Making something better of this class Money { private $amount; private $currency; public function __construct($amount, $currency) { $this->setAmount($amount); } private function setAmount($amount) { if (!is_int($amount) || $amount < 0) { throw new InvalidArgumentException(); } $this->amount = $amount; } } Private Required
- 56. Immutability • Once created, can not be modified • Can only be replaced
- 57. Consistent data! $savings = new Money(1000, 'USD'); // we already have consistent data // we can't change anything anymore Immutable data!
- 58. Using immutable values • Prevents bugs • Prevents invalid state
- 59. What about API messages? <money> <amount>1000</amount> <currency>USD</currency> </money> PUT /savings/ <money> <currency>EUR</currency> </money> POST /savings/
- 61. Forms & Doctrine ORM $form = $this->createForm(new MoneyType()); $form->handleRequest($request); if ($form->isValid()) { $em = $this->getDoctrine()->getManager(); $em->persist($form->getData()); // calculates change set and executes queries $em->flush(); }
- 62. If you allow your users to change every field at any time • You end up with inconsistent data • You loose the why of a change • You end up with the what of only the last change • You ignore the underlying real-world scenario
- 64. Commands and events Register ConfirmRegistration SendMessage RegistrationConfirmed MessageSent UserRegistered Application
- 65. Tomorrow!
- 66. True • Messages should serve actual use cases instead of patch operations • After processing them, data should be in a valid state
- 67. Part III Implementation I Stability II Information IV Conclusion
- 68. Implementation
- 70. class Person { /** * @return PhoneNumber[] */ public function getPhoneNumbers() { return $this->phoneNumbers; } } Initial implementation
- 71. class Person { /** * @return ArrayCollection */ public function getPhoneNumbers() { return $this->phoneNumbers; } } Implementation leakage (Doctrine)
- 72. class Person { /** * @return PhoneNumber[] */ public function getPhoneNumbers() { return $this->phoneNumbers->toArray(); } } Hiding implementation
- 73. class NameplateController { function getAction($id) { $nameplate = $this ->getDoctrine() ->getManager() ->getRepository(Nameplate::class) ->findOneBy(['id' => $id]); if ($nameplate === null) { throw new NotFoundHttpException(); } ... } } More implementation hiding Actual field names! null or false? "find"?
- 74. class NameplateRepository { function byId($id) { $nameplate = $this ->findOneBy(['id' => $id]); if ($nameplate === null) { throw new NameplateNotFound($id); } return $nameplate; } } Push it out of sight Domain-specific exception Hide specific return value No "find"
- 75. class NameplateController { function getAction($id) { try { $nameplate = $this ->nameplateRepository ->byId($id); } catch (NameplateNotFound $exception) { throw new NotFoundHttpException(); } ... } } Respect layers Convert domain exception to web specific exception
- 76. Plain old OOP • Encapsulation • Abstraction
- 78. <ticket> ... <priority type="integer">1</priority> ... Assembla API We do "switch ($priority)"
- 80. <ticket> ... <is-story type="boolean">false</is-story> <total-estimate type="float">0.0</total-estimate> ... Assembla API Table "tickets" has a column "is_story"
- 82. Design your messages in such a way that • You hide your implementation • Clients won't need to reimplement your application • Clients get the information they need
- 83. API discovery
- 84. /** * @param string $password * @param integer $algo * @param array $options */ function password_hash($password, $algo, array $options = array()); Undiscoverable API What are my options here? And here?
- 85. class Algorithm extends SplEnum { const __default = self::BCRYPT; const BCRYPT = 1; } Allow no mistakes
- 86. [ 'salt' => '...' 'cost' => 10 ] Options for bcrypt hashing
- 87. class Bcrypt implements HashingStrategy { /** * @param integer $cost * @param string|null $salt */ public function __construct($cost, $salt = null) { ... } } Inject a strategy
- 88. function password_hash( $password, HashingStrategy $hashingStrategy ); Inject a strategy More explicit and... discoverable!
- 89. Discoverability of an API • Full Reflection capabilities :) • Basic knowledge of English
- 90. // I've got this password I want to hash… $password = ...; // Look, I found a function for this: password_hash() password_hash($password, HashingStrategy $hashingStrategy); // It requires an argument: a password (string) // I already got a password right here: password_hash($password); // Wait, it requires a hashing strategy (a HashingStrategy object) // I just found a class implementing that interface: $hashingStrategy = new BcryptStrategy(); // That doesn't work, BcryptStrategy needs a cost $hashingStrategy = new BcryptStrategy(10); password_hash($password, $hashingStrategy); Example of API discovery Who is talking? How stupid are they? How do you find out a valid range?
- 91. /** * @param array $options */ function some_function(array $options); /** * @param integer $type */ function some_other_function($type); /** * @param object $command */ function handle($command); Undiscoverable APIs
- 92. Any kind of API should be maximally discoverable
- 93. Everything should be an object A class is a type
- 94. Define lots of interfaces An interface defines the public API of functions
- 95. <?xml version="1.0" encoding="UTF-8"?> <ticket> <reporter> <id>43</id> <link rel="self" href="/api/reporters/43" /> <link rel="index" href="/api/reporters/" /> </reporter> ... HATEOAS Links are a way to explain an "object"
- 96. Summary/Hypothesis • Objects are just like applications • Try to apply the same rules to them
- 97. Think about • Stable dependencies • Duplication of facts, not knowledge • Immutability over mutability • No leakage of implementation details • Everything should be maximally discoverable