Download the PHP package alex-no/field-lingo without Composer

🗂️ Field-lingo

Field-lingo — lightweight library to easily work with database columns that store multiple language versions of the same attribute in one row (e.g. name_en, name_uk, name_ru). It provides a simple, consistent mechanism to reference "structured localized attribute names" (like @@name) and transparently map them to the actual column name_<lang> according to current language settings.

This repository contains full integrations for:

• Yii2 (ActiveRecord / ActiveQuery / DataProvider) — src/Adapters/Yii2
• Yii3 (ActiveRecord / ActiveQuery) — src/Adapters/Yii3
• Laravel (Eloquent Models / Query Builder) — src/Adapters/Laravel
• Symfony (Doctrine Entities / Repositories / QueryBuilder) — src/Adapters/Symfony
• Framework-agnostic core — src/Core for custom implementations

📋 Table of Contents

• Overview
• Requirements
• Key Classes
• Quick Start
  • Yii2
  • Yii3
  • Laravel
  • Symfony
• Detailed Usage (Yii2)
  • Install
  • Optional Recommendation
  • Basic Idea
  • Configure
  • Configuration Options
• LocalizedAttributeTrait Behavior
• Usage Examples
  • ActiveRecord
  • ActiveQuery
  • ActiveDataProvider
• Fallback Mechanism
• Exception Handling
• Advanced Topics
• Migration Guide
• Troubleshooting
• Core Design
• Directory Structure
• Examples
• Testing
• Contribution
• Roadmap
• License
• Contact

🌍 Overview

Field-lingo provides three Yii2 adapters that transparently translate specially formatted field names into language-specific attributes. The pattern is simple: a prefix (by default @@) marks a structured field name. When Field-lingo encounters a name like @@name, it resolves the current language and converts that token to name_{lang} (for example name_en or name_uk).

Works in:

• Attribute access ($model->@@name) and property-style ($model->name via trait).
• Query building: select, where, orderBy, groupBy using @@ names.
• DataProvider sorting integration.

Primary goals:

• Allow code and queries to use language-agnostic field names (@@title) and get language-specific attributes automatically.
• Support per-adapter and per-model configuration (prefixes, fallback language, strict mode).
• Keep the adapter API close to native Yii classes so integration is minimal.

📦 Requirements

• PHP: >= 8.2

Framework-specific requirements:

• Yii2: ^2.0 (for Yii2 adapter)
• Yii3: ^3.0 (yiisoft/active-record ^3.0, optional: yiisoft/translator ^3.0)
• Laravel: ^9.0 || ^10.0 || ^11.0 (for Laravel adapter)
• Symfony: ^5.4 || ^6.0 || ^7.0 (for Symfony adapter)
• Doctrine ORM: ^2.10 || ^3.0 (for Symfony/Doctrine adapter)

Optional but recommended:

• alex-no/language-detector — for automatic user language detection (requires separate configuration)

🧩 Key classes

• \FieldLingo\Adapters\Yii2\LingoActiveRecord

  • Extends yii\db\ActiveRecord.
  • Used when working with model attributes (reads/writes, forms, toArray()).

• \FieldLingo\Adapters\Yii2\LingoActiveQuery

  • Extends yii\db\ActiveQuery.
  • Used to transform field names in conditions, select() lists, and custom textual SQL logic within the query layer.
• \FieldLingo\Adapters\Yii2\LingoActiveDataProvider
  • Extends yii\data\ActiveDataProvider (or yii\db\ActiveDataProvider depending on implementation).
  • Used for operations that require field translation in the data provider level (for example sorting, pagination where attribute names are passed externally).

These adapters rely on a shared trait LocalizedAttributeTrait which performs the core parsing and resolution logic.

⚙️ Quick Start

Installation

Choose your framework adapter:

Yii2

1. Install

Optional Recommendation

For automatic user language detection, it is recommended to install:

Note: This package requires its own separate configuration.

Basic idea

In DB table we keep language-specific columns:

In code we refer to @@name. FieldLingo maps @@name → name_{lang} (e.g. name_uk) depending on Yii::$app->language.

Configure

Add to params (or any config area) the LingoActive section (example):

Notes:

• Per-model overrides have higher priority than adapter-level defaults.
• The trait reads Yii::$app->params['LingoActive'] by adapter name or model class name.

Configuration options

Main options:

• localizedPrefixes (string|array) — prefix(es) used to mark structured names. Default: @@.
• defaultLanguage (string) — fallback language when localized column is missing. Default: en.
• isStrict (bool) — if true throw when localized column missing; if false fallback to defaultLanguage.

These options may be set globally, per-class (LingoActiveRecord / LingoActiveQuery) or per-model.

Yii3

1. Install

2. Extend your models

3. Use localized attributes

4. Database Connection

The compatibility layer uses PDO for database access. You can configure it in two ways:

1. Via Dependency Injection (recommended):

2. Via Environment Variables:

5. Optional: Integrate with Translator service

6. Working with Relations

Compatibility Layer

The Yii3 adapter includes a compatibility layer (src/Adapters/Yii3/Compatibility/) that provides basic ActiveRecord and ActiveQuery functionality using PDO. This layer includes:

• Basic CRUD operations (findOne(), all(), one(), count())
• Query building (select(), where(), orderBy(), groupBy(), limit(), offset())
• Attribute management (getAttribute(), setAttribute(), magic properties)
• Simple relations support (hasMany(), hasOne())

This compatibility layer is designed to work until Yii3 has an official stable ActiveRecord implementation.

Key Differences from Yii2:

• Explicit locale setting: Use setLocale('uk') instead of relying on Yii::$app->language
• Translator integration: Optional integration with yiisoft/translator for automatic locale detection
• Modern PHP: Uses PHP 8.2+ type hints and return types
• No global state: Doesn't depend on global application configuration

See examples/Yii3/ for complete examples and detailed documentation.

Laravel

1. Extend your Eloquent models

2. Use localized attributes

See examples/Laravel/ for complete examples.

Symfony

1. Extend your Doctrine entities

2. Create repository

3. Use in controllers

See examples/Symfony/ for complete examples and configuration.

⚙️ Detailed Usage (Yii2)

🧠 LocalizedAttributeTrait — behavior summary

The LocalizedAttributeTrait does the heavy lifting:

• Normalizes localizedPrefixes to an array (supports a single prefix string or an array).
• Reads runtime language from Yii::$app->language and uses its first part (e.g. en-US → en).
• Produces a candidate attribute name {base}_{lang}.
• If the using class implements hasAttribute() (as ActiveRecord does), the trait checks attribute existence:
  • If attribute exists — returns it.
  • If not and isStrict === true — throws MissingLocalizedAttributeException.
  • If not and isStrict === false — tries fallback {base}_{defaultLanguage} and returns it if exists; otherwise returns the candidate.
• If hasAttribute() is not available (e.g. at query layer), the trait returns the candidate name and lets the caller use it in SQL / selections.

You can call $this->convertLocalizedFields([ ... ]) to map arrays of fields at once.

🚀 Usage examples

ActiveRecord

When using LingoActiveRecord, you can reference localized attributes directly in code:

Notes for ActiveRecord:

• Because hasAttribute() is available, missing localized columns are validated according to isStrict.
• If you rely on toArray() or fields() to export language-aware data, ensure the adapter or model calls convertLocalizedFields() where appropriate.

ActiveQuery

LingoActiveQuery resolves names used in select(), andWhere(), orderBy(), groupBy() and similar places.

CRITICAL: Override the find() method To use LingoActiveQuery, you must override the find() method in your model:

Now you can use @@ fields in queries:

Notes for ActiveQuery:

• Query layer cannot check hasAttribute() easily before SQL execution. The trait returns language-specific candidates and the DB will determine if the column exists.
• Without overriding find(), your queries will use standard ActiveQuery and @@ fields will not be converted.

ActiveDataProvider

LingoActiveDataProvider is helpful when you expose sorting/filtering to external requests (like GridView) and need to map @@ tokens to real DB columns.

Basic usage:

Usage with GridView:

Advanced: Custom sort configuration

Notes for ActiveDataProvider:

• LingoActiveDataProvider automatically converts @@ field names in sort attributes and filter conditions.
• When defining custom sort attributes, use @@ notation consistently across query, sort config, and GridView columns.
• The provider works seamlessly with Yii2's pagination and filtering mechanisms.

🔄 Fallback Mechanism

Field-lingo includes a smart fallback system to handle missing localized columns gracefully. The behavior depends on the isStrict configuration option.

How Fallback Works

When you request a localized attribute (e.g., @@title with current language = uk):

1. Library looks for title_uk

   • If exists → returns title_uk ✅
   • If not exists → proceeds to step 2

2. Check isStrict mode:

   • If isStrict = true → throws MissingLocalizedAttributeException 🚫
   • If isStrict = false → tries fallback language (step 3)
3. Fallback to defaultLanguage:
   • Library looks for title_{defaultLanguage} (e.g., title_en if defaultLanguage = 'en')
   • If exists → returns title_en ✅
   • If not exists → returns candidate name title_uk (DB will handle error if column truly missing)

Configuration Examples

Strict mode (recommended for development):

Non-strict mode with fallback (production-friendly):

Practical Example

Per-Model Fallback Configuration

You can override fallback behavior for specific models:

Recommendation:

• Use isStrict = true during development to catch missing translations early
• Use isStrict = false in production to gracefully handle missing translations with fallback

⚠️ Exception

MissingLocalizedAttributeException is thrown when isStrict is enabled and a localized attribute candidate does not exist (only thrown when attribute existence can be checked).

Make sure this exception is available in the adapter namespace or imported where the trait is used.

🧩 Advanced topics / hooks

• Custom language resolver: If your app resolves the current language from a non-standard place (cookie, user preferences, model property), consider overriding the trait by providing a protected function resolveLanguage(): string or modify the trait to call a resolveLanguage() hook.
• Multiple prefixes: Set localizedPrefixes to an array such as ['@@', '##'] to support multiple patterns.
• Per-model overrides: Per-model keys in LingoActive allow you to change prefixes and strictness for specific models.

🔀 Migration Guide

Migrating an existing Yii2 project to Field-lingo is straightforward. Follow these steps:

Step 1: Install the package

Step 2: Prepare database schema

If you don't have localized columns yet, add them to your tables:

Step 3: Configure Field-lingo

Add configuration to config/params.php or config/web.php:

Step 4: Update your models

Before (standard ActiveRecord):

After (LingoActiveRecord):

Step 5: Update controllers and views

Before:

After:

Step 6: Update DataProviders

Before:

After:

Step 7: Update GridView columns

Before:

After:

Step 8: Test thoroughly

Migration Checklist

• [ ] Database schema updated with localized columns
• [ ] Existing data migrated to default language columns
• [ ] Configuration added to params
• [ ] Models extend LingoActiveRecord
• [ ] find() method overridden in models
• [ ] Controllers updated to use getAttribute()/setAttribute()
• [ ] Views updated to use getAttribute()
• [ ] DataProviders changed to LingoActiveDataProvider
• [ ] GridView columns updated
• [ ] Search models updated (if using)
• [ ] Tests updated
• [ ] All functionality tested in both languages

Gradual Migration Strategy

You can migrate gradually by:

1. Keep both old and new columns during transition period
2. Migrate model by model instead of all at once
3. Use per-model configuration to customize behavior:

🔧 Troubleshooting

Problem: @@field notation is not working in queries

Symptoms: Queries like Post::find()->where(['@@title' => 'Test']) fail or @@title is treated as literal string.

Solution:

1. Make sure you've overridden the find() method in your model:

2. Check that you're importing the correct class:

Problem: getAttribute('@@field') returns null or wrong value

Possible causes:

1. Configuration not loaded

   • Check Yii::$app->params['LingoActive'] is properly configured
   • Verify config file is being loaded

2. Column doesn't exist in database

   • If isStrict = true, you'll get MissingLocalizedAttributeException
   • If isStrict = false, library will try fallback language
   • Check database schema: SHOW COLUMNS FROM your_table
3. Language format mismatch
   • Current language: Yii::$app->language (e.g., en-US, uk)
   • Library uses first part: en-US → en
   • Make sure column names match: title_en, title_uk, etc.

Problem: GridView sorting not working with localized fields

Solution:

1. Use LingoActiveDataProvider instead of ActiveDataProvider:

2. Configure sort attributes with @@ notation:

Problem: How to check if Field-lingo is working correctly?

Quick test:

Problem: Exception "MissingLocalizedAttributeException"

Cause: isStrict = true and requested localized column doesn't exist in the table.

Solutions:

1. Add missing column to database:

2. Use fallback mode (non-strict):

3. Add only columns you need:
   • If you only support English and Ukrainian, only create *_en and *_uk columns
   • Set defaultLanguage to one you always have

Problem: Getting "Unknown column" SQL error

Cause: Query uses @@field but it wasn't converted to actual column name.

Check:

1. Model extends LingoActiveRecord
2. Query uses LingoActiveQuery (via overridden find())
3. DataProvider uses LingoActiveDataProvider
4. Column actually exists in database

FAQ

Q: Can I use multiple prefixes like @@ and ##?

A: Yes! Configure as array:

Q: Can I change the language dynamically during runtime?

A: Yes, Field-lingo reads Yii::$app->language on each call:

Q: Does Field-lingo work with relations?

A: Yes, as long as related models also extend LingoActiveRecord:

Q: Can I use this in forms and validation?

A: Yes, but reference actual column names in rules:

In forms, you can use @@ notation for display:

🧱 Core design

Core/Localizer.php — centralized logic for mapping structured names to real column names.

Core/Contracts/LocalizerInterface.php — contract for Localizer implementations.

The core can be reused later for adapters (Laravel Eloquent, Doctrine, plain SQL builders).

📁 Directory Structure

Examples

• Yii2: See examples/Yii2/ for ActiveRecord and ActiveQuery examples
• Yii3: See examples/Yii3/ for modern Yii3 ActiveRecord examples with Translator integration
• Laravel: See examples/Laravel/ for Eloquent model and query examples
• Symfony: See examples/Symfony/ for Doctrine entity and repository examples with detailed README

🧪 Testing

Unit tests in tests/. PHPUnit recommended. Example:

• Add unit tests that switch Yii::$app->language and assert correct conversions.
• Test both strict and non-strict modes and per-model overrides.

🤝 Contribution

Contributions welcome! Suggested workflow:

1. Fork repository.

2. Create feature branch.

3. Add tests.

4. Open pull request.

Please follow PSR-12 and add PHPDoc (English) for public APIs.

🗺️ Roadmap

• ✅ Core mapping logic.
• ✅ Yii2 integration (ActiveRecord, ActiveQuery, DataProvider).
• ✅ Yii3 integration (ActiveRecord, ActiveQuery with Translator support).
• ✅ Laravel Eloquent adapter (Models, Query Builder).
• ✅ Symfony/Doctrine adapter (Entities, Repositories, QueryBuilder).
• 🧩 Advanced column patterns: nested access, JSON, relation-aware localization.
• 💡 Optionally store translation meta in separate table(s) as alternative mode.

📄 License

MIT. See LICENSE.

📬 Contact

*Field-lingo © 2025 Oleksandr Nosov. Released under the MIT License.