sirius-program/sirius-helpers

This helper contain a lot of functions that can help you to build your apps.

1.1.7 2024-11-24 16:10 UTC

Requires

• php: ^8.2
• giggsey/libphonenumber-for-php: ^8.13
• guzzlehttp/guzzle: ^7.9
• illuminate/contracts: ^10.0||^11.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• pestphp/pest-plugin-laravel: ^2.3

MIT

• Fathul Husnan

• laravel
• SiriusProgram
• sirius-helpers

README

This helper contain a lot of functions that can help you to build your apps.

Installation

You can install the package via composer:

composer require sirius-program/sirius-helpers

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="sirius-helpers-config"

This is the contents of the published config file:

return [
    'country_code' => env('COUNTRY_CODE', 'ID'),
    'currency_locale' => env('CURRENCY_LOCALE', 'id_ID'),
];

Or you can easly change them through .env file.

COUNTRY_CODE=US
CURRENCY_LOCALE=en_US

Usage

// use Sirius class
$sirius = new Sirius();

// or use the helper function
sirius();

More detail can be found below.

Testing

To test this package, you can run the following command:

composer test

or

vendor/bin/pest

Check Current Version

You can check what version of SiriusHelpers you are using right now by run a command:

php artisan about

There is one line like this you can see under the Environment group:

SiriusHelpers Version ................................................................ 1.1.7

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Fathul Husnan

License

The MIT License (MIT). Please see License File for more information.

String Helpers

This helpers contains a lot of functions that can help you to manipulate string.

Usage

You can use it from the Sirius instance:

// use Sirius class
$sirius = new Sirius();
$helper = $sirius->string();

// or use the helper function
sirius()->string();

Or use it straight from the StringHelpers instance:

// use StringHelpers class
$helper = new StringHelpers();

// or use the helper function
sString();

There are 9 methods you can use to manipulate string: encrypt, decrypt, urlSafe, urlUnsafe, isPartOfPhoneNumber, toPhoneNumber, sanitizePhoneNumber, toInitials, and toStr.

encrypt(?string $salt = null)

This method will encrypt the string you give and implements an encryption method that uses AES-256-CBC encryption with a salt and an initialization vector to securely encrypt a string. The encrypted string is base64-encoded. By default this helper will use your APP_KEY for the salt.

echo sirius()->string('text you want to encrypt @ 123')->encrypt(salt: 'sirius');

Code above will echo encrypted text: MwTMh2laUQDG09O9ZsVCv2c8pON/3IlIHf+8Dq55gkg=

decrypt(?string $salt = null)

This method will decrypt the chipertext you give and implements an dencryption method that uses AES-256-CBC encryption algorithm (see encrypt() method above). By default this helper will use your APP_KEY for the salt.

echo sirius()->string('MwTMh2laUQDG09O9ZsVCv2c8pON/3IlIHf+8Dq55gkg=')->decrypt(salt: 'sirius');

Code above will echo the depcrypted text: text you want to encrypt @ 123

urlSafe()

This method will transforms your string into a URL-safe format by replacing specific characters with alternative characters that are less likely to cause issues in URLs.

echo sirius()->string('MwTMh2laUQDG09O9ZsVCv2c8pON/3IlIHf+8Dq55gkg=')->urlSafe();

Code above will echo the URL-safe format text: MwTMh2laUQDG09O9ZsVCv2c8pON_3IlIHf.8Dq55gkg-

urlUnsafe()

This method will transforms your URL-safe string to it's initial text before you transforms it to the URL-safe string (see urlSafe() method above).

echo sirius()->string('MwTMh2laUQDG09O9ZsVCv2c8pON_3IlIHf.8Dq55gkg-')->urlUnsafe();

Code above will echo the URL-safe format text: MwTMh2laUQDG09O9ZsVCv2c8pON/3IlIHf+8Dq55gkg=

isPartOfPhoneNumber(): bool

This method will check is the given string is part of phone number. It will remove plus signs (+), minus signs (-), parentheses, and spaces from the given string and check if the rest of the string is only contain number it will returns true, otherwise false.

print_r(sirius()->string('+62 812-3')->isPartOfPhoneNumber())

Code above will return true

print_r(sirius()->string('+62 812-3aa')->isPartOfPhoneNumber())

Code above will return false

toPhoneNumber(bool $zeroPrefix = false, ?string $countryCode = null)

This method will takes any phone number string, parses it, validates it, and formats it into more readable phone number style format. The default format will use a plus with country calling code prefix based on country code you set on the second parameter, or if it's null it will use the country code on your config in the sirius-helper.country_code. If you want the formatted string prefixed with zero, set the $zeroPrefix parameter to true. This method relying on package libphonenumber under the hood.

echo sirius()->string('[phone]')->toPhoneNumber();

Code above will echo the readable phone number text: [phone]

sanitizePhoneNumber(bool $zeroPrefix = false, ?string $countryCode = null)

This method will takes any phone number string, sanitizes it, so you will get the 'only number' text from the text you provide.

echo sirius()->string('[phone]')->sanitizePhoneNumber(zeroPrefix: true);

Code above will echo the sanitized phone number text: 08123456789

toInitials(int $length = 2)

This method will convert your text into it's initials. The default length will be 2, you can set it to 0 to return all the initials.

echo sirius()->string('Sirius Helpers by Sirius Program')->toInitials();

Code above will echo the initials text: SH

echo sirius()->string('Sirius Helpers by Sirius Program')->toInitials(length: 0);

Code above will echo the initials text: SHBSP

toStr()

This method will convert your text into Laravel's Stringable instance

Method Chaining

Every method above (except for isPartOfPhoneNumber() and toStr()) return $this, so you can also chain the methods like this:

echo sirius()->string('[phone]')
    ->toPhoneNumber() // [phone]
    ->sanitizePhoneNumber(zeroPrefix: true) // 08123456789
    ->encrypt() // OWb2zHt440dxKnH5jLkklg==
    ->urlSafe() // OWb2zHt440dxKnH5jLkklg--
    ->urlUnsafe() // OWb2zHt440dxKnH5jLkklg==
    ->decrypt() // 08123456789
    ->toStr(); // will convert the text into Laravel's Stringable instance

Dumping Everywhere

You can do dump() or dd() in every method above. For example:

echo sirius()->string('any text')
    ->encrypt()
    ->dump()
    ->decrypt()
    ->dd();

Number Helpers

This helpers contains a lot of functions that can help you to manipulate number.

Usage

You can use it from the Sirius instance:

// use Sirius class
$sirius = new Sirius();
$helper = $sirius->number();

// or use the helper function
sirius()->number();

Or use it straight from the NumberHelpers instance:

// use NumberHelpers class
$helper = new NumberHelpers();

// or use the helper function
sNumber();

There are 6 methods you can use to manipulate number: toInt, toFloat, format, toRoman, toCurrency, toCent, fromCent, and spell.

toInt()

This method will convert your number into Integer.

echo sirius()->number(1234.56)->toInt();

Code above will echo 1234

toFloat()

This method will convert your number into Float.

echo sirius()->number('1234.56')->toFloat();

Code above will echo 1234.56

format(?string $currencyLocale = null)

This method will add delimiter to your number based on your provided $currencyLocale or currency locale you set on the config file. The default currency locale will be id_ID if you don't provide any locale or if you don't set it on the config file.

echo sirius()->number(1234567.89)->format();

Code above will echo 1.234.567,89

echo sirius()->number(1234567.89)->format(currencyLocale: 'en_US');

Code above will echo 1,234,567.89

toRoman()

This method will convert your number into roman numerals.

echo sirius()->number(1234)->toRoman();

Code above will echo MCCXXXIV

toCurrency(?string $currencyLocale = null)

This method will convert your number into currency format. The default currency locale will be id_ID if you don't provide any locale or if you don't set it on the config file.

echo sirius()->number(1234567.89)->toCurrency();

Code above will echo Rp1.234.567,89

echo sirius()->number(1234567.89)->toCurrency(currencyLocale: 'en_US');

Code above will echo $1,234,567.89

toCent()

This method will convert your number into cent (times the given number by 100).

echo sirius()->number(1234567.89)->toCent();

Code above will echo 123.456.789

fromCent(bool $impactOriginalNumber = true)

This method will devide the given number by 100. By default, this method's result will also impact the original number, if you want to keep the original number in cent, set the $impactOriginalNumber parameter to false.

echo sirius()->number(123.456.789)->fromCent();

Code above will echo 1234567.89

spell(?string $currencyLocale = null)

This method will spell out your number. The default currency locale will be id_ID if you don't provide any locale or if you don't set it on the config file. Also the language will be spelled out based that same locale.

echo sirius()->number(1234567.89)->spell();

Code above will echo satu juta dua ratus tiga puluh empat ribu lima ratus enam puluh tujuh koma delapan sembilan

echo sirius()->number(1234567.89)->spell(currencyLocale: 'en_US');

Code above will echo one million two hundred thirty-four thousand five hundred sixty-seven point eight nine

If you chained this method after toCurrency() method, the result will be appended with the spelled currency symbol.

echo sirius()->number(1234567.89)->toCurrency(currencyLocale: 'en_US')->spell();

Code above will echo one million two hundred thirty-four thousand five hundred sixty-seven point eight nine dollars

Get the Original Number

You can always retrieve the original number.

echo sirius()->number(10000.05)->toCurrency()->getOriginal();

Code above will echo 10000.05

Method Chaining

Every method above return $this, so you can also chain the methods like this:

echo sirius()->number(10000)
    ->toCurrency() // Rp10.000
    ->spell() // sepuluh ribu rupiah
    ->getOriginal(); // 10000

Dumping Everywhere

You can do dump() or dd() in every method above. For example:

echo sirius()->number(10000.05)
    ->toCurrency()
    ->dump()
    ->spell()
    ->dd();

DateTime Helpers

This helpers contains a lot of functions that can help you to manipulate datetime string.

Usage

You can use it from the Sirius instance:

// use Sirius class
$sirius = new Sirius();
$helper = $sirius->dateTime();

// or use the helper function
sirius()->dateTime();

Or use it straight from the DateTimeHelpers instance:

// use DateTimeHelpers class
$helper = new DateTimeHelpers();

// or use the helper function
sDateTime();

There are 7 methods you can use to manipulate datetime string: toDateTime, toCarbon, format, toLongMonth, toShortMonth, toLongDay, and toShortDay.

toDateTime(string $fromFormat = 'Y-m-d H:i:s')

This method will convert your datetime string into PHP's DateTime object.

toCarbon(string $fromFormat = 'Y-m-d H:i:s')

This method will convert your datetime string into nesbot's Carbon object.

format(string $format = 'Y-m-d H:i:s')

This method will format your datetime string based on the $format parameter. The provided datetime string must be converted into PHP's DateTime object or nesbot's Carbon object first.

toLongMonth()

This method will convert your datetime string into long month string. The provided datetime string can be in integer, datetime string (ex: '2024-01-01'), PHP's DateTime, or nesbot's Carbon object. This method will use the language based on your config in app.locale.

echo sirius()->dateTime(12)->toLongMonth();

Code above will echo December

toShortMonth()

This method will convert your datetime string into short month string. The provided datetime string can be in integer, datetime string (ex: '2024-01-01'), PHP's DateTime, or nesbot's Carbon object. This method will use the language based on your config in app.locale.

echo sirius()->dateTime('2024-01-01')->toShortMonth();

Code above will echo Jan

toLongDay()

This method will convert your datetime string into long day string. The provided datetime string can be in integer, datetime string (ex: '2024-01-01'), PHP's DateTime, or nesbot's Carbon object. This method will use the language based on your config in app.locale.

echo sirius()->dateTime(6)->toLongDay();

Code above will echo Saturday

toShortDay()

This method will convert your datetime string into short day string. The provided datetime string can be in integer, datetime string (ex: '2024-01-01'), PHP's DateTime, or nesbot's Carbon object. This method will use the language based on your config in app.locale.

echo sirius()->dateTime('2024-01-01')->toShortDay();

Code above will echo Mon

Get the Original DateTime String

You can always retrieve the original datetime string.

echo sirius()->dateTime('2024-01-01')->toCarbon('Y-m-d')->getOriginal();

Code above will echo 2024-01-01

Method Chaining

Every method above return $this, so you can also chain the methods like this:

echo sirius()->dateTime('2024-01-01 01:01:01')
    ->toDateTime() // will be converted into PHP's DateTime object
    ->format('Y-m-d') // 2024-01-01
    ->toLongMonth() // January
    ->getOriginal(); // 2024-01-01 01:01:01

Dumping Everywhere

You can do dump() or dd() in every method above. For example:

echo sirius()->dateTime('2024-01-01 01:01:01')
    ->toDateTime()
    ->format('Y-m-d')
    ->dump()
    ->toLongMonth()
    ->dd()

Static Methods

This helpers contains 2 static methods: getAllMonths, and getAllDays. As the name says, these two methods will retrieve all months and days with the language based on your config in app.locale.

These two methods accept 2 arguments: $formatter and $format. The default $formatter will be new \IntlDateFormatter($locale, \IntlDateFormatter::FULL, \IntlDateFormatter::NONE) and the default $format will be MMMM. You can find the other format symbol in ICU Documentation.

$months = DateTimeHelpers::getAllMonths();

The $months variable will be an array of this:

[
    1 => "January",
    2 => "February",
    3 => "March",
    4 => "April",
    5 => "May",
    6 => "June",
    7 => "July",
    8 => "August",
    9 => "September",
    10 => "October",
    11 => "November",
    12 => "December",
]

$days = DateTimeHelpers::getAllDays();

The $days variable will be an array of this:

[
    0 => "Sunday",
    1 => "Monday",
    2 => "Tuesday",
    3 => "Wednesday",
    4 => "Thursday",
    5 => "Friday",
    6 => "Saturday",
]

The getAllDays method also accepts the 3rd argument $startingDay. The default value will be constant START_WITH_SUNDAY. You can set it to constant START_WITH_MONDAY to make it start with Monday.

$days = DateTimeHelpers::getAllDays(startingDay: DateTimeHelpers::START_WITH_MONDAY);

The $days variable will be an array of this:

[
    1 => "Monday",
    2 => "Tuesday",
    3 => "Wednesday",
    4 => "Thursday",
    5 => "Friday",
    6 => "Saturday",
    7 => "Sunday",
]

Other Static Helpers

There are 2 useful static methods that you can access from Sirius instance: calculateDistanceInMeters, and setNullIfBlank.

calculateDistanceInMeters(float $latitudeFrom, float $longitudeFrom, float $latitudeTo, float $longitudeTo, float $earthRadius = 6371000): float

This method will calculate the distance between two points of latitude and logitude in meters. The default $earthRadius will be 6371000 (in meters).

for example:

echo SiriusProgram\SiriusHelpers\Sirius::calculateDistanceInMeters(-7.3197956, 112.765537, -7.3231706, 112.7578611);

Code above will echo 926.0155020636498

setNullIfBlank(mixed $data, bool $keepZero = false, bool $keepEmptyArray = false, bool $keepEmptyString = false): mixed

This method will set null if the given data is either zero, empty array, or empty string. If the given data is in array (and it's not empty), this method will iterate and transform the data inside of it.

for example:

print_r(SiriusProgram\SiriusHelpers\Sirius::setNullIfBlank([0, 1, '', 2, null, 3, []]));

Code above will print [null, 1, null, 2, null, 3, null]

you can keep zero as zero, empty array as empty array and empty string as empty string by setting the $keepZero, $keepEmptyArray, and/or $keepEmptyString parameter to true.

getCountryDetail(string $countryCode): array

This method will hit an HTTP request to restcountries.com to get a various country detail in array, such as name and dailing code.

for example:

print_r(SiriusProgram\SiriusHelpers\Sirius::getCountryDetail('ID'));

Code above will print ['code' => 'ID', 'name' => 'Indonesia', 'dailingCode' => '+62']

This request is cached forever with the name country-detail-$countryCode, so if you find that the data you get from this request is not the same as in restcountries.com, try forget the cache first.