ArangoDumpAction uses trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, \oihana\commands\traits\EncryptTrait
The command to manage an ArangoDB database.
Table of Contents
Constants
- ARANGO_DUMP : string = 'arangodump'
- The arango dump command.
- ARCHIVE_REGEXP : string = \oihana\arango\commands\enums\ArchivePattern::R...
- The pattern to find the archive files.
- PARTIAL_MARKER : string = 'partial'
- Marker appended to the archive name when the dump targets a subset of collections (either `--collection` or `--ignore-collection`).
- COMPLETE_SYSTEM_COLLECTIONS : array<string|int, mixed> = ['_analyzers', '_graphs']
- The system collections added by a `--complete` backup (the custom analyzers and the named graph definitions).
- SYSTEM_ATTRIBUTES : array<string|int, mixed> = [\org\schema\constants\Schema::_KEY, \org\schem...
- The top-level ArangoDB system attributes that are never masked — they carry identity / edge references and must survive masking untouched (the same rule `arangodump` applies). Passed to {@see maskDocument()} as the protected attributes.
Properties
- $compression : string|null
- The compression of the dump file.
- $directory : string|null
- The dump/restore directory.
- $dumpConfig : array<string|int, mixed>
- The `[arango.dump]` config defaults (option name => value).
- $profiles : array<string|int, mixed>
- The declared named profiles, from the `[arango.profiles]` config section.
- $restoreConfig : array<string|int, mixed>
- The `[arango.restore]` config defaults (option name => value).
Methods
- arangoDump() : int
- Run the 'arangodump' command to dump the ArangoDB database.
-
compileMaskings()
: array<string, array{type: string, maskings: array
>}> - Compiles the convenient masking table into the masking structure (collection name => `{ type, maskings[] }`).
- dump() : int
- Dump the ArangoDB database.
- getArangoDumpArguments() : array<int, string>
- Builds the `arangodump` argument vector (argv[0] = binary name).
- initializeArangoOptions() : static
- Captures the `[arango.dump]` / `[arango.restore]` config sections from the init array. Non-array values are ignored, leaving the defaults empty.
- initializeArangoProfiles() : static
- Captures the `[arango.profiles]` config section from the init array.
- initializeDirectory() : static
- Initializes the dump/restore directory from an init array.
- maskDumpDirectory() : int
- Applies the compiled masking to the `*.data.json` files of a dump, in place.
- planRotation() : array<int, string>
- Plans the rotation: returns the archive paths to delete.
- profileConnection() : array<string|int, mixed>
- The optional **source** connection carried by a profile (dump only).
- profileDirectory() : string|null
- The optional output **directory** carried by a profile (dump only).
- profileExclude() : array<string|int, mixed>
- The `exclude` list of a profile.
- profilePositive() : array<string|int, mixed>
- The positive selection of a profile — `collections` + `edges` merged.
- profileSelection() : array<string|int, mixed>
- The effective collection list of a profile.
- pruneDumps() : int
- Enumerates the dump directory and prunes (or lists, on a dry run) the archives the policy designates for deletion.
- resolveProfile() : array<string|int, mixed>|null
- Resolves the `--profile` value to a profile array.
- resolveRetentionPolicy() : RotationPolicy
- Resolves the `[arango.dump.retention]` config into a pure policy for {@see planRotation()} (parses the ISO 8601 `max_age` into a cutoff and the `max_total` size into bytes).
- retentionEnabled() : bool
- True when the retention config carries at least one deletion criterion (`keep`, `max_age` or `max_total`). `auto` alone never deletes anything.
- assertCollectionTargeting() : void
- Asserts that `--collection` and `--ignore-collection` are not used together — `arangodump` rejects that combination.
- buildDatabase() : Database|null
- Builds a best-effort {@see Database} HTTP client from the resolved connection settings, or null when no usable endpoint/database is available or the client cannot be constructed.
- excludeCollections() : array<int, string>
- Returns the available collection names minus the excluded ones, order-preserving (case-sensitive).
- getArchiveNameSuffix() : string
- Builds the archive name suffix (without file extension) shared by the dump output name and the restore-by-date lookup.
- isSystemCollection() : bool
- Returns true when the given name is an ArangoDB system collection (its name starts with an underscore, e.g. `_jobs`, `_apps`).
- listDumps() : int
- List the dump files of the database.
- missingCollections() : array<int, string>
- Returns the requested collection names that are NOT present in the available set (case-sensitive, as ArangoDB collection names are).
- normalizeCollections() : array<int, string>
- Normalizes a raw collection option into a clean, de-duplicated, order-preserving list of collection names.
- resolveDatabase() : Database|null
- Builds the best-effort {@see Database} HTTP client of an action run: every connection setting reads its CLI option first (`--database` / `--endpoint` / `--user` / `--password`) and falls back on the command configuration ({@see ArangoConfigTrait}).
- resolveDumpOptions() : array<string|int, mixed>
- Layers the explicit dump options over the `[arango.dump]` config defaults, then lets the curated CLI flags override everything.
- resolveFacade() : ArangoDB|null
- Builds the best-effort high-level {@see ArangoDB} façade of an action run, from the same resolved connection settings as {@see resolveDatabase()} — the migration engine hands this façade to every {@see \oihana\arango\migrations\Migration}. Null when no usable endpoint is configured or the façade cannot be constructed.
- resolveRestoreOptions() : array<string|int, mixed>
- Layers the explicit restore options over the `[arango.restore]` config defaults, then lets the curated CLI flags override everything.
- restoreProtectedCollections() : array<int, string>
- The collection names the `restore` action refuses to overwrite unless `--force` is passed, read from the `protected` key of the `[arango.restore]` config section ({@see ArangoCommandParam::PROTECTED}).
- sanitizeLabel() : string|null
- Validates and normalizes the optional archive label.
- applyMaxTotal() : void
- Applies the global `max_total` size cap: deletes the oldest survivors across all buckets until the total fits, never violating the per-bucket floor nor pruning the current archive.
- archiveBucket() : string
- The bucket of an archive — its suffix signature (file name minus the leading 19-character ISO date, the joining dash and the extension).
- archiveDate() : DateTimeImmutable
- The date embedded at the start of an archive file name.
- dumpAvailableCollections() : array<int, string>
- Returns the user (non-system) collection names of the live database, or throws when the HTTP API is unavailable — used by the exclusion paths (`--ignore-collection` and exclude-only profiles) that need the universe.
- dumpCollectionName() : string
- Resolves the collection name a `*.data.json` file belongs to, by reading the `parameters.name` of its paired `*.structure.json` (falling back to the file-name prefix before the dump hash).
- dumpCompleteCollections() : array<int, string>
- Returns the collection list of a `--complete` backup: every user collection plus the {@see COMPLETE_SYSTEM_COLLECTIONS} that exist on the server. Throws when the HTTP API is unavailable.
- looksLikePath() : bool
- True when a `--profile` value designates an external `.toml` file rather than a named section.
- maskingRule() : array<string, mixed>
- Builds — and validates — a single attribute masking rule from a path and its value (a masker name string, or an inline table carrying `type`).
- normalizeProfileList() : array<string|int, mixed>
- Flattens a profile list value: arrays and comma-separated strings → a clean, de-duplicated list of trimmed names.
- parseRetentionSize() : int
- Parses a human size (`5G`, `500M`, `1.5G`, `2k`, `1024`) into bytes.
Constants
ARANGO_DUMP
The arango dump command.
public
string
ARANGO_DUMP
= 'arangodump'
ARCHIVE_REGEXP
The pattern to find the archive files.
public
string
ARCHIVE_REGEXP
= \oihana\arango\commands\enums\ArchivePattern::REGEXP
PARTIAL_MARKER
Marker appended to the archive name when the dump targets a subset of collections (either `--collection` or `--ignore-collection`).
public
string
PARTIAL_MARKER
= 'partial'
COMPLETE_SYSTEM_COLLECTIONS
The system collections added by a `--complete` backup (the custom analyzers and the named graph definitions).
private
array<string|int, mixed>
COMPLETE_SYSTEM_COLLECTIONS
= ['_analyzers', '_graphs']
SYSTEM_ATTRIBUTES
The top-level ArangoDB system attributes that are never masked — they carry identity / edge references and must survive masking untouched (the same rule `arangodump` applies). Passed to {@see maskDocument()} as the protected attributes.
private
array<string|int, mixed>
SYSTEM_ATTRIBUTES
= [\org\schema\constants\Schema::_KEY, \org\schema\constants\Schema::_ID, \org\schema\constants\Schema::_REV, \org\schema\constants\Schema::_FROM, \org\schema\constants\Schema::_TO]
Properties
$compression
The compression of the dump file.
public
string|null
$compression
= \oihana\files\enums\CompressionType::GZIP
$directory
The dump/restore directory.
public
string|null
$directory
= null
$dumpConfig
The `[arango.dump]` config defaults (option name => value).
protected
array<string|int, mixed>
$dumpConfig
= []
$profiles
The declared named profiles, from the `[arango.profiles]` config section.
protected
array<string|int, mixed>
$profiles
= []
$restoreConfig
The `[arango.restore]` config defaults (option name => value).
protected
array<string|int, mixed>
$restoreConfig
= []
Methods
arangoDump()
Run the 'arangodump' command to dump the ArangoDB database.
public
arangoDump([array<string|int, mixed>|ArangoDumpOptions|null $options = null ][, bool $silent = false ]) : int
Parameters
- $options : array<string|int, mixed>|ArangoDumpOptions|null = null
-
The arangodump options definition.
- $silent : bool = false
-
Indicates if the command is invoked silently.
Tags
Return values
intcompileMaskings()
Compiles the convenient masking table into the masking structure (collection name => `{ type, maskings[] }`).
public
compileMaskings(array<string|int, mixed> $table) : array<string, array{type: string, maskings: array>}>
Parameters
- $table : array<string|int, mixed>
-
The convenient
[…masking]table.
Tags
Return values
array<string, array{type: string, maskings: arraydump()
Dump the ArangoDB database.
public
dump(InputInterface $input, OutputInterface $output) : int
Parameters
- $input : InputInterface
- $output : OutputInterface
Tags
Return values
intgetArangoDumpArguments()
Builds the `arangodump` argument vector (argv[0] = binary name).
public
getArangoDumpArguments([array<string|int, mixed>|ArangoDumpOptions|null $options = null ]) : array<int, string>
The vector is executed without a shell (see ArangoProcessTrait::runProcess()), so option values are passed verbatim and never re-interpreted.
Parameters
- $options : array<string|int, mixed>|ArangoDumpOptions|null = null
Tags
Return values
array<int, string>initializeArangoOptions()
Captures the `[arango.dump]` / `[arango.restore]` config sections from the init array. Non-array values are ignored, leaving the defaults empty.
public
initializeArangoOptions([array<string|int, mixed> $init = [] ]) : static
Parameters
- $init : array<string|int, mixed> = []
Return values
staticinitializeArangoProfiles()
Captures the `[arango.profiles]` config section from the init array.
public
initializeArangoProfiles([array<string|int, mixed> $init = [] ]) : static
Parameters
- $init : array<string|int, mixed> = []
Return values
staticinitializeDirectory()
Initializes the dump/restore directory from an init array.
public
initializeDirectory([array<string|int, mixed> $init = [] ]) : static
Parameters
- $init : array<string|int, mixed> = []
-
The init definition, possibly containing ArangoCommandParam::DIRECTORY.
Return values
staticmaskDumpDirectory()
Applies the compiled masking to the `*.data.json` files of a dump, in place.
public
maskDumpDirectory(string $directory, array<string|int, mixed> $compiled) : int
Each data file is paired with its *.structure.json to resolve the
collection name, then matched against the compiled rules (an explicit
entry, otherwise the * default). Only masked collections are processed
— a non-masked mode raises, since collection selection/exclusion is done
by --collection / the profile, not by the engine. Files are expected
uncompressed (the dump action forces compressOutput = false).
Parameters
- $directory : string
-
The dump output directory holding the
*.data.jsonfiles. - $compiled : array<string|int, mixed>
-
The compiled masking structure (compileMaskings()).
Tags
Return values
int —The number of data files masked.
planRotation()
Plans the rotation: returns the archive paths to delete.
public
planRotation(array<int, Archive> $archives, RotationPolicy $policy[, string|null $current = null ]) : array<int, string>
Pure (no I/O, no clock): the caller supplies the resolved policy.
Parameters
- $archives : array<int, Archive>
- $policy : RotationPolicy
- $current : string|null = null
-
The freshly created archive, never deleted.
Return values
array<int, string> —The paths to delete.
profileConnection()
The optional **source** connection carried by a profile (dump only).
public
profileConnection(array<string|int, mixed> $profile) : array<string|int, mixed>
Parameters
- $profile : array<string|int, mixed>
Return values
array<string|int, mixed> —The present connection keys among endpoint/database/user/password.
profileDirectory()
The optional output **directory** carried by a profile (dump only).
public
profileDirectory(array<string|int, mixed> $profile) : string|null
When set, a dump using this profile writes its archive here unless the
--directory CLI flag overrides it. The restore action ignores this
key — it always writes to the local target.
Parameters
- $profile : array<string|int, mixed>
Return values
string|null —The directory, or null when absent or not a string.
profileExclude()
The `exclude` list of a profile.
public
profileExclude(array<string|int, mixed> $profile) : array<string|int, mixed>
Parameters
- $profile : array<string|int, mixed>
Return values
array<string|int, mixed>profilePositive()
The positive selection of a profile — `collections` + `edges` merged.
public
profilePositive(array<string|int, mixed> $profile) : array<string|int, mixed>
Parameters
- $profile : array<string|int, mixed>
Return values
array<string|int, mixed>profileSelection()
The effective collection list of a profile.
public
profileSelection(array<string|int, mixed> $profile[, array<string|int, mixed> $allCollections = [] ]) : array<string|int, mixed>
A positive selection minus exclude; when the positive list is empty,
$allCollections (the universe) minus exclude.
Parameters
- $profile : array<string|int, mixed>
- $allCollections : array<string|int, mixed> = []
-
The universe used for an exclude-only profile.
Return values
array<string|int, mixed>pruneDumps()
Enumerates the dump directory and prunes (or lists, on a dry run) the archives the policy designates for deletion.
public
pruneDumps(string $directory, RotationPolicy $policy, string|null $current, bool $dryRun, SymfonyStyle $io) : int
Parameters
- $directory : string
-
The dump directory.
- $policy : RotationPolicy
-
The resolved policy (resolveRetentionPolicy()).
- $current : string|null
-
The freshly created archive, never pruned.
- $dryRun : bool
-
List only, delete nothing.
- $io : SymfonyStyle
Tags
Return values
int —The number of archives deleted (or that would be).
resolveProfile()
Resolves the `--profile` value to a profile array.
public
resolveProfile(string|null $profile) : array<string|int, mixed>|null
A path-like value (absolute, containing a separator, or ending in
.toml) is loaded as an external file; otherwise it is looked up among
the declared named profiles.
Parameters
- $profile : string|null
Return values
array<string|int, mixed>|null —Null when no profile is requested.
resolveRetentionPolicy()
Resolves the `[arango.dump.retention]` config into a pure policy for {@see planRotation()} (parses the ISO 8601 `max_age` into a cutoff and the `max_total` size into bytes).
public
resolveRetentionPolicy(array<string|int, mixed> $retention) : RotationPolicy
Parameters
- $retention : array<string|int, mixed>
-
The
[arango.dump.retention]config section.
Tags
Return values
RotationPolicyretentionEnabled()
True when the retention config carries at least one deletion criterion (`keep`, `max_age` or `max_total`). `auto` alone never deletes anything.
public
retentionEnabled(array<string|int, mixed> $retention) : bool
Parameters
- $retention : array<string|int, mixed>
Return values
boolassertCollectionTargeting()
Asserts that `--collection` and `--ignore-collection` are not used together — `arangodump` rejects that combination.
protected
static assertCollectionTargeting(array<int, string> $collection, array<int, string> $ignore) : void
Parameters
- $collection : array<int, string>
- $ignore : array<int, string>
Tags
buildDatabase()
Builds a best-effort {@see Database} HTTP client from the resolved connection settings, or null when no usable endpoint/database is available or the client cannot be constructed.
protected
buildDatabase(string $endpoint, string $username, string $password, string $database) : Database|null
No network I/O happens here — the connection is only exercised when a request method (e.g. Database::collections()) is later called by the caller.
Parameters
- $endpoint : string
-
The ArangoDB endpoint (e.g.
tcp://127.0.0.1:8529). - $username : string
-
The connection user.
- $password : string
-
The connection password.
- $database : string
-
The target database name.
Return values
Database|nullexcludeCollections()
Returns the available collection names minus the excluded ones, order-preserving (case-sensitive).
protected
static excludeCollections(array<int, string> $available, array<int, string> $exclude) : array<int, string>
Used to resolve --ignore-collection client-side: arangodump has
no exclusion option, so the complement is computed here and passed
back as an explicit --collection list.
Parameters
- $available : array<int, string>
-
The collections that exist.
- $exclude : array<int, string>
-
The collections to drop.
Return values
array<int, string>getArchiveNameSuffix()
Builds the archive name suffix (without file extension) shared by the dump output name and the restore-by-date lookup.
protected
static getArchiveNameSuffix(string $database[, bool $partial = false ][, string|null $label = null ]) : string
Shape: -{database}[-partial][-{label}], e.g.
-mydb(full dump)-mydb-partial(targeted dump, no label)-mydb-partial-pre-migration(targeted dump with a label)
Parameters
- $database : string
-
The database name.
- $partial : bool = false
-
Whether the dump targets a subset of collections.
- $label : string|null = null
-
Optional label (validated via sanitizeLabel()).
Tags
Return values
stringisSystemCollection()
Returns true when the given name is an ArangoDB system collection (its name starts with an underscore, e.g. `_jobs`, `_apps`).
protected
static isSystemCollection(string $name) : bool
Parameters
- $name : string
Return values
boollistDumps()
List the dump files of the database.
protected
listDumps(InputInterface $input, OutputInterface $output[, string|null $directory = null ]) : int
The listed directory follows the same precedence as the dump and the
prune: the --directory CLI flag wins, then the optional $directory
(e.g. a profile output directory resolved by the caller), then the global
$this->directory.
Parameters
- $input : InputInterface
- $output : OutputInterface
- $directory : string|null = null
-
An optional directory override (the profile output directory), below the
--directoryCLI flag and above the global directory.
Tags
Return values
intmissingCollections()
Returns the requested collection names that are NOT present in the available set (case-sensitive, as ArangoDB collection names are).
protected
static missingCollections(array<int, string> $requested, array<int, string> $available) : array<int, string>
Order-preserving and de-duplicated.
Parameters
- $requested : array<int, string>
-
The collections asked for on the CLI.
- $available : array<int, string>
-
The collections that actually exist.
Return values
array<int, string> —The unknown collection names (empty when all exist).
normalizeCollections()
Normalizes a raw collection option into a clean, de-duplicated, order-preserving list of collection names.
protected
static normalizeCollections(array<int|string, mixed> $raw) : array<int, string>
Accepts both syntaxes (and any mix):
- repeated flags :
['users', 'products'] - comma-separated :
['users,products'] - mixed/with spaces :
[' users , products ', 'customers']
Empty fragments are dropped; the first occurrence order is kept.
Parameters
- $raw : array<int|string, mixed>
Return values
array<int, string>resolveDatabase()
Builds the best-effort {@see Database} HTTP client of an action run: every connection setting reads its CLI option first (`--database` / `--endpoint` / `--user` / `--password`) and falls back on the command configuration ({@see ArangoConfigTrait}).
protected
resolveDatabase(InputInterface $input) : Database|null
One-stop shop for the actions — see buildDatabase() for the null-on-failure semantics.
Parameters
- $input : InputInterface
-
The action input carrying the optional CLI overrides.
Return values
Database|nullresolveDumpOptions()
Layers the explicit dump options over the `[arango.dump]` config defaults, then lets the curated CLI flags override everything.
protected
resolveDumpOptions(array<string|int, mixed> $explicit, InputInterface $input) : array<string|int, mixed>
Parameters
- $explicit : array<string|int, mixed>
-
The options resolved by the action (connection, output directory, collection targeting).
- $input : InputInterface
-
The current console input.
Return values
array<string|int, mixed>resolveFacade()
Builds the best-effort high-level {@see ArangoDB} façade of an action run, from the same resolved connection settings as {@see resolveDatabase()} — the migration engine hands this façade to every {@see \oihana\arango\migrations\Migration}. Null when no usable endpoint is configured or the façade cannot be constructed.
protected
resolveFacade(InputInterface $input) : ArangoDB|null
Parameters
- $input : InputInterface
-
The action input carrying the optional CLI overrides.
Return values
ArangoDB|nullresolveRestoreOptions()
Layers the explicit restore options over the `[arango.restore]` config defaults, then lets the curated CLI flags override everything.
protected
resolveRestoreOptions(array<string|int, mixed> $explicit, InputInterface $input) : array<string|int, mixed>
Parameters
- $explicit : array<string|int, mixed>
-
The options resolved by the action (connection, input directory, create flags, collection targeting).
- $input : InputInterface
-
The current console input.
Return values
array<string|int, mixed>restoreProtectedCollections()
The collection names the `restore` action refuses to overwrite unless `--force` is passed, read from the `protected` key of the `[arango.restore]` config section ({@see ArangoCommandParam::PROTECTED}).
protected
restoreProtectedCollections() : array<int, string>
Non-array values and non-string entries are ignored.
Return values
array<int, string>sanitizeLabel()
Validates and normalizes the optional archive label.
protected
static sanitizeLabel(string|null $label) : string|null
Returns null for a null/empty value. Otherwise the label must only contain letters, digits, dot, underscore and hyphen so it stays safe inside a filename.
Parameters
- $label : string|null
Tags
Return values
string|nullapplyMaxTotal()
Applies the global `max_total` size cap: deletes the oldest survivors across all buckets until the total fits, never violating the per-bucket floor nor pruning the current archive.
private
applyMaxTotal(array<int, Archive> $archives, array<string, Archive> &$delete, int $maxTotalBytes, string|null $current) : void
Parameters
archiveBucket()
The bucket of an archive — its suffix signature (file name minus the leading 19-character ISO date, the joining dash and the extension).
private
archiveBucket(string $filename) : string
Parameters
- $filename : string
Return values
stringarchiveDate()
The date embedded at the start of an archive file name.
private
archiveDate(string $filename) : DateTimeImmutable
Parameters
- $filename : string
Return values
DateTimeImmutabledumpAvailableCollections()
Returns the user (non-system) collection names of the live database, or throws when the HTTP API is unavailable — used by the exclusion paths (`--ignore-collection` and exclude-only profiles) that need the universe.
private
dumpAvailableCollections(string $endpoint, string $username, string $password, string $database) : array<int, string>
Parameters
- $endpoint : string
- $username : string
- $password : string
- $database : string
Return values
array<int, string>dumpCollectionName()
Resolves the collection name a `*.data.json` file belongs to, by reading the `parameters.name` of its paired `*.structure.json` (falling back to the file-name prefix before the dump hash).
private
dumpCollectionName(string $dataFile) : string
Parameters
- $dataFile : string
-
The path to a
<name>_<hash>.data.jsonfile.
Return values
stringdumpCompleteCollections()
Returns the collection list of a `--complete` backup: every user collection plus the {@see COMPLETE_SYSTEM_COLLECTIONS} that exist on the server. Throws when the HTTP API is unavailable.
private
dumpCompleteCollections(string $endpoint, string $username, string $password, string $database) : array<int, string>
Parameters
- $endpoint : string
- $username : string
- $password : string
- $database : string
Return values
array<int, string>looksLikePath()
True when a `--profile` value designates an external `.toml` file rather than a named section.
private
looksLikePath(string $value) : bool
Parameters
- $value : string
Return values
boolmaskingRule()
Builds — and validates — a single attribute masking rule from a path and its value (a masker name string, or an inline table carrying `type`).
private
maskingRule(string $path, mixed $value) : array<string, mixed>
Parameters
- $path : string
- $value : mixed
Tags
Return values
array<string, mixed> —{ path, type, …params }
normalizeProfileList()
Flattens a profile list value: arrays and comma-separated strings → a clean, de-duplicated list of trimmed names.
private
normalizeProfileList(mixed $raw) : array<string|int, mixed>
Parameters
- $raw : mixed
Return values
array<string|int, mixed>parseRetentionSize()
Parses a human size (`5G`, `500M`, `1.5G`, `2k`, `1024`) into bytes.
private
parseRetentionSize(int|string $value) : int
Parameters
- $value : int|string