cache_engine

הדף הזה הוא רפרנס לכל המתודות הציבוריות של cache_engine (api/core/collections/cache_engine.php). הוא עונה על "מה בדיוק מקבלת ומחזירה המתודה הזו". להסבר מושגי ראו סקירת המטמון, מטמון עמוד שלם ו-ניהול המטמון בפאנל; דוגמאות שימוש נוספות ב-cache-api.

המנוע מבוסס קבצים בלבד: אין Redis או Memcached. כל ערך הוא קובץ תחת CONFIG::$cache_folder, והפרטים החשובים:

• תוקף הערך הוא ה-mtime של הקובץ. בעת כתיבה הקובץ מקבל touch לזמן שבו הוא אמור לפוג (עכשיו + מספר השעות). קובץ הוא "טרי" כל עוד filemtime($file) > time().
• שני תחומים: תיקיית פלטפורמה CONFIG::$cache_folder/<SERVER_NAME> (נפרדת לכל דומיין) ותיקיית שורש CONFIG::$cache_folder (משותפת לכל הדומיינים בשרת).
• כתיבה אטומית: כל כתיבה היא קובץ זמני ואז rename, כך שקורא לא רואה קובץ חצי-כתוב.
• דחיסה: נתונים נשמרים כ-.chc.gz ועמודים כ-.html.gz כברירת מחדל. קריאה מכבדת גם קבצים לא דחוסים ישנים.

מאפיינים סטטיים#

תיקיות ונתיבים#

cache_engine::get_platform_cache_folder()#

static function get_platform_cache_folder()

מחזירה: string, CONFIG::$cache_folder . '/' . $_SERVER["SERVER_NAME"], ונזכרת למשך הבקשה. אם SERVER_NAME ריק או מכיל /, \, .. או NUL, השם מוחלף ב-_invalid_host_<12 תווי hash> כדי שלא ייצא מתיקיית המטמון או יתמזג עם השורש.

cache_engine::check_server_name()#

static function check_server_name()

מחזירה: תמיד true. רשימת הדומיינים המותרים הושבתה בכוונה (הבידוד נעשה לפי תיקיית הדומיין). נשארה כדי שקוד קיים שקורא לה ימשיך לעבוד.

מטמון נתונים (.chc)#

מאחסן כל ערך PHP שאפשר לעשות לו serialize: מערכים, אובייקטים, מחרוזות, מספרים.

cache_engine::get()#

static function get($key, $func = false, $hours = 24, $in_platform = true)

מחזירה: את הערך מה-cache; אם אין cache, את תוצאת $func (אחרי שנשמרה); false כשאין cache ואין $func. אם DB::$error_count עלה בזמן ש-$func רץ, התוצאה מוחזרת אבל לא נשמרת.

$modules = cache_engine::get("modules_tbl", function () {
    return DB::get_all("SELECT * FROM " . CONFIG::$db_fullprefix . "modules", "id");
}, 24 * 7);

cache_engine::save_cache_file()#

static function save_cache_file($key, $data, $hours = 24*7, $in_platform = true)

כותבת ערך ל-cache בלי לחשב אותו. $hours ברירת המחדל כאן היא 7 ימים (לעומת 24 שעות ב-get). שומרת serialize($data) (דחוס gzip רמה 6 כש-$compress_data), ומוחקת את הגרסה בפורמט ההפוך כדי שלא תישאר גרסה ישנה. מחזירה: false רק אם $in_platform ו-check_server_name() נכשלה (לא קורה בפועל), אחרת כלום (null), גם כשהכתיבה עצמה נכשלה.

cache_engine::get_cache_file()#

static function get_cache_file($key, $in_platform = true)

מחזירה: את הערך שנשמר (אחרי unserialize) אם קיים קובץ טרי, אחרת false. קובץ .gz פגום נמחק והפונקציה מחזירה false. זו הליבה של get(), ושימושית כשרוצים לבדוק קיום בלי לבנות.

cache_engine::remove()#

static function remove($key)

מוחקת קבצי .chc ו-.chc.gz שמתחילים ב-$key (glob($key . "*")), בכל תיקיות המשנה הישירות של CONFIG::$cache_folder (כלומר כל הדומיינים, ותיקיית items), ובשורש עצמו. מחזירה: כלום.

cache_engine::remove("modules_tbl");     // גם modules_tbl_extra אם קיים

קטעי HTML (.html)#

cache_engine::get_html()#

static function get_html($key, $func = false, $hours = 24)

מחזירה: מחרוזת ה-HTML מה-cache, או התוצאה של $func (אחרי שנכתבה, ללא דחיסה), או false.

echo cache_engine::get_html("footer_" . (int)CONFIG::$lang, function () {
    return render_footer();   // הפונקציה שלכם
}, 6);

cache_engine::remove_html()#

static function remove_html($key)

מוחקת כל <key>*.html בתיקיית הפלטפורמה של הדומיין הנוכחי (prefix, כמו remove, אבל לדומיין הזה בלבד). מחזירה: כלום.

Items: אובייקט מטמון לפי סוג ומזהה#

Item הוא ערך שנבנה מרשומה אחת ומתרענן בנפרד. הסוג נרשם פעם אחת עם set_item(), ואז get_item() מחזיר את הערך מה-cache או בונה אותו. הקבצים נשמרים תחת items/<type>/<ה-id מפוצל לזוגות ספרות>/<id>, למשל id 12345 הופך ל-items/news/12/34/5/12345. ברירת המחדל היא השורש המשותף ($in_platform = false) ותוקף 30 יום.

cache_engine::set_item()#

static function set_item($type, $m_params)

מחזירה: כלום. הרישום נשמר ב-cache_engine::$cache_functions בלבד, לבקשה הנוכחית, ולכן חייבים להריץ אותו בכל בקשה לפני get_item (בליבה: בקובץ הקונטרולר או הספרייה שמשתמשים בו).

cache_engine::get_item()#

static function get_item($item_type, $item_id, $in_platform = false, $refresh = false, $create = true)

מחזירה: הערך (אחרי parse_after), או false כש-$create שקר ואין cache, או כש-query לא מצא רשומה (ואז, אם $refresh === true, גם נמחק ה-cache של ה-item).

cache_engine::set_item("news_card", [
    "query"   => function () { return DB::query("news", ["is_active" => 1]); },
    "parse"   => function ($row, $id) { return ["title" => $row["title"], "url" => "/news/" . (int)$id]; },
]);

$card = cache_engine::get_item("news_card", 15);

cache_engine::remove_item()#

static function remove_item($item_type, $item_id)

מוחקת את קבצי ה-item (בעזרת remove(), ולכן בכל הדומיינים ולפי prefix) ומפעילה את on_refresh אם רשום. מחזירה: כלום. קוראים לה בכל מקום שבו הרשומה משתנה או נמחקת (כך עושה admin/tag_manager.php).

cache_engine::refresh_item()#

static function refresh_item($item_type, $item_id, $in_platform = false)

קיצור ל-get_item($type, $id, $in_platform, true): בונה מחדש ושומר. מחזירה: כלום (הערך אינו מוחזר; קראו ל-get_item אם צריך אותו).

מטמון עמוד שלם#

העמוד המוכן נשמר ב-<platform>/pages/<url>.html.gz (למובייל pages_mobile, לפי PAGE::is_mobile()), ו-cache_php_check() מגיש אותו בתחילת הבקשה, לפני טעינת הקונטרולרים. זרימה: core.php קורא ל-cache_php_check() בשורה 17; קונטרולר שרוצה cache קורא ל-cache_all_page(); בסוף הבקשה core.php קורא ל-cache_all_page_save() כש-PAGE::$cache_this_page === true.

cache_engine::cache_php_check()#

static function cache_php_check($url = false)

מחזירה: כלום. אם יש עמוד טרי, שולחת את ה-Content-Type המתאים (HTML, JSON, RSS או XML לפי התוכן והכתובת), מדפיסה אותו ו-exit. אם $_POST["reload_cache"] קיים, מבטלת את מגבלת הזמן ויוצאת בלי להגיש (בקשה כזו בונה מחדש). אם אין עמוד טרי אבל יש עמוד שפג ובקשה אחרת בונה אותו כרגע, מגישה את הישן (stale). לבסוף בודקת גם קובץ CSS ב-scss/<url>.css.

cache_engine::cache_all_page()#

static function cache_all_page($hours = 24, $set_page = false)

מחזירה: כלום. מסמנת PAGE::$cache_this_page = true, ואם בקשה אחרת כבר בונה את אותו עמוד, ממתינה עד $build_lock_wait_ms (750ms) ומגישה את העמוד שלה ברגע שיופיע (בהצלחה: exit).

// בתוך קונטרולר של עמוד ציבורי
cache_engine::cache_all_page(6);   // העמוד יישמר ל-6 שעות

cache_engine::cache_all_page_save()#

static function cache_all_page_save($data, $url)

מחזירה: false כשהבקשה "הפסידה" במירוץ הבנייה ופג זמנה ($build_lock_loser); אחרת כלום. כותבת את $data (דחוס gzip רמה 6 כש-$compress_pages) ל-<platform>/pages[_mobile]/<encode_url($url)>.html.gz, עם תוקף PAGE::$cache_this_page_hours. נקראת מ-core.php; לא קוראים לה ידנית.

cache_engine::cache_all_page_update()#

static function cache_all_page_update($url)

מחזירה: תמיד true. מפעילה ping_cache($url) שגורם לבנייה מחדש של העמוד (דסקטופ ומובייל).

cache_engine::cache_all_page_remove()#

static function cache_all_page_remove($url, $hard_delete = false)

מחזירה: כלום. מבטלת את העמוד ב-pages וב-pages_mobile (כולל הווריאנטים + ו-bgl_url_encode) ואז כל קובץ שהכתובת שלו מתחילה באותו נתיב (תתי-עמודים וגרסאות עם פרמטרים). לדף הבית ($url ריק) מבטלת רק אותו.

cache_engine::cache_all_page_remove("/news/my-article");                  // התוצאה נבנית מחדש בביקור הבא
cache_engine::cache_all_page_remove("/legal/page", true);                 // תוכן שחייב להפסיק להיות מוגש מיד

cache_engine::drop_page_file()#

static function drop_page_file($file, $hard_delete = false)

מבטלת קובץ עמוד בודד: אם לא $hard_delete ו-stale מופעל, מקדימה את ה-mtime ב-60 שניות אחורה (פג, אבל קיים); אם ה-touch נכשל (למשל קובץ של משתמש אחר), או ב-$hard_delete, מוחקת. מחזירה: כלום.

cache_engine::set_page_url() ו-get_page_url()#

static function set_page_url($url)
static function get_page_url()

set_page_url($url) קובעת כתובת חלופית לשמירה ולנעילה ("/" . rtrim($url, "/")) וקוראת מיד ל-cache_php_check($url). get_page_url() מחזירה את הכתובת שנקבעה, או $_SERVER['REQUEST_URI']. שימושי כשהעמוד מוגש תחת כתובת שאינה ה-URI בפועל.

cache_engine::encode_url()#

static function encode_url($url)

הופכת כתובת למפתח קובץ בטוח. מחזירה: string: בלי / בקצוות, בלי ? (הוא נמחק, לא מוחלף, כך ש-/page?a=1 הופך ל-pagea=1), עם urldecode אם יש %, וכשהסגמנט האחרון ארוך מ-50 תווים הוא מוחלף ב-sha256 שלו. כתובת עם .. (גם אחרי פענוח, למשל %2e%2e) או NUL: die("Invalid URL").

cache_engine::strip_tracking_params()#

static function strip_tracking_params($url)

מסירה מה-query פרמטרים שמזהים מקור תנועה בלבד (הרשימה ב-$tracking_params, השוואה לא תלוית רישיות ואחרי urldecode) ושומרת את שאר הפרמטרים בסדרם. מחזירה: את הכתובת, או הנתיב בלבד אם לא נשאר דבר. cache_php_check משנה בעזרתה את $_SERVER['REQUEST_URI'] (לא את $_GET), כך שלחיצה עם utm_source משתמשת באותו cache כמו הכתובת הנקייה.

cache_engine::strip_tracking_params("/shop?utm_source=fb&color=red&gclid=abc");   // "/shop?color=red"

cache_engine::atomic_write()#

static function atomic_write($file, $content, $expire_ts = false)

כותבת לקובץ זמני באותה תיקייה, מגדירה לו touch($expire_ts) אם הועבר, ואז rename לשם הסופי. יוצרת את התיקייה אם חסרה. מחזירה: true בהצלחה, false בכשל. זו הדרך הנכונה לכתוב קובץ cache מותאם אישית.

cache_engine::ping_cache()#

static function ping_cache($url, $timeout = 1)

מחזירה: כלום. שולחת POST עם reload_cache=true פעמיים: כדסקטופ וכמובייל, ומעבירה את ה-cookies של הבקשה הנוכחית. עם exec זמין זה curl ברקע (&) שלא ממתין; אחרת curl עם timeout קצר.

cache_engine::try_serve_gz_direct()#

static function try_serve_gz_direct($page_file, $url)

מחזירה: כלום, ו-exit בהצלחה. מגישה את בייטי ה-.gz כמו שהם (Content-Encoding: gzip, Vary, Content-Length) במקום לפענח ולדחוס מחדש בכל hit. חוזרת בשקט (והקורא עובר למסלול הפענוח) אם PAGE::$parse_page_func מוגדר, zlib.output_compression דלוק, הלקוח לא מקבל gzip, יש output buffer שאינו ob_gzhandler או הברירת מחדל, או שלא ניתן לסווג את התוכן. נקראת מ-cache_php_check.

cache_engine::sniff_content_type_gz()#

static function sniff_content_type_gz($raw, $url)

מחזירה: Content-Type (string) או false אם אי אפשר לסווג בזול. מזהה לפי סיומת/נתיב (.json, rss/feed, .xml), ואחרת מפענחת רק את ~2KB הראשונים כדי לזהות <?xml, <rss/<feed או {; ברירת מחדל text/html; charset=UTF-8.

נעילת בנייה (build lock)#

מונעת מצב שבו אלפי מבקרים בונים במקביל את אותו עמוד אחרי שה-cache פג. הנעילה היא flock על קובץ ב-<platform>/locks[_mobile]/<sha256 של הכתובת>.lock, וחיה עד סוף הבקשה (המערכת משחררת אותה גם בקריסה).

cache_engine::acquire_build_lock()#

static function acquire_build_lock()

מחזירה: true אם הבקשה רשאית לבנות (תפסה את הנעילה, או שהנעילה כבויה/לא זמינה: "נכשלים פתוח"); false אם בקשה אחרת בונה כרגע את אותו עמוד.

cache_engine::build_lock_file()#

static function build_lock_file()

מחזירה: את נתיב קובץ הנעילה של העמוד הנוכחי (לפי get_page_url() ו-PAGE::is_mobile()).

cache_engine::build_in_progress()#

static function build_in_progress()

מחזירה: true אם בקשה אחרת מחזיקה כרגע את הנעילה של העמוד הנוכחי. לא חוסמת ולא נועלת. מחזירה false אם הבקשה הנוכחית היא הבונה.

cache_engine::wait_for_build()#

static function wait_for_build()

מחזירה: כלום. בודקת כל 50ms (עד $build_lock_wait_ms) אם העמוד הופיע (ואז cache_php_check מגיש ו-exit), ואם הבונה סיים בלי עמוד, תופסת את הנעילה ובונה בעצמה. בתום ההמתנה מסמנת $build_lock_loser = true: הבקשה תרנדר לגולש שלה, אבל לא תכתוב ל-cache.

תחזוקה וסטטיסטיקה#

cache_engine::cleanup_expired()#

static function cleanup_expired($type = 'all', $dry_run = false)

מחזירה: מערך deleted, freed_bytes, freed_mb, freed_gb, dry_run (ובמסלול המהיר גם 'method' => 'native'). מוחקת קבצים שתוקפם פג לפני יותר מ-$gc_grace_hours (48 שעות), ואז תיקיות ריקות. כשיש GNU find ו-exec פעיל, העבודה נעשית בפקודת find אחת (מהירה בהרבה), אחרת באיטרציה ב-PHP. שלוש הגנות: לא שורש ה-cache עצמו, לא מחוץ לשורש (בודקת realpath), ובלי תיקיית דומיין כשה-SERVER_NAME חשוד.

$preview = cache_engine::cleanup_expired('pages', true);   // כמה היה נמחק
$result  = cache_engine::cleanup_expired('all', false);

cache_engine::cleanup_empty_dirs()#

static function cleanup_empty_dirs($folder)

מוחקת תיקיות ריקות ברקורסיה בתוך $folder (ואת $folder עצמה אם התרוקנה). מחזירה: כלום. נקראת מ-cleanup_expired במסלול ה-PHP; במסלול ה-GNU find הניקוי נעשה בפקודה נפרדת, וה-folder העליון אינו נמחק.

cache_engine::compress_existing_cache()#

static function compress_existing_cache($dry_run = false, $type = 'all')

מחזירה: מערך converted, original_bytes/mb, saved_bytes/mb/gb, compression_ratio (אחוזים), dry_run, errors (רשימת הודעות). ממירה קבצים לא דחוסים ל-.gz בשמירת ה-mtime (התוקף), ומוחקת את המקור. מדלגת על קובץ שכבר יש לו .gz. ב-dry-run החיסכון הוא הערכה (יחס 0.25 ל-HTML ו-0.40 לנתונים).

cache_engine::get_stats()#

static function get_stats()

מחזירה: מערך עם המפתחות pages, pages_mobile, items, data, total. כל אחד הוא התוצאה של get_folder_stats (ל-total גם size_mb ו-size_gb). data סופר רק קבצי .chc ו-.chc.gz ישירות בתיקיית הדומיין (לא ברקורסיה); items נספר בשורש המשותף.

cache_engine::get_folder_stats()#

static function get_folder_stats($folder, $recursive = true)

מחזירה: מערך files, size_bytes, expired (קבצים ש-filemtime < time()), compressed (.gz), uncompressed, ו-size_mb (רק כשהתיקייה קיימת). תיקייה שלא קיימת מחזירה אפסים בלי size_mb. עם $recursive = false נספרים רק .chc ו-.chc.gz.

פונקציה גלובלית: cache_glob_recursive()#

function cache_glob_recursive($pattern, $flags = 0)

מחזירה: מערך נתיבים של קבצי .html ו-.html.gz שמתחילים ב-$pattern, או שנמצאים בתיקייה בשם $pattern, וברקורסיה בכל תת-תיקייה. זה מנגנון הבחירה של cache_all_page_remove ל"כל מה שמתחת לכתובת"; ה-$pattern הוא prefix ללא ולידציה, ותווי glob (*, ?) בו יתפרשו.

ראו גם#

• סקירת המטמון: איך נבנים ומתבטלים המטמונים והיחס ביניהם.
• מטמון עמוד שלם: cache_all_page, מובייל, stale ונעילה.
• cache-api: דפוסי שימוש במטמון הנתונים וב-items.
• ניהול מטמון בפאנל: ניקוי, סטטיסטיקה ודחיסה מהאדמין.
• DB: is_table_exists ו-is_column_exists שמסתמכים על cache_engine::get.
• ref-config: CONFIG::$allow_cache, CONFIG::$cache_folder.
• הקשחה: הרשאות כתיבה לתיקיית ה-cache ו-reload_cache.