README

This package provides handy utilities for Laravel applications.

Branch	Status	Code Coverage
Main
Staging
Dev

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:

• The Google Recaptcha V3 service is enabled by default. To disable it, set the recaptcha attribute to false.

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.