ה-Collections

ה-Collections הן מחלקות סטטיות שאין להן מופע: DB::get_all(...), PAGE::add_asset(...), cache_engine::get(...). כל הליבה ואתר הלקוח נשענים עליהן. בעמוד הזה מופיעה מפה של כולן, ולצידה מה כל אחת מחזיקה ועל מה היא תלויה. הפירוט המלא של כל מחלקה נמצא בעמודי הרפרנס שאליהם מפנה הטבלה.

נתיבי הקבצים בעמוד הם יחסית ל-api/core בריפו. באתר פרוס אותה תיקייה היא system/core/. {admin} הוא CONFIG::$admin_url.

איך הליבה טוענת אותן#

core.php טוען את כל הקבצים בתיקיית collections/ בלולאה אחת, בכל בקשה, בלי autoload:

foreach (glob($file_location . "/collections/*.php") as $filename) require_once($filename);

מכאן שלוש תוצאות מעשיות:

• כל מחלקה זמינה בכל מקום מהרגע שהבקשה התחילה. אין use, אין require ואין new.
• קובץ חדש ב-collections/ נטען אוטומטית. מחלקה שנוספת לשם משלמת עלות פענוח בכל בקשה, גם בבקשות שלא משתמשות בה.
• סדר הטעינה הוא סדר ה-glob (תלוי ב-locale של השרת), ולכן אין לבנות על סדר. שתי התלויות היחידות בין קבצים מתקיימות בשני הסדרים: CONFIG extends CONFIG_USER ו-CONFIG_USER נטענת קודם מ-system/config.php, ו-theme.php מרחיב את bgl_controller שמוגדר ב-MODULE.php.

אחרי הטעינה core.php מריץ בסדר קבוע: CONFIG::preinit(), MISC::cli_check(), CONFIG::init(), ‏application/includes/init.php, ‏cache_engine::cache_php_check(), ‏MISC::init_security(), ‏CronLogger::start_capture(), טעינת Smarty, ‏PAGE::load(...), ‏MASK::out והדפסה, ובסוף CronLogger::finish_capture(), ‏STORAGE::FtpClose() ו-DB::close_connection(). התיאור המלא של הזרימה נמצא ב-מחזור חיי בקשה.

טבלת סיכום#

הליבה: CONFIG, DB, PAGE#

CONFIG (collections/CONFIG.php)#

class CONFIG extends CONFIG_USER. מחזיקה את הגדרות האתר מ-system/config.php (בירושה) ואת מה שהליבה מחשבת בעצמה בכל בקשה.

מתודות: CONFIG::preinit() (אזור זמן Asia/Jerusalem, פרוטוקול, base_path, נתיבים מוחלטים לתיקיות המודלים והמטמון) ו-CONFIG::init() (בחירת הפלטפורמה). הפירוט ב-פלטפורמות ורב-לשוניות וב-CONFIG_USER.

DB (collections/DB.php)#

ארבע מחלקות: DB (חיבור ושאילתות גולמיות), DB_UPDATE_CLASS (בונה הוספה ועדכון), DB_QUERY_OBJECT (בונה שליפה עם JOIN רב-לשוני) ו-zend_query. הליבה תומכת בחיבור PDO ל-MySQL, ויש גם ענפים ל-mysql, ‏pg ו-clickhouse.

DB::sql($sql)                                   // שאילתה גולמית
DB::get_row($res, $return_key = false)
DB::get_all($res, $key = NULL, $val = NULL)
DB::escape($str)
DB::get_val($tblName, $filter = "", $rowName = "")
DB::update($table = "", $vars = array())        // מחזיר DB_UPDATE_CLASS
DB::query($table = "", $whereCond = array(), $orderBy = "", $lang = "", $limit = null)
DB::delete($table = "", $whereCond = array(), $orderBy = "", $lang = "", $limit = null)
DB::is_table_exists($table)
DB::is_column_exists($table, $column)

על ה-DB_UPDATE_CLASS רצים set_var($colName, $val, $tbType = "conf") (ו-set(...) כאליאס), ואז insert($mainLang = true) או update($whereQuery). אין DB::insert. על DB_QUERY_OBJECT רצים get_row(), ‏get_all($key = false, $value = false), ‏num_rows() ו-affected_rows().

מצב סטטי: $is_sql_debug, ‏$print_sql, ‏$log_sql (נדלק כשהפרמטר log_sql שווה "1"), ‏$throw_on_error, ‏$condb (החיבור), ‏$error_count, ‏$last_error, ‏$table_exist_array, ‏$table_columns_array ו-$encoding (utf8mb4). המחלקה תלויה ב-CONFIG (פרטי החיבור והשפה), ב-cache_engine (רשימת הטבלאות והעמודות נשמרת בו) וב-MISC.

PAGE (collections/PAGE.php)#

שתי מחלקות: PAGE ו-AddedFile. PAGE::load($url, $isMobile=null) מנהלת את כל מחזור הבקשה: אתחול PARAMS ו-SEO, פענוח ה-URL ב-ROUTER, בדיקת דומיין, טעינת קבצי application/includes, אתחול פאנל הניהול, טעינת מילים, בחירת ערכה, הרצת הקונטרולר ובסוף PAGE::output().

מתודות מרכזיות:

PAGE::set_theme($theme)
PAGE::add_asset($fileSrc, $must = false, $area = "head", $order = "append")
PAGE::add_asset_advanced($fileSrc, $m_settings=[])
PAGE::add_meta($val, $area = "head")
PAGE::bind($event, Closure $func)
PAGE::trigger($event, $args = array())
PAGE::is_mobile()
PAGE::parse_page($content)

מצב סטטי: $is_404, ‏$theme, ‏$robots (ברירת מחדל "ALL"), ‏$assets_css, ‏$assets_js, ‏$meta_tags, ‏$events, ‏$cache_this_page, ‏$cache_this_page_hours, ‏$include_system_js. תלויות: ROUTER, ‏MODULE, ‏SEO, ‏PARAMS, ‏LANGS, ‏ADMIN, ‏FILES ו-cache_engine. ראו PAGE: נכסים, מטא ואירועים ו-PAGE.

ניתוב וטעינת קוד: ROUTER, MODULE, theme#

ROUTER (collections/ROUTER.php)#

ROUTER::parse_friendly_url(string $url) הופכת כתובת ל-$_GET["module"], ‏$_GET["pname"], ‏$_GET["id"] או ל-$_GET["sys_controller"]. סדר ההתאמות (סוגי קבצים מיוחדים, נכסים, כתובות הניהול, seoUrl, ואז system/... ושם מודול) מתואר ב-ניתוב (ROUTER).

ROUTER::parse_friendly_url(string $url)
ROUTER::redirections()
ROUTER::get_seo_tbl()
ROUTER::get_by_url($url)
ROUTER::get_by_friendly($url)
ROUTER::remove_by_url($url)
ROUTER::is_trace_on()
ROUTER::trace($stage, $detail = [])
ROUTER::trace_render()

מצב סטטי: $trace (ציבורי). המחלקה מבקשת מ-cache_engine את seoUrl_tbl ו-redirections, ולכן תלויה ב-MASK (הקריאה הראשונה היא MASK::in), ב-CONFIG וב-WIZZO_NET (חריג לשער המדינות בפאנל). ראו גם כתובות ידידותיות, הפניות 301 ו-דיבוג ניתוב.

MODULE (collections/MODULE.php)#

MODULE::get_html דורשת שורה פעילה בטבלה modules לכל קונטרולר של אתר, ואינה דורשת אותה לקונטרולר מערכת. מתודה שמחזירה את המחרוזת "ERRORPAGE" הופכת ל-404. ראו קונטרולרים של אתר, קונטרולרי מערכת ו-404, 503 ושגיאות.

theme (collections/theme.php)#

class bgl_theme extends bgl_controller. מחלקת האב של TEMPLATE_<theme> שב-themes/<theme>/index.php. בנאי: __construct($name) (מציב content ו-pgClass ב-$this->vars). get_html() מרנדר את index.tpl מתיקיית הליבה עבור ערכות admin_login ו-admin_panel, ומתיקיית themes/<name>/ של האתר עבור כל השאר. ראו ערכות נושא.

נתונים וביצועים: cache_engine, PARAMS, LANGS#

cache_engine (collections/cache_engine.php)#

מטמון על דיסק: קבצי <key>.chc.gz (או .chc אם הדחיסה כבויה) בתיקיית CONFIG::$cache_folder.

cache_engine::get($key, $func = false, $hours = 24, $in_platform = true)
cache_engine::save_cache_file($key, $data, $hours = 24*7, $in_platform = true)
cache_engine::get_cache_file($key, $in_platform = true)
cache_engine::remove($key)
cache_engine::get_item($item_type, $item_id, $in_platform = false, $refresh=false, $create=true)
cache_engine::set_item($type, $m_params)
cache_engine::remove_item($item_type, $item_id)
cache_engine::cache_all_page($hours = 24, $set_page = false)
cache_engine::cache_all_page_remove($url, $hard_delete = false)
cache_engine::cleanup_expired($type = 'all', $dry_run = false)
cache_engine::get_stats()

מצב סטטי: $cache_folder, ‏$platform_cache_folder, ‏$compress_pages, ‏$compress_data, ‏$tracking_params, ‏$use_build_lock, ‏$build_lock_wait_ms, ‏$serve_stale_while_building, ‏$gc_grace_hours, ‏$serve_gz_direct. הפרמטר $in_platform קובע אם הערך נשמר בתיקייה של הדומיין הנוכחי (<cache_folder>/<SERVER_NAME>/) או בשורש המטמון. המטמון עצמו תלוי ב-CONFIG וב-DB (get לא שומר תוצאה אם נוספו שגיאות DB בזמן הבנייה). ראו איך המטמון עובד, cache_engine API ו-מטמון עמודים מלא.

PARAMS (collections/PARAMS.php)#

PARAMS::get($key)          // מחרוזת ריקה אם המפתח חסר
PARAMS::set($key, $value)  // משנה רק את הזיכרון של הבקשה
PARAMS::init()             // טוען את הטבלה params דרך המטמון הגלובלי "params" (30 יום)

המצב הוא private static $arrParams. הערכים נשמרים בטבלה params (עמודות sysName ו-value).

LANGS (collections/LANGS.php)#

LANGS::get_word($key, $lang = false)
LANGS::set_word($key, $value)
LANGS::translate($val)
LANGS::init_words()
LANGS::get_words_array()

המצב הוא private static $arrWords. init_words() טוענת את מילות השפה הנוכחית ל-cache_engine תחת המפתח words_lang<id> ל-4 שעות, לפי דומיין. הטבלאות: langs_words ו-langs_words_content. ראו פרמטרים ומילים ו-PARAMS ו-LANGS.

קלט, קבצים ועזרים: MISC, FILES, STORAGE#

MISC (collections/MISC.php)#

מחלקת עזרים כללית. המצב הסטטי החשוב הוא MISC::$GLOBALS, מערך שאליו הליבה מציבה נתונים לאורך הבקשה (lang, ‏langs, ‏admin_lang_id, ‏app_html ועוד).

MISC::init_security()                       // סינון GET/POST והעלאות; "SECURITY ERROR" בעת חשד
MISC::cli_check()                           // מצב CLI: key=value הופכים ל-$_GET
MISC::bgl_implode($arr) / MISC::bgl_explode($str)   // פורמט |1||2|
MISC::encode($str) / MISC::decode($str)
MISC::get_modules_tbl()                     // שורות הטבלה modules, מהמטמון
MISC::service_unavailable($reason = "", $retry_after = 120)
MISC::email($to,$from,$subj,$msg, $bcc = "")
MISC::add_mail_to_queue($mail, $priority = 1, $mail_tpl= "", $is_sent=false,$pid=false)
MISC::get_ip()
MISC::uuid($data = null)
MISC::absolute_url($url)

כל השאר ב-עזרים (MISC) וב-MISC.

FILES (collections/FILES.php)#

FILES::html_template($tmpl_file, $varsArr = array(), $settings = array())
FILES::string_template($tmpl_string, $varsArr = array(), $settings = array())
FILES::include_dir($directoryincl)
FILES::scss($file)
FILES::vue($url, $m_settings)
FILES::make_dir($path, $mode = 0777)
FILES::remove_dir($directory, $empty=FALSE)
FILES::get_extension($filename)
FILES::is_img($str)

html_template עובדת לפי CONFIG::$use_smarty: ‏true מריצה Smarty (תיקיית הקומפילציה היא cache/Smarty/templates_c/), ‏"plain" מחזירה את הקובץ כמות שהוא, וכל ערך אחר עובר דרך eval של התבנית. include_dir טוענת את כל קבצי ה-php בתיקייה (ממוינים) פעם אחת בלבד. ראו תבניות Smarty, צינור הנכסים ו-FILES.

STORAGE (collections/STORAGE.php)#

STORAGE::add($file_path, $opts = array())
STORAGE::get($id)
STORAGE::get_url($id)
STORAGE::get_thumb($id, $width = "auto", $height = "auto")
STORAGE::get_by_name($id, $name = "", $width = "auto", $height = "auto")
STORAGE::remove($id, $only_files = false)
STORAGE::addFromBase64($base64, $name, $ext, $path, $remote = "local", $extra_settings = [])
STORAGE::convert($sid, $type)
STORAGE::forget($id = false)
STORAGE::FtpClose()

מצב סטטי: $table ("storage"), ‏$filename_type (uuid או id), ‏$temp_folder (media/System/CropTmp), הגדרות הגלריה ($gallery_*), הגדרות Cloudflare ($cloudfare_cache*, כך כתוב בקוד) ואיכות JPEG ($default_jpeg_quality). STORAGE::get שומרת שורות בזיכרון לבקשה, וכל פעולת כתיבה חייבת לקרוא ל-forget(). ראו STORAGE: העלאה ואחסון, כללי העלאת קבצים, עיבוד תמונה ו-STORAGE.

משתמשים, עוגיות ואבטחה: ADMIN, COOKIES, SESSION, LOGIN, CRYPT#

ADMIN (collections/ADMIN.php)#

ADMIN::is_admin()
ADMIN::get_id()
ADMIN::login ($username, $password)
ADMIN::check_details ($username, $password, $phone = false, $record_bad_attempt = true)
ADMIN::admin_log($adminID)
ADMIN::admin_logout()
ADMIN::has_perms($perm = "", $curr_page = false, $curr_action = false)
ADMIN::GetAdminGroup()
ADMIN::init_multilang()
ADMIN::generate_csrf_cookie()
ADMIN::verify_csrf_token($posted_token)
ADMIN::is_developer()

הטבלאות: adminPanel_admins, ‏adminPanel_admins_groups ו-adminPanel_panels. ל-ADMIN שירותי סשנים (get_active_sessions, ‏revoke_session, ‏logout_all) וכניסה בשם מנהל אחר (create_login_as_token, ‏validate_login_as_token). ראו התחברות, סשנים ו-WIZZO ID, הרשאות וקבוצות ו-ADMIN. הבחירה של שפת הפאנל מתוארת ב-פלטפורמות ורב-לשוניות.

COOKIES (collections/COOKIES.php)#

כל עוגייה נקראת CRM_<name>. מצב סטטי: $login_use_ip (true), ‏$samesite ("None"), ‏$prefix ("user_").

COOKIES::set($ckiName, $ckiValue, $ckiHours = 0, $base_domain = true)
COOKIES::get($ckiName)
COOKIES::is_set($ckiName)
COOKIES::kill($ckiName, $base_domain = true)
COOKIES::set_secure($ckiName, $ckiValue, $ckiHours = 0, $base_domain = true)
COOKIES::user_log($tableName, $id, $sessTime = 72)
COOKIES::user_is_logged($tableName)
COOKIES::user_logout($tableName)

ברירת המחדל היא דומיין .base_domain. עם $base_domain = false הדומיין נבחר מתוך הדומיין הראשי והדומיינים המורשים של הפלטפורמה. set_secure יוצרת עוגיית httponly עם SameSite=Lax, ואילו set רגילה אינה httponly. ראו COOKIES ו-SESSION.

SESSION (collections/SESSION.php)#

SESSION::set($key, $val), ‏get($key), ‏remove($key), ‏is_set($key), ‏init(), ‏close(), ‏destroy(). כל קריאה פותחת את הסשן וסוגרת אותו מיד, כך שהמנעול לא נתפס לאורך הבקשה. ערכים שאינם מחרוזת או מספר שלם נשמרים בצורה מסודרת (serialize).

LOGIN (collections/LOGIN.php)#

התחברות של משתמשי צד-לקוח, לפי טוקן שמתועד בטבלה users_logins.

LOGIN::login_by_details($username, $password, $sessTime = 24*7*30*12)
LOGIN::login_by_id($id, $sessTime = 24*7*30*12)
LOGIN::logout()
LOGIN::is_logged()
LOGIN::get_id()
LOGIN::get_token()

מצב סטטי: $table ("users"), ‏$encryption ("md5", ועוד "bcrypt" ו-"wp"), ‏$login_use_ip (false), ‏$max_devices (3). ראו משתמשי צד-לקוח.

CRYPT (collections/CRYPT.php)#

AES-256-CBC עם IV אקראי: CRYPT::set_secret_key($key), ‏CRYPT::encode($data) (קידוד JSON, הצפנה, ואז base64 בטוח ל-URL של ה-IV והטקסט המוצפן), ‏CRYPT::decode($data). המפתח המשותף ברירת מחדל הוא ערך קבוע בקוד, ולכן יש להגדיר מפתח משלכם. ראו הצפנה וקידוד.

ממשק עם תשתית Wizzo: WIZZO_KEY, WIZZO_NET, CronLogger, MASK, SEO#

WIZZO_KEY ו-WIZZO_NET#

WIZZO_KEY היא הדלת היחידה שדרכה מקור הליבה קורא את המפתח ש-Wizzo שולחת לאתר, כדי שהוא יגיע גם באתרים שבהם הכותרת Authorization לא מועברת ל-PHP (FastCGI).

WIZZO_KEY::incoming($body = null)           // המפתח שבבקשה, "" אם אין
WIZZO_KEY::matches($expected, $body = null)  // השוואה מול המפתח הצפוי

WIZZO_NET מחזיקה את רשימת הכתובות של שרתי Wizzo (private static $ips), והיא הרשימה היחידה בליבה.

WIZZO_NET::all()
WIZZO_NET::caller_ips()
WIZZO_NET::caller_ip()
WIZZO_NET::is_wizzo()
WIZZO_NET::is_wizzo_strict()

is_wizzo() מתחשבת גם בכותרות CF-Connecting-IP ו-X-Forwarded-For, ולכן היא שכבה אחת בלבד ולעולם לא הוכחה בפני עצמה. is_wizzo_strict() בודקת REMOTE_ADDR בלבד, ובה משתמשת בדיקת ה-IP של עוגיית משתמש. ראו מודל האבטחה ו-שרת הסוכן.

CronLogger (collections/CronLogger.php)#

לוכד את הפלט והסטטוס של בקשה ש-cron_runner מפעיל. הפעלה מותנית בפרמטרים tk (טוקן הריצה) ו-cron_save_log_id (שורה קיימת ב-cron_logs); בבקשה רגילה שתי הקריאות ב-core.php הן no-op.

CronLogger::start_capture(): void
CronLogger::finish_capture(): void
CronLogger::shutdown_handler(): void
CronLogger::create_running_log(int $taskId, string $url, string $params): int
CronLogger::prune_task_logs(int $taskId): void

קבועים: KEEP_PER_TASK = 50 (כמות הלוגים לכל משימה) ו-MAX_OUTPUT = 50000 (בתים לכל לוג). ראו מנהל משימות (Cron).

MASK (collections/MASK.php)#

הסוואה של נתיבים ציבוריים (themes/<theme>/, ‏system/js/, ‏minify/ ועוד) לשמות ניטרליים, בלי להזיז קבצים. כבויה כברירת מחדל ונדלקת דרך CONFIG_USER::$mask.

MASK::in($url)       // מסכה אל אמיתי, בראש ROUTER::parse_friendly_url
MASK::out($html)     // אמיתי אל מסכה, על ה-HTML והנכסים בצד הלקוח
MASK::enabled()
MASK::map()
MASK::words()

באתר שלא מפעיל הסוואה המחיר הוא בדיקת property_exists אחת בכל בקשה. ראו מצב הסוואה (MASK).

SEO (collections/SEO.php)#

SEO::init()
SEO::set_key($key)
SEO::set($fields, $value)
SEO::set_var($field, $value)
SEO::get_schema($type)
SEO::tags_summary()

מצב סטטי: $fields (og_url, meta_title, meta_description, meta_keywords, og_title, og_description, og_image), ‏$title_include_sitename, ‏$page_key. ברירות המחדל של התגיות נלקחות מ-seo_title, ‏seo_description ו-seo_keywords של הפלטפורמה. ראו תגיות SEO ו-Schema, SEO למפתחי אתר ו-SEO.

מה הלאה#

• איך כל המחלקות האלה נפגשות בבקשה אחת: מחזור חיי בקשה ו-סקירת ארכיטקטורה.
• איך מקצים שמות לטבלאות, קבצים ומחלקות: מוסכמות ושמות.
• איך הפלטפורמה קובעת את השפה שבה כל מחלקה פועלת: פלטפורמות ורב-לשוניות.