=== CirculationDesk Export Tool for Document Library ===
Contributors: arothmanmusic
Tags: document library, export, zip, download manager, documents
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Export a Barn2 document library as a single .zip, organised into one folder per
Document Category, with a CSV manifest.

== Description ==

Adds a page under Tools that exports your whole document library as one .zip file,
sorted into a folder per Document Category, alongside a CSV manifest describing
every document.

Requires Document Library Lite (free) or Document Library Pro by Barn2 Plugins:
https://wordpress.org/plugins/document-library-lite/
https://barn2.com/wordpress-plugins/document-library-pro/

This utility is provided with the approval of, but is not affiliated with, Barn2 Plugins.

== Installation ==

Upload the zip via Plugins > Add New > Upload Plugin, or copy the
circulationdesk-export-tool folder into wp-content/plugins/. Then activate.

Document Library Lite or Pro must be active.

== Usage ==

Tools > Export Documents. Requires the `export` capability, which belongs to
Administrators by default.

Options:

* **Include statuses** — which post statuses to export. Published and privately
  published are ticked by default; drafts, pending, scheduled and archived are
  available where they exist.
* **Folders** — one checkbox per Document Category, plus one for documents with no
  category. Untick a folder to leave it out.
* **Copy multi-category documents into every matching folder** — on by default, so
  each folder is complete. Off files them under their first selected category only.
* **Filenames** — keep the original upload filename, or name files after the
  document title.

Click Build archive, then Download .zip.

== What to expect ==

The archive:

    Some-Category/
    Another-Category/
    _no-category/
    document-library-manifest.csv

Folder names come from the category name, alphabetically ordered, so repeat exports
match. The download is named document-library-YYYY-MM-DD.zip.

The manifest has a row per document: ID, title, status, slug, permalink, dates,
author, link type, path in the zip, filename, size, attachment ID, external URL,
taxonomy terms, document metadata, and a Notes column flagging anything unusual.

Documents that point at a file hosted elsewhere have nothing on the server to
archive. They appear in the manifest with their URL and are counted as skipped.
Missing files are reported the same way.

Progress runs in batches, so a large library will not time out. Leaving the page
mid-build abandons the archive, which is cleaned up within six hours. The archive is a
download: it is deleted from the server once sent, and nothing is added to the Media
Library. It can contain private and draft documents, so treat it accordingly.

== Filters ==

    // Smaller batches on a host with a short execution limit.
    add_filter( 'circulationdesk_export_tool_batch_size', function () { return 10; } );

    // Build the archive somewhere specific.
    add_filter( 'circulationdesk_export_tool_staging_dir', function () { return '/var/tmp/dl-exports'; } );

    // Change the download filename.
    add_filter( 'circulationdesk_export_tool_download_filename', function () { return 'documents.zip'; } );

    // Add extra postmeta keys as manifest columns.
    add_filter( 'circulationdesk_export_tool_manifest_meta_keys', function ( $keys ) { return $keys; } );

== Changelog ==

= 1.0.0 =
* Initial release.
