=== BMGR Plugin Library ===
Contributors: Art Harvey
Donate link: https://brewmgr.com/
Tags: wordpress, library, ajax, composer, plugin-framework
Requires at least: 5.0
Tested up to: 6.7
Requires PHP: 5.4
Stable tag: 1.2.7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Composer library shared by BrewMGR host plugins: plugin shell, AJAX/REST, data access, jobs, logging, UI helpers, and front-end JS utilities.

== Description ==

bmgr/bmgr-plugin-library is a PHP Composer package used to build WordPress plugins that share one container-based architecture. Host plugins (for example BrewMGR and ExAuth) require this package, load the library autoloader, and extend WP_PLUGIN_HANDLER.

It is a library, not a stand-alone WordPress plugin. Product-specific catalogs and business rules stay in the host plugin; this package provides the reusable kernel.

Author: Art Harvey (art@artharvey.com)

== Installation ==

1. In the host plugin composer.json require section add:
   "bmgr/bmgr-plugin-library": "^1.2"
2. Configure the private Composer repository that hosts the package (SSH/git remote as used by your environment).
3. Run: composer install
4. Load the library from the host plugin (typical path after install):
   require_once plugin_dir_path( dirname( __FILE__ ) ) . 'vendor/bmgr/bmgr-plugin-library/src/includes/bmrg-lib-autoloader.php';
5. Make the main plugin class extend WP_PLUGIN_HANDLER and pass a shared container array.

Optional Composer suggest:
* square/square — required only if you use BMGR_Square_API helpers.

== Usage ==

= Minimal host plugin setup =

1. Create a WordPress plugin (or use an existing BrewMGR-style plugin).
2. Require bmgr/bmgr-plugin-library via Composer and run composer install.
3. Require bmrg-lib-autoloader.php early from the main plugin includes file.
4. Extend WP_PLUGIN_HANDLER:

   class My_Plugin extends WP_PLUGIN_HANDLER {
       public function __construct( &$c = null ) {
           // put PLUGIN_HANDLER, LOGGER, etc. on $c
           parent::__construct( $c );
       }
       public function load_admin_settings() { /* Settings API fields */ }
       public function render_settings_page() { /* admin settings HTML */ }
   }

5. Register host AJAX routes on the AJAX manager (bmgr_router), custom page routes on PAGES_MGR, and enqueue host scripts as needed.

= Front-end AJAX URL (required for lib JS) =

Library JavaScript resolves the WordPress admin-ajax endpoint from:

   bmgr_lib_ajax_obj.ajax_url

Localize it from PHP (wp_localize_script or an inline script using admin_url( 'admin-ajax.php' )). Host plugins may also expose a plugin-specific object and alias it, for example:

   var brewmgr_ajax_obj = { "ajax_url": "...", "nonce": "..." };
   var bmgr_lib_ajax_obj = brewmgr_ajax_obj;

AJAX calls typically post to action=bmgr_router with _ajax_nonce and nested ajaxr_l1 / ajaxr_l2 / action fields.

= JavaScript modules =

* public/js/bmgr-lib-public.js — UI helpers, editable fields, Select2 helpers, ajax()/qAjax(), widgets.
* public/js/bmgr-lib-loader.js — ES module loader/hoist helper for host pages.
* public/js/bmgr-dms2.js — DMS-oriented helpers (shares ajax URL resolution).

Import or hoist via the host page (see comments at the top of bmgr-lib-public.js).

= Extra documentation =

Package docs/ folder:

* BMGR_Square_API.md
* BMGR_DATA_PDO.md
* BMGR_JOURNAL.md
* BMGR_TOOLS.md

== Features ==

= Plugin shell (WP_PLUGIN_HANDLER) =

* Container-based plugin lifecycle and shared singleton patterns
* Admin Settings API helpers (sections, text/toggle fields, settings page render hooks)
* Nonce create/verify helpers used by AJAX and pages
* Config loading (public/private config files via load_config)
* Login / redirect / branding hooks used by host plugins
* HTTP header / CORS related send_headers behavior for host pages

= Routing and request handling =

* BMGR_AJAX — central bmgr_router handler, route registration (add_route), nonce checks, dispatch to container objects or classes
* BMGR_REST — REST-oriented routing helpers
* Brewmgr_Page / custom pages manager — front-end custom page routes, permission hooks, ajax_l2 page handlers
* Page templates under includes/ for custom/login/generic pages

= Data and persistence =

* Brewmgr_Data / data layer helpers used by host plugins
* BMGR_PDO — PDO wrapper for remote/shared databases
* BMGR_API_CLIENT / BMGR_WEB_CLIENT — outbound HTTP/API helpers
* BMGR_JOURNAL — journaling / flush helpers (see docs/BMGR_JOURNAL.md)
* BMGR_DOM_DOC — DOM/document utilities

= Jobs, users, communication =

* Job status constants and host job-processor integration points
* BMGR_TASK — task/reminder oriented helpers
* BMGR_USER — user/org helpers used by hosts
* BMGR_COMM — email/SMS and related communication helpers

= Observability and hardening =

* Brewmgr_Logger / bmgr_wlog — leveled file logging
* BMGR_PMON — performance monitoring, page stats, optional client ban tooling (disabled by default; host enables)
* BMGR_Lib::configure() — host opt-in for Tools admin / headless ban+cache settings (see docs/BMGR_TOOLS.md)
* BMGR_Tools — Tools admin UI (opt-in via configure) for cache mode and ban settings; register_data_mgr() / register_pmon()
* Shared defines in bmgr-lib-defines.php (log size, record/job status constants); hosts may override before load

= Integrations =

* BMGR_Square_API — Square billing helpers (suggests square/square; see docs/BMGR_Square_API.md)
* BMGR_NTFY — lightweight notification helper
* Carbon (nesbot/carbon) for date/period handling

= Front-end library =

* Shared public CSS/JS for widgets, modals, editable fields, Select2, and quiet AJAX
* Expects bmgr_lib_ajax_obj.ajax_url (and typically a nonce exposed by the host)

== Frequently Asked Questions ==

= Is this installed as its own WordPress plugin? =

No. Install it with Composer into a host plugin under vendor/bmgr/bmgr-plugin-library and load bmrg-lib-autoloader.php from that host.

= Where should product-specific constants live? =

In the host plugin. The library only defines kernel constants (logging, record/job status, and similar). Domain catalogs stay in the host.

= Why do AJAX calls fail with "ajax URL missing"? =

The library JS looks for bmgr_lib_ajax_obj.ajax_url. Localize admin_url( 'admin-ajax.php' ) under that name before loading bmgr-lib-public.js (or an alias that assigns bmgr_lib_ajax_obj).

= Can more than one host plugin use the library on one site? =

Yes. WP_PLUGIN_HANDLER uses a once-per-site guard for some shared init work. Each host still has its own container and settings.

== Changelog ==

= 1.3.2 =
* added missing $_SERVER component catches to logger.

= 1.2.7 =
* BMGR_Lib::configure() facade: Tools admin is opt-in (hidden unless a host sets tools.show_admin).
* When Tools admin is enabled, bmgr_tools_options are authoritative; when hidden, code enable_ban_*/lock/defaults drive getters.
* Documented authority split and merge rules in docs/BMGR_TOOLS.md.

= 1.2.6 =
* Updated this readme.

= 1.2.5 =
* Library JS expects bmgr_lib_ajax_obj.ajax_url (renamed from my_ajax_object).
* Package type: Composer library (vendor artifacts not shipped in the package).
* Square API helpers and Tools/PMON registration APIs documented under docs/.

= 1.0 =
* Initial shared plugin-handler, AJAX, data, and UI helper library used by BrewMGR hosts.

== Upgrade Notices ==

= 1.2.7 =
Settings → BMGR Tools no longer appears unless a host calls BMGR_Lib::configure([ 'tools' => [ 'show_admin' => true ] ]). See docs/BMGR_TOOLS.md.

= 1.2.5 =
Breaking update: If you localize AJAX for library JS, use bmgr_lib_ajax_obj (not my_ajax_object). Review docs/ for Square, Tools, Journal, and PDO notes when upgrading hosts.
