Oihana Php System

ArchiveTrait uses trait:short

Provides helpers to bundle files into an archive (tar/zip) and stream it as a PSR-7 download response, and to extract incoming archives back to disk.

The download helpers build the archive (delegating creation to the oihana\files\archive tar/zip helpers) then delegate header emission, streaming and temporary-file cleanup to the shared self::archiveDownload() method. The extraction helpers delegate to the same package, which guards against path traversal (Zip Slip) and decompression bombs.

Methods

extractTar() : true|array<string|int, mixed>: Extracts a tar archive into a destination directory.
extractZip() : true|array<string|int, mixed>: Extracts a ZIP archive into a destination directory.
fail() : ResponseInterface|null: Generates a structured error response with an HTTP status code and optional detailed messages.
response() : ResponseInterface: Return a response in the format accepted by the client : JSON by default or CBOR.
status() : ResponseInterface|null: Outputs a generic HTTP status message in a JSON response.
success() : mixed: Outputs a success message with optional JSON metadata.
successWithNewBody() : mixed: Same as {@see self::success()} but guarantees a fresh response body stream before writing the envelope.
tarResponse() : ResponseInterface: Bundles files and/or directories into a tar archive (optionally compressed) and streams it as a download response.
withFreshBody() : ResponseInterface|null: Returns the same response with a fresh, empty body stream.
zipResponse() : ResponseInterface: Bundles a set of files into a ZIP archive and streams it as a download response.
archiveDownload() : ResponseInterface: Emits the download headers for a produced archive, streams its content into the response body, then removes the temporary archive file.

extractTar()

Extracts a tar archive into a destination directory.


    public
                    extractTar(string $archive, string $destDir[, array<string|int, mixed> $options = [] ]) : true|array<string|int, mixed>

Thin wrapper around oihana\files\archive\tar\untar(), which already guards against path traversal and decompression bombs (see TarOption).

Parameters

$archive : string: Path of the tar archive to extract.
$destDir : string: Directory where the archive is extracted.
$options : array<string|int, mixed> = []: Optional flags, keyed by TarOption.

Return values

true|array<string|int, mixed> —

true on success, or the list of entries when dryRun is enabled.

extractZip()

Extracts a ZIP archive into a destination directory.


    public
                    extractZip(string $archive, string $destDir[, array<string|int, mixed> $options = [] ]) : true|array<string|int, mixed>

Thin wrapper around oihana\files\archive\zip\unzip(), which guards against path traversal (Zip Slip) and decompression bombs, and supports a dry run and overwrite control (see ZipOption).

Parameters

$archive : string: Path of the ZIP archive to extract.
$destDir : string: Directory where the archive is extracted.
$options : array<string|int, mixed> = []: Optional flags, keyed by ZipOption (dryRun, overwrite, maxEntries, maxSize, keepPermissions).

Return values

true|array<string|int, mixed> —

true on success, or the list of entries when dryRun is enabled.

fail()

Generates a structured error response with an HTTP status code and optional detailed messages.


    public
                    fail(ServerRequestInterface|null $request, ResponseInterface|null $response[, int|string|null $code = 400 ][, string|null $details = null ][, array<string|int, mixed> $options = [] ][, string|null $accept = null ]) : ResponseInterface|null

Automatically logs the error if logging is enabled.

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: The PSR-7 Response object.
$code : int|string|null = 400: The HTTP status code (default: 400).
$details : string|null = null: Optional detailed error message to override default description.
$options : array<string|int, mixed> = []: Optional array of additional data to include (e.g., errors).
$accept : string|null = null: The header accepted by the client : 'application/cbor' or by default 'application/json'

Tags

example

return $this->fail(
    $response,
    406,
    'fields validation failed',
    [
        'firstName' => 'firstName is required',
        'lastName'  => 'lastName must be a string'
    ]
);

Return values

ResponseInterface|null —

Returns a PSR-7 Response object with JSON content or null if $response is not provided.

response()

Return a response in the format accepted by the client : JSON by default or CBOR.


    public
                    response(ResponseInterface $response[, mixed $data = null ][, int $status = 200 ][, string|null $accept = null ]) : ResponseInterface

Checks the Accept header in the request to determine the preferred format.

Parameters

$response : ResponseInterface: PSR-7 Response object to write to.
$data : mixed = null: Data to send in the response.
$status : int = 200: HTTP status code (default: 200).
$accept : string|null = null: The header accepted by the client : 'application/cbor' or by default 'application/json'

Return values

ResponseInterface

status()

Outputs a generic HTTP status message in a JSON response.


    public
                    status(ServerRequestInterface|null $request, ResponseInterface|null $response[, mixed $message = Char::EMPTY ][, int|string|null $code = 200 ][, array<string|int, mixed>|null $options = null ][, string|null $accept = null ]) : ResponseInterface|null

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: PSR-7 Response object to send output.
$message : mixed = Char::EMPTY: The message content.
$code : int|string|null = 200: The HTTP status code (default: 200).
$options : array<string|int, mixed>|null = null: Optional array of additional output properties.
$accept : string|null = null: The header accepted by the client : 'application/cbor' or by default 'application/json'

Tags

example

return $this->status($response, 'bad request', 405);

Return values

ResponseInterface|null —

Returns a PSR-7 Response object with JSON content or null if $response is not provided.

success()

Outputs a success message with optional JSON metadata.


    public
                    success(ServerRequestInterface|null $request, ResponseInterface|null $response[, mixed $data = null ][, array<string|int, mixed>|null $init = null ][, string|null $accept = null ]) : mixed

If $response is null, returns the $data directly. Supports optional initialization properties like count, limit, offset, owner, URL, status, total, position, options.

Parameters

$request : ServerRequestInterface|null

Optional PSR-7 Request object.

$response : ResponseInterface|null

Optional PSR-7 Response object.

$data : mixed = null

The main payload or data to return.

$init : array<string|int, mixed>|null = null

Optional associative array with keys:

count (int): Number of elements
limit (int): Pagination limit
offset (int): Pagination offset
params (array): Parameters for getCurrentPath()
status (int): HTTP status code
total (int): Total elements
url (string): URL to include in response
owner (array|object): Owner reference
options (array): Additional properties
position (int): Optional position in list

$accept : string|null = null

The header accepted by the client : 'application/cbor' or by default 'application/json'

Tags

example

return $this->success(
    $request,
    $response,
    $data,
    [Output::COUNT => count($data), Output::PARAMS => $request->getQueryParams()]
);

Return values

mixed —

Returns a PSR-7 Response object with JSON if $response is provided, otherwise returns $data directly.

successWithNewBody()

Same as {@see self::success()} but guarantees a fresh response body stream before writing the envelope.


    public
                    successWithNewBody(ServerRequestInterface|null $request, ResponseInterface|null $response[, mixed $data = null ][, array<string|int, mixed>|null $init = null ][, string|null $accept = null ]) : mixed

Use this only when an upstream actor (typically a sub-controller called from the current controller method) may have already written into the shared PSR-7 body stream. Calling the plain success() in that case would concatenate two JSON envelopes — invalid JSON for any strict parser (NextJS RSC, modern fetch, etc.).

Implementation: swaps the response body for an empty stream via self::withFreshBody(), then delegates to success(). Whatever was previously written is discarded; the resulting body contains exactly one envelope.

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: Optional PSR-7 Response object.
$data : mixed = null: The main payload or data to return.
$init : array<string|int, mixed>|null = null: Same keys as success().
$accept : string|null = null: The header accepted by the client.

Tags

example

// POST /users where dispatchAutoInvitation() writes into the shared body
public function post( ?Request $request , ?Response $response , array $args , array $init ) :mixed
{
    $result = parent::post( $request , $response , $args , $init ) ;
    $this->dispatchAutoInvitation( $request , $response , $userKey ) ;

    return $this->successWithNewBody
    (
        $request ,
        $result  ,
        $this->refetchHydratedUser( $userKey )
    ) ;
}

see

success()

Plain variant when the body has not been touched.

Return values

mixed —

Same return contract as success().

tarResponse()

Bundles files and/or directories into a tar archive (optionally compressed) and streams it as a download response.


    public
                    tarResponse(ServerRequestInterface|null $request, ResponseInterface $response, string|array<string|int, mixed> $paths, string $archive[, string|null $compression = CompressionType::GZIP ][, array<string|int, mixed> $options = [] ]) : ResponseInterface

Delegates the archive creation to oihana\files\archive\tar\tar(). Only GZIP, BZIP2 and NONE compressions are supported; any other value raises an UnsupportedCompressionException, reported as a 500 response.

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object (used to build the failure response).
$response : ResponseInterface: The PSR-7 Response object to write the archive into.
$paths : string|array<string|int, mixed>: File and/or directory path(s) to add to the archive.
$archive : string: Absolute path of the tar archive to create.
$compression : string|null = CompressionType::GZIP: One of CompressionType: GZIP (default), BZIP2 or NONE.
$options : array<string|int, mixed> = []: Optional header switches (see FileResponseOption).

Return values

ResponseInterface —

The response carrying the archive, or a 500 failure response on error.

withFreshBody()

Returns the same response with a fresh, empty body stream.


    public
                    withFreshBody(ResponseInterface|null $response) : ResponseInterface|null

Use to discard whatever an upstream actor (sub-controller, middleware) may have already written, then chain into any other response helper.

Parameters

$response : ResponseInterface|null: Optional PSR-7 Response object.

Tags

example

return $this->fail( $request , $this->withFreshBody( $response ) , 502 , 'zitadel_sync_failed' ) ;

Return values

ResponseInterface|null —

The same response with a fresh empty body, or null if $response was null.

zipResponse()

Bundles a set of files into a ZIP archive and streams it as a download response.


    public
                    zipResponse(ServerRequestInterface|null $request, ResponseInterface $response, array<string|int, mixed> $files, string $archive, string $path[, array<string|int, mixed> $options = [] ]) : ResponseInterface

Delegates the archive creation to oihana\files\archive\zip\zip(), with $path used as the preserved root so each entry keeps its name relative to $path (i.e. $path . $name). If the archive cannot be created, a 500 response is returned.

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object (used to build the failure response).
$response : ResponseInterface: The PSR-7 Response object to write the archive into.
$files : array<string|int, mixed>: List of file names (relative to $path) to add to the archive.
$archive : string: Absolute path of the ZIP archive to create.
$path : string: Base directory prepended to each entry in $files (preserved root).
$options : array<string|int, mixed> = []: Optional header switches (see FileResponseOption).

Return values

ResponseInterface —

The response carrying the archive, or a 500 failure response on error.

archiveDownload()

Emits the download headers for a produced archive, streams its content into the response body, then removes the temporary archive file.


    private
                    archiveDownload(ResponseInterface $response, string $produced, string $contentType[, array<string|int, mixed> $options = [] ]) : ResponseInterface

Parameters

$response : ResponseInterface: The PSR-7 Response object to write the archive into.
$produced : string: Absolute path of the produced archive file.
$contentType : string: The Content-Type to advertise when enabled.
$options : array<string|int, mixed> = []: Optional header switches (see FileResponseOption).

Return values

ResponseInterface —

The response carrying the archive body.

ArchiveTrait uses trait:short

Table of Contents

Methods

Methods

extractTar()

Parameters

Tags

Return values

extractZip()

Parameters

Tags

Return values

fail()

Parameters

Tags

Return values

response()

Parameters

Tags

Return values

status()

Parameters

Tags

Return values

success()

Parameters

Tags

Return values

successWithNewBody()

Parameters

Tags

Return values

tarResponse()

Parameters

Return values

withFreshBody()

Parameters

Tags

Return values

zipResponse()

Parameters

Return values

archiveDownload()

Parameters

Return values