Helper Utilities

Helper packages are foundational utilities with minimal dependencies, used across all other packages.

array-helpers

Array manipulation utilities extending Laravel’s Illuminate\Support\Arr.

Key Features

• Deep array operations (flatten/unflatten, recursive merge)
• Arithmetic operations on arrays (sum, accumulate, normalize)
• Precision-aware comparisons with epsilon tolerance
• Matrix transposition and column extraction

Public API

use RightCapital\ArrayHelpers\Arr;

// Expand dotted keys to nested array
Arr::undot(['a.b.c' => 1]); // ['a' => ['b' => ['c' => 1]]]

// Cumulative sums
Arr::accumulate([1, 2, 3]); // [1, 3, 6]

// Array arithmetic
Arr::arithmeticAdd([1, 2], [3, 4]); // [4, 6]

// Deep equality with tolerance
Arr::isEqual([1.0001], [1.0002], 0.001); // true

// Round with sum preservation
Arr::round([33.33, 33.33, 33.34], 0); // [33, 33, 34]

Dependencies

• numeric-helpers, string-helpers
• illuminate/collections

---

string-helpers

String manipulation utilities extending Laravel’s Illuminate\Support\Str.

Key Features

• English grammar helpers (possessive, ordinal, indefinite articles)
• Phone number parsing and formatting
• US state code lookups
• Rich text truncation with HTML handling

Public API

use RightCapital\StringHelpers\Str;

Str::possessive('James');        // "James'"
Str::ordinal(3);                 // "3rd"
Str::indefiniteArticle('apple'); // "an"
Str::formatPhone('1234567890');  // "(123) 456-7890"

Str::getStatePostalCodeFromName('California'); // "CA"
Str::joinWordsWithConjunction(['a', 'b', 'c'], 'and'); // "a, b, and c"

Helper Functions

strpos_or_fail($haystack, $needle);  // Throws on not found
get_string_value_of($enum);          // Convert enum to string
class_namespace($class);              // Extract namespace

---

numeric-helpers

Numeric operations with precision handling and floating-point tolerance.

Key Features

• Safe increment (null-aware)
• Epsilon-based comparisons
• Scientific notation conversion
• Safe division with zero protection

Public API

use RightCapital\NumericHelpers\Num;

Num::increment($value, 10);     // Safe null-aware increment
Num::clamp(150, 0, 100);        // 100
Num::isZero(0.0000001);         // false (EPSILON = 1e-8)
Num::isNumericallyEqual(1.0, 1.0000000001); // true

Num::convertScientificNotationToDecimalForm('1E-5'); // "0.00001"
Num::safeDivision(10, 0, fallback: 0); // 0

---

file-helpers

File and directory operations with safe error handling.

Key Features

• Recursive directory operations
• Stream-based file processing
• RAII pattern for resource management
• Non-empty line generators

Public API

// Directory operations
mkdir_force('/path/dir', 0o775);
copy_recursive('/src', '/dest');
rmdir_recursive('/dir');

// Stream utilities
use_tmp_file(function($handle, $path) {
    fwrite($handle, $data);
    // Auto-closes after callback
});

// Line reading generator
foreach (read_none_empty_lines($file) as $lineNum => $line) {
    // Process non-empty lines
}

// Safe stream close
ensure_fclose($stream);

---

html-helper

HTML validation and sanitization with security focus.

Key Features

• Tag whitelist validation
• Attribute sanitization (href, style)
• Empty tag removal
• Comment stripping
• Graceful fallback on parse errors

Public API

use RightCapital\HtmlHelper\HtmlHelper;

$allowedTags = ['p', 'br', 'strong', 'em', 'a'];

// Validate HTML
if (HtmlHelper::validate($html, $allowedTags)) {
    // HTML only contains allowed tags
}

// Sanitize HTML
$safe = HtmlHelper::sanitize($html, $allowedTags);
// - Removes disallowed tags/attributes
// - Adds rel="noreferrer" target="_blank" to links
// - Removes empty tags recursively
// - Strips HTML comments

Preserved Attributes

Tag	Attributes
<a>	href (must start with “http”)
<span>	style (color only)
<mark>	style (background-color, color:inherit)
<ol>	start

---

billing-helpers

Billing domain operations for Stripe integration and subscription management.

Key Features

• Billing plan enum with metadata
• Stripe invoice operations
• Coupon/discount handling
• Plan conflict detection

Public API

use RightCapital\BillingHelpers\BillingPlan;
use RightCapital\BillingHelpers\BillingInvoice;
use RightCapital\BillingHelpers\StripeUtils;

// BillingPlan enum
$plan = BillingPlan::PREMIUM;
$plan->displayName();      // "Premium"
$plan->isCorePlan();       // true
$plan->applicableTo();     // "advisor"

BillingPlan::isPlanConflicted([BillingPlan::BASIC, BillingPlan::PREMIUM]); // true

// Stripe utilities
StripeUtils::convertCouponCodeToDiscountDatas('XYPN2025');
StripeUtils::extractSubscriptionCurrentPeriodEndDate($subscription);

---

method-delegate

Method interception using PHP 8 attributes for aspect-oriented programming.

Key Features

• Attribute-based method decoration
• Composable delegate chains
• Precompilation for zero overhead
• Method/class context access

Public API

use RightCapital\MethodDelegate\Delegate;
use RightCapital\MethodDelegate\DelegateInterface;

// Define a delegate
#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
final class LoggingDelegate extends Delegate {
    public function __invoke(mixed ...$args): mixed {
        echo "Before {$this->method_name}\n";
        $result = ($this->next)(...$args);
        echo "After {$this->method_name}\n";
        return $result;
    }
}

// Apply to methods
class UserService {
    #[LoggingDelegate]
    public function getUser(int $id): User {
        return User::find($id);
    }
}

DelegateInterface

interface DelegateInterface {
    public function compose(
        callable $next,
        string $method_name,
        object|string|null $bind
    ): callable;
}

Precompilation

# In composer.json scripts
"post-autoload-dump": [
    "RightCapital\\MethodDelegate\\PrecompileCommand::run"
]

---

Summary

Package	Type	Main Export	Dependencies
array-helpers	Static class	Arr	numeric-helpers, string-helpers
string-helpers	Static class	Str, helpers	illuminate/support
numeric-helpers	Static class	Num	None
file-helpers	Functions	helpers.php	thecodingmachine/safe
html-helper	Static class	HtmlHelper	ext-dom, laravel-sentry
billing-helpers	Enum + classes	BillingPlan	laravel-stripe
method-delegate	Framework	Delegate	nikic/php-parser