Laravel Helperia Laravel Package

Getting Started

• Install with composer require kanekescom/laravel-helperia. The service provider is auto-discovered on Laravel 9+, so no manual registration is normally required.
• Look here first: vendor/kanekescom/laravel-helperia/src/ — specifically the helpers file (typically helpers.php) and any HelperiaServiceProvider. Global helper functions are not discoverable via IDE autocomplete or php artisan list, so the source is the authoritative API reference. Read it once end-to-end; it is small.
• Check for publishable config/assets with php artisan vendor:publish --provider="KanekesCom\Helperia\HelperiaServiceProvider" (adjust the namespace to match the provider you find in composer.json's extra.laravel.providers).
• First use case: Indonesian number-to-words (terbilang) on an invoice or receipt, paired with Rupiah formatting. This is the highest-value, lowest-risk entry point — it is pure string transformation with no database or config dependency:

// e.g. on an invoice model
$total = 1250000;
$terbilang = terbilang($total);          // "satu juta dua ratus lima puluh ribu"
$formatted = 'Rp ' . number_format($total, 0, ',', '.');

Verify the exact function names and signatures from source before committing; this package has shipped naming adjustments across minor versions.

• Baseline the package with a single test asserting your expected output for a handful of representative values (zero, one, thousands, millions, negative, decimal). This becomes your regression guard against the frequent small patch releases.

Implementation Patterns

• Wrap, don't sprinkle. Global helpers are convenient but create untested coupling across views, controllers, and jobs. Introduce a thin application-level service (e.g. App\Support\IndonesianFormatter) that delegates to the helpers. You then have one place to swap implementations, add caching, or shim a signature change after an upgrade.

final class IndonesianFormatter
{
    public function currency(int|float $amount): string
    {
        return 'Rp ' . number_format($amount, 0, ',', '.');
    }

    public function spell(int|float $amount): string
    {
        return terbilang($amount);
    }

    public function date(CarbonInterface $date): string
    {
        return $date->locale('id')->translatedFormat('d F Y');
    }
}

• Locale discipline. Helpers that emit Indonesian month names, day names, or currency symbols do not consult app()->getLocale() in most implementations. If your app is multilingual, gate usage behind an explicit if (app()->getLocale() === 'id') branch rather than assuming the helper is locale-aware. Otherwise an English-locale PDF will silently render "Rp" and "Januari".

• Blade usage for read-only output. These are pure formatting functions, which makes them safe in Blade and in queued jobs alike. Prefer formatting at render time over persisting formatted strings — you keep the raw numeric/date columns queryable and can restyle later.

• PDF and export pipelines. The strongest day-to-day fit is invoice, receipt, and report generation via DomPDF/Snappy/Browsershot. Format once in a view-model or DTO and pass the resulting strings into the template, so the PDF layer never calls global functions directly and stays testable.

• Validation rule integration. If the package exposes Indonesian-specific validators (NIK, NPWP, phone numbers), register them as custom rules wrapping the helper. That gives you Rule::nik() with a translatable failure message instead of raw boolean checks in controllers.

• Seeders and factories. For demo data, Indonesian-locale names, addresses, and region codes are far more convincing than fake()->name(). Use any region/wilayah dataset the package ships in seeders; if it is a separate publishable asset, publish it to database/ and seed a lookup table.

Gotchas and Tips

• Global namespace pollution. Helper packages register functions in the root namespace. A collision with an app-defined terbilang() or rupiah() produces a fatal redeclare error that is easy to misdiagnose. Run grep -rn "function terbilang" app/ before installing, and remember Composer's autoload order determines which wins when no error is thrown.
• No IDE support. Global functions don't participate in autocomplete or static analysis. Add a _ide_helper.php stub or a @method docblock, and exclude the vendor helpers from PHPStan/Psalm analysis or you will get undefined-function errors in CI.
• Version pinning matters more than usual. The v2.1.x line moves in small increments and v2.1.16 is a documentation-only chore commit — evidence that releases are frequent and often non-functional. Pin to a caret range (^2.1) but read the changelog on each bump; do not auto-merge patch updates in production without your baseline test passing.
• Floating-point input. Number-to-words helpers typically cast to int. Passing 1250000.75 may truncate silently or produce odd output. Normalise with (int) round($value) at the call site and handle the sen/cents portion yourself if you need it.
• Negative and zero values. Confirm behaviour for 0, -5000, and very large numbers (>1 triliun) explicitly — these are the classic off-by-one failures in terbilang implementations and are rarely covered by the package's own tests.
• Debugging strategy. When a helper returns unexpected output, first check whether the file was autoloaded: php -r "var_dump(function_exists('terbilang'));" inside the project root. If false, run composer dump-autoload — helper files are loaded via files autoload, which is not refreshed by composer install alone in some stale-vendor cases.
• Extension points. Prefer subclassing or wrapping over editing vendor files. If the package exposes a config file, publish it rather than relying on undocumented defaults; published config is the intended contract and survives composer update.
• Contribution path. With PRs like #45 being docs-only, the maintainer is responsive but the package is effectively single-maintainer. Treat it as a convenience dependency, not load-bearing infrastructure — anything you cannot afford to lose should sit behind your own wrapper class so a removal is a one-file change.