[Colaboró Tony Evers, arquitecto técnico senior de Adobe]{class="badge informative" title="Colaboró Tony Evers"}

Patrón de arquitectura de referencia global de paquetes masivos

En esta guía se explica cómo configurar Adobe Commerce con el patrón de arquitectura de referencia global (GRA) de paquetes en lote.

El patrón GRA de paquetes masivos implica un único repositorio Git para alojar todas las personalizaciones comunes. Este repositorio único de Git se expone a través de Composer como un paquete único composer, que contiene varios módulos Adobe Commerce.

{align="center"}

Ventajas y desventajas de este patrón

Ventajas:

Desventajas:

Configuración de Adobe Commerce con el patrón Split Git GRA

La estructura del directorio

El GRA de paquetes masivos instala todo el código reutilizable a través de los repositorios de Composer. El código específico de una sola instancia reside dentro del repositorio Git de esa instancia. El código específico de la instancia no se reutiliza en otras instancias de Adobe Commerce.

La estructura final de directorios de una instalación completa de Adobe Commerce con el patrón GRA de paquetes en lote tiene este aspecto:

.
├── app/
│   └── etc/
│       └── config.php
├── composer.json
├── composer.lock
└── packages/
    └── local/

Los directorios app/code, app/i18n y app/design se omiten a propósito, porque Composer no evalúa el código de estos directorios. Como resultado, las dependencias que se declaran en los paquetes no se instalan automáticamente. El patrón GRA de paquetes masivos resuelve este problema instalando código personalizado en packages/ y tratando ese directorio como un repositorio del compositor. El compositor enlaza simbólicamente paquetes dentro de packages/ a vendor/.

Preparación de los repositorios de Git

Cree dos repositorios Git para el código GRA compartido y para el primer almacén. Comience con el repositorio GRA, que tiene la siguiente estructura de archivos:

El resultado es la siguiente estructura de directorio:

.
├── composer.json
└── src/
    ├── GraOne/
    │   ├── composer.json
    │   └── registration.php
    ├── GraTwo/
    │   ├── composer.json
    │   └── registration.php
    └── registration.php

Esta estructura de directorio solo menciona el archivo composer.json y el archivo registration.php de los módulos GraOne y GraTwo. En realidad, hay más archivos dentro de estos módulos.

Ejecute estos comandos para iniciar el repositorio Git:

mkdir gra-bulk-foundation
cd gra-bulk-foundation
git init
git remote add origin git@github.com:AntonEvers/gra-bulk-foundation.git
vim composer.json # see code snippet below for contents
git add composer.json
git commit -m 'initialize GRA foundation repository'
git push -u origin main

El archivo composer.json contiene lo siguiente:

{
    "name": "antonevers/gra-bulk-foundation",
    "description": "Shared code repository",
    "type": "library",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "require": {},
    "autoload": {
        "files": [
            "src/registration.php"
        ],
        "psr-0": {
            "": "src/"
        }
    }
}

Cambie el área de nombres del paquete composer.json a su propia área de nombres.

El archivo src/registration.php contiene:

<?php

declare(strict_types=1);

$pathList[] = dirname(__DIR__) . '/src/*/*/registration.php';
foreach ($pathList as $path) {
    $files = glob($path, GLOB_NOSORT | GLOB_ERR);
    if ($files === false) {
        throw new RuntimeException('glob() returned error while searching in \'' . $path . '\'');
    }
    foreach ($files as $file) {
        require_once $file;
    }
}

El archivo registration.php busca otros archivos registration.php dentro de los módulos Adobe Commerce y los ejecuta.

Cree los dos módulos de ejemplo con el código de https://github.com/AntonEvers/gra-bulk-foundation. Composer no evalúa los archivos composer.json en los módulos de ejemplo. Están ahí como un hábito. Si decide mover los módulos a otro lugar, los archivos composer.json volverán a ser necesarios.

Configuración del repositorio de almacenamiento

El repositorio de implementación contiene toda la instalación de Adobe Commerce, incluido el código GRA. Cree el repositorio de implementación:

mkdir gra-bulk-brand-x
cd gra-bulk-brand-x
composer create-project --repository-url=https://repo.magento.com/ magento/project-enterprise-edition .
git init
git remote add origin git@github.com:AntonEvers/gra-bulk-brand-x.git
git add composer.json composer.lock
git commit -m 'initialize Brand X repository'
git push -u origin main

Instale Adobe Commerce con bin/magento setup:install. Instale los módulos de muestra GRA en el repositorio de implementación con Composer:

composer config repositories.gra-foundation vcs git@github.com:AntonEvers/gra-bulk-foundation.git
composer require antonevers/gra-bulk-foundation:@dev
bin/magento module:enable AntonEvers_GraOne AntonEvers_GraTwo
bin/magento test:gra-one
bin/magento test:gra-two
git add app/etc/config.php composer.json composer.lock
git commit -m 'install GRA foundation'
git push origin main

El último comando debería generar el siguiente resultado para probar que el módulo está instalado y en funcionamiento:

GRA One module is installed successfully and working!
GRA Two module is installed successfully and working!

Puede crear varios paquetes masivos para organizar el código. Por ejemplo, un paquete masivo de terceros para código de terceros que no está disponible a través de Composer. Todo lo que instalaría tradicionalmente en app/code debería estar ahora en el directorio src/ del paquete en bloque. Una excepción a esa regla es el código que solo se utiliza en una sola instancia. Estos paquetes se denominan paquetes locales.

Instalación de paquetes locales

El repositorio de implementación aloja los paquetes locales. No viven en el paquete masivo GRA. La ubicación de los paquetes locales no es app/code sino packages/local. Indique al Compositor que trate este directorio como un repositorio:

composer config repositories.local path 'packages/local/*/*'
git add composer.json
git commit -m 'initialize local composer package storage'
git push origin main

Agregue el módulo de ejemplo que se hospeda en https://github.com/AntonEvers/module-example-local:

mkdir -p packages/local
cd packages/local
mkdir antonevers
cd antonevers
curl -OL https://github.com/AntonEvers/module-example-local/archive/refs/heads/main.zip
unzip main.zip
rm main.zip
mv module-example-local-main module-local
git add module-local
cd ../../..
composer require antonevers/module-local:@dev
bin/magento module:enable AntonEvers_Local
bin/magento test:local

El último comando debería generar el siguiente resultado para probar que el módulo está instalado y en funcionamiento:

Local module is installed successfully and working!

Asigne el módulo local al repositorio de la marca:

git add packages/local/antonevers/module-local app/etc/config.php composer.json composer.lock
git commit -m 'add local module'
git push origin main

Información general sobre las ubicaciones de código

Solo si el tercero no ofrece la instalación a través de un repositorio de Composer, puede almacenar módulos de terceros en el directorio src/ de su repositorio base o en un paquete masivo de terceros dedicado.

Desarrollo de un módulo GRA

Instale el paquete masivo desde el origen para habilitar Git en el directorio de paquetes masivos:

rm -r vendor/antonevers/gra-bulk-foundation
composer install --prefer-source

El paquete masivo se ha extraído mediante Git. Cuando escribe el directorio vendor/antonevers/gra-bulk-foundation, también está entrando en el repositorio Git de base masiva. Puede crear, extraer y fusionar ramas en este directorio.

Agregue dependencias de Composer al archivo composer.json en la raíz del paquete masivo de GRA, que es el único archivo del paquete masivo que Composer evalúa.

Incluir módulos de terceros en el paquete masivo de GRA

Agregue paquetes de terceros en la sección de requisitos del archivo composer.json en la raíz de la base de GRA para agregarlos a su GRA. De este modo, los paquetes siempre se instalan en todas las instancias a través de composer.

Entrega del código

Para enviar código a la rama principal, hay dos rutas. Primero los módulos locales, que se combinan en la rama principal. Ejecute la actualización del Compositor para esos módulos. No permita que los desarrolladores actualicen composer.lock en sus ramas de tickets para reducir los conflictos. Actualice únicamente el archivo composer.lock en las ramas de ensayo y producción, lo que reduce el riesgo de conflictos.

En segundo lugar, los paquetes GRA a granel, que se combinan en la rama principal del repositorio GRA a granel. A continuación, puede agregar una etiqueta Git a la rama principal, creando versiones del paquete Composer. Requiera su nueva versión del paquete masivo de GRA en el composer.json del repositorio de implementación para instalarlo.

Estrategia de ramas

Este patrón GRA funciona con todas las estrategias de ramificación, siempre y cuando refleje la estrategia de ramificación de los repositorios de implementación en el repositorio masivo de GRA. Para las versiones, cree una rama de versión con el mismo nombre en ambos repositorios. Para el desarrollo, cree una rama de tickets en ambos repositorios.

En las ramas de tickets, casi nunca debería tener que actualizar el archivo composer.lock. Solo tiene que consultar las ramas adecuadas en su entorno de desarrollo tanto para la tienda como para el repositorio de base GRA con Git. La excepción se produce al actualizar los requisitos en el archivo composer.json de base de GRA. La actualización de la base de GRA en el repositorio de implementación solo se realiza al crear la versión o al crear una rama de control de calidad.

Ejemplos de código

Los ejemplos de código de este artículo están disponibles como un conjunto de repositorios Git, que puede utilizar para probar la prueba de concepto.