2. Install & run on a module

2. Install & run on a module

Prerequisites

This package is a rule library — you also need Rector itself and a rector.php in the module. Require both (dev only):

composer require --dev rector/rector "xoops/rector-xoops:^1.0@alpha"

Pre-release: the only published version is 1.0.0-alpha1, so the @alpha stability flag is required (it lifts minimum-stability for this package only — your project config is untouched). Once a stable 1.0.0 ships, drop it: composer require --dev xoops/rector-xoops.

Quick-start checklist

1. composer require --dev rector/rector "xoops/rector-xoops:^1.0@alpha" (pre-release — see note above)
2. Create rector.php (below) with your paths + XoopsSetList::XOOPS.
3. Dry-run — read the diff: vendor/bin/rector process --dry-run
4. Apply, then run the module's tests / load it with XOOPS_DEBUG on: vendor/bin/rector process
5. Handle .tpl templates separately (the XOOPS upgrade preflight scanner, not this tool).

rector.php

You choose the PHP level via withPhpSets(); the XOOPS set only adds the XOOPS-specific rules, so it composes cleanly. Add a withSkip() for paths that must never be rewritten:

use Rector\Config\RectorConfig;
use Rector\ValueObject\PhpVersion;
use Xoops\Rector\Set\XoopsSetList;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/class', __DIR__ . '/admin', __DIR__ . '/include', __DIR__ . '/blocks'])
    ->withPhpVersion(PhpVersion::PHP_82)        // your TARGET runtime (php74 for XoopsCore25)
    ->withPhpSets(php82: true)                  // PHP upgrade level for the GENERATED code
    ->withSets([XoopsSetList::XOOPS])           // XOOPS modernisation rules
    ->withSkip([
        '*/vendor/*', '*/language/*', '*/templates/*', '*/templates_c/*',
    ]);

Running it

This package ships no composer rector scripts — run Rector's binary directly, or add your own scripts to the module's composer.json:

vendor/bin/rector process --dry-run   # preview, change nothing
vendor/bin/rector process             # apply

// optional, in the MODULE's composer.json:
"scripts": { "rector": "rector process --dry-run", "rector:fix": "rector process" }

Always dry-run one module first, read the diff, then run the module's test suite / load it with XOOPS_DEBUG on. Roll out module-by-module; never run unattended on system or protector.

Two sets

Set	What it contains	When
XoopsSetList::XOOPS	behaviour-preserving modernisation (DB API, removed-function fixes, type-only)	default — safe to run
XoopsSetList::XOOPS_RISKY	behaviour-changing rewrites (input filtering, escaping, output encoding)	opt-in; review every diff

// opt into the risky set in addition to the default:
->withSets([XoopsSetList::XOOPS, XoopsSetList::XOOPS_RISKY])

Standalone sweep (a whole tree)

For a one-off pass across many modules, the bundled rector-xoops.php adds withPhpSets(php84: true), an example path/skip list, and the default XOOPS set only (it does not enable XOOPS_RISKY):

# config path depends on layout — from the package root use rector-xoops.php; from a consumer use vendor/...
vendor/bin/rector process /path/to/htdocs/modules/news \
  --config=vendor/xoops/rector-xoops/rector-xoops.php --dry-run