netresearch / nr-sync

1.0.7 2025-02-05 13:09 UTC

Requires

• ext-ftp: *
• ext-zlib: *
• netresearch/nr-scheduler: *
• typo3/cms-backend: ^12.4
• typo3/cms-core: ^12.4
• typo3/cms-extbase: ^12.4
• typo3/cms-fluid: ^12.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.65
• overtrue/phplint: ^9.5
• phpstan/phpstan: ^1.0 || ^2.0
• phpstan/phpstan-deprecation-rules: ^1.0 || ^2.0
• phpstan/phpstan-strict-rules: ^1.0 || ^2.0
• saschaegerer/phpstan-typo3: ^1.0 || v2.x-dev
• ssch/typo3-rector: ^2.0 || ^3.0

GPL-3.0-or-later

• Sebastian Mendel
• Rico Sonntag

• sync
• extension
• typo3

Published on Packagist.org on 2025-02-05 13:09 UTC

README

nr-sync - TYPO3 Content Synchronization

Introduction

• Prepares your Content for a synchronization wherever you want
• Easy integration for your own extensions
• No content editing on live systems anymore

Description

The extension provides an easy and editor friendly way to prepare the content for a synchronization to other environments e.g. live, testing or development systems. All the synchronizations can be done complete or incremental to keep the required load to an absolute minimum. The extension won't do the synchronization by itself.

Installation

Composer

composer require netresearch/nr-sync

GIT

git clone [e-mail]:netresearch/t3x-sync.git

PSR-14 Events

The extension provides several PSR-14 events that allow you to extend and customize the synchronization behavior:

BeforeSyncEvent

Dispatched before a sync dump is created. Allows you to modify the tables that will be synced.

Event Class: Netresearch\Sync\Event\BeforeSyncEvent

Example Usage:

<?php
namespace Vendor\MyExtension\EventListener;

use Netresearch\Sync\Event\BeforeSyncEvent;

final class ModifyTablesBeforeSync
{
    public function __invoke(BeforeSyncEvent $event): void
    {
        $tables = $event->getTables();
        // Add a custom table to the sync
        $tables[] = 'tx_myextension_domain_model_item';
        $event->setTables($tables);
    }
}

Register in Configuration/Services.yaml:

Vendor\MyExtension\EventListener\ModifyTablesBeforeSync:
    tags:
        - name: event.listener
          event: Netresearch\Sync\Event\BeforeSyncEvent

AfterSyncEvent

Dispatched after a sync dump has been created. Allows you to perform actions after the sync completes.

Event Class: Netresearch\Sync\Event\AfterSyncEvent

Example Usage:

<?php
namespace Vendor\MyExtension\EventListener;

use Netresearch\Sync\Event\AfterSyncEvent;
use Psr\Log\LoggerInterface;

final class LogAfterSync
{
    public function __construct(
        private readonly LoggerInterface $logger
    ) {
    }

    public function __invoke(AfterSyncEvent $event): void
    {
        if ($event->isSuccess()) {
            // Log successful sync
            $this->logger->info('Sync completed successfully', [
                'dumpFile' => $event->getDumpFile(),
                'tables' => $event->getTables(),
            ]);
        }
    }
}

Register in Configuration/Services.yaml:

Vendor\MyExtension\EventListener\LogAfterSync:
    tags:
        - name: event.listener
          event: Netresearch\Sync\Event\AfterSyncEvent

ModifyMenuItemsEvent

Dispatched when building the sync module menu. Allows you to add custom menu items to the backend module.

Event Class: Netresearch\Sync\Event\ModifyMenuItemsEvent

Example Usage:

<?php
namespace Vendor\MyExtension\EventListener;

use Netresearch\Sync\Event\ModifyMenuItemsEvent;
use TYPO3\CMS\Backend\Template\Components\Menu\MenuItem;

final class AddCustomMenuItem
{
    public function __invoke(ModifyMenuItemsEvent $event): void
    {
        $menuItem = GeneralUtility::makeInstance(MenuItem::class);
        $menuItem->setTitle('Custom Sync');
        $menuItem->setHref('/custom-sync-url');
        $menuItem->setActive(false);
        
        $event->addMenuItem($menuItem);
    }
}

Register in Configuration/Services.yaml:

Vendor\MyExtension\EventListener\AddCustomMenuItem:
    tags:
        - name: event.listener
          event: Netresearch\Sync\Event\ModifyMenuItemsEvent

ModifyTableListEvent

Dispatched when determining which tables to sync for a module. Allows you to dynamically add or remove tables.

Event Class: Netresearch\Sync\Event\ModifyTableListEvent

Example Usage:

<?php
namespace Vendor\MyExtension\EventListener;

use Netresearch\Sync\Event\ModifyTableListEvent;

final class AddCustomTables
{
    public function __invoke(ModifyTableListEvent $event): void
    {
        // Add a table only for specific modules
        if ($event->getModuleIdentifier() === 'netresearch_sync_singlePage') {
            $event->addTable('tx_myextension_domain_model_item');
        }
        
        // Or remove a table
        $event->removeTable('unwanted_table');
    }
}

Register in Configuration/Services.yaml:

Vendor\MyExtension\EventListener\AddCustomTables:
    tags:
        - name: event.listener
          event: Netresearch\Sync\Event\ModifyTableListEvent

FalSyncEvent

Dispatched to immediately trigger a FAL (File Abstraction Layer) sync.

Event Class: Netresearch\Sync\Event\FalSyncEvent

Example Usage:

<?php
namespace Vendor\MyExtension\Service;

use Netresearch\Sync\Event\FalSyncEvent;
use Psr\EventDispatcher\EventDispatcherInterface;

final class MyService
{
    public function __construct(
        private readonly EventDispatcherInterface $eventDispatcher
    ) {
    }

    public function triggerFalSync(): void
    {
        $event = new FalSyncEvent(
            areaId: 1,
            dumpFilePrefix: 'my-custom-prefix'
        );
        $this->eventDispatcher->dispatch($event);
    }
}

Development

Testing

composer install

composer ci:cgl
composer ci:test
composer ci:test:php:lint
composer ci:test:php:phpstan
composer ci:test:php:rector

Security

docs/SECURITY-ASSURANCE.md describes which data the sync modules write, what the extension protects and what it leaves to the operator, its trust boundaries and the deployment requirements. Report vulnerabilities as described in SECURITY.md.

Governance and policies

This extension follows the organisation-wide Netresearch policies:

• Governance: ownership, roles, how decisions are made and conflicts resolved.
• Roadmap: planned and excluded work for the next twelve months.
• Handling of dependency and code analysis findings: which vulnerability, licence and static-analysis findings must be fixed, by when, and how exceptions are recorded.
• Secret management: where CI and release credentials are stored, who may use them, how committed secrets are detected, and when secrets are rotated.
• Access roster: the people and teams with administrative or write access to this repository.

Checks that the workflows in .github/workflows/ run on pull requests:

• .github/workflows/checks.yml: Composer Audit (fails on any advisory for an installed package; composer.json lists no config.audit.ignore exceptions) and Opengrep SAST (which findings block is set organisation-wide, see Static analysis (SAST)), both through typo3-ci-workflows' security.yml; Dependency Review (fails on newly added dependencies with a vulnerability of severity high or higher); PHP License Audit (license-check.yml, fails on an SSPL or BSL licensed Composer dependency); CodeQL with language auto-detection, which finds no Go or JavaScript source here and analyses the workflow files (CodeQL has no PHP analysis; PHPStan and Opengrep cover the PHP code); Betterleaks secret scanning; zizmor for the workflow files (reported to code scanning, not blocking); the pull request quality check (pr-quality, on non-draft pull requests only: its Quality Gate job reports the size of the change and warns on large pull requests, its Auto-Approve job approves pull requests opened from this repository by authors GitHub associates with it as owner, member or collaborator); and the aggregate gate All security checks, which fails when one of these jobs fails or is cancelled. The fuzz job finds no Fuzz test suite in Build/phpunit.xml and is skipped.
• .github/workflows/ci.yml: lint (php -l, plus checks that ext_emconf.php declares no strict_types and that .gitattributes has export-ignore rules), PHPStan (level 6 with the baseline Build/phpstan-baseline.neon) and the unit tests on PHP 8.2 to 8.5 with TYPO3 ^13.4; code style (PHP-CS-Fixer, Build/.php-cs-fixer.dist.php) and Rector (Build/rector.php) on one PHP version; an advisory PHPStan pass against the PHPUnit the matrix resolves without the version cap (PHPStan (unpinned PHPUnit)); and the aggregate gate All CI checks. There are no functional tests (run-functional-tests: false), Fractor is not part of the CI run, and there is no Documentation/guides.xml to render.
• .github/workflows/harness-verify.yml: scripts/verify-harness.sh checks the agent documentation against the tree.
• .github/workflows/labeler.yml: labels the pull request by the paths it changes; .github/workflows/community.yml: greets a contributor on their first pull request; .github/workflows/auto-merge-deps.yml: approves and enables auto-merge for Dependabot and Renovate pull requests that carry neither the deps-no-automerge nor the deps-major label, and is skipped for all others.

The reusable workflows also run helper jobs that decide which of their jobs apply, for example Preflight (event gate), Detect Documentation and CodeQL's Prepare languages.