JPKCom Allow Block Types

import-export.php

Import and export

Serialises the settings to a portable JSON payload so a site's block permissions can be moved to another install, and reads that payload back in with a preview step before anything is written.

Tags
since
3.0.0

Table of Contents

Constants

JPKCOM_ALLOW_BLOCKS_IMPORT_MAX_BYTES  : mixed = 1048576

Functions

jpkcom_allow_blocks_export_payload()  : array<string|int, mixed>
Build the exportable payload for a settings structure.
jpkcom_allow_blocks_export_filename()  : string
Filename offered for a downloaded export.
jpkcom_allow_blocks_parse_import()  : array{ok: bool, error: string, rejected: int, settings: array}
Decode and validate an import payload.
jpkcom_allow_blocks_merge_import()  : array<string|int, mixed>
Merge an imported settings structure into the current one.
jpkcom_allow_blocks_import_preview()  : array{roles_changed: int, blocks_changed: int, unknown_roles: string[], unknown_blocks: string[]}
Describe what an import would change, before anything is written.
jpkcom_allow_blocks_import_error_redirect()  : never
Redirect back to the settings page with an import error notice.

Constants

JPKCOM_ALLOW_BLOCKS_IMPORT_MAX_BYTES

public mixed JPKCOM_ALLOW_BLOCKS_IMPORT_MAX_BYTES = 1048576

Functions

jpkcom_allow_blocks_export_payload()

Build the exportable payload for a settings structure.

jpkcom_allow_blocks_export_payload(array<string|int, mixed> $settings) : array<string|int, mixed>

Adds provenance fields so an import can tell where a file came from: which plugin version wrote it, which site it was exported from, and when.

Parameters
$settings : array<string|int, mixed>

Validated settings.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

The settings plus plugin_version, site_url and exported.

jpkcom_allow_blocks_export_filename()

Filename offered for a downloaded export.

jpkcom_allow_blocks_export_filename() : string

Includes the site's host so two exports made on the same day from different sites do not collide once both files sit in the same downloads folder.

Tags
since
3.0.0
Return values
string —

Filename ending in .json.

jpkcom_allow_blocks_parse_import()

Decode and validate an import payload.

jpkcom_allow_blocks_parse_import(string $json) : array{ok: bool, error: string, rejected: int, settings: array}

Every rejection path leaves settings empty and carries a short error code rather than a translated message: the code travels through a redirect's query string, and a free-text message there would let a crafted link put arbitrary words in front of an administrator. includes/admin-page.php's jpkcom_allow_blocks_import_error_message() maps each code to its translated text. Nothing here writes anything.

Parameters
$json : string

Raw file contents.

Tags
since
3.0.0
Return values
array{ok: bool, error: string, rejected: int, settings: array} —

Parse result. error is a stable code ('invalid-json', 'bad-schema', 'no-roles') on failure, empty on success. rejected counts entries the raw payload contained that did not survive sanitising, always 0 on failure since nothing is sanitised on that path.

jpkcom_allow_blocks_merge_import()

Merge an imported settings structure into the current one.

jpkcom_allow_blocks_merge_import(array<string|int, mixed> $current, array<string|int, mixed> $incoming) : array<string|int, mixed>

The unit is the role, not the individual block: a role present in $incoming replaces that role's whole list, a role absent from it is left completely untouched. A role that does not exist on this site is stored anyway - it may be created later, or come from a plugin that is currently deactivated - which mirrors why this plugin stores a deny list at all: nothing is ever pruned. Labels are merged with the incoming file winning for keys it contains.

Parameters
$current : array<string|int, mixed>

Current validated settings.

$incoming : array<string|int, mixed>

Validated settings decoded from an import file.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

Merged settings, not yet stored.

jpkcom_allow_blocks_import_preview()

Describe what an import would change, before anything is written.

jpkcom_allow_blocks_import_preview(array<string|int, mixed> $current, array<string|int, mixed> $incoming, array<string|int, string> $known_roles[, array<string|int, string> $known_blocks = array() ]) : array{roles_changed: int, blocks_changed: int, unknown_roles: string[], unknown_blocks: string[]}

Counts are taken per role: a role counts as changed when its list would differ from what is currently stored, whether or not the role exists on this site. unknown_roles names incoming roles absent from $known_roles so the import is not silently doing more than it appears to. unknown_blocks names blocks the incoming file mentions that are not in $known_blocks - the live block registry, passed in rather than read here so this stays a pure, testable function. That includes a block already present in $current: a plugin that is currently switched off still leaves its block name in the stored settings, and the whole point of this count is to surface exactly that "this install cannot currently offer it" case.

Parameters
$current : array<string|int, mixed>

Current validated settings.

$incoming : array<string|int, mixed>

Validated settings decoded from an import file.

$known_roles : array<string|int, string>

Role slugs that exist on this site.

$known_blocks : array<string|int, string> = array()

Block names registered on this site. Defaults to empty, which marks every incoming block unknown; callers should always pass the real registry list.

Tags
since
3.0.0
Return values
array{roles_changed: int, blocks_changed: int, unknown_roles: string[], unknown_blocks: string[]} —

Preview summary.

jpkcom_allow_blocks_import_error_redirect()

Redirect back to the settings page with an import error notice.

jpkcom_allow_blocks_import_error_redirect(string $code, string $back_url) : never

Used in place of wp_die() for anything short of a failed capability or nonce check, so a rejected upload never throws the user out of the admin interface - they land back on the settings screen with an explanation instead of a bare error page. Carries a short error code rather than a translated message: admin-page.php maps the code to text, and ignores anything it does not recognise, so a crafted link cannot put arbitrary words in front of an administrator through this query argument.

Parameters
$code : string

Error code, one of the keys jpkcom_allow_blocks_import_error_message() understands.

$back_url : string

Settings page URL to redirect to.

Tags
since
3.0.0
Return values
never
On this page

Search results