Downloaded 18 times
![$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-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-18-2048.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-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-19-2048.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-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-46-2048.jpg)
![$nameplate = deserialize($xml);!
!
$width = $nameplate['width'];
Accepting messages
No duplicate knowledge
anymore](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-48-2048.jpg)
![class Person!
{!
! /**!
! * @return PhoneNumber[]!
! */!
! public function getPhoneNumbers() {!
! ! return $this->phoneNumbers;!
! }!
}
Initial implementation](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-70-2048.jpg)
![class Person!
{!
! /**!
! * @return PhoneNumber[]!
! */!
! public function getPhoneNumbers() {!
! ! return $this->phoneNumbers->toArray();!
! }!
}
Hiding implementation](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-72-2048.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-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-73-2048.jpg)
![class NameplateRepository!
{!
! function fromId($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-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-74-2048.jpg)
![[!
! 'salt' => '...'!
! 'cost' => 10!
]
Options for bcrypt hashing](https://image.slidesharecdn.com/thequestforglobaldesignprinciples-150626103507-lva1-app6892/75/Dutch-PHP-Conference-2015-The-quest-for-global-design-principles-86-2048.jpg)
Uploaded byMatthias Noback
Dutch PHP Conference 2015 - The quest for global design principles
The document discusses global design principles that can be applied to both inter-object and inter-application communication. It advocates treating objects like applications and applying similar design rules to both. Specifically, it recommends: depending on abstractions rather than concretions to achieve stable dependencies; avoiding duplication of knowledge while allowing duplication of facts; using immutable objects to prevent inconsistent states; hiding implementation details to avoid tight coupling; and ensuring APIs are maximally discoverable. The overall message is that communication between systems, whether objects or applications, can be improved by recognizing them as equivalent and applying cross-cutting principles of stability, information hiding, and implementation independence.
More Related Content
Similar to Dutch PHP Conference 2015 - The quest for global design principles
Dutch PHP Conference 2015 - The quest for global design principles
- 1. Global Design Principles Matthias Noback Dutch PHPConference, Amsterdam, June 26th, 2015 The Quest for
- 2.
- 3. Stability versus change •Backwards compatibility of APIs • Semantic versioning • HTTP status codes • XML schemas
- 4.
- 6. The key isin the concept of communication ReceiverSender
- 7. What's being communicated? Message Type("BookHotel") Value ("Inntel Hotels", "25-06-2015", "27-06-2015")
- 8.
- 9.
- 10. Sender Construct the message Message Translate Construct (Prepare for transport)
- 11.
- 12. Global design principles canbe discovered if we recognise the fact that communication between objects and applications are (more or less) equal
- 13. Communication between objects • Callinga 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! {! ! publicfunction deposit($accountId, Money $amount) ! {! ! ! ...! ! }! } Opportunity for sending a message Inter-object communication
- 15. $money = newMoney(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 • AnHTTP 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") */! functiondepositAction(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 beapplicable to both inter-object and inter-application communication
- 21. Part I Stability III Implementation IIInformation
- 22.
- 23. Stable Unstable What issafer? Unstable Stable OR
- 24. To be stable "Steadyin 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 nota 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 dependenciesprinciple Depend in the direction of stability
- 31. Stable thing Unstablething What to do when this happens?
- 32. Also stable Half stablethingStable thing Unstable thing Depend on something that you own
- 33. –The Dependency inversionprinciple 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
- 35.
- 36.
- 37.
- 38. Dependency inversion for systems •Depend on your own (messaging) system • Communicate with other applications via a message queue
- 39. Part II Information I Stability IIIImplementation
- 40.
- 41. Nameplate order system Nameplate machine Business automationfor creating nameplates
- 42. <h1>You are aboutto 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 aboutto 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
- 45.
- 46. // calculate thewidth 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>Buildings</name>! ! <width>120</width>! </nameplate> Deduplication Knowledgeis in one place, facts can be everywhere
- 48. $nameplate = deserialize($xml);! ! $width= $nameplate['width']; Accepting messages No duplicate knowledge anymore
- 49. –The Don't repeatyourself 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.
- 52. What's the difference between... classMoney! {! ! private $amount;! ! private $currency;! ! ! public function setAmount($amount) {! ! ! $this->amount = $amount;! ! }! ! ! public function getAmount() {! ! ! return $this->amount;! ! }! ! ! ...! }
- 53. ... and this classMoney! {! ! 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 betterof 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 APImessages? <money>! ! <amount>1000</amount>! ! <currency>USD</currency>! </money> PUT /savings/ <money>! ! <currency>EUR</currency>! </money> POST /savings/
- 60. Large object graphs <user>! !<first-name/>! ! <last-name/> ! ! <mobile-phone-number/> ! ! <email-address/> ! ! <homepage/> ! ! <orders>! ! ! <order/>! ! ! ...! ! </orders>! ! <tickets>! ! ! <ticket/>! ! ! ...! ! </tickets>! ! <payments>! ! ! <payment/>! ! ! ...! ! </payments>! </user>
- 61. Forms & DoctrineORM $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 allowyour 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 RegisterConfirmRegistration SendMessage RegistrationConfirmed MessageSent UserRegistered Application
- 65.
- 66. True • Messages shouldserve actual use cases instead of patch operations • After processing them, data should be in a valid state
- 67. Part III Implementation I Stability IIInformation IV Conclusion
- 68.
- 69.
- 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! {! ! functiongetAction($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! {! ! functionfromId($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! {! ! functiongetAction($id) {! ! ! try {! ! ! ! $nameplate = $this! ! ! ! ! ->nameplateRepository! ! ! ! ! ->fromId($id);! ! ! } catch (NameplateNotFound $exception) {! ! ! ! throw new NotFoundHttpException();! ! ! }! ! ! ! ...! ! }! } Respect layers Convert domain exception to web specific exception
- 76. Plain old OOP •Encapsulation • Abstraction
- 77.
- 78. <ticket>! ...! <priority type="integer">1</priority>! ... Assembla API Wedo "switch ($priority)"
- 79.
- 80. <ticket>! ...! <is-story type="boolean">false</is-story>! <total-estimate type="float">0.0</total-estimate>! ... AssemblaAPI Table "tickets" has a column "is_story"
- 81.
- 82. Design your messagesin such a way that • You hide your implementation • Clients won't need to reimplement your application • Clients get the information they need
- 83.
- 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 extendsSplEnum! {! ! const __default = self::BCRYPT;! ! ! const BCRYPT = 1;! } Allow no mistakes
- 86. [! ! 'salt' =>'...'! ! 'cost' => 10! ] Options for bcrypt hashing
- 87. class Bcrypt implementsHashingStrategy! {! ! /**! * @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 anAPI • Full Reflection capabilities :) • Basic knowledge of English
- 90. // I've gotthis password! $password = ...;! // I want to hash it...! // 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 ofAPI should be maximally discoverable
- 93. Everything should bean object A class is a type
- 94. Define lots ofinterfaces An interface defines the public API of functions
- 95. <?xml version="1.0" encoding="UTF-8"?>! <ticket>! <reporter>! <id>43</id>! <linkrel="self" href="/api/reporters/43" />! <link rel="index" href="/api/reporters/" />! </reporter>! ... HATEOAS Links are a way to explain an "object"
- 96. In summary • Objectsare just like applications • Try to apply the same rules to them
- 97. Think about • Stabledependencies • Duplication of facts, not knowledge • Immutability over mutability • No leakage of implementation details • Everything should be maximally discoverable
- 98.