Adobe Commerce Implementation Playbook

https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook
Admin
A comprehensive guide providing best practices and methodologies for planning, developing,...
Tokens:54,210
Snippets:629
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### Create Example Patch File

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/patching-at-scale?lang=en

An example of a patch file format using standard diff syntax to modify Magento framework files.

```diff
diff --git a/vendor/magento/framework/Mview/View/Subscription.php b/vendor/magento/framework/Mview/View/Subscription.php
index 03a3bf9..681e0b0 100644
--- a/vendor/magento/framework/Mview/View/Subscription.php
+++ b/vendor/magento/framework/Mview/View/Subscription.php
@@ -16,6 +16,7 @@ use Magento\Framework\Mview\ViewInterface;
 
 /**
  * Mview subscription.
+ * Test Patch File
  */
 class Subscription implements SubscriptionInterface
 {
```

--------------------------------

### Start Asynchronous Image Resize Queue Handlers

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/catalog-image-resizing

Starts multiple queue consumer processes for image resizing based on the number of available processors. This command should be run on every web server to increase throughput.

```bash
for i in {1.."$((2 * `nproc --all`))"};do bin/magento queue:consumers:start media.storage.catalog.image.resize &;done;
```

--------------------------------

### Log Exception Messages and Trace with PSR-3 in PHP

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/exception-handling

This PHP example shows how to log both the exception message and its full trace using the PSR-3 context standard. It catches an exception and logs its message, the exception object, and the exception's trace. This is useful for detailed debugging.

```php
try {
    $this->productRepository->getById($sku);
} catch (Exception $e) {
    $this->logger->critical($e->getMessage(), ['exception' => $e, 'trace' => $e->getTrace()]);
}
```

--------------------------------

### Downgrade Exceptions Safely in PHP

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/exception-handling

This PHP example shows how to downgrade an exception to an error log entry without losing crucial context. It highlights the importance of passing the full exception object or its relevant details to the logger, rather than just the message, to preserve the stack trace.

```php
try {
    $this->productRepository->getById($sku);
} catch (Exception $e) {
    $this->logger->error($e->getMessage());
}
```

--------------------------------

### Composer Get Subscribed Events Method

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/patching-at-scale

Specifies the events that this Composer plugin subscribes to. It returns an array mapping event names to the methods that should be called when those events occur.

```php
public static function getSubscribedEvents()
{
    return [
        ScriptEvents::POST_UPDATE_CMD => 'installPatches',
        ScriptEvents::POST_INSTALL_CMD => 'installPatches',
    ];
}
```

--------------------------------

### Implement Dependency Injection and Class Overrides in PHP

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/modifying-core-and-third-party-code

Demonstrates how to inject dependencies via constructor and how to extend existing classes to override core functionality. These patterns are essential for modifying Adobe Commerce behavior while maintaining modularity.

```php
class SomeClass
{
    public function __construct(
        private readonly AllowedCountries $allowedCountriesReader
    ) {}

    /**
     * Check is address allowed for store
     *
     * @param AddressInterface $address
     * @param int|null $storeId
     * @return bool
     */
    private function isAddressAllowedForWebsite(AddressInterface $address, $storeId): bool
    {
        $allowedCountries = $this->allowedCountriesReader->getAllowedCountries(ScopeInterface::SCOPE_STORE, $storeId);

        return in_array($address->getCountryId(), $allowedCountries);
    }
}
```

```php
use Magento\Store\Model\ScopeInterface;

class OverrideAllowedCountries extends AllowedCountries
{
    /**
     * Retrieve all allowed countries for scope or scopes
     *
     * @param string $scope
     * @param string|null $scopeCode
     * @return array
     * @since 100.1.2
     */
    public function getAllowedCountries($scope, $scopeCode)
    {
        // Override logic implementation
    }
}
```

--------------------------------

### Implement Around and After Plugins for CategoryRepository

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/modifying-core-and-third-party-code

Demonstrates the use of aroundGet and afterGet plugins to intercept category retrieval. These methods allow developers to modify input parameters, execute custom logic before or after the original method, or replace the method entirely.

```php
public function aroundGet($subject, $origMethod, $categoryId, $storeId = null): \Magento\Catalog\Api\Data\CategoryInterface
{
    // Logic before original method
    $result = $origMethod($categoryId, $storeId);
    // Logic after original method
    return $result;
}

public function afterGet($subject, $result, $categoryId, $storeId = null): \Magento\Catalog\Api\Data\CategoryInterface
{
    // Modify or process the result after the original method executes
    return $result;
}
```

--------------------------------

### Implement CentralizedPatcher Composer Plugin in PHP

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/patching-at-scale

This PHP class implements the Composer PluginInterface and EventSubscriberInterface to hook into the composer lifecycle. It is designed to read and apply quality patches automatically after package installation.

```php
<?php
declare(strict_types=1);

namespace MagentoServices\CentralizedPatcherComposerPlugin;

use Composer\Composer;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
use Composer\Script\ScriptEvents;
```

--------------------------------

### Configure Cache Preload Keys in .magento.env.yaml

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/planning/valkey-service-configuration

This YAML configuration snippet demonstrates how to define cache backend settings and specify keys for preloading. It includes options for merging configurations and lists the exact keys to be preloaded, identified by a prefix.

```yaml
stage:
  deploy:
    VALKEY_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          id_prefix: '061_'                       # Prefix for keys to be preloaded
          backend_options:
            preload_keys:                         # List the keys to be preloaded
              - '061_EAV_ENTITY_TYPES:hash'
              - '061_GLOBAL_PLUGIN_LIST:hash'
              - '061_DB_IS_UP_TO_DATE:hash'
              - '061_SYSTEM_DEFAULT:hash'
```

--------------------------------

### Run Magento Coding Standard

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/code-review

Executes the PHP_CodeSniffer tool against a specific module to ensure compliance with Magento 2 coding standards. The script assumes the coding standard tool is installed in the user's home directory.

```bash
#!/usr/bin/env bash
$HOME/web/magento/magento-coding-standard/vendor/bin/phpcs --standard=Magento2 "$@"
```

--------------------------------

### Generate Image Resize URLs with Bash `find` and `sed`

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/catalog-image-resizing

This snippet demonstrates how to generate a list of image URLs for resizing using bash commands. It utilizes `find` to locate image files and `sed` to transform their paths into accessible URLs, excluding cached versions. This is useful for preparing images for bulk processing.

```bash
cd pub/
find ./media/catalog/product -path ./media/catalog/product/cache -prune -o -type f -print | sed 's~./media/catalog/product/~https://www.example.com/media/catalog/product/cache/0047d83143a5a3a4683afdf1116df680/~g' > images.txt
```

--------------------------------

### Modify Plugin Result in PHP

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/modifying-core-and-third-party-code

This PHP code snippet demonstrates how to modify the result produced by an original 'get' function within a plugin. It shows access to original function arguments for reading and returning the modified result. This functionality is specific to PHP classes.

```php
    {
        // here you modify the result produced by the original `get` function or you can execute some other functionality
        // note that you also have access to the original function arguments. it's too late to modify them, but if needed, they are available for readi
        // ng

        return $result;
    }
}
```

--------------------------------

### Perform DI Compilation and Deployment

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/code-review

This script automates the Magento dependency injection compilation process. It clears generated files, resets caches, and executes the compilation and static content deployment commands.

```bash
bin/magento module:disable -n -q --all || exit;
bin/magento module:enable -n -q --all || exit;
bin/magento cache:enable -n -q || exit;
bin/magento cache:flush -n -q || exit;
rm -rf generated/*
rm -rf var/view_preprocessed/*
rm -rf pub/static/*
rm -rf var/cache/*
bin/magento deploy:mode:set --skip-compilation production || exit;
bin/magento setup:di:compile -vv || exit;
bin/magento setup:static-content:deploy en_US || exit;
bin/magento deploy:mode:set developer || exit;
```

--------------------------------

### Install Centralized Quality Patches via Composer Script

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/patching-at-scale

This PHP function iterates through locked Composer packages to locate the centralized patcher, extracts patch configurations, and executes the patch application command. It requires the magento-services/centralized-patcher package and outputs status messages to the console.

```php
public function installPatches(\Composer\Script\Event $event)
{
    $patches = [];
    $this->io->write('Applying centralized quality patches');
    $packages = $this->composer->getLocker()->getLockData()['packages'];
    foreach ($packages as $package) {
        if ($package['name'] !== 'magento-services/centralized-patcher') {
            continue;
        }
        $patches = $package['extra']['quality-patches'] ?? [];
    }
    if (empty($patches)) {
        $this->io->error("No centralized quality patches to install");
        exit(0);
    }
    $command = array_merge(
        ['php','./vendor/bin/magento-patches','apply','--no-interaction']
    );
}
```

--------------------------------

### Identify MyISAM tables in Adobe Commerce database

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/planning/database-on-cloud

This SQL query scans the information_schema to locate any database tables currently using the MyISAM storage engine, excluding system schemas. It is useful for auditing third-party extensions before or after installation.

```sql
SELECT table_schema, CONCAT(ROUND((index_length+data_length)/1024/1024),'MB') AS total_size FROM information_schema.TABLES WHERE engine='myisam' AND table_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys');
```

--------------------------------

### Enable Valkey slave connection in .magento.env.yaml

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/planning/valkey-service-configuration

Configures the deployment environment to utilize a Valkey slave connection. This setting allows read-only traffic to be offloaded to slave nodes, improving performance on supported architectures.

```yaml
stage:
  deploy:
    VALKEY_USE_SLAVE_CONNECTION: true
```

--------------------------------

### Implement Category Repository Plugin in PHP

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/modifying-core-and-third-party-code

This PHP code defines a plugin class that intercepts calls to the `CategoryRepositoryInterface`. It demonstrates the `beforeGet` method, which is executed before the original method. This allows for pre-processing of arguments or early termination of the method.

```php
<?php

declare(strict_types=1);

namespace Adobe\CatalogAdjustments\Plugin;

class CategoryRepositoryPlugin
{
    /**
     * @param \Magento\Catalog\Api\CategoryRepositoryInterface $subject
     * @param int $categoryId
     * @param int $storeId
     *
     * @return array
     */
    public function beforeGet($subject, $categoryId, $storeId = null): array
    {

```

--------------------------------

### Prevent Empty Catch Blocks in PHP Exception Handling

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/exception-handling

This PHP code illustrates an empty `catch` block, which is an incorrect exception handling practice. Empty catch blocks can unintentionally mute errors and should be avoided. This example catches a `NoSuchEntityException` but does nothing within the block.

```php
try {
    $this->productRepository->deleteById($sku);
} catch (NoSuchEntityException $e) {
}
```

--------------------------------

### Configure Fastly VCL for Multi-site Sitemap and Robots Rewrites

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/launch/robots-txt

This VCL snippet redirects requests for robots.txt and sitemap.xml to site-specific files located in the pub/media directory. It uses regex matching on the request host to determine the correct file prefix based on the domain.

```vcl
{
  "name": "sitemaprobots_rewrite",
  "dynamic": "0",
  "type": "recv",
  "priority": "90",
  "content": "if ( req.url.path == \"/robots.txt\" ) { if ( req.http.host ~ \"(domainone|domaintwo).com$\" ) { set req.url = \"pub/media/\" re.group.1 \"_robots.txt\"; }} else if ( req.url.path == \"/sitemap.xml\" ) { if ( req.http.host ~ \"(domainone|domaintwo).com$\" ) {  set req.url = \"pub/media/\" re.group.1 \"_sitemap.xml\"; }}"
}
```

--------------------------------

### Declare and Implement an Adobe Commerce Preference

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/modifying-core-and-third-party-code

This snippet demonstrates how to register a class override in the di.xml configuration file and the corresponding PHP class implementation that extends the original class to maintain type compatibility.

```xml
<preference for="Magento\Elasticsearch7\SearchAdapter\Adapter" type="Vendor\Namespace\Adapter\AlgoliaElasticSearch7Adapter"/>
```

```php
<?php

declare(strict_types=1);

namespace Vendor\Namespace\Adapter;

class AlgoliaElasticSearchAdapter extends \Magento\Elasticsearch7\SearchAdapter\Adapter
{
}
```

--------------------------------

### Enable JavaScript Bundling via CLI

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/optimize-css-js-files

Enables the built-in basic JavaScript bundling feature using the Magento CLI. Note that bundling and merging cannot be enabled simultaneously in the system configuration.

```bash
php -f bin/magento config:set dev/js/enable_js_bundling 1
```

--------------------------------

### Enable asynchronous indexing via Magento CLI

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/order-processing-configuration

Uses the Magento CLI command to set the configuration for asynchronous grid indexing. This is primarily intended for Adobe Commerce on cloud infrastructure and on-premises sites running in Production mode.

```bash
php bin/magento config:set dev/grid/async_indexing 1
```

--------------------------------

### Log messages using Monolog

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/debugging

Shows how to instantiate a custom Monolog logger with a StreamHandler to write logs to a specific file. This method is useful for custom logging requirements outside the standard framework flow.

```php
$log = new \Monolog\Logger('custom', [new \Monolog\Handler\StreamHandler(BP.'/var/log/test.log')]);
$log->info('Your Logging Message', ['context' => ['email' => 'john@example.com']]);
```

--------------------------------

### Create Composer Plugin Configuration (JSON)

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/patching-at-scale?lang=en

This JSON defines the configuration for the `centralized-patcher-composer-plugin` Composer plugin. It specifies dependencies, autoloading rules, and the main plugin class, enabling it to hook into Composer's lifecycle.

```json
{
 "name": "magento-services/centralized-patcher-composer-plugin",
 "version": "0.0.1",
 "description": "Centralized patcher composer plugin to apply quality patches from the centralized patcher",
 "type": "composer-plugin",
 "license": [
     "OSL-3.0",
     "AFL-3.0"
 ],
 "require": {
     "symfony/process": "^4.1 || ^5.1",
     "magento/magento-cloud-patches": "~1.0.20",
     "magento/framework": "~103.0.5-p1",
     "composer-plugin-api": "^2.0"
 },
 "require-dev": {
     "composer/composer": "^2.0"
 },
 "suggest": {
     "magento-services/centralized-patcher": "~0.0.1"
 },
 "autoload": {
     "psr-4": {
         "MagentoServices\CentralizedPatcherComposerPlugin\": ""
     }
 },
 "extra": {
     "class": "MagentoServices\CentralizedPatcherComposerPlugin\Patcher"
 }
}

```

--------------------------------

### Configure Fastly VCL for Sitemap and Robots.txt Redirection

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/launch/robots-txt

This VCL snippet intercepts requests for root-level sitemap.xml and robots.txt files and rewrites the URL path to point to the pub/media directory. This is required for Adobe Commerce on cloud infrastructure due to the read-only file system constraints.

```vcl
{
  "name": "sitemaprobots_rewrite",
  "dynamic": "0",
  "type": "recv",
  "priority": "90",
  "content": "if ( req.url.path ~ \"^/?sitemap.xml$\" ) { set req.url = \"pub/media/sitemap.xml\"; } else if (req.url.path ~ \"^/?robots.txt$\") { set req.url = \"pub/media/robots.txt\";}"
}
```

--------------------------------

### Log messages using Zend Log

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/development/debugging

Illustrates the legacy approach of using Zend Log components to write messages to a stream. It supports logging both simple strings and serialized array data.

```php
$writer = new \Zend\Log\Writer\Stream(BP . '/var/log/test.log');
$logger = new \Zend\Log\Logger();
$logger->addWriter($writer);
$logger->info('Your text message');
$logger->info(print_r($yourArray, true));
```

--------------------------------

### Convert Table to Dynamic Format (MySQL)

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/maintenance/mariadb-upgrade

This snippet demonstrates the SQL command to convert a specified table to the dynamic row format. This is useful for optimizing storage and performance for tables with variable-length data. Ensure you replace '[ table name here ]' with the actual table name.

```mysql
ALTER TABLE [ table name here ] ROW_FORMAT=DYNAMIC;
```

--------------------------------

### Configure Valkey L2 Cache Backend in .magento.env.yaml

Source: https://experienceleague.adobe.com/en/docs/commerce-operations/implementation-playbook/best-practices/planning/valkey-service-configuration

This snippet shows how to configure the Valkey L2 cache by setting the VALKEY_BACKEND deployment variable in the .magento.env.yaml file. This is a crucial step for enabling remote synchronized caching in Adobe Commerce.

```yaml
stage:
  deploy:
    VALKEY_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'
```
Tokens:
Raw