Compression and Archives

Compress, extract, and manage ZIP and archive files with BoxLang

BoxLang provides built-in functions and components for creating, reading, extracting, and managing compressed files. Use compress() and extract() for straightforward archive workflows, or use <bx:zip> when you need to list entries, read content, filter files, or add in-memory content with <bx:zipParam>.

Compress an archive

Pass the source and destination as named arguments when creating an archive:

compress(
    source = "/tmp/project",
    destination = "/tmp/project.tar.gz",
    format = "tar.gz"
)

source may be a file or directory. When the source is a directory, compress() includes its contents recursively by default. Set includeBaseFolder = false when the archive should contain the directory contents without the top-level directory name.

compress(
    source = "/tmp/project",
    destination = "/tmp/project.zip",
    format = "zip",
    includeBaseFolder = false,
    compressionLevel = 9
)

Extract an archive

Use destination for the output directory:

extract(
    source = "/tmp/project.tbz2",
    destination = "/tmp/project-out",
    format = "tbz2"
)

The destination argument replaces the older target spelling. The transpiler maps target to destination for compatibility with older source code.

Use overwrite, filter, and entryPaths to control extraction:

extract(
    source = "/tmp/project.tar.gz",
    destination = "/tmp/project-out",
    format = "tar.gz",
    overwrite = true,
    filter = ( path ) => path.endsWith( ".json" )
)

When an archive is created inside the directory being compressed, BoxLang avoids adding the archive itself to the archive. This supports destinations such as /tmp/project/project.zip without recursively including the output file.

Supported archive formats

Format	compress()	extract()
zip	Yes	Yes
gzip	Yes	Yes
bzip	Yes	Yes
bzip2	Yes	Yes
tar	Yes	Yes
tar.bz	Yes	No
tbz	Yes	Yes
tbz2	Yes	Yes
tgz	Yes	Yes
tar.gz	Yes	Yes

ZIP components

The <bx:zip> component creates and manages ZIP archives. Use its action attribute to choose whether to create an archive, extract it, inspect its entries, read entry content, or remove entries.

Actions

Action	Purpose	Common attributes	Result
zip	Add a file or directory to a ZIP archive. Use <bx:zipParam> for in-memory content or per-entry filters.	file, source, recurse, overwrite, prefix, filter	Creates or updates the archive.
unzip	Extract all or selected entries from a ZIP archive into a directory.	file, destination, entryPath, recurse, overwrite, filter	Writes extracted files to destination.
list	List the entries in an archive.	file, entryPath, filter, flatList, recurse, result	Stores entry metadata or paths in result.
read	Read an entry as text.	file, entryPath, charset, variable	Stores the entry content in variable.
readBinary	Read an entry as binary data.	file, entryPath, variable	Stores the binary content in variable.
delete	Remove one or more entries from an archive.	file, entryPath, filter	Updates the archive without the deleted entries.

The default action is zip. For zip, file is the archive to create or update and source identifies the input. For unzip, destination is the output directory. The entryPath attribute accepts a single path or an array of paths for entry-specific operations.

Zip a file or directory

<bx:zip
    action="zip"
    file="/tmp/archive.zip"
    source="/tmp/project"
    recurse="true"
    overwrite="true">
</bx:zip>

The script form is also available:

bx:zip
    action = "zip"
    file = "/tmp/archive.zip"
    source = "/tmp/project"
    recurse = true
    overwrite = true

Extract a ZIP file

<bx:zip
    action="unzip"
    file="/tmp/archive.zip"
    destination="/tmp/project-out"
    overwrite="true">
</bx:zip>

List or read entries

bx:zip action = "list" file = "/tmp/archive.zip" result = "entries"

bx:zip
    action = "read"
    file = "/tmp/archive.zip"
    entryPath = "config/settings.json"
    variable = "settings"

Add in-memory content

Use <bx:zipParam> to add content directly to an archive or to apply a source filter:

<bx:zip action="zip" file="/tmp/archive.zip">
    <bx:zipParam
        content="Hello BoxLang"
        entryPath="hello.txt">
    </bx:zipParam>
</bx:zip>

<bx:zip action="zip" file="/tmp/logs.zip" source="/tmp/logs">
    <bx:zipParam filter="*.log">
    </bx:zipParam>
</bx:zip>

Related reference

• compress()
• extract()
• isZipFile()
• <bx:zip>
• <bx:zipParam>