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

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

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('magento@varien.com'); $this->setType('text');}

Dead code should be removed without mercy

// from Mage_Shipping_Model_Carrier_Abstract

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

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

Further reading

Link to Amazon

Further reading

Link to Amazon

Further reading

Link to Amazon

Thank you

Questions | Comments

Tweet me @VinaiKopphttp://vinaikopp.com

The beautiful Magento module - MageTitans 2014

Software

Transcript of The beautiful Magento module - MageTitans 2014

Geo IP Ultimate FME Module for Magento

Magento Referral System FME Module

Module 3XCB – Magento 2 Guide d’installation et de ...€¦ · Module 3XCB – Magento 2 | Version 1| 29/07/2019 Module 3XCB – Magento 2 Guide d’installation et de configuration

Magento module User manual Version 4.1 - Bpost

Magento Docdata zencart module user manual

Magento Year make Module

Magento GEO IP Location Tracking FME's Module

Magento Percentage pricing FME’s Module

Worldpay Magento Module Guide - d2uars7xkdmztq.cloudfront.net · How to install the Worldpay Magento Module within your Magento Platform How to configure your integration How to understand

Your First Magento 2 Module

Magento Twinfield module user manual

Magento Event Booking Module by FME

Magento Ultimate Banner module user manual

Magento Store Pickup Module by FME

Best Magento Blog Module For Ecommerce

Klarna Magento module

User Manual Computop Paygate module for Magento€¦ · User Manual Computop Paygate module for Magento Magento module for the Paygate payment interface By: dotSource GmbH Leutragraben

Bizrate Buyers Survey Magento Module Installation and ......5/22/2013 Bizrate Buyers Survey Magento Module Page 5 3. From the Extensions tab, Search for the module via Magento Connect.

ICEPAY Magento Advanced Module4 ICEPAY Magento Advanced Module – Manual for merchants / developers 1.2 Overview This module enables the use of ICEPAY payment methods in your Magento

ICEPAY Magento Basic Module · ICEPAY Magento Basic Module – Manual for merchants / developers 5 Upgrading from ICEPAY Magento module 2.0.0 – 2.1.x . This section only applies