Skip to content

Commit cd56bae

Browse files
petrzpavpetrzpav
committed
Update README file
1 parent cec0366 commit cd56bae

File tree

1 file changed

+99
-38
lines changed

1 file changed

+99
-38
lines changed

‎README.md

Lines changed: 99 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -17,28 +17,40 @@ You can install the package via Composer:
1717
composer require internetguru/laravel-common
1818
```
1919

20-
Create aliases for the package classes in the `config/app.php` file:
20+
## Helper Methods ~ Globals
2121

22-
```php
22+
> The `Helpers` class provides useful methods for Laravel applications.
23+
24+
Configuration and example usage:
25+
26+
1) Add the following lines to the `config/app.php` file:
27+
28+
```php
2329
use Illuminate\Support\Facades\Facade;
2430

2531
'aliases' => Facade::defaultAliases()->merge([
2632
'Helpers' => InternetGuru\LaravelCommon\Support\Helpers::class,
2733
])->toArray(),
28-
```
34+
```
35+
36+
2) Use `Helpers` class methods in your application:
2937

30-
## Usage
38+
```html
39+
<meta name="generator" content="{{ Helpers::getAppInfo() }}"/>
40+
```
3141

32-
### Translation Service Provider
42+
For all available methods, see the [Helpers](src/Support/Helpers.php) class.
3343

34-
> Custom `TranslationServiceProvider` class that adds enhanced logging for missing translations and variables, helping in debugging localization issues.
44+
## Translation Service Provider
45+
46+
> Enhanced logging for missing translations and variables.
3547

3648
- **Missing Translation Logging**: Logs warnings when a translation key is missing.
3749
- **Missing Variables Logging**: Logs warnings when variables required in a translation string are not provided.
38-
- **Debug Mode Checks**: In debug mode, it checks all available locales for missing translations and variables.
50+
- **All Locale Check**: In debug mode, it checks all available locales for missing translations and variables.
3951
- **TranslatorException**: Throws an `InternetGuru\LaravelCommon\Exceptions\TranslatorException` exception instead of logging when the app is not in production mode.
4052

41-
Add the following lines to the `config/app.php` file:
53+
Add the following lines to the `config/app.php` file to use the `TranslationServiceProvider`:
4254

4355
```php
4456
use Illuminate\Support\ServiceProvider;
@@ -48,24 +60,12 @@ Add the following lines to the `config/app.php` file:
4860
])->toArray(),
4961
```
5062

51-
### Helpers
52-
53-
> The `Helpers` class provides useful methods for Laravel applications.
54-
55-
You can use the `Helpers` class methods, such as `getAppInfoArray` and `getAppInfo`, to get information about the application.
56-
57-
```html
58-
<meta name="generator" content="{{ Helpers::getAppInfo() }}"/>
59-
```
60-
61-
For more available methods, please refer to the `Helpers` class.
62-
63-
### Casts
64-
65-
#### Carbon Interval
63+
## Carbon Interval Cast
6664

6765
> Casts a string to a `CarbonInterval` and back.
6866
67+
Example usage:
68+
6969
```php
7070
use Illuminate\Database\Eloquent\Model;
7171
use InternetGuru\LaravelCommon\Casts\CarbonIntervalCast;
@@ -78,31 +78,92 @@ class Task extends Model
7878
}
7979
```
8080

81-
### Blade Components
81+
## Blade Components
8282

83-
#### Breadcrumb
83+
> The package provides a set of Blade components for Laravel applications.
8484
85-
> Blade component that renders breadcrumb navigation.
85+
### Breadcrumb
8686

87-
Key features:
88-
- Breadcrumb items are generated from the current URL path.
89-
- Translation support for each breadcrumb item as `navig.{segment}`.
90-
- Short translation support for each breadcrumb item as `navig.{segment}.short`.
91-
- Divider character can be customized, default `›`.
92-
- Skip first N path segments option `skip-first`, default `0`. E.g. to skip the language.
87+
> The Breadcrumb Blade component renders breadcrumb navigation in your application, helping users understand their location within the app's hierarchy.
9388
94-
Note: The `navig` translation file should be created in the `resources/lang/{lang}` directory.
89+
Key Features:
90+
91+
- **Automatic Path Parsing**: Automatically parses the current URL and generates breadcrumb items based on your routes and translations.
92+
- **Customizable Divider**: Allows customization of the divider symbol between breadcrumb items.
93+
- **Localization Support**: Supports translation of breadcrumb items using Laravel's localization system.
94+
- **Short and Long Labels**: Supports both short and long labels for breadcrumb items.
95+
- **Segment Skipping**: Optionally skip a specified number of URL segments, useful for nested routes or prefixes.
96+
97+
Usage:
9598

9699
```html
97-
<x-ig::breadcrumb divider="|" skip-first="1">
100+
<!-- By default, this will generate breadcrumb items based on the current URL path. -->
101+
<x-ig::breadcrumb/>
102+
<!-- You can change the divider symbol by setting the divider attribute -->
103+
<x-ig::breadcrumb divider="|" />
104+
<!-- If you need to skip certain segments of the URL (e.g., an language prefix), use the skipFirst attribute -->
105+
<x-ig::breadcrumb :skipFirst="1" />
98106
```
99107

100-
#### Form components
108+
Example:
109+
110+
- Assuming you have the following routes defined:
111+
```php
112+
<?php
113+
Route::get('/', function () {
114+
// ...
115+
})->name('home');
116+
117+
Route::get('/products', function () {
118+
// ...
119+
})->name('products.index');
120+
121+
Route::get('/products/{product}', function ($product) {
122+
// ...
123+
})->name('products.show');
124+
```
125+
- And your translation files (resources/lang/en/navig.php) include:
126+
```php
127+
<?php
128+
return [
129+
'home' => 'Long Application Name|LAN',
130+
'products.index' => 'All Products|Products',
131+
'products.show' => 'Product Details',
132+
];
133+
```
134+
- When you visit the `/products/123` URL, the breadcrumb will render as follows:
135+
```
136+
LAN > Products > Product Details
137+
```
138+
- When you visit the `/products` URL, the long label will be used for the `products.index` route:
139+
```
140+
LAN > All Products
141+
```
142+
- When you visit the `/` URL, the long label will be used for the `home` route:
143+
```
144+
Long Application Name
145+
```
146+
147+
### System Messages
148+
149+
> The `messages` Blade component renders system success messages and errros messages.
150+
151+
Include the component in your Blade template where you want the system messages to appear:
152+
153+
```html
154+
<x-ig::system-messages />
155+
```
156+
157+
### Form Inputs
158+
159+
> The package provides a set of Blade components for form inputs.
160+
161+
Notes:
101162

102-
> Blade components that render form elements.
163+
- Google Recaptcha V3 is enabled by default. To disable it, set the `recaptcha` attribute to `false`.
164+
- You need to install the [internetguru/laravel-recaptchav3](https://github.com/internetguru/laravel-recaptchav3) package for the Recaptcha to work.
103165

104-
Recaptcha is enabled by default. To disable it, set the `recaptcha` attribute to `false`.
105-
You need to install the `internetguru/laravel-recaptchav3` package for the Recaptcha to work. See the [documentation](https://github.com/internetguru/laravel-recaptchav3) for more information.
166+
Complete example:
106167

107168
```html
108169
<x-ig::form action="route('test')" :recaptcha="false"/>

0 commit comments

Comments
 (0)