Libraries - thepoopooman652/proishs-webtools GitHub Wiki

The lib/ directory contains shared code and small utilities used across the webtools in this repository. It is intended to group reusable client- and server-side helper code (CSS/JS assets and PHP utilities), and to make it easy for individual tools to require or reference common functionality.

• css/ — shared stylesheet fragments and small theme files used by multiple tools.
• js/ — small client-side helper scripts that are loaded by front-end pages (utility functions, tiny wrappers, helpers for UI behaviors).
• php/ — server-side helpers and lightweight API scripts. Example subfolders may include APIs/ for tiny HTTP endpoints and helpers/ for common PHP functions.
• lib.md — this file: notes about purpose, usage and developer guidance.

• php/APIs/ — lightweight HTTP endpoints that can be mounted by tools (e.g., file-api.php). Keep endpoint files small and focused on a single action set.
• php/helpers/ — pure-PHP helper functions grouped by purpose (file_helpers.php, string_helpers.php, http_client.php).
• php/tests/ — optional PHPUnit tests for helpers.

1. Shared file helper usage (PHP)

// Load a shared helper from a tool
require_once __DIR__ . '/../lib/php/helpers/file_helpers.php';

$content = read_text_file(__DIR__ . '/../some/tool/files/example.txt');
echo sanitize_text_for_display($content);

2. Shared JS helper usage (client)

<script src="/lib/js/dom-utils.js"></script>
<script>
	window.addEventListener('DOMContentLoaded', () => {
		ProishLib.dom.ready(() => ProishLib.dom.initWidgets());
	});
</script>

1. PHP: include a helper from lib/php

   // from a tool page inside the repo
   require_once __DIR__ . '/../lib/php/helpers.php';
   // or
   require_once __DIR__ . '/lib/php/APIs/file-api.php';

   Place common helper functions (string helpers, file utilities, small wrappers) in lib/php/helpers.php and call them from tools so code is not duplicated.

2. JavaScript: load a shared client utility

   <script src="/lib/js/dom-utils.js"></script>
   <script>
     // Use helpers registered by dom-utils.js
     DomUtils.ready(() => { /* ... */ });
   </script>

3. CSS: import a shared stylesheet

   <link rel="stylesheet" href="/lib/css/controls.css">

• Namespace and autoloading: this repository uses small, flat PHP helper files rather than a composer-managed autoload structure. When adding new PHP helpers, prefer clear filenames and keep each file focused on a single responsibility (e.g., db.php, file_helpers.php, email.php).
• JS helpers should avoid global pollution: use a single global (e.g., ProishLib) or attach to window.ProishLib to keep things organized.
• Keep assets small and dependency-free where possible. If a third-party library is needed, prefer CDN loading or add installation docs in this README.

If a helper includes small CLI or unit tests, document how to run them here. Common quick-check steps:

1. Start a local PHP server at the repository root (development):

php -S 127.0.0.1:8000 -t .

2. Open the relevant tool page in a browser (for example, a tool that depends on lib/php or lib/js).

3. If you add PHPUnit tests under lib/php/tests, run them with your installed PHPUnit binary:

./vendor/bin/phpunit --configuration lib/php/phpunit.xml

• Additions to lib/ should be generic and useful across multiple tools. If something is tool-specific, prefer keeping it inside that tool's folder.
• Keep function names and exported API stable; changing an exported helper may require updates across multiple tools.
• Document any public helper with a short docblock and a usage example in this README or in a README.md inside the specific subfolder.

• Add a short changelog entry here for notable changes to lib/ that affect multiple tools. Example:

  • 2025-11-06: Refactored file_helpers.php to expose get_safe_path() and read_text_file() helpers.

• If you want a per-file inventory (document every file under lib/php and lib/js) I can generate that next, including short one-line descriptions and simple usage examples.

This README is focused on developer usage: structure, examples, and conventions for adding new shared helpers to the repo.