Project: Build a Custom Magento 2 Module

Module Structure

Vendor/CustomWishlist/
├── etc/
│   ├── module.xml
│   ├── registration.php
│   ├── di.xml
│   ├── routes.xml
│   └── acl.xml
├── Block/
│   └── Product/
│       └── View.php
├── Controller/
│   └── Index
│       └── Add.php
├── Model/
│   ├── ResourceModel/
│   │   └── Wishlist.php
│   └── Wishlist.php
├── view/
│   ├── frontend/
│   │   ├── layout/
│   │   │   └── catalog_product_view.xml
│   │   ├── templates/
│   │   │   └── wishlist.phtml
│   │   └── web/
│   │       └── js/
│   │           └── wishlist.js
│   └── adminhtml/
│       └── layout/
├── Setup/
│   └── InstallSchema.php
├── Test/
│   └── Unit/
│       └── Model/
│           └── WishlistTest.php
└── composer.json

registration.php

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Vendor_CustomWishlist',
    __DIR__
);

module.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_CustomWishlist" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Catalog"/>
            <module name="Magento_Customer"/>
        </sequence>
    </module>
</config>

composer.json

{
    "name": "vendor/module-custom-wishlist",
    "description": "Custom Wishlist Module",
    "type": "magento2-module",
    "version": "1.0.0",
    "require": {
        "php": ">=8.1",
        "magento/framework": "^103.0",
        "magento/module-catalog": "^103.0",
        "magento/module-customer": "^103.0"
    },
    "autoload": {
        "files": ["registration.php"],
        "psr-4": {
            "Vendor\\CustomWishlist\\": ""
        }
    }
}

The module structure follows Magento 2 conventions: etc/ for configuration, Block/ for presentation logic, Model/ for business logic, and view/ for frontend templates.

Wishlist Model

Model Class

<?php
namespace Vendor\CustomWishlist\Model;

use Magento\Framework\Model\AbstractModel;
use Vendor\CustomWishlist\Model\ResourceModel\Wishlist as WishlistResource;

class Wishlist extends AbstractModel
{
    const ID_FIELD_NAME = 'wishlist_id';
    
    protected function _construct()
    {
        $this->_init(WishlistResource::class);
    }
    
    public function getId()
    {
        return $this->getData(self::ID_FIELD_NAME);
    }
    
    public function getCustomerId()
    {
        return $this->getData('customer_id');
    }
    
    public function setCustomerId($customerId)
    {
        return $this->setData('customer_id', $customerId);
    }
    
    public function getProductId()
    {
        return $this->getData('product_id');
    }
    
    public function setProductId($productId)
    {
        return $this->setData('product_id', $productId);
    }
    
    public function getAddedAt()
    {
        return $this->getData('added_at');
    }
}

Resource Model

<?php
namespace Vendor\CustomWishlist\Model\ResourceModel;

use Magento\Framework\Model\ResourceModel\Db\AbstractDb;

class Wishlist extends AbstractDb
{
    protected function _construct()
    {
        $this->_init('vendor_custom_wishlist', 'wishlist_id');
    }
}

Collection

<?php
namespace Vendor\CustomWishlist\Model\ResourceModel\Wishlist;

use Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection;
use Vendor\CustomWishlist\Model\Wishlist as WishlistModel;
use Vendor\CustomWishlist\Model\ResourceModel\Wishlist as WishlistResource;

class Collection extends AbstractCollection
{
    protected function _construct()
    {
        $this->_init(WishlistModel::class, WishlistResource::class);
    }
    
    public function getCustomerWishlist($customerId)
    {
        $this->addFieldToFilter('customer_id', $customerId);
        return $this;
    }
}

The Model-ResourceModel-Collection pattern separates data representation (Model) from database operations (ResourceModel) from query building (Collection).

Block Class

<?php
namespace Vendor\CustomWishlist\Block\Product;

use Magento\Framework\View\Element\Template;
use Magento\Catalog\Model\Product;
use Vendor\CustomWishlist\Api\WishlistRepositoryInterface;
use Magento\Customer\Model\Session as CustomerSession;

class View extends Template
{
    public function __construct(
        Template\Context $context,
        private WishlistRepositoryInterface $wishlistRepository,
        private CustomerSession $customerSession,
        array $data = []
    ) {
        parent::__construct($context, $data);
    }
    
    public function getProduct()
    {
        return $this->getData('product');
    }
    
    public function isInWishlist()
    {
        $product = $this->getProduct();
        $customerId = $this->customerSession->getCustomerId();
        
        if (!$customerId || !$product) {
            return false;
        }
        
        $wishlist = $this->wishlistRepository->getCustomerWishlist($customerId);
        
        foreach ($wishlist as $item) {
            if ($item->getProductId() == $product->getId()) {
                return true;
            }
        }
        
        return false;
    }
    
    public function getAddToWishlistUrl()
    {
        return $this->getUrl('customwishlist/index/add');
    }
}

Layout XML

<!-- view/frontend/layout/catalog_product_view.xml -->
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="product.info.extrahint">
            <block class="Vendor\CustomWishlist\Block\Product\View"
                   name="custom.wishlist.button"
                   template="Vendor_CustomWishlist::wishlist.phtml"
                   after="-"/>
        </referenceContainer>
    </body>
</page>

Template

<!-- view/frontend/templates/wishlist.phtml -->
<?php /** @var Vendor\CustomWishlist\Block\Product\View $block */ ?>
<div class="custom-wishlist">
    <a href="<?php echo $block->getAddToWishlistUrl(); ?>"
       class="action towishlist <?php echo $block->isInWishlist() ? 'in-wishlist' : ''; ?>"
       data-action="add-to-wishlist"
       role="add to wishlist">
        <span><?php echo $block->isInWishlist() ? 'In Wishlist' : 'Add to Wishlist'; ?></span>
    </a>
</div>

Blocks provide data to templates via getter methods. Layout XML controls where the block renders on the page.

Unit Test

<?php
namespace Vendor\CustomWishlist\Test\Unit\Model;

use PHPUnit\Framework\TestCase;
use Vendor\CustomWishlist\Model\Wishlist;
use Vendor\CustomWishlist\Model\ResourceModel\Wishlist as WishlistResource;

class WishlistTest extends TestCase
{
    private $wishlist;
    private $resourceMock;
    
    protected function setUp(): void
    {
        $this->resourceMock = $this->createMock(WishlistResource::class);
        
        $this->wishlist = new Wishlist(
            $this->resourceMock
        );
    }
    
    public function testGetSetCustomerId()
    {
        $customerId = 123;
        $this->wishlist->setCustomerId($customerId);
        $this->assertEquals($customerId, $this->wishlist->getCustomerId());
    }
    
    public function testGetSetProductId()
    {
        $productId = 456;
        $this->wishlist->setProductId($productId);
        $this->assertEquals($productId, $this->wishlist->getProductId());
    }
    
    public function testResourceInit()
    {
        $this->resourceMock->expects($this->once())
            ->method('load')
            ->with($this->wishlist, null);
        
        $this->wishlist->load();
    }
}

Integration Test

<?php
namespace Vendor\CustomWishlist\Test\Integration\Model;

use Magento\TestFramework\Helper\Bootstrap;
use PHPUnit\Framework\TestCase;
use Vendor\CustomWishlist\Model\WishlistFactory;
use Vendor\CustomWishlist\Api\WishlistRepositoryInterface;

class WishlistRepositoryTest extends TestCase
{
    private $repository;
    private $factory;
    
    protected function setUp(): void
    {
        $this->repository = Bootstrap::getObjectManager()->create(WishlistRepositoryInterface::class);
        $this->factory = Bootstrap::getObjectManager()->create(WishlistFactory::class);
    }
    
    public function testSaveAndRetrieve()
    {
        $wishlist = $this->factory->create();
        $wishlist->setCustomerId(1);
        $wishlist->setProductId(100);
        
        $this->repository->save($wishlist);
        
        $retrieved = $this->repository->getCustomerWishlist(1);
        $this->assertNotEmpty($retrieved);
    }
    
    public function testDelete()
    {
        $wishlist = $this->factory->create();
        $wishlist->setCustomerId(2);
        $wishlist->setProductId(200);
        
        $this->repository->save($wishlist);
        $this->repository->delete($wishlist);
        
        $retrieved = $this->repository->getCustomerWishlist(2);
        $this->assertEmpty($retrieved);
    }
}

Unit tests mock dependencies for fast isolated testing. Integration tests verify real database operations through Magento's object manager.

Business Requirements Context

Who is the Customer?

Custom Magento modules are built by development teams for:

• Internal IT teams at retailers who need functionality not available in the marketplace (custom loyalty programs, ERP integrations)
• Agencies building bespoke features for merchant clients
• ISVs (Independent Software Vendors) creating marketplace extensions for sale on the Magento Marketplace
• System integrators connecting Magento to external systems (WMS, PIM, CRM)

What Problem Does This Solve?

1. Feature gap: Magento core + marketplace extensions don't cover 100% of business requirements; ~30% of Magento implementations require at least one custom module
2. Business process automation: Custom modules encode unique business rules (loyalty tiers, custom pricing, specialized checkout flows)
3. System integration: Connecting Magento to ERP (SAP, NetSuite), WMS (ShipStation), or CRM (Salesforce) requires custom API modules
4. Competitive differentiation: Custom features (personalization engines, configurators) create unique shopping experiences
5. Compliance: Industry-specific regulations (pharma, automotive) require custom data capture and validation

Architecture Decisions

Decision 1: Preference vs Plugin vs Observer

Decision 2: InstallSchema vs DB Schema (declarative)

Decision 3: API-First vs Direct Model Access

Decision 4: Module Packaging

Production Deployment Checklist

Pre-Deployment

• Run php bin/magento module:status to verify module state
• Run full test suite (unit + integration)
• Run php bin/magento setup:dry-run to preview schema changes
• Verify composer.json dependencies are compatible
• Check ACL permissions for admin features
• Verify database backup exists before schema changes
• Test module enable/disable cycle (ensure clean uninstall)
• Review di.xml for circular dependencies

Deployment

• Enable maintenance mode: php bin/magento maintenance:enable
• Deploy code via composer or CI/CD
• Run php bin/magento setup:upgrade
• Run php bin/magento setup:di:compile
• Run php bin/magento setup:static-content:deploy
• Disable maintenance mode: php bin/magento maintenance:disable
• Clear all caches: php bin/magento cache:clean && cache:flush

Post-Deployment

• Verify module appears in php bin/magento module:status
• Test core functionality (add to wishlist, check persistence)
• Verify admin ACL works (if applicable)
• Check exception.log for errors
• Verify cron jobs run if module registers any
• Test module disable/enable without data loss

Monitoring and Alerting

Module Health Metrics

Custom table row count           → Track growth rate
Controller request volume        → Endpoint usage
Block render time                → Template performance
Cache hit ratio for module data  → Redis/Memcached efficiency
Exception count in module code   → Error rate

Alerting Thresholds

Logging

// In your module's code
use Psr\Log\LoggerInterface;

protected $logger;

public function __construct(LoggerInterface $logger)
{
    $this->logger = $logger;
}

public function riskyOperation(): void
{
    try {
        // operation
    } catch (\Exception $e) {
        $this->logger->error('CustomWishlist error: ' . $e->getMessage(), [
            'exception' => $e,
            'module' => 'Vendor_CustomWishlist',
        ]);
        throw $e;
    }
}

Use Magento's PSR-3 logger to write to var/log/exception.log. Monitor via ELK stack or CloudWatch.

Cost Estimation

Development Cost

Infrastructure Cost (Monthly)

Ongoing Maintenance

Cost vs Marketplace Extension