GravityKit\GravityMigrate\Media\MediaArchive
The archive half of packaged media: what an uploaded file is called inside the bundle, and
which of a bundle's entries may be written back to disk.
Both directions handle another site's data: the entry names written here are read back by a different site, and a bundle being unpacked was written somewhere this site does not control. Nothing that arrives from a bundle is trusted to name its own destination.
Since: %ver%
Source: src/Media/MediaArchive.php:22
Details
- Kind:
class - Namespace:
GravityKit\GravityMigrate\Media
Methods
| Method | Description |
|---|---|
__construct() | |
manifest_paths() | The paths recorded in info.json for a set of absolute paths. |
add_files() | Adds files to an open archive under {@see MediaPaths::ARCHIVE_DIR}. |
extractable_entries() | The entries of a bundle that may be unpacked, given the manifest it declared. |
unpacked_path() | Where an unpacked file of a bundle sits on this site, or null when it may not be written. |
records_manifest() | Whether a bundle should record what it was asked to carry. |
reconcile() | Moves the files the archive would not take from included to excluded. |
summary() | What packaging actually carried, for whoever has to report it. |
Method Reference
__construct()
public function __construct( ?callable $logger=null )
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$logger | callable | null | null | Receives one string per refused or failed file. |
Since: %ver%
Source: src/Media/MediaArchive.php:38
manifest_paths()
public function manifest_paths( array $paths, string $upload_base ): array
The paths recorded in info.json for a set of absolute paths.
Relative to the source's uploads directory, the only form that survives the trip: the destination's uploads directory is somewhere else entirely.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$paths | string[] | Absolute paths. | |
$upload_base | string | The source's uploads directory. |
Returns
string[]
Since: %ver%
Source: src/Media/MediaArchive.php:55
add_files()
public function add_files( ZipArchive $zip, array $paths, string $upload_base, bool $encrypted=false ): array
Adds files to an open archive under {@see MediaPaths::ARCHIVE_DIR}.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$zip | ZipArchive | The open archive. | |
$paths | string[] | Absolute paths of the files to add. | |
$upload_base | string | The source's uploads directory. | |
$encrypted | bool | false | Whether the archive is password-protected. |
Returns
array{entries:string,temp_files:string,skipped:string}— The entry names written, the temporary copies the caller must delete AFTER close(), and the paths that were refused.
Since: %ver%
Source: src/Media/MediaArchive.php:83
extractable_entries()
public function extractable_entries( array $manifest ): array
The entries of a bundle that may be unpacked, given the manifest it declared.
Two independent gates, both required. The manifest bounds extraction to what the exporter declared, so entries the archive holds but the manifest does not name are ignored; the path rules bound it to what is safe to write. The same site writes both the manifest and the archive, so neither gate constrains the other.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$manifest | string[] | The files_paths an info.json declared. |
Returns
array<string,string>— Archive entry name => relative path, for the entries to extract.
Since: %ver%
Source: src/Media/MediaArchive.php:147
unpacked_path()
public function unpacked_path( string $relative_path, string $media_root ): ?string
Where an unpacked file of a bundle sits on this site, or null when it may not be written.
Re-runs the path rules rather than trusting \self::extractable_entries(): this is
called during the import, one bundle-declared path at a time, and by then the only thing
standing between that string and a file write is this method.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$relative_path | string | Path the bundle named. | |
$media_root | string | Absolute path of the unpacked media directory. |
Returns
string|null
Since: %ver%
Source: src/Media/MediaArchive.php:181
records_manifest()
public static function records_manifest( array $media ): bool
Whether a bundle should record what it was asked to carry.
True whenever packaging was requested, even if nothing was carried: without the manifest, an export whose every file exceeded the size limit is indistinguishable from one exported with packaging unticked, and the importing site cannot tell "these files were meant to be here and are not" from "this bundle never carried files".
False when it was not requested. Bundles from versions that predate the manifest look the same, and the importer must keep reading both as "download everything".
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$media | array | The collector's result. |
Returns
bool
Since: %ver%
Source: src/Media/MediaArchive.php:298
reconcile()
public static function reconcile( array $media, array $skipped ): array
Moves the files the archive would not take from included to excluded.
The collector decides what an export should carry; the archive decides what it could.
A file outside the uploads directory, one the process cannot read, or one libzip refuses
is skipped. Left in included it would still reach the manifest as carried, and the
importing site would then neither find it in the bundle nor download it -- a manifest
entry is what says a file is already here.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$media | array | The collector's result. | |
$skipped | string[] | Absolute paths \self::add_files() could not add. |
Returns
array— The collector's result, with the skipped files counted as excluded.
Since: %ver%
Source: src/Media/MediaArchive.php:318
summary()
public static function summary( array $media ): ?array
What packaging actually carried, for whoever has to report it.
The bundle's manifest and the screen shown when the export finishes are the same claim made to two audiences, so both read these counts rather than each totalling its own.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$media | array | The collector's result. |
Returns
array|null— Counts and sizes, or null when packaging was not requested.
Since: %ver%
Source: src/Media/MediaArchive.php:366