Skip to content

Commit

Permalink
Merge pull request #1 from omaralalwi/enhancements-for-update-or-create
Browse files Browse the repository at this point in the history
enhancments for Update or create
  • Loading branch information
omaralalwi authored Nov 16, 2024
2 parents eb5a51f + 2ba0c94 commit 0084d66
Show file tree
Hide file tree
Showing 10 changed files with 293 additions and 115 deletions.
82 changes: 47 additions & 35 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,18 @@ Its lightweight design and flexibility make it an excellent choice for applicati
- [Installation](#installation)
- [Usage](#usage)
- [Defining LexiTranslatable Models](#defining-lexitranslatable-models)
- [Create Translations](#Create-translations)
- [update or Create Translations](#update-or-Create-translations)
- [Retrieving Translations](#retrieving-translations)
- [Eager Loading Translations](#eager-loading-translations)
- [Cache Handling](#cache-handling)
- [More Examples](#more-examples)
- [Helper Functions](#helper-functions)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Features](#features)
- [Security](#security)
- [License](#license)
- [Helpful Packages](#helpful-open-source-packages)

## Installation

Expand Down Expand Up @@ -76,55 +78,64 @@ class Post extends Model
}
```

### Create Translations
### Update or Create Translations

Easily store translations for your model using the built-in relationship:
You can use `setTranslations` method to create or update bulk translations for a model in a single step:

```php
$post = Post::find(1);

// Store a translation for the title in Arabic
$post->translations()->create([
'locale' => 'ar',
'column' => 'title',
'text' => 'العنوان بالعربية',
// must same following format
$post->setTranslations([
'ar' => [
'name' => 'العنوان باللغة العربية',
'description' => 'الوصف باللغة العربية',
],

'en' => [
'name' => 'English language Title',
'description' => 'description in English language',
],
]);

// Store a translation for the title in English
$post->translations()->create([
'locale' => 'en',
'column' => 'title',
'text' => 'English Title',
]);
```

OR You can use `setTranslation` method to create or update one translation for a model in a single step:

```php
$post->setTranslation('title', 'en', 'English Language Title');
$post->setTranslation('description', 'en', 'English Language description');

$post->setTranslation('title', 'ar', 'عنوان باللغة العربية');
$post->setTranslation('description', 'ar', 'وصف باللغة العربية');
```

**Note** you can add translated `name` and `description` for `Post` model even if `Post` model did not has (`name` and `description`) attributes .

### Retrieving Translations

To retrieve translations, simply use the `translate` method:
**Important Note:** To get better performance , **Do Not Depend on `translations`** relation directly when return translations, because it did not use cache Never.
it did not use cache to keep it return `MorphMany` relation , it Return fresh translations from DB , So you can depend on it to create and update translations .

**To retrieve translations, simply use `transAttr` method :**

By default it return default app local, else you can specify local.

```php
$title = $post->transAttr('title', 'ar');
```
Or
```php
// get title and description in default app local
$title = $post->transAttr('title');
$title = $post->transAttr('description');

// or get title and description in specific local
$titleInArabic = $post->translate('title', 'ar');
$titleInEnglish = $post->translate('title', 'en');
$titleInEnglish = $post->translate('title', 'ar');
```

### Eager Loading Translations
### More Examples

You can eager load the translations relationship when querying your models to reduce the number of queries:
you can find more detail examples in **[Examples File](examples.md)** .

```php
$posts = Post::with('translations')->get();

// Access translations directly after eager loading
foreach ($posts as $post) {
$titleInArabic = $post->translate('title', 'ar');
$titleInEnglish = $post->translate('title', 'en');
}
```
### Helper Functions
you can use `lexi_locales` to get supported locals as array, depend on `supported_locales` in config file.

### Cache Handling

Expand Down Expand Up @@ -155,12 +166,13 @@ If you add additional locales for translations, make sure to include them in the

## Features

- **Dynamic Morph Relationships:** Manage translations across different models with ease, thanks to its dynamic morphable relationships.
- **Dynamic Morph Relationships:** Manage translations across different models with ease, thanks to its dynamic morph able relationships.
- **Automatic Caching:** Enjoy enhanced performance as translations are automatically cached and invalidated, ensuring quick access and updates.
- **Fallback Mechanism:** Never worry about missing translations—Lexi Translate falls back to the default language if a translation is not available.
- **Simple, Intuitive API:** A clean and consistent API for adding, retrieving, and managing translations.
- **Eloquent-Friendly:** Seamlessly integrates with Laravel's Eloquent ORM, making it easy to work with translated data while maintaining the power of Laravel’s query builder.
- **Feature Tests:** supported with Feature Tests .
- **Customize table name:** in config file you can change `table_name` to any name as you want.

## Testing

Expand Down Expand Up @@ -195,7 +207,7 @@ The MIT License (MIT). Please see the [License File](LICENSE.md) for more inform
---


## 📚 Helpful Open Source Packages
## Helpful Open Source Packages

- <a href="https://github.com/omaralalwi/Gpdf"><img src="https://raw.githubusercontent.com/omaralalwi/Gpdf/master/public/images/gpdf-banner-bg.jpg" width="26" height="26" style="border-radius:13px;" alt="laravel Taxify" /> Gpdf </a> Open Source HTML to PDF converter for PHP & Laravel Applications, supports Arabic content out-of-the-box and other languages..

Expand Down
7 changes: 5 additions & 2 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
"homepage": "https://github.com/omaralalwi/lexi-translate",
"license": "MIT",
"type": "library",
"version": "1.0.2",
"version": "1.0.3",
"authors": [
{
"name": "Omar alalwi",
Expand All @@ -62,7 +62,10 @@
"autoload-dev": {
"psr-4": {
"Omaralalwi\\LexiTranslate\\Tests\\": "tests/"
}
},
"files": [
"src/helpers.php"
]
},
"scripts": {
"test": "vendor/bin/phpunit",
Expand Down
84 changes: 84 additions & 0 deletions examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Lexi Translate Examples

### First Example

the following controller handle update or create translations from request

```php
namespace App\Http\Controllers;

use App\Models\Post;

class SetTranslationsController extends Controller
{
public function handle()
{
$service = Post::create([
'name' => 'original name',
'description' => 'original description',
]);

$service->setTranslations([
'en' => [
'name' => 'English Name'
'description' => 'English description'
],
'ar' => [
'name' => 'اسم باللغة العربية'
'description' => 'وصف باللغة العربية'
],
]);

return view('set_translations', compact('service'));
}
}

```

---

### second example from blade file to controller

#### blade file

```php
<form action="{{ route('translations.store', $post->id) }}" method="POST">
@csrf

@foreach (lexi_locales() as $locale)
<h4>{{ strtoupper($locale) }}</h4>

@foreach ($post->getTranslatableFields() as $field)
<div>
<label for="{{ $field }}_{{ $locale }}">{{ ucfirst($field) }} ({{ $locale }}) </label>
<input type="text" name="translations[{{ $locale }}][{{ $field }}]"
value="{{ $post->transAttr($field, $locale) }}" />
</div>
@endforeach
@endforeach

<button type="submit">Save Translations</button>
</form>
```

### in controller
```php
use Illuminate\Http\Request;
use App\Models\Post;

class TranslationsController extends Controller
{
public function store(Request $request, $id)
{
$translations = $request->input('translations');
$post = Post::findOrFail($id);
$post->setTranslations($translations);

return redirect()->back()->with('success', 'Translations updated successfully!');
}
}

```

**Validations will coming Soon** .

Loading

0 comments on commit 0084d66

Please sign in to comment.