Layout Debugging

Enable Layout Compilation Debug

# Compile layoutin/magento setup:di:compile

# Check for XML errors
bin/magento setup:di:compile 2>&1 | grep -i error

# View compiled layout
var/di/processed.xml

Layout XML Validation

// Validate layout XML
use Magento\Framework\View\Layout\Reader\Layout;

class LayoutValidator
{
    public function validate($xmlFile)
    {
        $xml = simplexml_load_file($xmlFile);
        
        if ($xml === false) {
            $errors = libxml_get_errors();
            foreach ($errors as $error) {
                echo "Error: {$error->message} in {$error->file} at line {$error->line}\n";
            }
            return false;
        }
        
        return true;
    }
}

Common Layout Issues

<!-- 1. Invalid XML syntax -->
<!-- Wrong: unclosed tag -->
<block type="Magento\Framework\View\Element\Text" />
<!-- Right: self-closing -->
<block type="Magento\Framework\View\Element\Text" />

<!-- 2. Missing module reference -->
<!-- Wrong: -->
<block class="Vendor\Module\Block\Product" />
<!-- Right: -->
<block class="Vendor\Module\Block\Product" before="-" />

<!-- 3. Invalid handle -->
<!-- Wrong: -->
<handle name="catalog_product_view_custom" />
<!-- Right: -->
<handle name="catalog_product_view">
    <!-- Add layout updates here -->
</handle>

Key Points

• Layout XML errors prevent page rendering
• Use XML validation tools
• Check var/log/exception.log for layout errors
• Clear cache after layout changes

Block Rendering Debug

// Enable block debug output
use Magento\Framework\View\Element\AbstractBlock;

class DebugBlock extends AbstractBlock
{
    protected function _toHtml()
    {
        if ($this->request->getParam('debug')) {
            return '<!-- Block: ' . get_class($this) . ' -->' . parent::_toHtml();
        }
        return parent::_toHtml();
    }
}

Block Data Inspection

// In template file
<pre>
Block Class: <?= get_class($block) ?>
Block ID: <?= $block->getNameInLayout() ?>
Block Name: <?= $block->getName() ?>
Is Protected: <?= $block->isProtected() ? 'Yes' : 'No' ?>
Children:
<?php foreach ($block->getChildren() as $child): ?>
    - <?= get_class($child) ?> (<?= $child->getNameInLayout() ?>)
<?php endforeach; ?>
</pre>

Block Arguments Debug

<!-- Layout XML with arguments -->
<block class="Vendor\Module\Block\Product">
    <arguments>
        <argument name="product_id" xsi:type="number">123</argument>
        <argument name="title" xsi:type="string">Test Product</argument>
    </arguments>
</block>

// Access arguments in block
public function __construct(
    array $data = []
) {
    parent::__construct($data);
    $this->productId = $data['product_id'] ?? null;
    $this->title = $data['title'] ?? '';
}

Key Points

• Block class must extend AbstractBlock
• Use getNameInLayout() for debugging
• Arguments are passed via layout XML
• Clear cache after block changes

Enable Template Hints

# Enable frontend template hints
bin/magento dev:template-hints:enable

# Enable admin template hints
bin/magento dev:template-hints:enable --area adminhtml

# Disable template hints
bin/magento dev:template-hints:disable

# Clear cache
bin/magento cache:clean

Template Hints Output

<!-- Template hints show: -->
<!-- [block_class] template_file.phtml -->
<div class="product-item">
    <!-- [Magento\Catalog\Block\Product\View\Description] description.phtml -->
    <div class="product attribute description">
        <?= $block->escapeHtml($_product->getDescription()) ?>
    </div>
</div>

Custom Template Debug

// In phtml template
<?php if ($block->getRequest()->getParam('debug')): ?>
<div class="debug-info">
    <strong>Template:</strong> <?= __FILE__ ?><br>
    <strong>Block:</strong> <?= get_class($block) ?><br>
    <strong>Product ID:</strong> <?= $_product->getId() ?><br>
    <strong>Variables:</strong>
    <pre><?php print_r(get_defined_vars()); ?></pre>
</div>
<?php endif; ?>

Key Points

• Template hints show block class and template file
• Use debug parameter for custom debugging
• Disable hints in production
• Check var/log/exception.log for template errors

Compile Layout

# Full compilation
bin/magento setup:di:compile

# Compile specific area
bin/magento setup:di:compile --area frontend

# Check compilation status
bin/magento setup:di:compile --dry-run

Compiled Layout Files

# Compiled files location
var/di/processed.xml     # Compiled layout
var/di/global.php        # Compiled DI
var/cache/               # Compiled blocks

# Clear compiled files
rm -rf var/di/*
rm -rf var/cache/*
bin/magento setup:di:compile

Layout Cache

// Cache configuration
// app/etc/env.php
return [
    'cache' => [
        'frontend' => [
            'layout' => [
                'backend' => 'Magento\Cache\Backend\File',
                'backend_options' => [
                    'cache_dir' => 'var/cache/layout',
                    'file_lock_timeout' => 5,
                ],
            ],
        ],
    ],
];

Key Points

• Compile after layout XML changes
• Clear cache for layout changes to take effect
• Compiled files improve performance
• Debug compilation errors for issues