# aimes/module-checkout-designs

> Swap checkout layouts via system configuration, or conditions

`composer require aimes/module-checkout-designs`

Canonical URL: https://packagento.com/aimes/module-checkout-designs

## At a glance

- **Vendor**: Rob Aimes (https://packagento.com/aimes.md)
- **Latest version**: 1.1.0 — released 2022-03-02
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/aimes/module-checkout-designs and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require aimes/module-checkout-designs:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Swap checkout layouts via system configuration, or conditions

## README

!["Supported Magento Version"][magento-badge] !["Latest Release"][release-badge]

* Compatible with _Magento Open Source_ and _Adobe Commerce_ `2.3.x` & `2.4.x`
* Compatible with _[Hyvä Themes][hyva]_ using the _Luma Checkout Fallback_

### Features

This module provides the ability to change checkout page designs/layout similar to [page specific selectable layouts][page-layouts].

The module currently provides the following functionality:

* Provide a different checkout user experience per store
* Provide a different checkout user experience per customer group

<details>
  <summary>Example Config</summary>
   
  ![Example Config](https://user-images.githubusercontent.com/4225347/112895353-ec7ccb00-90d4-11eb-937f-cd54636fbf19.png)
</details>

This in turn will allow you to do things such as, but not limited to, the following:

> Please note: These are only examples of functionality that this module makes possible. This module itself does not provide any additional functionality and serves only as a base for other modules. For example usage, please see [`Aimes_CheckoutDesigns`][example-module].

* AB Testing any checkout changes
* Something broken or users can't checkout with a specific design? Select a different design or the default Magento checkout so that users can still checkout until you can deploy your fixed code.
* Collect different data per design to help determine any issues
    * Track the different drop-off points
    * Track conversion rates

Any feature requests and/or pull requests are welcomed!

### Requirements

* Magento Open Source or Adobe Commerce version `2.3.x` or `2.4.x`

### Installation

Please install this module via Composer. This module is hosted on [Packagist][packagist].

* `composer require aimes/module-checkout-designs`
* `bin/magento module:enable Aimes_CheckoutDesigns`
* `bin/magento setup:upgrade`

### Usage

#### Step 1: Define new checkout layout
`di.xml`
```xml
<virtualType name="Vendor\Module\Model\Checkout\Design\MyDesign"
             type="Aimes\CheckoutDesigns\Model\CheckoutDesign">
    <arguments>
        <argument name="code" xsi:type="string">my_design_code</argument>
        <argument name="name" xsi:type="string">My Design Name</argument>
        <argument name="layoutHandle" xsi:type="string">my_design_layout_handle</argument>
        <argument name="layoutProcessors" xsi:type="array">
            <item name="defaultProcessor" xsi:type="object">
                <!-- Object must implement \Magento\Checkout\Block\Checkout\LayoutProcessorInterface -->
            </item>
        </argument>
        <argument name="configProviders" xsi:type="array">
            <item name="defaultProvider" xsi:type="object">
                <!-- Object must implement \Magento\Checkout\Model\ConfigProviderInterface -->
            </item>
        </argument>
    </arguments>
</virtualType>
```

##### Explanation

* Designs must implement `\Aimes\CheckoutDesigns\Api\CheckoutDesignInterface` 
    * `code` is a unique string identifier for your design
    * `name` is a string to represnt the frontend / human friendly label
    * `layoutHandle` is a string to represent the layout handle that will be processed when the design is in use. The above would include `my_design_layout_handle.xml`
    * `layoutProcessors` is an array of objects that will only be processed when the associated design is utilised
        * Items must implement `\Magento\Checkout\Block\Checkout\LayoutProcessorInterface`
    * `configProviders` is an array of objects that will only be processed when the associated design is utilised
        * Items must implement `\Magento\Checkout\Model\ConfigProviderInterface`
    
##### Example code
For working code examples, please refer to [`Aimes_CheckoutDesignsExample`][example-module]. This package can also be installed.
    
#### Step 2: Add your design to the available options

`di.xml`
```xml
<type name="Aimes\CheckoutDesigns\Model\Config\Source\CheckoutDesigns">
    <arguments>
        <argument name="designs" xsi:type="array">
            <item name="my_design" xsi:type="object">
                Vendor\Module\Model\Checkout\Design\MyDesign
            </item>
        </argument>
    </arguments>
</type>
```
    
#### Step 3: Select design
Your design should now show up as an option in the system configuration below:

`Sales -> Checkout -> Design / Layout -> Checkout Design`

* Select the default design
* Select specific designs per customer groups

### Licence
[GPLv3][gpl] © [Rob Aimes][author]

[magento-badge]:https://img.shields.io/badge/magento-2.3.x%20%7C%202.4.x-orange.svg?logo=magento&style=for-the-badge
[release-badge]:https://img.shields.io/github/v/release/robaimes/module-checkout-designs?sort=semver&style=for-the-badge&color=blue
[page-layouts]:https://devdocs.magento.com/guides/v2.4/frontend-dev-guide/layouts/xml-manage.html#create-cms-pageproductcategory-specific-selectable-layouts
[example-module]:https://github.com/robaimes/module-checkout-designs-example
[packagist]:https://packagist.org/packages/aimes/module-checkout-designs
[gpl]:https://www.gnu.org/licenses/gpl-3.0.en.html
[author]:https://aimes.dev/
[hyva]:https://hyva.io/

## Recent Versions

| Version | Released |
|---|---|
| 1.1.0 | 2022-03-02 |
| 1.0.0 | 2021-07-03 |
| 0.1.1 | 2021-04-13 |
| 0.1.0 | 2021-03-29 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/module-checkout | ^100.3 \|\| ^100.4 |

### Suggest

| Package | Constraint |
|---|---|
| aimes/module-checkout-designs-example | Provides code examples to utilise this package |

## Quality

Latest release (1.1.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 9 | 9 warnings (ruleset: Magento2) |
| PHPMD | Warning | 2 | 2 rule violations (IfStatementAssignment:2) |
| Cpd | Pass | 0 |  |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 11 | 11 | – | – |
| 2.4.8 | – | 11 | 11 | – |
| 2.4.9 | – | – | 9 | 9 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["aimes/module-checkout-designs"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

Rob Aimes is a Magento 2 vendor on Packagento. See https://packagento.com/aimes.md for their full catalogue.