 DownloadXOOPS Helpers
Convention-over-configuration utility and service helpers for XOOPS CMS development.
41 source files. 151 tests. Zero configuration. XSS-safe HTML by default. One composer require.
What Is This?
XOOPS Helpers is a standalone utility library that makes every XOOPS module safer and shorter by replacing the repetitive, error-prone boilerplate every module developer writes over and over:
// Before ? scattered across every XOOPS module
$escaped = htmlspecialchars($value, ENT_QUOTES | ENT_HTML5, 'UTF-8');
$url = XOOPS_URL . '/modules/' . $dirname . '/article.php?id=' . $id;
$path = XOOPS_ROOT_PATH . '/modules/' . $dirname . '/language/' . $language . '/blocks.php';
$sitename = $GLOBALS['xoopsConfig']['sitename'];
// After
$escaped = HtmlBuilder::escape($value);
$url = Url::module($dirname, 'article.php', ['id' => $id]);
$path = Path::module($dirname, "language/{$language}/blocks.php");
$sitename = Config::get('system.sitename');
> That first line is not just shorter ? it is structurally safer.
> Every manual htmlspecialchars() call is a place where a future developer can introduce
> a stored XSS vulnerability by forgetting it once. HtmlBuilder escapes all attribute
> values and class names automatically ? the source of the vast majority of real-world XSS.
> Tag content is your responsibility, intentionally: content can legitimately contain HTML
> (rendered markup, trusted template fragments). The safe path is explicit: pass user-supplied
> content through HtmlBuilder::escape(). This htmlspecialchars pattern appears 30+ times
> in the XOOPS Core alone ? each one a place where this library makes the correct choice the
> easiest choice.
Requirements
-
PHP 8.2 or later with the `ext-mbstring` extension
-
No other runtime dependencies
Optional extensions for enhanced functionality:
- ext-intl ? locale-aware number and date formatting
- ext-apcu ? APCu caching backend
- ext-zip ? zip/unzip filesystem operations
Installation
composer require xoops/helpers
Quick Start
use Xoops\Helpers\Utility\HtmlBuilder;
use Xoops\Helpers\Service\Url;
use Xoops\Helpers\Service\Path;
use Xoops\Helpers\Service\Config;
use Xoops\Helpers\Service\Cache;
use Xoops\Helpers\Utility\Arr;
use Xoops\Helpers\Utility\Str;
use Xoops\Helpers\Utility\Number;
use Xoops\Helpers\Utility\Collection;
// HTML ? attribute values escaped automatically; use text() for tag content
HtmlBuilder::attributes(['class' => 'btn', 'disabled' => true, 'data-id' => $userInput]);
HtmlBuilder::classes(['btn', 'btn-primary' => $isPrimary, 'disabled' => false]);
HtmlBuilder::tag('div', ['class' => 'alert'], HtmlBuilder::text($userMessage)); // user text
HtmlBuilder::tag('div', ['class' => 'body'], $renderedHtmlBlock); // trusted HTML
// URLs ? zero concatenation
Url::module('news', 'article.php', ['id' => 42]);
Url::asset('themes/starter/css/style.css');
Url::theme('starter', 'images/logo.png');
// Paths ? cross-platform, always correct; languageFile() resolves language fallback
Path::module('news', 'language/english/main.php');
Path::languageFile('news', $language, 'main.php'); // tries $language, falls back to english
Path::storage('caches/xmf');
Path::uploads('images/avatars');
// Config ? dot notation, auto-cached
Config::get('system.sitename', 'XOOPS');
Config::get('news.items_per_page', 10);
// Cache ? compute-and-cache in one call
$articles = Cache::remember('news_latest', 3600, fn() => loadArticles());
// Arrays ? dot notation, pluck, group, filter
$value = Arr::get($config, 'database.host', 'localhost');
$names = Arr::pluck($users, 'uname', 'uid');
$grouped = Arr::groupBy($articles, 'category_id');
// Strings ? slug, validation, case conversion
Str::slug('Hello World'); // "hello-world"
Str::isEmail('a@example.com'); // true
Str::camel('module_config'); // "moduleConfig"
Str::limit($body, 150); // "First 150 chars..."
Str::random(32); // cryptographically secure
// Numbers ? human-readable formatting
Number::fileSize(1572864); // "1.50 MB"
Number::forHumans(2300000); // "2.3M"
Number::ordinal(21); // "21st"
Number::currency(99.99, 'EUR', 'de_DE');
// Collections ? fluent data transformation
Collection::make($items)
->filter(fn($item) => $item['active'])
->sortBy('name')
->pluck('title', 'id')
->all();
Library Contents
Tier 0 ? Utility (Pure PHP, zero XOOPS dependency)
These work anywhere ? CLI scripts, cron jobs, unit tests ? no XOOPS boot required.
| Class | Purpose |
|-------|---------|
| HtmlBuilder | XSS-safe HTML: attributes, classes, tag, escape, text, stylesheet, script, meta ? attribute values escaped automatically; use text() to explicitly escape tag content |
| Arr | Array helpers with dot notation: get, set, has, pluck, groupBy, sortBy, where, flatten, dot/undot, only/except, first/last, wrap, collapse |
| Str | String helpers: slug, camel/snake/studly/kebab, limit, random, contains/startsWith/endsWith, between, mask, isEmail/isUrl/isIp/isJson/isHexColor |
| Number | Number formatting: format, fileSize, forHumans, percentage, ordinal, currency, clamp |
| Date | Date helpers with injectable time source: now, range, diff, isValid, addDays/subDays, isWeekend/isToday/isPast/isFuture, reformat, age |
| Value | Value resolution: value (Closure resolver), blank/filled, optional (null-safe access), once (memoization), missing (sentinel) |
| Collection | Fluent array wrapper: map, filter, reject, reduce, pluck, groupBy, sortBy, first/last, chunk, take/skip, sum/avg/min/max, when, pipe, tap |
| Pipeline | Data transformation chains: Pipeline::send($v)->pipe(fn)->pipe(fn)->thenReturn() |
| Stringable | Fluent string builder: Stringable::of($s)->trim()->lower()->slug()->toString() |
| Filesystem | File operations: readJson/putJson, mimeType, isImage, mkdir, deleteDirectory, copyDirectory, zip/unzip, readChunked |
| Environment | Runtime detection: isProduction/isDevelopment/isTesting, get/require/has |
| Benchmark | Profiling: measure (time + memory), time, average (multi-iteration) |
| Encoding | URL-safe base64: base64UrlEncode/base64UrlDecode |
| Data | Conversion: toArray, toObject, toQueryString, fromQueryString |
| Retry | Error recovery: retry (with backoff), rescue (with fallback) |
| ThrowHelper | Guard clauses: throwIf, throwUnless |
| Transform | Conditional transforms: transform (if filled), when (predicate-based) |
| Tap | Side-effect helper: call callback, return original value |
Tier 1 ? Contracts (Interfaces)
| Interface | Purpose |
|-----------|---------|
| PathLocatorInterface | Filesystem path resolution |
| UrlGeneratorInterface | URL generation |
| CacheInterface | Cache operations |
| ConfigProviderInterface | Configuration loading |
| DateTimeProviderInterface | Clock abstraction for testing |
Tier 2 ? Service Facades (Zero-config, XOOPS-aware)
| Facade | Purpose | Override |
|--------|---------|----------|
| Path | Path::base(), module(), storage(), uploads(), themes(), languageFile() | Path::use($locator) |
| Url | Url::to(), asset(), module(), theme() | Url::use($generator) |
| Config | Config::get(), set(), has(), all(), registerLoader() | Config::setProvider($p) |
| Cache | Cache::get(), set(), forget(), remember(), flush() | Cache::use($adapter) |
All facades work immediately using XOOPS constants (XOOPS_ROOT_PATH, XOOPS_URL, etc.). Override with ::use() for testing or custom installations. Reset with ::reset().
Tier 3 ? Providers (Default implementations)
| Provider | Purpose |
|----------|---------|
| DefaultPathLocator | Maps to XOOPS constants |
| DefaultUrlGenerator | Uses XOOPS_URL, falls back to $_SERVER |
| XoopsCacheAdapter | Auto-detects: XoopsCache, APCu, or file cache |
| ArrayCache | In-memory cache for testing |
| SystemDateTimeProvider | System clock |
Tier 4 ? Integration (XOOPS-specific)
| Component | Purpose |
|-----------|---------|
| XoopsCollection | XoopsCollection::fromHandler($handler, $criteria) with pluckVar() for getVar() |
| AssetUrlPlugin | Smarty: <{asset_url path="css/style.css"}> |
| FormatNumberPlugin | Smarty: <{format_number value=$size type="filesize"}> |
| CssClassesPlugin | Smarty: <{css_classes classes=$classArray}> |
| PluginRegistrar | Register all Smarty plugins at once |
Cross-cutting
| Component | Purpose |
|-----------|---------|
| Tappable | Trait adding tap() to any class |
| functions.php | Optional global function wrappers (not auto-loaded) |
Architecture
Dependencies flow downward only. Tier 0 classes can be used in any PHP 8.2+ project without XOOPS ? in CLI scripts, cron jobs, and unit tests with no bootstrap required.
graph TD
T4["Tier 4 · Integration
Depend on XOOPS classes
XoopsObject · Smarty"]
T3["Tier 3 · Provider
Default implementations
XOOPS-aware"]
T2["Tier 2 · Service
Static facades
Depend on XOOPS constants"]
T1["Tier 1 · Contracts
Interfaces only
No implementation"]
T0["Tier 0 · Utility
Pure PHP · Zero dependencies
Works anywhere"]
T4 --> T3
T3 --> T2
T2 --> T1
T1 --> T0
style T4 fill:#b7e0ff,stroke:#4a90d9,color:#000
style T3 fill:#c8f0d0,stroke:#3a9a5c,color:#000
style T2 fill:#fff3b0,stroke:#c8a200,color:#000
style T1 fill:#ffd6a5,stroke:#d48000,color:#000
style T0 fill:#ffadad,stroke:#c0392b,color:#000
Optional Global Functions
The file src/functions.php provides short function wrappers like collect(), str(), pipeline(), tap(), retry(), env(), etc. It is not auto-loaded ? opt in explicitly.
Recommended pattern: load it once in your XOOPS bootstrap, not in individual module files. This prevents redundant require calls across a multi-module installation:
// In mainfile.php or a central preload script ? once per request
if (file_exists(XOOPS_ROOT_PATH . '/vendor/xoops/helpers/src/functions.php')) {
require_once XOOPS_ROOT_PATH . '/vendor/xoops/helpers/src/functions.php';
}
If you are building a single module and do not control the bootstrap, load it in your module's entry point:
require_once 'vendor/xoops/helpers/src/functions.php';
$slug = str('Hello World')->slug()->toString();
$data = collect($items)->filter(fn($i) => $i['active'])->pluck('name')->all();
$value = retry(3, fn() => fetchFromApi(), sleepMs: 500);
All functions are guarded with function_exists() to prevent fatal redeclaration errors.
Compatibility
XOOPS 2.5.x
Fully compatible. Designed for inclusion in XOOPS 2.5.12+.
XMF 1.x (xoops/xmf)
No conflicts. Different namespace (Xoops\Helpers\ vs Xmf\), no shared class names, no shared global functions. Both can be loaded simultaneously via Composer.
Where both libraries offer related functionality, they serve different scopes:
| Area | XMF 1.x | XOOPS Helpers |
|------|---------|---------------|
| URL/Path | $helper->url() ? module-scoped | Url::module() ? global, works without module context |
| Config | $helper->getConfig() ? per-module handler | Config::get('mod.key') ? dot notation, cached |
| Cache | Helper\Cache::cacheRead() ? module-prefixed | Cache::remember() ? global, auto-backend |
| Random | Random::generateKey() ? SHA512 hash tokens | Str::random() ? URL-safe strings, configurable length |
| SEO | Metagen::generateSeoTitle() ? full meta tags | Str::slug() ? pure string transformation |
Migration Strategy
You do not need to refactor existing XMF 1.x code to adopt this library. Both coexist safely. The recommended approach depends on where you are in a project:
Starting a new module ? use XOOPS Helpers exclusively from the first line. There is no legacy to consider and you get the full benefit of automatic escaping, dot-notation config, and fluent collections from day one.
Actively developing an existing module ? use XOOPS Helpers for all new code and any functions you touch during the current sprint. When you open a file to add a feature, convert the XMF 1.x patterns in that file as you go. Do not schedule a dedicated refactoring sprint; let the migration happen organically as the module evolves.
Maintaining a stable module with no active development ? do nothing. The libraries coexist with zero conflicts. The migration cost is not justified by a pure maintenance ticket. If it is not broken, leave it until you have a reason to open the file.
When you do migrate a specific pattern, the Cache facade is the most common conversion:
// XMF 1.x ? before
if (!$data = \XoopsCache::read("{$dirname}_config")) {
$data = xoops_getModuleConfig($dirname);
\XoopsCache::write("{$dirname}_config", $data);
}
// XOOPS Helpers ? after
$data = Cache::remember("{$dirname}_config", 3600, fn() => xoops_getModuleConfig($dirname));
XMF 2.0 (xoops/xmf next generation)
Designed as a companion. XMF 2.0 provides the architectural framework (Repository, EventBus, Container, QueryBuilder); XOOPS Helpers provides the day-to-day utilities (Arr, Str, Number, HtmlBuilder, Collection). XMF 2.0 will declare xoops/helpers as a dependency ? requiring XMF 2.0 pulls this library in automatically.
Testing
composer install
vendor/bin/phpunit
All services are mockable for testing:
use Xoops\Helpers\Service\{Path, Url, Config, Cache};
use Xoops\Helpers\Provider\ArrayCache;
// Inject test implementations
Cache::use(new ArrayCache());
Config::registerLoader('mymod', fn() => ['key' => 'value']);
// Reset after tests
Cache::reset();
Config::reset();
Path::reset();
Url::reset();
The Date utility accepts an injectable time provider:
use Xoops\Helpers\Utility\Date;
use Xoops\Helpers\Contracts\DateTimeProviderInterface;
Date::setProvider(new class implements DateTimeProviderInterface {
public function now(): \DateTimeImmutable {
return new \DateTimeImmutable('2025-06-15 12:00:00');
}
});
Date::isToday('2025-06-15'); // true ? deterministic in tests
Date::resetProvider();
Contributing
Contributions are welcome. Please follow XOOPS coding standards:
- declare(strict_types=1) in every file
- PHP 8.2+ features (readonly, match, named arguments, union types)
- Final classes for utility classes
- Full type hints on all methods
- PHPUnit tests for all new functionality
Documentation
See TUTORIAL.md for a comprehensive guide with before/after comparisons from real XOOPS Core and module code.
License
GNU GPL v2 or later. See LICENSE for details.
|
