internetguru/laravel-common

There is no license information available for the latest version (v0.6.3) of this package.

v0.6.3 2025-03-14 13:04 UTC

README

This package provides handy utilities for Laravel applications.

Branch Status Code Coverage
Main tests coverage
Staging tests coverage
Dev tests coverage

Installation

You can install the package via Composer:

composer require internetguru/laravel-common

Run Tests Locally

In Visual Studio Code you can simpy use Ctrl+Shift+B to run the tests.

To run the tests manually, you can use the following commands:

# Build the Docker image
docker build -t laravel-common .
# Run the tests
docker run --rm laravel-common
# Both steps combined
docker build -t laravel-common . && docker run --rm laravel-common

Helper Methods ~ Globals

The Helpers class provides useful methods for Laravel applications.

Configuration and example usage:

  1. Add the following lines to the config/app.php file:

    use Illuminate\Support\Facades\Facade;
    
    'aliases' => Facade::defaultAliases()->merge([
        'Helpers' => InternetGuru\LaravelCommon\Support\Helpers::class,
    ])->toArray(),
  2. Use Helpers class methods in your application:

    <meta name="generator" content="{{ Helpers::getAppInfo() }}"/>

For all available methods, see the Helpers class.

Helper Macros

Package registers a set of useful macros for Carbon and Numbers. See the macros.php file for the complete list.

Example usage:

use Carbon\Carbon;
use Illuminate\Support\Facades\Number;

Number::useCurrency('USD'); // Set the default currency
echo Number::currencyForHumans(1234);
// Output (en_US locale): $1,234
echo Number::currencyForHumans();
// Output (en_US locale): $
echo Number::currencyForHumans(1234.567, in: 'EUR', precision: 2);
// Output (en_US locale): €1,234.57
app()->setLocale('cs_CZ'); // Set the locale to Czech
echo Number::currencyForHumans(1234.567, in: 'EUR', precision: 2);
// Output (cs_CZ locale): 1 234,57 €

$date = Carbon::parse('2023-12-31');
echo $date->dateForHumans();
// Output (en_US locale): 12/31/2023
$dateTime = Carbon::parse('2023-12-31 18:30:00');
echo $dateTime->dateTimeForHumans();
// Output (en_US locale): 12/31/2023 6:30 PM

CheckPostItemNames Middleware

Middleware that checks for invalid POST parameter names containing dots ".". This middleware helps prevent issues with Laravel's input handling. Throws an exception in non-production environments and logs a warning in production.

To use the middleware for the web group, add the following lines to the bootstrap/app.php file:

$middleware->group('web', [
      // ...
      \InternetGuru\LaravelCommon\Middleware\CheckPostItemNames::class,
 ]);

Alternatively, you can assign the middleware to specific routes or controllers as needed.

Example:

  • When a POST request contains parameter names with dots:

    POST /submit-form
    Content-Type: application/x-www-form-urlencoded
    
    username=johndoe&user.email=johndoe@example.com
  • In Non-Production Environments: The middleware will throw an exception with the message:

    Invalid POST parameter names containing dots: user.email
    
  • In Production Environment: The middleware will log a warning:

    [WARNING] Invalid POST parameter names containing dots: user.email
    

Translation Service Provider

Logs missing translations and translation variables in the current language. Throws an exception when not in production environment. In debug mode, checks all available languages.

  • Logs warning when a translation key is missing or a variable required in a translation string is not provided.
  • Checks all languages in debug mode from all available locales.
  • Throws exception InternetGuru\LaravelCommon\Exceptions\TranslatorException instead of logging when the app is not in production mode.

To use the provider, add the following lines to the config/app.php file:

use Illuminate\Support\ServiceProvider;

'providers' => ServiceProvider::defaultProviders()->replace([
    Illuminate\Translation\TranslationServiceProvider::class => InternetGuru\LaravelCommon\TranslationServiceProvider::class,
])->toArray(),

Carbon Interval Cast

Casts a string to a CarbonInterval and back.

Example usage:

use Illuminate\Database\Eloquent\Model;
use InternetGuru\LaravelCommon\Casts\CarbonIntervalCast;

class Task extends Model
{
    protected $casts = [
        'duration' => CarbonIntervalCast::class,
    ];
}

Breadcrumb Blade Component

Renders breadcrumb navigation based on routes matching the current URL segments. Supports translations with short and long labels, custom divider, and segment skipping.

Key Features:

  • Customizable Divider – Allows a custom divider symbol between breadcrumb items.
  • Short and Long Labels – Using trans_choice if available shows n-th right translation based on the item positon.
  • Segment Skipping – Skips a specified number of URL segments. Useful for nested routes or routes with prefixes (e.g. language).

Usage:

<!-- By default, this will generate breadcrumb items based on the current URL path. -->
<x-ig::breadcrumb/>
<!-- You can change the divider symbol by setting the divider attribute -->
<x-ig::breadcrumb divider="|" />
<!-- If you need to skip certain segments of the URL (e.g., a language prefix), use the skipFirst attribute -->
<x-ig::breadcrumb :skipFirst="1" />

Example:

  • Assuming you have the following routes defined:
    <?php
    Route::get('/', function () {
        // ...
    })->name('home');
    
    Route::get('/products', function () {
        // ...
    })->name('products.index');
    
    Route::get('/products/{product}', function ($product) {
        // ...
    })->name('products.show');
  • And your translation files (resources/lang/en/navig.php) include:
    <?php
    return [
        'home' => 'Long Application Name|LAN',
        'products.index' => 'All Products|Products',
        'products.show' => 'Product Details',
    ];
  • When you visit the /products/123 URL, the short translation will be used for the home and products.index routes.
    LAN > Products > Product Details
    
  • When you visit the /products URL, the short label will be used for the home route.
    LAN > All Products
    
  • When you visit the / URL, the long label will be used for the home route.
    Long Application Name
    

System Messages Blade Component

Renders system temporary success messages and persistent error messages in different colors, with a close button.

Include the component in your Blade template where you want the system messages to appear:

<x-ig::system-messages />

Form Blade Components

The package provides a set of Blade components for form and various inputs.

Notes:

Complete example:

<x-ig::form action="route('test')" :recaptcha="false"/>
    <x-ig::input type="text" name="name" required>Name</x-ig::input>
    <x-ig::input type="option" name="simple-options" :value="['a', 'b', 'c']">Simple Options</x-ig::input>
    <x-ig::input type="option" name="advanced-options" :value="[
        ['id' => '1', 'value' => 'User 1' ],
        ['id' => '2', 'value' => 'User 2' ],
        ['id' => '3', 'value' => 'User 3' ],
    ]">Advanced Options</x-ig::input>
    <x-ig::input type="checkbox" name="checkbox" value="1">Checkbox</x-ig::input>
    <x-ig::input type="radio" name="radio" value="1">Radio</x-ig::input>
    <x-ig::input type="textarea" name="description">Description</x-ig::input>
    <x-ig::submit>Submit Form</x-ig::submit>
</x-ig::form>

Language Switch Blade Component

Renders a language switcher as a list of links with the current language highlighted.

Include the component in your Blade template where you want the language switcher to appear:

<x-ig::lang-switch />

License

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