Draft: Implement Magento 2 Phase 1 parity

.gitattributes

@@ -0,0 +1,16 @@
+/.github export-ignore
+/.gitignore export-ignore
+/.gitattributes export-ignore
+/.test-results export-ignore
+/docs export-ignore
+/tests export-ignore
+/node_modules export-ignore
+/vendor export-ignore
+/test-results export-ignore
+/playwright-report export-ignore
+/package.json export-ignore
+/package-lock.json export-ignore
+/playwright.config.js export-ignore
+/playwright.integration.config.js export-ignore
+/phpstan.neon export-ignore
+/phpcs.xml export-ignore

.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  composer:
+    name: Composer 2.10 strict validation
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out source
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Validate Composer metadata strictly
+        run: docker run --rm -v "$GITHUB_WORKSPACE:/app" -w /app composer:2.10 validate --strict --no-check-publish
+
+      - name: Check optimized production classmap
+        run: |
+          docker run --rm -v "$GITHUB_WORKSPACE:/app" -w /app composer:2.10 dump-autoload --optimize --strict-psr --no-dev --no-scripts --no-plugins --no-interaction
+          docker run --rm -v "$GITHUB_WORKSPACE:/module:ro" -w /module php:8.3-cli php tests/php/check-classmap.php
+
+  php:
+    name: PHP ${{ matrix.php }} validation
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+    container: php:${{ matrix.php }}-cli
+    steps:
+      - name: Install Git for committed-package regression checks
+        run: apt-get update && apt-get install -y --no-install-recommends git
+
+      - name: Check out source
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Report runtime
+        run: php --version
+
+      - name: Lint PHP
+        run: find . -type f \( -name '*.php' -o -name '*.phtml' \) -not -path './vendor/*' -print0 | xargs -0 -n1 php -l
+
+      - name: Run focused PHP checks
+        run: php tests/php/run.php
+
+      - name: Validate declared PHP constraint
+        run: php -r '$data=json_decode(file_get_contents("composer.json"), true, 512, JSON_THROW_ON_ERROR); if (($data["require"]["php"] ?? "") !== ">=8.2 <8.5") { exit(1); }'
+
+  browser:
+    name: Chromium loader and beacon checks
+    runs-on: ubuntu-24.04
+    env:
+      BASICRUM_TEST_PHP: php
+    steps:
+      - name: Check out source
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up PHP for rendered browser fixtures
+        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # 2.35.5
+        with:
+          php-version: '8.3'
+          tools: none
+          coverage: none
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.19.0
+          cache: npm
+
+      - name: Install test dependencies
+        run: npm ci
+
+      - name: Check native integration test discovery (no Magento execution)
+        run: npx --no-install playwright test --config=playwright.integration.config.js --list
+
+      - name: Install Chromium
+        run: npx --no-install playwright install --with-deps chromium
+
+      - name: Run loader and real-Boomerang checks
+        run: npm test
+
+      - name: Upload browser report and failure traces
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: chromium-report
+          path: playwright-report/
+          retention-days: 7

.github/workflows/native.yml

@@ -0,0 +1,22 @@
+name: Pinned native Magento
+on:
+  workflow_dispatch:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  native:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Build and provision isolated Mage-OS mirror baseline
+        run: sh tests/integration/docker/start.sh
+      - name: Install distribution and run pinned native gate
+        run: |
+          docker compose -f tests/integration/docker/compose.yaml exec -T -w /module php sh tests/integration/build-artifact.sh
+          docker compose -f tests/integration/docker/compose.yaml exec -T php sh /module/tests/integration/docker/install-artifact.sh
+          docker compose -f tests/integration/docker/compose.yaml exec -T -w /module -e BASICRUM_RELEASE_TAG=0.1.0 php sh tests/integration/release-gate.sh
+      - name: Stop only this disposable stack
+        if: always()
+        run: docker compose -f tests/integration/docker/compose.yaml down

.github/workflows/quality.yml

@@ -0,0 +1,47 @@
+name: Magento code quality
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  quality:
+    name: PHP ${{ matrix.php }} / ${{ matrix.dependencies }} components
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+        dependencies: [lowest, stable]
+        include:
+          - php: '8.3'
+            dependencies: locked
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # 2.35.5
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer:2.10
+          extensions: bcmath, gd, intl, pdo_mysql, soap, sodium, xsl, zip
+          coverage: none
+      - name: Resolve real Magento components, never test doubles
+        working-directory: tests/quality
+        env:
+          DEPENDENCIES: ${{ matrix.dependencies }}
+        run: |
+          case "$DEPENDENCIES" in
+            locked) composer install --prefer-dist --no-scripts --no-interaction ;;
+            lowest) composer update --prefer-lowest --prefer-stable --prefer-dist --no-scripts --no-interaction ;;
+            stable) composer update --prefer-stable --prefer-dist --no-scripts --no-interaction ;;
+          esac
+      - name: Record resolved Magento component versions
+        working-directory: tests/quality
+        run: composer show 'magento/*' --no-interaction
+      - name: PHPStan level 8 and Magento coding standards
+        run: sh tests/quality/check.sh
+      - name: Build and verify production distribution
+        if: matrix.dependencies == 'locked'
+        run: |
+          sh tests/integration/build-artifact.sh
+          php tests/integration/test-artifact.php

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.test-results/
+test-results/
+playwright-report/
+vendor/

Api/PageTypeDetectorInterface.php

@@ -1,7 +1,7 @@
 <?php
 declare(strict_types=1);
 
-namespace BasicRum\Analytics\Api;
+namespace Basicrum\Analytics\Api;
 
 /**
  * Interface for page type detection service

Block/Adminhtml/System/Config/BoomerangVersion.php

@@ -1,16 +1,21 @@
 <?php
 declare(strict_types=1);
 
-namespace BasicRum\Analytics\Block\Adminhtml\System\Config;
+namespace Basicrum\Analytics\Block\Adminhtml\System\Config;
 
-use Magento\Config\Block\System\Config\Form\Field;
-use Magento\Backend\Block\Template\Context;
+use Basicrum\Analytics\Model\Config;
 use Magento\Framework\Data\Form\Element\AbstractElement;
 
-class BoomerangVersion extends Field
+class BoomerangVersion extends ReadOnlyField
 {
-    protected function _getElementHtml(AbstractElement $element)
+    /**
+     * @inheritDoc
+     */
+    protected function _getElementHtml(AbstractElement $element): string
     {
-        return 'Boomerang JS v. 1.815.60 - cutting-edge - 30 KB (gzipped)';
+        return (string) $this->escapeHtml(sprintf(
+            'Boomerang JS v. %s - cutting-edge - 30 KB (gzipped)',
+            Config::BOOMERANG_VERSION
+        ));
     }
-}
+}

Block/Adminhtml/System/Config/Logo.php

@@ -1,32 +1,37 @@
 <?php
 declare(strict_types=1);
 
-namespace BasicRum\Analytics\Block\Adminhtml\System\Config;
+namespace Basicrum\Analytics\Block\Adminhtml\System\Config;
 
 use Magento\Config\Block\System\Config\Form\Field;
-use Magento\Backend\Block\Template\Context;
 use Magento\Framework\Data\Form\Element\AbstractElement;
 
 class Logo extends Field
 {
-    public function __construct(
-        Context $context,
-        array $data = []
-    ) {
-        parent::__construct($context, $data);
-    }
+    /** @var string */
+    protected $_template = 'Basicrum_Analytics::system/config/logo.phtml';
 
-    public function render(AbstractElement $element)
+    /**
+     * @inheritDoc
+     */
+    public function render(AbstractElement $element): string
     {
-        $html = '<div style="margin: 20px 0; text-align: center; font-size: 3rem;">';
-        $html .= '<img src="' . $this->getViewFileUrl('BasicRum_Analytics::images/basicrum-log.svg') . '" alt="BasicRum Logo" style="width: 35px; height: 35px;" />'; 
-        $html .= 'BasicRUM Analytics';
-        $html .= '</div>';
-        return $html;
+        return $this->_toHtml();
     }
 
-    protected function _getElementHtml(AbstractElement $element)
+    /**
+     * @inheritDoc
+     */
+    protected function _getElementHtml(AbstractElement $element): string
     {
         return $this->render($element);
     }
+
+    /**
+     * Resolve the logo through Magento's deployed static-asset URLs.
+     */
+    public function getLogoUrl(): string
+    {
+        return $this->getViewFileUrl('Basicrum_Analytics::images/basicrum-logo.png');
+    }
 }

Block/Adminhtml/System/Config/ReadOnlyField.php

@@ -0,0 +1,24 @@
+<?php
+declare(strict_types=1);
+
+namespace Basicrum\Analytics\Block\Adminhtml\System\Config;
+
+use Magento\Config\Block\System\Config\Form\Field;
+use Magento\Framework\Data\Form\Element\AbstractElement;
+
+/** Display-only information has no saved value to inherit or restore. */
+class ReadOnlyField extends Field
+{
+    /**
+     * @inheritDoc
+     */
+    public function render(AbstractElement $element): string
+    {
+        $element->unsScope()
+            ->unsCanUseWebsiteValue()
+            ->unsCanUseDefaultValue()
+            ->unsCanRestoreToDefault();
+
+        return parent::render($element);
+    }
+}