پیکربندی

تمام تنظیمات فینچ در یک نمونه FinchConfigs قرار دارد که یک‌بار ساخته شده و به FinchApp ارسال می‌شود. این صفحه تمام گزینه‌ها و معادل متغیر محیطی آن‌ها را مستند می‌کند.

ساختار پروژه

یک پروژه فینچ معمولی به این شکل است:

.
├── lib/
│   ├── app.dart              # تنظیم FinchApp و main()
│   ├── configs/
│   │   └── setting.dart      # ثابت‌های سطح app (اختیاری)
│   ├── controllers/
│   ├── models/
│   ├── db/
│   ├── route/
│   │   ├── web_route.dart
│   │   └── socket_route.dart
│   ├── languages/            # فایل‌های JSON زبان (en.json, fa.json …)
│   └── widgets/              # فایل‌های قالب Jinja (*.j2.html)
├── public/                   # فایل‌های استاتیک با سرویس مستقیم
├── migrations/               # فایل‌های SQL مهاجرت MySQL
├── migrations_sqlite/        # فایل‌های SQL مهاجرت SQLite
├── .env
└── pubspec.yaml

FinchConfigs

FinchConfigs کلاس مرکزی پیکربندی است. تمام پارامترهای سازنده معادل .env دارند.

import 'package:finch/finch_app.dart';
import 'package:finch/finch_tools.dart'; // pathTo(), env

FinchConfigs configs = FinchConfigs(
  // --- سرور ---
  port: (env['DOMAIN_PORT'] ?? '8080').toInt(def: 8080),
  ip: '0.0.0.0',
  domain: env['DOMAIN'] ?? 'localhost',
  domainScheme: env['DOMAIN_SCHEME'] ?? 'http',

  // --- مسیرها ---
  publicDir: pathTo(env['PUBLIC_DIR'] ?? './public'),
  widgetsPath: pathTo(env['WIDGETS_PATH'] ?? './lib/widgets'),
  widgetsType: env['WIDGETS_TYPE'] ?? 'j2.html',
  languagePath: pathTo(env['LANGUAGE_PATH'] ?? './lib/languages'),
  pathCache: pathTo(env['PATH_CACHE'] ?? './cache_routes'),
  pathMigrationMySQL: './migrations',
  pathMigrationSQLite: './migrations_sqlite',

  // --- زبان ---
  languageSource: LanguageSource.json, // یا LanguageSource.dart
  // dartLanguages: languageDart,        // هنگام استفاده از languageSource == dart

  // --- دیتابیس‌ها ---
  dbConfig: FinchDBConfig(
    enable: true,
    host: env['MONGODB_CONNECTION'] ?? 'localhost',
    port: env['MONGODB_PORT'] ?? '27017',
    user: env['MONGODB_USER'] ?? 'root',
    pass: env['MONGODB_PASSWORD'] ?? 'password',
    dbName: env['MONGODB_NAME'] ?? 'my_app',
    auth: env['MONGODB_AUTH'] ?? 'admin',
  ),
  mysqlConfig: FinchMysqlConfig(
    enable: true,
    host: env['MYSQL_HOST'] ?? 'localhost',
    port: (env['MYSQL_PORT'] ?? '3306').toInt(def: 3306),
    user: env['MYSQL_USER'] ?? 'db_user',
    pass: env['MYSQL_PASS'] ?? 'db_password',
    databaseName: env['MYSQL_DATABASE'] ?? 'my_db',
  ),
  sqliteConfig: FinchSqliteConfig(
    enable: true,
    filePath: env['SQLITE_PATH'] ?? './app.sqlite',
  ),

  // --- ایمیل ---
  mailDefault: '[email protected]',
  mailHost: 'smtp.example.com',

  // --- موتور قالب (Jinja) ---
  blockStart: '{%',
  blockEnd: '%}',
  variableStart: '{{',
  variableEnd: '}}',
  commentStart: '{#',
  commentEnd: '#}',
  // jinjaMapTemplate: mapTemplates,

  // --- امنیت ---
  cookiePassword: env['COOKIE_PASSWORD'] ?? 'change-me-in-production',

  // --- توسعه ---
  enableLocalDebugger: (env['ENABLE_LOCAL_DEBUGGER'] ?? false).toString().toBool,
);

مرجع ویژگی‌های کلیدی

کلاس‌های پیکربندی دیتابیس

FinchDBConfig (MongoDB)

FinchDBConfig(
  enable: true,
  host: 'localhost',
  port: '27017',       // String
  user: 'root',
  pass: 'password',
  dbName: 'my_app',
  auth: 'admin',       // دیتابیس منبع احراز هویت
)

FinchMysqlConfig

FinchMysqlConfig(
  enable: true,
  host: 'localhost',
  port: 3306,          // int
  user: 'db_user',
  pass: 'db_password',
  databaseName: 'my_db',
  collation: 'utf8mb4_general_ci',
)

FinchSqliteConfig

FinchSqliteConfig(
  enable: true,
  filePath: './app.sqlite',
)

متغیرهای محیطی (.env)

فینچ به صورت خودکار فایل .env در ریشه پروژه را می‌خواند. تمام مقادیر FinchConfigs را می‌توان از طریق متغیرهای محیطی بازنویسی کرد. نقشه env (از finch_tools.dart) هر دو متغیر .env و سیستم را ارائه می‌دهد.

DOMAIN_PORT=8080
DOMAIN=example.com
DOMAIN_SCHEME=https

MONGODB_CONNECTION=localhost
MONGODB_PORT=27017
MONGODB_USER=root
MONGODB_PASSWORD=secret
MONGODB_NAME=my_app
MONGODB_AUTH=admin

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=db_user
MYSQL_PASS=db_pass
MYSQL_DATABASE=my_db

SQLITE_PATH=./app.sqlite

ENABLE_LOCAL_DEBUGGER=true

isLocalDebug

FinchApp.config.isLocalDebug زمانی true برمی‌گرداند که متغیر محیطی LOCAL_DEBUG روی true تنظیم شده باشد، یا هنگامی که دارت در حالت debug اجرا می‌شود (Console.isDebug). از این flag برای فعال‌سازی خروجی verbose یا نوار debugger محلی استفاده کنید.

if (FinchApp.config.isLocalDebug) {
  Console.p('حالت Debug فعال است');
}