[ADD] scopeLang() and scopeWithTVs(). Deprecated scopeLangAndTvs().

Author: Seiger

README.md

@@ -33,6 +33,13 @@ Evolution CMS-powered websites.
 
 ![Multilingual tabs](https://github.com/Seiger/slang/releases/download/v1.0.0/sLang.png)
 
+### Requirements
+
+- Evolution CMS **3.3+**
+- PHP **8.3+**
+- Composer **2.2+**
+- One of: **MySQL 8.0+** / **MariaDB 10.5+** / **PostgreSQL 10+** / **SQLite 3.25+**
+
 ## Install by artisan package installer
 
 Go to You /core/ folder:
@@ -99,4 +106,36 @@ Implementing a Language Switcher
 @endforeach
 ```
 
+## Working with localized content (Eloquent)
+
+The `Seiger\sLang\Models\sLangContent` model now applies the current locale automatically.
+
+- Fetch translated rows for the active locale:
+  ```php
+  use Seiger\sLang\Models\sLangContent;
+
+  $items = sLangContent::active()->get(); // locale resolved via evo()->getLocale()
+  ```
+- Select a specific locale explicitly:
+  ```php
+  $items = sLangContent::lang('en')->get();
+  ```
+- Include template variables while keeping the locale filtering:
+  ```php
+  $items = sLangContent::withTVs(['color', 'price'])->get();
+  ```
+- Combine multiple helpers:
+  ```php
+  $items = sLangContent::lang('uk')
+      ->withTVs(['color', 'price'])
+      ->whereParent($parentId)
+      ->active()
+      ->get();
+  ```
+- Legacy helper is preserved for backward compatibility:
+  ```php
+  $items = sLangContent::langAndTvs('en', ['color', 'price'])->get();
+  ```
+  > **Deprecated:** `langAndTvs()` is deprecated since `1.0.8` and is scheduled for removal in `v1.2`. Use `lang()->withTVs()` instead.
+
 [See full documentation here](https://seiger.github.io/sLang/)

composer.json

@@ -17,7 +17,8 @@
     }
   ],
   "require": {
-    "php": "^8.3"
+    "php": "^8.3",
+    "evolutioncms/evolution": "^3.3"
   },
   "autoload": {
     "psr-4": {

docs/pages/getting-started.md

@@ -5,15 +5,12 @@ description: Getting started with sLang
 permalink: /getting-started/
 ---
 
-## Minimum requirements
+### Requirements
 
-- Evolution CMS 3.2.0
-- PHP 8.1.0
-- Composer 2.2.0
-- PostgreSQL 10.23.0
-- MySQL 8.0.3
-- MariaDB 10.5.2
-- SQLite 3.25.0
+- Evolution CMS **3.3+**
+- PHP **8.3+**
+- Composer **2.2+**
+- One of: **MySQL 8.0+** / **MariaDB 10.5+** / **PostgreSQL 10+** / **SQLite 3.25+**
 
 ## Install by artisan package installer
 
@@ -41,7 +38,7 @@ php artisan migrate
 
 ## Management
 
-After installing the module, you can use it immediately. Path to the module in the 
+After installing the module, you can use it immediately. Path to the module in the
 administrator panel **Admin Panel -> Modules -> Multilingual**.
 
 The resource includes tabs for each language separately.
@@ -52,7 +49,7 @@ The resource includes tabs for each language separately.
 
 ## Extra
 
-If you write your own code that can integrate with the sLang module, 
+If you write your own code that can integrate with the sLang module,
 you can check the presence of this module in the system through a configuration variable.
 
 ```php
@@ -61,5 +58,18 @@ if (evo()->getConfig('check_sLang', false)) {
 }
 ```
 
-If the plugin is installed, the result of ```evo()->getConfig('check_sLang', false)``` 
+If the plugin is installed, the result of ```evo()->getConfig('check_sLang', false)```
 will always be ```true```. Otherwise, you will get an ```false```.
+
+### Working with localized content
+
+Use the `sLangContent` model to fetch translated resources:
+
+```php
+use Seiger\sLang\Models\sLangContent;
+
+$items = sLangContent::active()->get(); // locale resolved automatically
+$itemsEn = sLangContent::lang('en')->withTVs(['preview'])->get();
+```
+
+> **Deprecated:** The `langAndTvs()` scope is deprecated since `1.0.8` and will be removed in `v1.2`. Replace it with `lang()` and `withTVs()`.

docs/pages/index.md

@@ -19,8 +19,8 @@ permalink: /
 admin panel. This dynamic package empowers users to seamlessly implement and manage
 multilingual tools within the Evolution CMS environment. By utilizing Evolution CMS
 as its platform, sLang offers a streamlined solution for users seeking efficient and
-intuitive ways to handle diverse language content, making it an indispensable asset 
-for administrators and developers navigating the intricacies of multilingual website 
+intuitive ways to handle diverse language content, making it an indispensable asset
+for administrators and developers navigating the intricacies of multilingual website
 management.
 
 The work of the module is based on the use of the standard Laravel functionality for
@@ -40,11 +40,18 @@ Evolution CMS-powered websites.
 - [x] Unlimited Translation Language Support.
 - [x] Multilingual SEO Support.
 
-## Minimum requirements
+## Locale-aware content model
 
-- Evolution CMS >= 3.2.0
-- PHP >= 8.1.0
-- Composer >= 2.2.0
+- `Seiger\sLang\Models\sLangContent` now respects the current locale by default (via `evo()->getLocale()`).
+- Explicit locale selection is available through the `lang()` scope, and template variables can be appended with `withTVs()`.
+- `langAndTvs()` remains for backward compatibility but is **deprecated since `1.0.8`** and scheduled for removal in **`v1.2`**.
+
+### Requirements
+
+- Evolution CMS **3.3+**
+- PHP **8.3+**
+- Composer **2.2+**
+- One of: **MySQL 8.0+** / **MariaDB 10.5+** / **PostgreSQL 10+** / **SQLite 3.25+**
 
 ## Support
 

docs/pages/use-in-blade.md

@@ -85,14 +85,14 @@ use Seiger\sLang\Models\sLangContent;
 
 public function globalElements()
 {
-    $this->data['mainMenu'] = sLangContent::langAndTvs(evo()->getConfig('lang', 'uk'))
+    $this->data['mainMenu'] = sLangContent::withTVs(['menu_main'])
         ->whereTv('menu_main', 1)
         ->where('hidemenu', 0)
         ->orderBy('menuindex')
         ->active()
         ->get();
 
-    $this->data['footerMenu'] = sLangContent::langAndTvs(evo()->getConfig('lang', 'uk'))
+    $this->data['footerMenu'] = sLangContent::withTVs(['menu_footer'])
         ->whereTv('menu_footer', 1)
         ->where('hidemenu', 0)
         ->orderBy('menuindex')
@@ -122,23 +122,25 @@ Output in the Blade template
 
 ## TV variables
 
-The ```langAndTvs()``` method makes it quite easy to get TV parameters associated with a resource. For example, the **tv_image** parameter.
+The `withTVs()` scope makes it easy to retrieve TV parameters associated with a resource. For example, the **tv_image** parameter.
 
 Get in the controller.
 ```php
-$resource = sLangContent::langAndTvs(evo()->getConfig('lang'), ['tv_image'])->active()->first();
+$resource = sLangContent::withTVs(['tv_image'])->active()->first();
 ```
 
 Display in the template.
 ```php
 {% raw %}{{$resource->tv_image}}{% endraw %}
 ```
 
-The ```whereTv()``` method allows you to use a filter based on the value of the TV parameter if necessary.
+The `whereTv()` method allows you to use a filter based on the value of the TV parameter if necessary.
 ```php
-$resource = sLangContent::langAndTvs(evo()->getConfig('lang'), ['tv_image'])->whereTv('tv_image', '!=', '')->get();
+$resource = sLangContent::withTVs(['tv_image'])->whereTv('tv_image', '!=', '')->get();
 ```
 
+> **Deprecated:** The `langAndTvs()` helper is deprecated since `1.0.8` and will be removed in `v1.2`. Replace it with the `lang()` and `withTVs()` scopes.
+
 ## Resource fields in Admin panel
 
 You can control the display of resource fields on general tabs through an event ```sLangDocFormFieldRender```.

src/Models/sLangContent.php

@@ -11,26 +11,40 @@ class sLangContent extends Eloquent\Model
     protected $fillable = ['resource', 'lang', 'pagetitle', 'longtitle', 'description', 'introtext', 'content', 'menutitle', 'seotitle', 'seodescription'];
 
     /**
-     * Add the language and template variable fields to the query
+     * Add the language and template variable fields to the query.
      *
      * @param Builder $query The query builder instance
      * @param string $locale The language locale
      * @param array $tvNames The array of template variable names
      * @return Builder The modified query builder instance
+     *
+     * @deprecated since 1.0.8
+     * TODO: REMOVE IN v1.2
      */
     public function scopeLangAndTvs($query, $locale, $tvNames = [])
     {
-        $query->select('*', 's_lang_content.resource as id', 's_lang_content.pagetitle as pagetitle');
-        $query->addSelect('s_lang_content.longtitle as longtitle', 's_lang_content.description as description');
-        $query->addSelect('s_lang_content.introtext as introtext', 's_lang_content.content as content');
-        $query->addSelect('s_lang_content.menutitle as menutitle');
-        $query->selectTvs($tvNames);
-
-        return $query->addSelect('site_content.pagetitle as pagetitle_orig', 'site_content.longtitle as longtitle_orig')
-            ->addSelect('site_content.description as description_orig', 'site_content.introtext as introtext_orig')
-            ->addSelect('site_content.content as content_orig', 'site_content.menutitle as menutitle_orig')
-            ->leftJoin('site_content', 's_lang_content.resource', '=', 'site_content.id')
-            ->where('lang', '=', $locale);
+        $query = $this->scopeLang($query, $locale);
+        return $query->withTVs($tvNames);
+    }
+
+    /**
+     * Limit the query to a specific language. Falls back to evo()->getLocale() when locale is not provided.
+     */
+    public function scopeLang($query, ?string $locale = null)
+    {
+        $query = $query->withoutGlobalScope('language');
+        $locale = static::resolveLocale($locale);
+        $this->applyContentSelects($query);
+        return $query->where('lang', '=', $locale);
+    }
+
+    /**
+     * Append template variable fields while preserving base selects.
+     */
+    public function scopeWithTVs($query, array $tvNames = [])
+    {
+        $this->applyContentSelects($query);
+        return $this->scopeSelectTvs($query, $tvNames);
     }
 
     /**
@@ -143,8 +157,94 @@ public function getFullLinkAttribute()
     {
         $base_url = UrlProcessor::makeUrl($this->resource);
         if (str_starts_with($base_url, '/')) {
-            $base_url = MODX_SITE_URL . ltrim($base_url, '/');
+            $base_url = EVO_SITE_URL . ltrim($base_url, '/');
         }
         return $base_url;
     }
+
+    /**
+     * Applies base selects and joins required for language-aware scopes.
+     */
+    protected function applyContentSelects(Builder $query): Builder
+    {
+        $eloquentQuery = $query->getQuery();
+
+        if (empty($eloquentQuery->columns)) {
+            $query->select('s_lang_content.*');
+        }
+
+        $query->addSelect(
+            's_lang_content.resource as id',
+            's_lang_content.pagetitle as pagetitle',
+            's_lang_content.longtitle as longtitle',
+            's_lang_content.description as description',
+            's_lang_content.introtext as introtext',
+            's_lang_content.content as content',
+            's_lang_content.menutitle as menutitle'
+        );
+
+        if (!$this->hasSiteContentJoin($eloquentQuery->joins ?? [])) {
+            $query->leftJoin('site_content', 's_lang_content.resource', '=', 'site_content.id');
+        }
+
+        return $query->addSelect(
+            'site_content.pagetitle as pagetitle_orig',
+            'site_content.longtitle as longtitle_orig',
+            'site_content.description as description_orig',
+            'site_content.introtext as introtext_orig',
+            'site_content.content as content_orig',
+            'site_content.menutitle as menutitle_orig'
+        );
+    }
+
+    /**
+     * Detect whether site_content join has already been added.
+     */
+    protected function hasSiteContentJoin(array $joins): bool
+    {
+        foreach ($joins as $join) {
+            if (($join->table ?? null) === 'site_content') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Resolve the locale used by language-aware scopes.
+     */
+    protected static function resolveLocale(?string $locale): string
+    {
+        $locale = $locale ?? (function_exists('evo') ? (string)evo()->getLocale() : '');
+
+        if ($locale === '' && function_exists('evo')) {
+            $locale = (string)evo()->getConfig('lang', 'uk');
+        }
+
+        if ($locale === '') {
+            $locale = 'uk';
+        }
+
+        $underscorePos = strpos($locale, '_');
+        if ($underscorePos !== false) {
+            $locale = substr($locale, 0, $underscorePos);
+        }
+
+        return strtolower($locale);
+    }
+
+    /**
+     * Register the default language scope for the model.
+     */
+    protected static function booted(): void
+    {
+        static::addGlobalScope('language', function (Builder $builder) {
+            /** @var self $model */
+            $model = new static;
+            $locale = static::resolveLocale(null);
+            $model->applyContentSelects($builder);
+            $builder->where($model->getTable() . '.lang', '=', $locale);
+        });
+    }
 }