Architecture in-the-small-slides

Architecturein the Small

1 Architecture in the Small - MageTitans 2015 - ! - @VinaiKopp - [email protected] - © 2015

Hi!

Vinai KoppFreelance Developer and Trainer@VinaiKopp


https://twitter.com/VinaiKopp

My PHP Evolution:1. Quick Hacks (1999)2. Typo3 Plugin Developer (2003)3. Magento Developer (2008)4. Experienced Magento Developer (2012)5. Discovering Code Beyond Magento (2014)


I hope some of the following will be useful and interesting to play with for you, too


Some of the many Peoplewho inspired and helped me• Rich Hickey• Robert C. Martin• Martin Fowler• Kent Beck

All brilliant people with a sense of humor!


https://twitter.com/richhickey

https://twitter.com/unclebobmartin

https://twitter.com/martinfowler

https://twitter.com/KentBeck

DisclaimerThe following thoughts are all mine, but influenced by reading these great peoples work.If I get something wrong, it is all my fault.

I might change my mind about something at any time.


Topics

• Extraction & Encapsulation• Managing State with Immutable Objects• The Value of Validity• Immutable Variables• Reasoning about Code with Idempotence


Extraction&Encapsulation


Extraction?WTF?


A subset of

Refactoring


„Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure“

-- Martin Fowler, Refactoring (Addison-Wesley)



The usual purpose of refactoring:

Get rid of smelly code


But in case of extraction

It can be more


Simplicityvs.

Amount of code


SimplicityCan make things

visiblethat where hidden in the code


Extract Method Example - Before// Magento\Catalog\Model\Product

protected function convertToMediaGalleryInterface(array $mediaGallery){ $entries = []; foreach ($mediaGallery as $image) { $entry = $this ->mediaGalleryEntryConverterPool ->getConverterByMediaType($image['media_type']) ->convertTo($this, $image); $entries[] = $entry; } return $entries;}


Extract Method Example - After (1/2)// Magento\Catalog\Model\Product

protected function convertToMediaGalleryInterface(array $mediaGallery){ $entries = []; foreach ($mediaGallery as $image) { $entries[] = $this->convertImageToMediaGalleryEntry($image); } return $entries;}

private function convertImageToMediaGalleryEntry(array $image){ $converter = $this->mediaGalleryEntryConverterPool ->getConverterByMediaType($image['media_type']); return $converter->convertTo($this, $image);}


Extract Method Example - After (2/2)// Magento\Catalog\Model\Product

protected function convertToMediaGalleryInterface(array $mediaGallery){ $entries = []; foreach ($mediaGallery as $image) { $entries[] = $this->mediaGalleryEntryConverterPool ->convertImageToMediaGalleryEntry($image, $this); } return $entries;}

// Magento\Catalog\Model\Product\Attribute\Backend\Media\EntryConverterPool

public function convertImageToMediaGalleryEntry(array $image, Product $product){ $converter = $this->getConverterByMediaType($image['media_type']); return $converter->convertTo($product, $image);}


Encapsulation„In general, encapsulation is the inclusion of one thing within another thing so that the included thing is not apparent.“

-- TechTarget SearchNetworking


http://searchnetworking.techtarget.com/definition/encapsulation

Encapsulation„Other objects ... use the object without having to be concerned with how the object accomplishes it.“

-- TechTarget SearchNetworking


http://searchnetworking.techtarget.com/definition/encapsulation

Tell, don't ask!


Extraction enables us to properly encapsulate functionality.


Proposition:It is good to write code that is simple to extract.


Topics



Managing State with Immutable Objects


Immutawhat?


„In object-oriented and functional programming, an immutable object is an object whose state cannot be modified after it is created.“

-- Wikipedia, Immutable object


https://en.wikipedia.org/wiki/Immutable_object

Yes, but... why?


I've read it helps avoid a whole class of bugs.

So, what are they?


Reasonability


Reading ➡ Understanding


Understanding ➡ Knowing• Is it correct

or

• Is it incorrect


When objects change in distant code, it becomes more complex to track what changed where and why.


Immutability helps to avoid temporal coupling


For Example:// \Magento\Braintree\Model\PaymentMethod::partialCapture()$this->config->initEnvironment($payment->getOrder()->getStoreId());


Temporal Coupling:// \Magento\Braintree\Model\PaymentMethod::partialCapture()$this->config->initEnvironment($payment->getOrder()->getStoreId());

What state does the config start out in before it is initialized?



What happens if the config is initialized twice with different store ids?



What happens if another method is called before this one and the other one also relies on the config environment being initialized?



What happens if the call to initEnvironment is missed?



Extracting methods is tricky because the extracted part might rely on a different method being called first.This might not be apparent.



What happens if another object has a reference to the same config instance, but it doesn't know about or expect the config change?



What happens if a response of the payment instance is cached and then the config environment is changed?


ExternalInitialization methodsandSetters

add complexity


External immutability&Internal immutability


Internal mutability allows for memoization


Memoization :

„An optimization technique to speed up expensive method calls by storing the result after the first call and returning the cached result if the same inputs occur again.“


Memoization Examplepublic function getAltitudeAvg(Location $loc, Date $date){ $coords = (string) $loc->getCoords(); $dateStr = (string) $date;

if (! @$this->memoizedResults[$coords][$dateStr]) { $avgAltitude = $this->doExpensiveCalculation($loc, $date); $this->memoizedResults[$coords][$dateStr] = $avgAltitude; }

return $this->memoizedResults[$coords][$dateStr];}


Anyway...

Memoization is a lot simpler to do withexternally immutable objectssince nothing can invalidate the result.


Testing code which uses immutable objects is simpler


Test Double: Mutable Object$initWasCalled = false;$mockConfig = $this->getMock(\Magento\Braintree\Model\Config, [], [], '', false);

$mockConfig->method('initEnvironment') ->willReturnCallback(function () use (&$initWasCalled) { $initWasCalled = true; });

$mockConfig->method('canUseForCountry') ->willReturnCallback(function ($country) use (&$initWasCalled) { return $initWasCalled ? false : true; });


Yuck!


Incomplete Test Double:Mutable Object$initializedConfigMock = $this->getMock(\Magento\Braintree\Model\Config, [], [], '', false);

$initializedConfigMock->method('canUseForCountry')->willReturn(true);

Easy to miss calling initEnvironment in the system under test!


Test Double: Immutable Object$configMock = $this->getMock(\Magento\Braintree\Model\Config, [], [], '', false);$configMock->method('canUseForCountry')->willReturn(true);


Simpler to cacheNo need to worry that an object changes after it is written to cache.


Example:

Magento EE PageCache<controller_front_send_response_before> <observers> <enterprise_pagecache> <class>enterprise_pagecache/observer</class> <method>cacheResponse</method> </enterprise_pagecache> </observers></controller_front_send_response_before>


Example:

Magento EE PageCache

Events after cache write:

• controller_front_send_response_before(in a later Observer)

• controller_front_send_response_after

• http_response_send_before


Once validalways validCan something be „half valid“?


Example: invalidation of a mutable object

$product = $productCollection->getFirstItem();

$product->getPrice(); // 24.99$product->getSpecialPrice(); // 19.99

$product->setPrice(11.95);$product->setSpecialPrice(10.95);

$product->getFinalPrice() // 19.99


So how do the values get into an immutable object?


Constructor Injection


__construct()$request = new HttpRequest( HttpRequest::METHOD_GET, HttpUrl::fromString('http://example.com/lookie/here'), HttpHeaders::fromArray($httpHeaders), HttpRequestBody::fromString($httpRequestBodyString));


Named constructor$request = HttpRequest::fromGlobalState();


Example 1: named constructorpublic static function fromGlobalState($requestBody = ''){ $method = $_SERVER['REQUEST_METHOD'];

$protocol = isset($_SERVER['HTTPS']) && $_SERVER['HTTPS']) ? 'https' : 'http';

$path = $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']; $url = $protocol . '://' . $path; $headers = self::getGlobalRequestHeaders();

return static::fromScalars($method, $url, $headers, $requestBody);}


Example 2: named constructorpublic static function fromScalars( $methodString, $urlString, $headersArray, $bodyString) { $url = HttpUrl::fromString($urlString); $headers = HttpHeaders::fromArray($headersArray); $body = HttpRequestBody::fromString($bodyString);

return new self($methodString, $url, $headers, $body);}


But IRLthings change


Modeling change with immutable objectsChange is introduced by creating a new instance.


Looks like mutation, but it ain't$today = new DateTimeImmutable();echo $today->format('Y-m-d H:i:s'); // 2015-10-29 21:32:06

$day = DateInterval::createFromDateString('24 hours');$tomorrow = $today->add($day);

echo $today->format('Y-m-d H:i:s'); // 2015-10-29 21:32:06echo $tomorrow->format('Y-m-d H:i:s');// 2015-10-30 21:32:06


Contraindications


Does immutability make code more

complexor

simple?


A thing that changes over time.

$room = new ConferenceRoom( $location, $event, $attendees)


Is it a new conference room just because the number of people change?


A mutable conference room model:

$nPeople = $room->countPeople();$room->addPerson($attendee);

$room->countPeople() === $nPeople + 1;


A immutable conference room model:

$nPeople = $room->countPeople();$updatedRoom = $room->addPerson($attendee);

$room->countPeople() === $nPeople;$updatedRoom->countPeople() === $nPeople + 1;


Temporal modelingAn instance represents the objectat one moment in time.


Temporal modeling(Immutable object at a moment in time)(Immutable object at a moment in time)(Immutable object at a moment in time)(Immutable object at a moment in time)...

All the same Entity that changes over time.


Temporal modelingKeeps History !

Not a natural way to do OOP, adds complexity !

Unaccustomed way to think ! "


Bottom LineIf you don't have to model changes over time, using immutability will probably make your code simpler.

If you do have to worry about changes over time...it depends.


Topics



The Value of Validity


Enforce object validity at instantiation.


Validation at Instantiation• __construct()• Named constructor (aka Factory Method)• Builder or Factory


Constructor validationThe safest place to enforce validity


Example Constructor Validation public function __construct($amount){ if (!is_int($amount)) { $type = gettype($amount); $msg = sprintf('Can not create price from "%s"', $type); throw new InvalidAmountTypeException($msg); }

$this->amount = $amount;}


When it gets more complex...


Example Delegation of Validation// ProductAttributeListBuilder

public static function fromArray(array $attributesArray){ $attributes = array_map(function (array $attributeArray) { return ProductAttribute::fromArray($attributeArray); }, $attributesArray); return new self(...$attributes);}

public function __construct(ProductAttribute ...$attributes){ $this->validateAllAttributesHaveCompatibleContextData(...$attributes); $this->attributes = $attributes;}


Each thing is a classEach object validates it's data


Plug: Value ObjectsIntroduction slides on Value Objectsby Tim Bezhashvyly

http://vin.ai/tims_value_objects


http://vin.ai/tims_value_objects

https://twitter.com/tim_bezhashvyly

The cost of validityClasses require time to write, test and maintain.

• Each thing is a new class• Lots of code


What about scalars?• string• int• bool• float• null• arrays of scalars


Code Smell:Primitives Obsession„Primitives Obsession is using primitive data types to represent domain ideas.“


Primitives ObsessionNo Type Safety

(until PHP 7)

Tests help


Primitives ObsessionEasy to end up with Code Duplication


Primitives ObsessionMagic values

„I knew at once what process(1.34, true) meant!“

-- Noone, ever

Class names have documentary value


Primitives ObsessionNo built-in validation

Tests help (again)


Benefits of scalar types



They are immutable



They are easily created



They are comparable



Serializable

They work over the wire



Completely upgrade safe



They are fast



They are language independent


Scalarsvs.Value Objects


Scalars make greatboundary interfaces


Scalar Boundary Interfaces• Web API• Components API• Message Queue Payload


Scalar Boundary Interfaces• Less interface dependencies• But implicit coupling to data format


Topics



Immutable Variables


In PHP?No


But we can treat variables as immutable.


Example 1: reusing local variablespublic function testTwoRequestsAddTwoMessages(){ $request = $this->createProductUpdateRequest(); $app = new WebFront($request, $this->testFactory); $app->runWithoutSendingResponse();

$request = $this->createStockUpdateRequest(); $app = new WebFront($request, $this->testFactory); $app->runWithoutSendingResponse();

$queue = $this->testFactory->createQueue(); $this->assertCount(2, $queue);}// Multiple assignments to $request and $app


What is the problem?• Messy to move or extract• Complex to reason about


Example 1: treating local variables as immutablepublic function testTwoRequestsAddTwoMessages(){ $productUpdateRequest = $this->createProductUpdateRequest(); $firstApp = new WebFront($productUpdateRequest, $this->testFactory); $firstApp->runWithoutSendingResponse();

$stockUpdateRequest = $this->createStockUpdateRequest(); $secondApp = new WebFront($stockUpdateRequest, $this->testFactory); $secondApp->runWithoutSendingResponse();

$queue = $this->testFactory->createQueue(); $this->assertCount(2, $queue);}


Example 2: local variable mutation in a loop// Magento\Catalog\Model\Product

protected function convertToMediaGalleryInterface(array $mediaGallery){ $entries = []; foreach ($mediaGallery as $image) { $entries[] = $this->mediaGalleryEntryConverterPool ->convertImageToMediaGalleryEntry($image, $this); } return $entries;}// Multiple assignments to $image, mutation of $entries


Example 2: map/reduce helps avoiding local variable mutation// Magento\Catalog\Model\Product

protected function convertToMediaGalleryInterface(array $mediaGallery){ return array_map( function ($image) { $this->mediaGalleryEntryConverterPool ->convertImageToMediaGalleryEntry($image, $this); }, $mediaGallery );}


Immutable Variables++Reasonability


Immutable VariablesLess bugs


Immutable VariablesSimple to refactor


Immutable VariablesMy new friends:

• \Closure• array_map()• array_reduce()• array_merge()• array_filter()• recursion• ...120 Architecture in the Small - MageTitans 2015 - ! - @VinaiKopp - [email protected] - © 2015

Topics



Reasoning about Code with Idempotence


Another of those words...


Idempotence

„In computer science, the term idempotent is used ... to describe an operation that will produce the same results if executed once or multiple times.“

-- Wikipedia, Idempotence, Computer Science


https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning

What it ain'tExample 1class Logger{ public function log($level, $message) { $f = fopen($this->file . '-' . $level, 'a'); flock($f, LOCK_EX); fwrite($f, message); flock($f, LOCK_UN); fclose($f); }}// repeated calls add additional records


Idempotent loggerExample 1class Logger{ public function log($level, $message) { $f = fopen($this->file . '-' . $level, 'a'); flock($f, LOCK_EX); if ($this->getLastLineFromFile() !== $message) { fwrite($f, message); } flock($f, LOCK_UN); fclose($f); }}// repeated calls add NO additional records


What it ain'tExample 2protected function validateIsFoo($object){ if (! $object instanceof Foo) { echo "\$object is not an instance of Foo\n"; return false; } return true;}// repeated calls may produce repeated output


Idempotent validateIsFooExample 2

protected function validateIsFoo($object){ return $object instanceof Foo;}// no output


Pure FunctionsAll pure functions are idempotent


Pure FunctionsNo side effects


Pure FunctionsRely only on input arguments


Pure FunctionsNo dependency on global state such as

• $_SERVER, $_SESSION• getcwd()• file_exists()• Mage::getIsDeveloperMode()


Pure FunctionsFor the same input they always return the same output


And my point is?


Idempotent Functions areSimpler to reuseSimpler to compose

Pure Functions areSimpler to refactorSimpler to changeSimpler to reason about


It pays to focus on the dependencies of every methodOOP is all about dependency management


I'm still learningBut so far results are very encouraging.I'm happy for every tool that helps to reduce complexity


Thanks for your attention!Please,Ask questions, andI'm eager to hear your thoughts and comments!


Software

Architecture in-the-small-slides