README

The Homeful\Common package is a utility package that contains reusable helpers, constants, enumerations, and abstract types used across the Homeful system. It aims to promote consistency and reduce duplication of logic in other domain-specific packages such as Mortgage, Payment, Property, and Borrower.

📦 Contents

Utilities
Classes
Enumerations

🧰 Utilities

`documents_path(?string $path = null): string`

Returns the path to the /resources/documents directory.

documents_path(); // /resources/documents
documents_path('legal/contract.pdf'); // /resources/documents/legal/contract.pdf

`formatted_age(DateTime $born, ?DateTime $reference = null): string`

Returns a human-readable age string based on birthdate.

formatted_age(new DateTime('1990-05-23')); // "33 years, 10 months and 3 days old"

`doc_stamps(mixed $value): float`

Returns the documentary stamp fee based on property value.

doc_stamps(450000); // 50.0

`filter_trim_recursive_array(array $array): array`

Trims strings and filters empty values recursively in nested arrays.

`dot_shift(&$dot_notation): string`

Shifts off the first key in a dot notation string.

$key = dot_shift($dot = "property.name"); // $key = "property", $dot = "name"

`titleCase(?string $text, array $exclusions = []): string`

Applies Str::title() but preserves Roman numerals and exceptions.

titleCase('juan dela cruz ii'); // Juan Dela Cruz II

`validateJson(string $json): bool`

Returns true if a valid JSON string.

`resolveOptionalCollection(DataCollection|Optional|null $collection): Collection`

Handles resolution of Spatie DataCollection and Optional.

`array_when(array $array, $condition, callable $callback): array`

Conditionally apply a transformation on an array.

array_when([1,2,3], false, fn($arr) => array_map(fn($x) => $x * 2, $arr)); // [1,2,3]

`convertNumberToWords(float $value): string`

Converts a float value to words.

convertNumberToWords(1500.75); // ONE THOUSAND FIVE HUNDRED AND 75/100

📚 Core Classes

`Homeful\Common\Classes\Input`

A collection of constants used for data keys in form input and parameter arrays. Examples include:

Input::TCP - Total Contract Price
Input::PERCENT_DP - Percent Down Payment
Input::BP_TERM - Balance Payment Term

Usage:

$params = [
    Input::TCP => 2500000,
    Input::PERCENT_DP => 0.05,
];

`Homeful\Common\Classes\Assert`

A collection of constants used to assert derived or calculated values in computations:

Assert::LOAN_AMOUNT
Assert::INCOME_REQUIREMENT
Assert::LOAN_AMORTIZATION

Used commonly in unit tests:

expect($mortgage->getLoan()->getPrincipal()->inclusive()->compareTo($params[Assert::LOAN_AMOUNT]))->toBe(Amount::EQUAL);

🧮 AmountCollectionItem

Base class representing any item with:

a name
a Price value
deductible flag
a tag

Used as a base for:

AddOnFeeToPayment
DeductibleFeeFromPayment

📈 Enumerations

`UploadFile`

Maps file-related attributes to suffixes for Media Library collections.

UploadFile::Image->suffix(); // 'images'
UploadFile::deriveCollectionNameFromAttribute('propertyImage'); // 'property-images'

`WorkArea`

Represents whether a user operates in a Highly Urbanized City or Region.

WorkArea::fromRegional(true); // WorkArea::REGION
WorkArea::default(); // WorkArea::HUC

✅ Example Usage

use Homeful\Common\Classes\Input;
use Homeful\Common\Classes\Assert;

$params = [
    Input::TCP => 2500000,
    Input::PERCENT_DP => 0.05,
    Assert::LOAN_AMOUNT => 2375000.0,
];

expect($params[Assert::LOAN_AMOUNT])->toBe(2375000.0);

📂 Path Resolution

documents_path('mortgage/terms.pdf'); 
// => /resources/documents/mortgage/terms.pdf

🧪 Testing Helpers

Used extensively in test scripts to:

Assert expected results via Assert
Pass parameters using Input
Use formatted_age, doc_stamps, etc.

Behold, a new you awaits. ✨

jn-devops / common

Maintainers

Details