# FileMaker Functions

## `cwpSendToFM($data, $layout, $field, $script = null, $fm_opts = [])`
Send any array/object as JSON to FileMaker, with optional script trigger. Designed for event-driven data dumps (e.g., after checkout, form submission, etc.).

- **Purpose:**
  - Quickly send data to FileMaker as a JSON string in a specified field
  - Optionally trigger a FileMaker script after record creation
  - Keeps integration simple and safe (not for arbitrary FM actions)

- **Parameters:**
  - `$data` (array|object): Data to send (will be JSON-encoded)
  - `$layout` (string): FileMaker layout to use
  - `$field` (string): FileMaker field to store JSON
  - `$script` (string|null): Optional FileMaker script to run
  - `$fm_opts` (array): Optional override for FM connection constants (host, db, user, pass)

- **Returns:**
  - Array with keys: `success` (bool), `message` (string), `response` (FM API response or script result)

- **Example:**
  ```php
  $result = cwpSendToFM($checkout_data, 'Web_Orders', 'json_field', 'AfterOrderScript');
  if (!$result['success']) {
      fmcwpShowResponse($result, 'FileMaker Error');
  }
  ```

---

## `handle_filemaker_download()`

Purpose:
- Securely fetch and stream a file from a FileMaker server (or any HTTPS URL) via AJAX.

Handlers:
- Registered actions: `fm_download` (logged-in) and `fm_download` (nopriv) — both map to `handle_filemaker_download()` in this plugin.

Usage:
- Call via `admin-ajax.php` with query parameters `action=fm_download&url=<encoded_url>&filename=<optional_filename>`.
- Example direct link (browser):
```
https://example.com/wp-admin/admin-ajax.php?action=fm_download&url=https%3A%2F%2Ffm-server.example%2Ffile.pdf&filename=file.pdf
```

Server-side example (PHP):
```php
$download_url = admin_url('admin-ajax.php') . '?action=fm_download&url=' . urlencode($fileUrl) . '&filename=' . rawurlencode($fileName);
$response = wp_remote_get($download_url);
// handle $response as usual (wp_remote_retrieve_body, etc.)
```

Behavior and validation:
- Requires the `url` parameter and enforces that it begins with `https://`.
- Uses `wp_remote_get()` with a 30s timeout and follows redirects.
- On success returns the file contents streamed to the client with `Content-Disposition: attachment; filename="<filename>"`.
- On failure the handler calls `wp_die()` with an error message (appropriate for AJAX downloads).

Security notes:
- The handler does NOT enforce authentication by default; the action is registered for both logged-in and non-logged-in users. Restrict usage in production by:
  - Requiring a nonce or `current_user_can('manage_options')` check at the top of `handle_filemaker_download()`; or
  - Moving the action registration to only `wp_ajax_fm_download` (remove `nopriv`) so only authenticated users may call it; or
  - Adding a token parameter and validating it in the handler.
- Always validate `filename` and avoid reflecting untrusted values in headers without sanitization.

Example cURL (server-to-server) to download via the AJAX handler:
```bash
curl --location --request GET "https://example.com/wp-admin/admin-ajax.php?action=fm_download&url=https%3A%2F%2Ffm-server.example%2Ffile.pdf&filename=file.pdf" -o file.pdf
```

Notes:
- This helper is intended as a convenience for remote FileMaker-hosted files. If you require complex authentication to access the FileMaker file, handle auth inside `handle_filemaker_download()` or use a server-side proxy with credentials stored securely (not in client-facing code).