Wp Cubi Helpers Laravel Package

Getting Started

globalis/wp-cubi-helpers is a small, opinionated collection of functions extracted from the wp-cubi WordPress boilerplate. It is not a general-purpose utility library — it assumes you are working inside a wp-cubi–style project (Bedrock-like layout, .env-driven config, config/environments/*.php, web/wp docroot). If you're not, expect some helpers to be no-ops or fatal.

Minimal path:

1. Confirm it's installable for you. It's on Packagist under globalis/wp-cubi-helpers; if your project's minimum-stability blocks it, or you need a specific commit, add a vcs repository entry. Pin to the 2025-06-09 tag rather than dev-master.
2. Check composer.json first. Look at type (likely wordpress-muplugin or library) and, critically, the autoload block. If it uses "files", the functions are loaded on every request automatically; if it's PSR-4 only, you must require a bootstrap file.
3. Read the source, not the README. With 5 stars and 0 dependents, the README is likely thin. grep -rn "function " vendor/globalis/wp-cubi-helpers/src gives you the real API surface in about ten seconds. That list is the documentation.
4. First use case: replace a hardcoded value in wp-config.php or functions.php with the package's environment/config helper. That's the smallest change that proves the autoloading and the wp-cubi conventions line up in your install.

If the package isn't already pulled in transitively, and you're running a wp-cubi project, check whether wp-cubi itself already requires it — you may find it in vendor/ without having added it.

Implementation Patterns

Loading it as an mu-plugin. If composer.json declares a muplugin type and you use composer/installers with wordpress-muplugin, it lands in web/wp-content/mu-plugins/. Otherwise add a one-line loader in your existing mu-plugin bootstrap:

// web/wp-content/mu-plugins/000-loader.php
require_once __DIR__ . '/../../vendor/autoload.php';

Thin adapter layer. Because these are global functions with no namespace guarantee, wrap the two or three you actually use in your own project-level helpers:

function acme_env( string $key, $default = null ) {
    return function_exists( 'wp_cubi_get_env' )
        ? wp_cubi_get_env( $key, $default )
        : ( $_ENV[ $key ] ?? $default );
}

This lets you drop the dependency later without a grep-and-replace across the theme.

Environment-driven config. The natural workflow is: values live in .env, per-environment overrides live in config/environments/{development,staging,production}.php, and the helpers bridge the two. Use them in wp-config.php and in theme setup rather than scattering getenv() calls.

Theme integration. The most common day-to-day use is in functions.php for asset versioning/manifest resolution and environment checks (is this production? then enqueue minified). Keep the calls at the top of setup functions, not inside template files — templates get included per-render and helper calls there are noise.

In WP-CLI and deploy scripts. Helpers that only read config are safe in WP-CLI commands and Composer scripts. Helpers that touch wp_enqueue_* or query the DB are not — test each in wp eval before wiring into a deploy hook.

Gotchas and Tips

• Global function namespace collisions. Any plugin or theme can define the same function name. If you see Cannot redeclare, that's the cause. Guard your own wrappers with function_exists and consider prefixing everything you write around it.
• autoload.files runs everywhere — front-end, admin, cron, WP-CLI. If a helper calls a WordPress function at include time (rather than inside a hook), it will fatal in contexts where WP isn't loaded. Verify by running wp --info after install.
• Hard dependency on wp-cubi constants. Things like WP_ENV or a specific config directory structure are assumed. Outside a wp-cubi project, results range from null to a fatal. Do a smoke test in a scratch install before adopting.
• Pin and review diffs. Zero dependents and a low star count mean nobody else is catching regressions. Use an exact version constraint, and read the diff before bumping — the release cadence (last: 2025-06-09) is not a stability signal.
• Debugging autoload issues. composer dump-autoload -o, then check vendor/composer/autoload_files.php for the package's include path. If it's missing, your type or installer config is wrong, not the package.
• Extension points are limited. A helper collection rarely ships filters. If you need to change behavior, the pragmatic path is to copy the one function you need into your own mu-plugin and drop the dependency — for a package this size that's often cheaper than forking.
• Licensing. GPL-2.0 is fine for WordPress work; if you fork into a private repo, keep the license and attribution intact.