the beautiful magento module - magetitans 2014

Manchester, November 1st 2014

Vinai Kopp

Introduction

2 The beautiful Magento Module November, 1st 2014

Magento 1.x

Introduction


Magento 1.x

It has contributed to the collective knowledge of the PHP community.

Both as a good and a bad example :)

Introduction


This is not an introduction into Magento development.

Introduction


How cana Magento modulebe "beautiful"?

Introduction


Qualities of a beautiful module

1.It provides business value2.Magento can be upgraded without breaking the module3.It is easy to understand and modify4.It has good test coverage5.It is free of bugs


Principles and Patterns



Robert C. Martin (Uncle Bob)



Some principles and some of their fancy acronyms

•Single Responsibility Principle (SRP) •Open Closed Principle (OCP)•Liskov Substitution Principle (LSP)•Interface Segregation Principle (ISP)•Dependency Inversion Principle (DIP)



Some more principles and some more fancy acronyms

•Encapsulate what varies (ECV)•Strive for loosely coupled designs between objects that interact (LC)•Favor composition over inheritance (FCoI)•Only talk to friends (LoD)•Don't call us, we'll call you (IoC)



What have you done for me lately, principles?



Like with all good things in life,there can be too much.


Open Closed Principle


“Classes should be open for extension but closed for modification”

The Open Closed PrincipleUncle Bob

The Open Closed Principle


Does Magento have it?



Configuration XML merging

Often the cause of conflicts



Lets look deeper



Self-Documenting Code

Method visibility and naming



public Methods

Are an open invitation to the world



public Methods

Once published should never change their signature or functionality



protected Methods

Communicate “override me!”



protected Methods

Change in signature or functionality risks breaking subclasses



private Methods

Safe to change



How is method visibility used in Magento?

Only public and protected

A too open design!



A good example ofmethod visibility documentinghow to extend a class.


abstract class Mage_Core_Block_Abstract ...{ final public function toHtml() { // ...housekeeping $html = $this->_toHtml(); // ...more housekeeping

return $html; }

protected function _toHtml() { return ''; }

A good example from the core how method visibility helps



Another good example of OCP

Event Observers



How can we apply this principleto our modules?

By dispatching events


Mage::dispatchEvent('events_example_import_prepare', ['importer' => $this]);

// ...

Mage::dispatchEvent( 'events_example_import_batch_start', ['importer' => $this, 'batch' => $batch]);

// ...

Mage::dispatchEvent( 'events_example_import_batch_end', ['importer' => $this, 'batch' => $batch]);

// ...

Mage::dispatchEvent('events_example_import_complete', ['importer' => $this]);

Choosing strategic places to dispatch events.



Favor domain events overinstructional events



Choose the right method visibility

Use private as the default



Use the Magento Factory Methodsand Class Aliases


Rewrites are applied during class name resolution.

Using a Factory Method with a PHP class nameis no better then using new.

$notLikeThis = new Mage_Catalog_Model_Product();

$badExample = Mage::getModel('Mage_Catalog_Model_Product');


Rewrites are applied during class name resolution.

Using class aliases allows for rewrites.

$correctlyInstantiated = Mage::getModel('catalog/product');

gist of class name resolution steps: http://vin.ai/class-name-resolution


$model = Mage::getModel('example_module/import_parser_xml');$resource = Mage::getResourceModel('example_module/search');$helper = Mage::helper('example_module');$block = Mage::app()->getLayout()->createBlock('example_module/list');

To keep our code open for extension, we should use class aliases for our classes.


Encapsulate what varies


“Encapsulate the Concept that Varies, i.e. a design is better when those parts that vary are encapsulated in a separate module”On the Criteria To Be Used inDecomposing Systems into ModulesDavid Parnas



Keep changes local so they don't affect other parts of the system



Magento, do you ECV?



First some "missed opportunities"



Configuration of theTax Calculation Algorithm


// from Mage_Tax_Model_Sales_Quote_Tax::collect()

switch ($this->_config->getAlgorithm($this->_store)) { case Mage_Tax_Model_Calculation::CALC_UNIT_BASE: $this->_unitBaseCalculation($address, $request); break; case Mage_Tax_Model_Calculation::CALC_ROW_BASE: $this->_rowBaseCalculation($address, $request); break; case Mage_Tax_Model_Calculation::CALC_TOTAL_BASE: $this->_totalBaseCalculation($address, $request); break; default: break;}

Choosing the tax calculation algorithm based on the system configuration



Order State Management


public function canCancel(){ if (!$this->_canVoidOrder()) { return false; } if ($this->canUnhold()) { // $this->isPaymentReview() return false; } // ... more of the same + comments removed for brevity...

$state = $this->getState(); if ($this->isCanceled() || $state === self::STATE_COMPLETE || $state === self::STATE_CLOSED) { return false; }

if ($this->getActionFlag(self::ACTION_FLAG_CANCEL) === false) { return false; } return true;}

Example of sales/order state behavior management


class Mage_Sales_Model_Order_State_Complete implements OrderState{ public function canInvoice() { return false; } public function canShip() { return false; } public function canReorder() { return true; }

// ...

Theoretical example of encapsulating the stateful behavior



Where does the core adhere to the principle, at least in parts?



Total Models

Total calculationPreparation of display data



EAV Attribute Models

Backend,Source and Frontend models



How can we apply this principlein our Modules?



A simple example scenario

Add informationdepending on a the attribute setto the product detail page.



A simple example scenario

Kitchen Attribute Set

Chair Attribute Set

Insurance Attribute Set


private function getTemplateForAttributeSet(){ switch ($this->getAttributeSetId()) { case $this->kitchenAttributeSetId: return 'example/attributesetinfo/kitchen-info.phtml'; case $this->chairAttributeSetId: return 'example/attributesetinfo/chair-info.phtml'; case $this->insuranceAttributeSetId: return 'example/attributesetinfo/insurance-info.phtml'; }}

First try, not adhering to the principle


private function getTemplateForAttributeSet(){ switch ($this->getAttributeSetId()) { case $this->kitchenAttributeSetId: return 'example/attributesetinfo/kitchen-info.phtml'; case $this->chairAttributeSetId: return 'example/attributesetinfo/chair-info.phtml'; case $this->insuranceAttributeSetId: return 'example/attributesetinfo/insurance-info.phtml'; }}

public function getChairCoverWashingInstructionsPDFUrl() {...}

public function getInsuranceTermsAndConditions() {...}

public function getKitchenDesignPdfUrl() {...}

public function getServicePartnerDirectoryUrl() {...}

The block also needs to provide all the methods called from the templates



Decomposed classes

Kitchen Attribute Set Info Block

Chair Attribute Set Info Block

Insurance Attribute Set Info Block

Attribute Set Info Block Locator


class Example_AttributeSetInfo_Block_InfoBlockLocator extends Mage_Core_Block_Text_List{ // ...}

The locator extends core/text_list


protected function _prepareLayout(){ $infoBlockAlias = $this->_getInfoBlockClassAlias(); if (null !== $infoBlockAlias) { $this->insert($this->_createChildBlock($infoBlockAlias)); }}

private function _getInfoBlockClassAlias(){ switch ($this->getAttributeSetId()) { case $this->kitchenAttributeSetId: return 'example_attributesetinfo/info_kitchen'; case $this->chairAttributeSetId: return 'example_attributesetinfo/info_chair'; case $this->insuranceAttributeSetId: return 'example_attributesetinfo/info_insurance'; }}

Select and instantiate the delegate object


class Example_AttributeSetInfo_Block_Info_Chair extends Mage_Core_Block_Template{ protected function _prepareLayout() { $this->setTemplate('example/attributesetinfo/chair-info.phtml'); }

public function getChairCoverWashingInstructionsPDFUrl() { return 'the url of the chair cover washing instructions pdf'; }}

The attribute set dependent differences are encapsulated



What would be affected by change?

What would be affected by adding an attribute set?

What would be affected if the output for one attribute set needs to change?


More Principles


What else makes a module beautiful?


Readable Code

Readable Code


What makes code readable?

Coding Standard


private function getInfoBlockClassAliasBadExample () { if ($this->getAttributeSetId()==$this->kitchenAttributeSetId) return 'example_attributesetinfo/info_kitchen'; if($this->chairAttributeSetId == $this->getAttributeSetId()) return 'example_attributesetinfo/info_chair'; else // insurance attribute set return 'example_attributesetinfo/info_insurance';}

private function getInfoBlockClassAliasGoodExample(){ switch ($this->getAttributeSetId()) { case $this->kitchenAttributeSetId: return 'example_attributesetinfo/info_kitchen'; case $this->chairAttributeSetId: return 'example_attributesetinfo/info_chair'; case $this->insuranceAttributeSetId: return 'example_attributesetinfo/info_insurance'; }}

Obviously

Readable Code


What else makes code readable?

Descriptive method names

Readable Code


How can we choose good method names?

A method should do only one thing.The name should state that thing.

Readable Code


If naming a method is hard split it into smaller ones.

Readable Code


First some examples of method names that could be improved


protected function _construct(){ $this->_init('example_module/foo');}

One bad example straight out of the Magento ORM


protected function _initializeCollection(){ $this->_setModelClassAlias('example_module/foo');}

I find this would be nicer to read


public function isNewObject() {...}

public function hasChildren() {...}

Methods returning a boolean value should start with is or has

Readable Code


$request->setDispatched(false)

Setters should start with set

Readable Code

Readable Code


Some more good bad examples


// from Mage_Catalog_Model_Category

public function getChildrenCategories() {...}public function getChildrenCategoriesWithInactive() {...}public function getChildren() {...}public function getAllChildren(...) {...}public function getCategories(...) {...}

Similar methods need very descriptive names to be self documenting


// from Mage_Core_Model_Email

public function __construct(){ // TODO: move to config $this->setFromName('Magento'); $this->setFromEmail('[email protected]'); $this->setType('text');}

Dead code should be removed without mercy


// from Mage_Shipping_Model_Carrier_Abstract

public function getTotalNumOfBoxes($weight){ // ... return $weight;}

WTF


Wrap up

Wrap up


What qualifies a Magento module as beautiful?

1.It provides business value2.Magento can be upgraded without breaking the module3.It is easy to understand and modify4.It has good test coverage5.It is free of bugs

Further reading


Link to Amazon


Thank you


Questions | Comments

Tweet me @VinaiKopphttp://vinaikopp.com

the beautiful magento module - magetitans 2014

Software

beautiful magento module

beautiful module1

open closed principlelets

open closed principle13

open invitation

patternssome principles

changetheir signature

fancy acronymsencapsulate