DCT Sollers - WordPress.org review notes
======================================

This document describes intentional implementation choices, not an approval by
the WordPress Plugin Review Team. PHPCS exceptions are limited to individual
reviewed lines and specific rules. No whole-file or whole-project checks are
disabled. The normal Plugin Check command must still run without ignored codes.

Migration is WP-CLI only
-----------------------
modules/migration/class-module.php loads operational classes and registers
commands only when WP_CLI is true. There are no HTTP, REST or AJAX migration
handlers. Imports are explicitly requested by the operator, warn about replacing
files/users/tables, require --mode, and require confirmation or --yes.

Only import trusted packages. They contain executable site code and database
schemas. Format validation and SHA-256 checks do not authenticate the sender or
turn an arbitrary package into untrusted input that is safe to execute.

Exports append bin2hex(random_bytes(16)) to the operator-supplied base filename:
a cryptographically random 128-bit identifier, not a public download token.
The final local path is printed for subsequent imports. Known public directories
remain rejected, archives retain 0600 permissions, and no HTTP download endpoint
or public archive URL is created. Random naming is defense in depth, not access
control. Temporary working files are cleaned up; the exported archive and imported
source package are intentionally retained under the operator's control.

Isolated import startup and direct access protection
----------------------------------------------------
Process::bootstrap() builds a native WP-CLI --exec argument for the replacement
process explicitly started by the operator. The plugin never automatically starts
or replaces that import process. An ordinary import exits before site writes and prints the required
command. This configures isolation and cache filters before WordPress loads; it
does not expose an executable pre-WordPress PHP file. Its after_wp_load callback
loads import-bootstrap.php, which requires ABSPATH, PHP_SAPI=cli, the real WP_CLI
runtime, isolation and both skip flags before executing any operations.
All operational PHP files reject direct access without WordPress. HTTP is also
rejected by the worker even when ABSPATH and WP_CLI are externally defined.

PHP constants cannot be reassigned. Between WP-CLI's before_wp_config_load and
after_wp_config_load hooks, a temporary handler consumes only E_WARNING with the
exact message "Constant WPMU_PLUGIN_DIR already defined". This is the expected
effect of a normal, unconditional wp-config define while the worker intentionally
uses an empty mu-plugin root. Other diagnostics are delegated unchanged. The
previous handler is restored unless wp-config installed its own; any intermediate
wrapper becomes inactive after configuration. No error_reporting/WP_DEBUG flags
are disabled and the real mu-plugin path remains in the worker's trusted context.
Roots/context use JSON quoted as PHP string literals and decoded as data. The
generated argument contains no formatting newlines, so the fallback startup
command remains copyable after terminal-control escaping.

Content locations
-----------------
The migration uses WP_Filesystem_Direct::wp_content_dir()/wp_plugins_dir(), the
theme APIs and wp_get_upload_dir() rather than assuming a standard filesystem
layout. Packages use logical plugins/themes/uploads/mu-plugins names mapped to
the destination's configured local directories. Nested physical roots are scanned
once, exclusions are preserved and mirror stays within configured roots.
Destination uploads settings are retained on finalization. Symlinks, overlapping
component roots, multiple theme roots and logical-name collisions are rejected.
WPMU_PLUGIN_DIR is the sole necessary directory constant: WordPress exposes no
filesystem getter for it and isolation must redirect it before mu-plugins load.
Original paths/context are preserved by the replacement process, not chosen by
the package.
Before preparing plans, ordinary content entries are checked against the physical
aliases of the destination's component roots and their ancestors. An overlap is
rejected before maintenance or site writes, never silently treated as an exclusion.
This applies to merge, mirror and dry-run; explicit logical exclusions still apply.

Frontend resource hints and template variables
---------------------------------------------
The two s.w.org comparisons in modules/frontend/class-module.php remove the
WordPress emoji CDN DNS hint, including a saved entry that would reintroduce it.
They do not download, embed or offload content. Only those two comparison lines
ignore PluginCheck.CodeAnalysis.Offloading.OffloadedContent.

The frontend REQUEST_METHOD gate compares the original value strictly to GET.
It is neither stored nor reflected. Unslashing or lossy text sanitization could
turn a rejected value into an accepted method, so only this comparison line
ignores MissingUnslash and InputNotSanitized. Other validation checks remain on.
Template loop variables are prefixed instead of ignoring the naming rule.

Repository-only files
---------------------
.gitignore is excluded only when checking the source working tree, alongside
development rules and tests. It is not included in installable ZIPs. No PHP
distribution file or check code is excluded from the normal check command.

Settings API sanitization
-------------------------
Every register_setting() supplies a literal array with type=array and a named static
sanitize_callback. Each validator checks the complete expected structure and
preserves previous normalized settings on invalid input. tests/modules.php checks
the registered callbacks and invokes them through WordPress sanitize_option(),
not just directly. The existing validation is retained, not replaced with a
generic text sanitizer that cannot validate these structured settings.

SQL execution and bounded results
---------------------------------
Database::query() is an internal executor, not a sanitization function. Callers
must supply static SQL, wpdb::prepare() results, or validated schema/identifier
fragments. identifier() only accepts 1-64 ASCII letters, digits, underscores or
dollar signs and adds backticks. Runtime integer settings are cast before use.
Restored row values are NULL or UNHEX() of bin2hex(), never raw quoted strings.
Foreign key clauses are extracted from the canonical supported grammar and
rebuilt with validated identifiers and actions. Packages are operator-trusted;
schema checks enforce the supported format, not a general SQL sandbox.

The single wpdb::query($sql) boundary is annotated for the two rules that cannot
trace these protections through callers. Do not add a raw user value there or
pass an entire statement to esc_sql(). SQL contract/integration tests cover
invalid identifiers, hostile-looking binary data and invalid package structures.

Exports use wpdb on its existing connection, in batches of 100 rows within the
same read-only REPEATABLE READ snapshot. Identifier placeholders (%i) and integer
pagination placeholders (%d) are prepared by wpdb. USE INDEX () forces the same
full InnoDB clustered scan for each batch, including tables without a primary
key. NULL and binary values are retained. No entire table is buffered, although
individual rows may be large. OFFSET scans become more expensive on large tables;
this is not a constant-time or constant-byte-memory export.

SHOW COUNT(*) WARNINGS is executed through wpdb immediately after inserts and
foreign-key creation. This diagnostic statement preserves the warning state;
nonzero warnings stop publication instead of accepting truncation. The migration
database class makes no direct mysqli calls and opens no independent connection.

Native filesystem operations
----------------------------
wp_is_writable() is used for WordPress-compatible permission checks. Native
operations remain only where the migration contract needs local guarantees:

* fopen(x/xb), fwrite and fclose: exclusive creation and bounded streaming for
  NDJSON, ZIP extraction and the standard WordPress .maintenance file. Loading
  whole dumps through WP_Filesystem::get_contents() is not a streaming substitute.
* mkdir/chmod: private staging is created with 0700, ZIPs published with 0600,
  and restored files receive validated safe permissions independently of umask.
* touch and same-directory rename: preserve dates and replace a complete prepared
  file atomically, without a remote transport or copy fallback.
* fwrite(STDERR): cancellation returns through finally cleanup; WP_CLI::confirm()
  exits directly and would bypass that resource cleanup.

Paths are validated, symbolic links rejected, exclusions preserved, and cleanup
is scoped to resources created by the operation. These guarantees do not make a
restore atomic as a whole, prevent concurrent external writers, or add rollback.

File deletions now use WP_Filesystem_Direct::delete(path, false, 'f'); empty
directories use its rmdir(path, false). No recursive API deletion is requested,
and wp_delete_file() filters cannot redirect or skip these critical deletions.
There are no link() calls. ZIP publication exclusively creates a new destination
with fopen(xb), sets private 0600 permissions before copying, streams the verified
archive, flushes the output and compares SHA-256. Existing files and dangling
symlinks are never overwritten. Publication is not atomic: a forced interruption
can leave a partial ZIP. Normal failure attempts to remove only the created file,
checking device/inode before cleanup; the operator must inspect forced interruptions.
wp_plugins_dir() deliberately obtains the entire site's configured plugin root,
not this plugin's directory. The package context's core root uses the filesystem
abspath() getter for path replacement. Own plugin paths/URLs are based on __FILE__
and plugin_dir_path()/plugin_dir_url() in the main plugin file.
The plugin does not launch programs, including via WP_CLI::launch_self(). After
publishing imported data and cleaning its private resources, it prints seven
shell commands joined by && for the operator to execute. Maintenance remains
enabled and the import is explicitly marked as pending finalization. The steps
apply destination settings, update SQL, flush rewrite rules, check installation,
verify tables, flush caches and only then disable maintenance. A failed step
prevents the remaining commands from running. Runtime state and isolation are
not inherited; the final cache step loads the restored site's active plugins.
The SQL advisory lock is released before handing control to the operator; no
other migration or external writer should run between these phases.

Maintenance deliberately uses $upgrading = time() so it does not expire during
long imports or after a failure. A random per-import token marks the exact file.
The last external step runs finish-maintenance.php through WP-CLI eval-file,
not maintenance-mode deactivate (its timestamp parser rejects time()).
The worker requires ABSPATH, PHP_SAPI=cli, WP_CLI=true and the actual WP-CLI
runtime. It checks the token, rejects symlinks and changed/missing files, reads
without evaluating PHP, compares the complete expected content and checks stable
device/inode metadata before deletion via WP_Filesystem_Direct. This is not an
HTTP operation or a sandbox against operators with equivalent filesystem access.

The DOCUMENT_ROOT read in Command::output() has line-specific MissingUnslash
and InputNotSanitized annotations: this is a server/CLI filesystem path, not
magic-quoted request data. Its type is checked and realpath() resolves it before
the public-root comparison; generic text sanitization or unslashing could change
the actual path. The raw value is not rendered. Other input checks remain enabled.

CLI exception messages
----------------------
Dynamic migration exceptions reach the command's CLI error boundary, not HTML.
Command::terminal() converts ASCII and UTF-8 C1 control sequences to visible hex
escapes before error/success output. This prevents rejected paths from injecting
terminal control sequences without HTML-encoding normal diagnostic text. Each
exception annotation is specific to this context; HTML templates must still use
WordPress context-appropriate escaping. The same boundary protects the diagnostic
subcommand shown after verification. Tests cover controls and unchanged UTF-8.
The two dynamic exceptions in class-import.php follow that same CLI boundary:
target() names only WP_HOME or WP_SITEURL from its fixed map; restore_files()
reports a validated mirror-relative path when unlink fails. Only those throw
lines ignore ExceptionNotEscaped; no HTML escaping is added to CLI diagnostics.
Integration tests verify that conflicting URL constants remain named in errors.
Locations::assert_content_path() follows the same boundary for the validated
relative path in a preflight collision diagnostic; its annotation covers only
that throw statement.

Remaining warning contexts
--------------------------
The following warning families are intentionally left visible rather than
silenced. These explanations apply to the current callers, not future code:

* DirectQuery/NoCaching: login queries read current block state or execute schema
  and row-lock transactions; migration context and finalization query persisted
  values directly, deliberately bypassing possibly stale option caches. There
  are no core APIs for the private IP table, advisory SQL locks or site dumps.
* SchemaChange: uninstall.php drops only this plugin's own prefixed IP table,
  guarded by WP_UNINSTALL_PLUGIN and using wpdb::prepare() with %i.
* InputNotSanitized/MissingUnslash: REMOTE_ADDR must be a string validated as an
  IP and normalized with inet_pton/inet_ntop; POST ip is unslashed and validated
  the same way before the nonce-protected unlock. REQUEST_METHOD is compared
  strictly to GET/POST, never stored or reflected.
  Do not replace strict validation with lossy text sanitization that changes
  rejected input into accepted input.
* DevelopmentFunctions: operational error_log() messages describe failures,
  optionally with an integer schema version, not credentials, SQL or visitor IPs.
  Process::bootstrap() uses var_export() to serialize trusted local roots/context
  and the worker path into executable CLI arguments; this is not debug output.
* NonPrefixedVariableFound: finalize.php and verify.php are guarded CLI eval-file
  scripts. Their locals belong to WP-CLI's evaluation scope, not plugin globals
  exported during a normal WordPress HTTP bootstrap.
* trademarked_term: WP may produce an automated naming warning. DCT Sollers
  does not claim affiliation with WordPress or Sollers Consulting and includes
  no WordPress logo. The chosen name and slug still require directory review;
  this note is not trademark clearance or approval.
DCT Sollers uses dct-sollers as its public slug, installation directory,
main filename and text domain. The WP-CLI namespace is wp dct-sollers.
Internal class, storage, hook and archive identifiers use DCTSollers/dctsollers.
This intentionally breaks compatibility with previous internal prefixes: no data
adoption, aliases or old-format acceptance is provided. WordPress.org must assign
the requested permalink separately.
