=== ToolDocs ===
Contributors: fmgconsultants
Tags: document management, file manager, downloads, documents, shortcodes
Requires at least: 5.8
Tested up to: 6.9
Requires PHP: 8.2
Stable tag: 0.9.9
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A document management plugin that provides ungated, persistent permalinks for your uploaded documents.

== Description ==

ToolDocs is a document management plugin for WordPress that lets you upload, organize, and share documents with your visitors through direct permalinks.

**Key Features:**

* Upload and manage PDF, Word, Excel, ZIP, and other file types
* Add external URLs as managed documents
* Organize documents into categories
* Generate direct permalink URLs for each document
* Embed document download links using shortcodes
* Track download counts and view per-document download history
* Export download statistics to CSV (summary, by day, by week, by month)
* File version history with configurable retention (0-4 versions)
* File usage detection across your site
* Customize shortcode icon color
* Font Awesome icon support with customizable file type icons
* Modern Vue.js admin dashboard
* REST API for programmatic access
* Developer-friendly with filters for customization

**Shortcodes:**

* `[tooldocs_file id="X"]` - Display a single document download link with file type icon
* `[tooldocs_category_files category_id="Y"]` - Display all documents in a category, with optional modal popup

**How It Works:**

1. Upload documents through the ToolDocs admin panel or add external URLs
2. Organize them into categories
3. Use shortcodes or direct URLs to share documents on your site
4. Track downloads and export reports

== Installation ==

1. Upload the `tooldocs` folder to the `/wp-content/plugins/` directory, or install directly through the WordPress plugins screen.
2. Activate the plugin through the "Plugins" screen in WordPress.
3. Navigate to the ToolDocs menu item in your admin sidebar to start uploading documents.

== Frequently Asked Questions ==

= What file types can I upload? =

ToolDocs uses WordPress native MIME type detection, so any file type allowed by your WordPress configuration can be uploaded. This includes PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, ZIP, and many more.

= Where are uploaded files stored? =

By default, files are stored in `wp-content/uploads/tooldocs/`. You can change this in the ToolDocs settings, but the path must remain within `wp-content/uploads/`.

= How do I embed a document link on a page? =

Use the `[tooldocs_file id="X"]` shortcode, replacing X with the document ID shown in the ToolDocs admin panel. You can also use `[tooldocs_file id="X" link_text="Custom Text"]` to set custom link text.

= Can I display all documents in a category? =

Yes. Use the `[tooldocs_category_files category_id="Y"]` shortcode, replacing Y with the category ID. By default, files display in a modal popup. Set `modal="false"` to display them inline.

= Can I track how many times a document has been downloaded? =

Yes. ToolDocs automatically tracks download counts for each file. You can view per-document download history in the admin panel and export download statistics as CSV files with daily, weekly, and monthly breakdowns.

= Can I add external URLs as documents? =

Yes. You can add external URLs as managed documents. They receive their own permalink and can be organized into categories just like uploaded files.

= Does this plugin require any external services? =

No. ToolDocs works entirely within your WordPress installation with no external service dependencies.

= How does Font Awesome work with this plugin? =

The plugin bundles a minimal subset of Font Awesome Regular icons for file type display. If your theme or another plugin already loads Font Awesome, the plugin detects this and skips loading its own copy to avoid conflicts. You can disable the plugin's Font Awesome loading entirely in ToolDocs settings.

= What is the difference between ToolDocs and ToolDocs Premium? =

ToolDocs provides document management with direct download links. ToolDocs Premium adds gated document access, user registration forms, login system, email notifications, bot verification, session tracking, and more.

== Development ==

The admin interface is built with Vue.js. Source code is included in the `admin/src/` directory.
Frontend JavaScript source is in `front/`.

To build the admin interface:
1. Navigate to the `admin/` directory
2. Run `npm install`
3. Run `npm run build`

To build the frontend JavaScript:
1. Navigate to the `front/` directory
2. Run `npm install`
3. Run `npm run build`


== Screenshots ==

1. Admin dashboard - Manage your documents
2. Category management - Organize files into categories
3. Download history - View document download history
4. Settings panel - Configure upload directory, Font Awesome, and colors

== Review Responses ==

= Nonces and User Permissions (document-download.php) =

The document download template is a public-facing page with no authentication or access restrictions - all documents are freely downloadable. The `h` parameter is simply a unique file identifier (like a post slug), and `src` is a tracking parameter similar to UTM parameters. These URLs are distributed in emails, press releases, and external sites, so they cannot be bound to a WordPress nonce (which would expire and require an active session to generate). Both `$_GET` parameters are sanitized with `sanitize_text_field(wp_unslash())` and the hash is validated against the database before any file operation.

= Variables and options must be escaped when echo'd (fread) =

The `echo fread()` on this line streams raw binary file data (PDFs, ZIPs, documents, etc.) to the browser. Escaping binary data would corrupt the file. The Content-Type header is set from the WordPress media library MIME type, and the file path is resolved from a validated database record. This is the standard pattern for file streaming in PHP and cannot be escaped.

= Changing global behaviour (DONOTCACHEPAGE) =

The `DONOTCACHEPAGE` constant is only defined on the specific ToolDocs download page, not globally. It is set inside a conditional that checks `get_queried_object_id()` against the stored download page ID. This is a standard WordPress cache-busting constant recognised by all major caching plugins, and it is necessary to ensure download tracking fires on every visit to the download page.

== Changelog ==

= 0.9.9 =
* Excel export of download statistics replaced with native CSV (ZIP of summary, by-day, by-week, by-month, and detailed CSVs). Single-file download history exports now produce a CSV file. Removes the OpenSpout dependency entirely.
* Removed legacy `[td_file]` and `[td_category_files]` shortcodes. Use `[tooldocs_file]` and `[tooldocs_category_files]` instead.
* Tightened REST upload permissions: `/upload`, `/upload/external`, and the document replace endpoints now also require the `upload_files` capability.
* Hardened shortcode output: filter-provided icon HTML is now sanitized through `wp_kses()` with a tight SVG-aware allowlist.
* Removed the `ini_set('memory_limit', '256M')` raise from the document download template; the chunked 8 KB stream keeps memory usage bounded without it.
* Added the public source repository URL to the readme Development section.

= 0.9.7 =
* Initial release.

== Upgrade Notice ==

= 0.9.9 =
The legacy `[td_file]` and `[td_category_files]` shortcodes have been removed. If your pages use them, replace them with `[tooldocs_file]` and `[tooldocs_category_files]`. Excel export of download history is now CSV (a ZIP archive for the multi-period stats export, a single CSV for per-file history).

= 0.9.7 =
Initial release.
