cache_engine API · WIZZO CMS Docs

כל המתודות של cache_engine הן סטטיות וציבוריות (אין להן מילת visibility, ולכן ברירת המחדל public של PHP). הדף מסודר לפי תחום: נתונים, קטעי HTML, items, עמודים שלמים, נעילת בנייה, תחזוקה. הסבר מושגי על המטמון נמצא ב-איך המטמון עובד.

בעמוד הזה system/ הוא תיקיית הליבה הפרוסה (= api/core בריפו) ו-{admin} הוא CONFIG::$admin_url של האתר.

מטמון נתונים#

חתימה	מחזירה	הערה
`get($key, $func = false, $hours = 24, $in_platform = true)`	הערך מהמטמון או מה שבנתה `$func`	ללא קובץ תקף: `$func === false` מחזיר `false`. `$func` מערך נשמר כמות שהוא. `$func` פונקציה מורצת, והתוצאה נשמרת רק אם `DB::$error_count` לא עלה בזמן הריצה (ואז היא עדיין מוחזרת)
`remove($key)`	כלום	מוחק `<key>.chc` ו-`<key>.chc.gz` בכל תיקיות הדומיינים ובשורש. התאמה לפי קידומת
`save_cache_file($key, $data, $hours = 24*7, $in_platform = true)`	כלום (`false` אם הדומיין לא תקין)	`serialize` ואחריו gzip ו-`atomic_write`. מוחק את הגרסה בפורמט ההפוך (`.chc` מול `.chc.gz`)
`get_cache_file($key, $in_platform = true)`	הערך או `false`	מעדיף `.chc.gz`, נופל ל-`.chc`. קובץ gzip פגום נמחק ומוחזר `false`

$data = cache_engine::get("price_list", function () {
    return DB::query("prices", [], "ord")->get_all("id");
}, 6);                                    // 6 שעות, בתיקיית הדומיין

cache_engine::get("shared_cfg", ["a" => 1], 24, false);   // ערך ישיר, גלובלי לכל הדומיינים
cache_engine::remove("price_list");

$key הוא נתיב יחסי ומותרים בו תווי / (התיקיות נוצרות לפי הצורך). אין סינון של .., ולכן אל תבנו מפתח מקלט משתמש בלי לנקות אותו.

remove הוא מחיקה לפי קידומת

remove("params") מוחק גם params_backup, וגם את הקבצים בתיקיות של כל הדומיינים. מי שמריץ כמה אתרים בהתקנה אחת מוחק לכולם.

קטעי HTML#

חתימה	מחזירה	הערה
`get_html($key, $func = false, $hours = 24)`	התוכן, או `false`	קובץ `<domain>/<key>.html`. תקף: מחזיר. אחרת, אם יש `$func`: מריץ, שומר ומחזיר. אין הגנת שגיאות DB
`remove_html($key)`	כלום	מוחק `<domain>/<key>*.html`

$menu = cache_engine::get_html("main_menu", function () {
    return $this->view("menu.tpl");      // מחרוזת HTML
}, 12);

Items#

Item הוא רשומה בודדת לפי id, שמשותפת לכל הדומיינים ($in_platform = false ברירת מחדל) ו-TTL קבוע של 30 יום.

חתימה	מחזירה	הערה
`set_item($type, $m_params)`	כלום	רישום "איך בונים item מסוג `$type`". חייב לרוץ לפני `get_item` באותה בקשה
`get_item($item_type, $item_id, $in_platform = false, $refresh = false, $create = true)`	הנתונים או `false`	סוג שלא נרשם, או `parse` שאינו פונקציה: `trigger_error(E_USER_ERROR)`. `$create = false` הוא קריאה בלבד
`remove_item($item_type, $item_id)`	כלום	מוחק את הקובץ ומריץ `on_refresh` אם הוגדר
`refresh_item($item_type, $item_id, $in_platform = false)`	כלום	`get_item(..., refresh=true)`: בונה מחדש מיד

מפתחות ההגדרה של set_item:

מפתח	חובה	משמעות
`parse`	כן	`function ($row, $id)` שבונה את המבנה שנשמר
`query`	לא	פונקציה שמחזירה `DB_QUERY_OBJECT`. הליבה מוסיפה לו את התנאי `queryKey = $id` ו-`limit "0,1"`. אם לא נמצאה שורה, `get_item` מחזיר `false`
`queryKey`	לא	שם העמודה לחיפוש (ברירת מחדל `"id"`)
`parse_after`	לא	`function ($data)` שמורצת בכל קריאה, גם ב-HIT, והתוצאה לא נשמרת
`on_refresh`	לא	`function ($id)` אחרי יצירה, רענון או מחיקה (למשל לבנות מחדש עמודים תלויים)

cache_engine::set_item("product_card", [
    "query"    => function () { return DB::query("products"); },
    "parse"    => function ($row, $id) { return ["id" => $id, "title" => $row["title"]]; },
    "on_refresh" => function ($id) { /* למשל ping לעמוד המוצר */ },
]);

$card = cache_engine::get_item("product_card", 42);
cache_engine::refresh_item("product_card", 42);

הקובץ נשמר ב-items/<type>/<id מפוצל לזוגות ספרות>/<id>.chc.gz, למשל id 12345 ב-items/product_card/12/34/5/12345.chc.gz. הליבה עצמה משתמשת בזה ב-tag_manager (controllers/minify.php).

עמודים שלמים#

חתימה	מחזירה	הערה
`cache_php_check($url = false)`	כלום, או `exit` ב-HIT	נקראת מ-`core.php` בתחילת כל בקשה. מגישה עמוד מהמטמון אם יש. ראו מטמון עמודים מלא
`cache_all_page($hours = 24, $set_page = false)`	כלום	נקראת מבקר האתר. מסמנת שהעמוד יישמר, ותופסת נעילת בנייה או ממתינה לבונה
`cache_all_page_save($data, $url)`	`false` אם לא נשמר	נקראת מ-`core.php` אחרי רינדור העמוד. gzip ואז `atomic_write`. לא כותבת אם הבקשה הפסידה במרוץ הבנייה
`cache_all_page_remove($url, $hard_delete = false)`	כלום	מבטלת עמוד, וכל עמוד תחת אותו נתיב. ברירת מחדל: מסמנת כפג תוקף, לא מוחקת. `true` מוחק פיזית
`cache_all_page_update($url)`	`true`	קוראת ל-`ping_cache($url)`: בנייה מחדש בפועל
`ping_cache($url, $timeout = 1)`	כלום	שולחת `POST reload_cache=true` לכתובת, פעם בדסקטופ ופעם כטלפון
`drop_page_file($file, $hard_delete = false)`	כלום	מבטלת קובץ עמוד אחד: `touch` לעבר, ואם נכשל, `unlink`. עם `$hard_delete` תמיד `unlink`
`set_page_url($url)` / `get_page_url()`	כלום / המחרוזת	מאפשרות לשמור עמוד תחת כתובת שונה מ-`REQUEST_URI`. `set_page_url` גם קוראת ל-`cache_php_check`
`strip_tracking_params($url)`	הכתובת	מסירה פרמטרי מעקב (`utm_*`, `gclid`, `fbclid` ועוד), ושומרת את שאר הפרמטרים בסדרם
`encode_url($url)`	מחרוזת	הופכת כתובת לשם קובץ בטוח. `die("Invalid URL")` על `..` או NUL
`try_serve_gz_direct($page_file, $url)`	כלום, או `exit` אחרי שליחה	שולחת את קובץ ה-gz כמות שהוא. אם אחד מתנאי הבטיחות לא מתקיים היא חוזרת בשקט והעמוד מוגש בדרך הרגילה
`sniff_content_type_gz($raw, $url)`	`Content-Type` או `false`	מזהה סוג תוכן (HTML, XML, RSS, JSON) לפי הכתובת ואחר כך לפי תחילת התוכן

נעילת בנייה#

מונעת "עדר" של בקשות שכולן בונות את אותו עמוד, כשהמטמון שלו פג.

חתימה	מחזירה	הערה
`acquire_build_lock()`	`bool`	`flock` בלתי חוסם על קובץ נעילה של הכתובת. `true` גם כשאין נעילה בפועל (כבויה, אין `flock`, או אין מטמון)
`build_lock_file()`	נתיב	`<domain>/locks[_mobile]/<sha256(url)>.lock`
`build_in_progress()`	`bool`	האם בקשה אחרת מחזיקה את הנעילה
`wait_for_build()`	כלום	בודקת כל 50 מ"ש עד `$build_lock_wait_ms`. אם הקובץ הופיע, מגישה אותו. אם הבונה סיים בלי קובץ, משתלטת. בתום הזמן מסמנת `$build_lock_loser = true`

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

חתימה	מחזירה	הערה
`cleanup_expired($type = 'all', $dry_run = false)`	`['deleted','freed_bytes','freed_mb','freed_gb','dry_run']`	מוחקת קבצים שפג תוקפם לפני יותר מ-`$gc_grace_hours`. `$type`: `all`, `pages`, `items`
`cleanup_empty_dirs($folder)`	כלום	מסירה תיקיות ריקות
`compress_existing_cache($dry_run = false, $type = 'all')`	מערך: `converted`, `original_mb`, `saved_mb`, `compression_ratio`, `dry_run`, `errors` ועוד	דוחסת קבצי מטמון קיימים ל-gzip. `$type`: `all`, `pages`, `data`
`get_stats()`	מערך	ספירה לפי `pages`, `pages_mobile`, `items`, `data` (קבצי `.chc` בשורש הדומיין בלבד) ו-`total`
`get_folder_stats($folder, $recursive = true)`	מערך	`files`, `size_bytes`, `size_mb`, `expired`, `compressed`, `uncompressed`
`atomic_write($file, $content, $expire_ts = false)`	`bool`	כותבת לקובץ זמני, מציבה תפוגה, ומחליפה ב-`rename`
`get_platform_cache_folder()`	נתיב	`<cache>/<SERVER_NAME>`, או `_invalid_host_<hash>`
`check_server_name()`	`true` תמיד	נשארה לתאימות לאחור

cleanup_expired מוגנת

המתודה מוגבלת לתיקיות שנמצאות בתוך שורש המטמון בלבד, לא נוגעת בשורש עצמו, ובודקת שהדומיין תקין. כשיש find של GNU היא משתמשת בו לריצה מהירה, אחרת סורקת ב-PHP. הגדירו $dry_run = true כדי לראות מה יימחק.

הפונקציה הגלובלית cache_glob_recursive($pattern, $flags = 0) בסוף הקובץ היא glob רקורסיבי, והליבה משתמשת בה לביטול עמודים תחת כתובת.

מטמון נתונים#

קטעי HTML#

Items#

עמודים שלמים#

נעילת בנייה#

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

ראו גם#