Kirby Headless CMS: שילוב KQL, REST API ואימות

Kirby Headless CMS: הגדרת API לאינטגרציית Frontend מהירה

לקוחות מתלוננים לעיתים קרובות על טעינת עמודים איטית בעת שימוש בעיבוד הישיר של Kirby—זמני תגובה יכולים להגיע ל-2–3 שניות. מעבר לארכיטקטורת headless מפחית את ה-TTFB ל-200–400 אלפיות השנייה על ידי שמירת תגובות JSON במטמון והעברת העיבוד ל-frontend. בפרויקט אחד לחנות מקוונת על Next.js, לאחר ההעברה, ה-TTFB ירד מ-2.3 שניות ל-180 אלפיות השנייה, וה-LCP ירד ב-64%. Kirby CMS אידיאלי לכך: הוא קל משקל, כולל פלט JSON מובנה, ותוסף ה-KirbyQL (KQL) הרשמי. עם זאת, הגדרת ה-API לסביבת production דורשת תשומת לב לפרטים: אימות, CORS, ואופטימיזציית שאילתות. אנו עוזרים לך להפוך את Kirby במהירות ובאמינות ל-backend מסוג headless המוכן לאינטגרציה עם React, Next.js או Vue.

ייצוגי תוכן מובנים

Kirby יכול להציג תוכן ב-JSON דרך קבצי .json.php בתבניות. פשוט הוסף קובץ blog.json.php וגש אל /blog.json:

// site/templates/blog.json.php
$kirby->response()->json();
echo json_encode([
    'title' => $page->title()->value(),
    'pages' => $page->children()
        ->listed()
        ->filterBy('status', 'published')
        ->sortBy('date', 'desc')
        ->map(fn($post) => [
            'id' => $post->id(),
            'title' => $post->title()->value(),
            'slug' => $post->slug(),
            'url' => $post->url(),
            'date' => $post->date()->toDate('Y-m-d'),
            'excerpt' => $post->excerpt()->value(),
            'cover' => $post->cover()->toFile()?->url(),
        ])
        ->values(),
]);

שיטה זו פשוטה אך אינה מתאימה לשאילתות מורכבות עם סינון ופאג'ינציה. לגישה גמישה יותר, השתמש ב-KQL או בנתיבים מותאמים אישית.

איך לבחור בין KQL ל-REST?

KQL יכול להפחית את גודל התגובה פי 3–5 בהשוואה ל-REST, מה שחשוב במיוחד עבור מערכי נתונים גדולים או רשתות סלולריות איטיות. המעבר ל-KQL מקצץ את העברת הנתונים פי 3–5, ומפחית את עלויות ה-CDN בממוצע ב-40%.

KirbyQL — API דמוי GraphQL

התקן את תוסף ה-KQL דרך Composer: // site/templates/blog.json.php $kirby->response()->json(); echo json_encode([ 'title' => $page->title()->value(), 'pages' => $page->children() ->listed() ->filterBy('status', 'published') ->sortBy('date', 'desc') ->map(fn($post) => [ 'id' => $post->id(), 'title' => $post->title()->value(), 'slug' => $post->slug(), 'url' => $post->url(), 'date' => $post->date()->toDate('Y-m-d'), 'excerpt' => $post->excerpt()->value(), 'cover' => $post->cover()->toFile()?->url(), ]) ->values(), ]); . לאחר מכן שלח בקשת POST אל composer require getkirby/kql. דוגמה לבקשה להבאת פוסטים עם פאג'ינציה וקשרים:

// Запрос к /api/query
const response = await fetch(`${KIRBY_URL}/api/query`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${btoa(`${KIRBY_EMAIL}:${KIRBY_PASSWORD}`)}`,
  },
  body: JSON.stringify({
    query: {
      pages: {
        query: 'page("blog").children.listed.sortBy("date", "desc").paginate(12)',
        select: {
          id: true,
          title: true,
          slug: true,
          url: true,
          date: 'page.date.toDate("Y-m-d")',
          excerpt: true,
          cover: {
            query: 'page.cover.toFile',
            select: {
              url: true,
              width: true,
              height: true,
              alt: true,
            },
          },
          categories: {
            query: 'page.categories.toPages',
            select: {
              title: true,
              slug: true,
              url: true,
            },
          },
        },
        pagination: {
          page: 1,
          limit: 12,
        },
      },
    },
  }),
});

KQL נוח כי אתה מבקש רק את השדות הדרושים—מה שמפחית את גודל התגובה ומאיץ את ה-frontend. ביצועי ה-API גדלים ב-40% עם הגדרת מטמון נכונה באמצעות כותרות HTTP Cache-Control. התיעוד הרשמי של Kirby KQL מכיל תיאור תחביר מלא.

איך להגדיר אימות API?

אבטחה היא קריטית. בקונפיג של Kirby, הפעל אימות בסיסי ו-CORS. להגנה נוספת, הגדר הגבלת קצב ורשימת IP מותרים אם ה-API נגיש רק מהתשתית שלך:

// site/config/config.php
return [
    'api' => [
        'allowInsecure' => false,
        'basicAuth' => true,
        'cors' => true,
    ],
    'api.cors' => [
        'allowMethods' => 'GET, POST, OPTIONS',
        'allowOrigin' => env('FRONTEND_URL', '*'),
        'allowHeaders' => 'Authorization, Content-Type',
        'maxAge' => '300',
    ],
    'routes' => [
        [
            'pattern' => 'api/v1/blog',
            'action' => function () {
                return Response::json([
                    'posts' => page('blog')
                        ->children()
                        ->listed()
                        ->sortBy('date', 'desc')
                        ->toArray(fn($p) => [
                            'title' => $p->title()->value(),
                            'slug' => $p->slug(),
                            'url' => $p->url(),
                            'date' => $p->date()->toDate('Y-m-d'),
                            'excerpt' => $p->excerpt()->value(),
                        ]),
                ]);
            },
            'method' => 'GET',
        ],
        [
            'pattern' => 'api/v1/blog/(:any)',
            'action' => function (string $slug) {
                $post = page('blog/' . $slug);
                if (!$post) return Response::json(['error' => 'Not found'], 404);
                return Response::json([
                    'title' => $post->title()->value(),
                    'content' => $post->text()->kirbytext()->value(),
                    'date' => $post->date()->toDate('Y-m-d'),
                ]);
            },
            'method' => 'GET',
        ],
    ],
];

לסביבת production, צור משתמש לקריאה בלבד עם תפקיד /api/query. שמור את הסיסמה במשתני סביבה. השווה בין שיטות אימות:

נתיבי API מותאמים אישית

אם KQL נראה מוגזם, אתה יכול להגדיר נקודות קצה REST משלך (דוגמה למעלה בבלוק הקונפיג). נתיבים מותאמים אישית נותנים לך שליטה מלאה על פורמט התגובה והלוגיקה.

אינטגרציה עם Next.js

כדי לחבר את Kirby ל-Next.js, השתמש ב-KQL. צור כלי שאילתה. React Server Components יעילים במיוחד—הם מאפשרים בקשות בצד השרת ומעבירים JSON מוכן ללקוח ללא בקשות נוספות:

// lib/kirby.ts
const KQL_ENDPOINT = `${process.env.KIRBY_URL}/api/query`;
const AUTH = Buffer.from(`${process.env.KIRBY_API_USER}:${process.env.KIRBY_API_PASSWORD}`).toString('base64');

export async function kqlQuery(query: object) {
  const res = await fetch(KQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Basic ${AUTH}`,
    },
    body: JSON.stringify({ query }),
    next: { revalidate: 3600 },
  });
  return res.json();
}

עכשיו אתה יכול לקרוא ל-// Запрос к /api/query const response = await fetch(`${KIRBY_URL}/api/query`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${btoa(`${KIRBY_EMAIL}:${KIRBY_PASSWORD}`)}`, }, body: JSON.stringify({ query: { pages: { query: 'page("blog").children.listed.sortBy("date", "desc").paginate(12)', select: { id: true, title: true, slug: true, url: true, date: 'page.date.toDate("Y-m-d")', excerpt: true, cover: { query: 'page.cover.toFile', select: { url: true, width: true, height: true, alt: true }, }, categories: { query: 'page.categories.toPages', select: { title: true, slug: true, url: true }, }, }, pagination: { page: 1, limit: 12 }, }, }, }), }); ברכיבי השרת של Next.js. שמירה במטמון עם // site/config/config.php return [ 'api' => [ 'allowInsecure' => false, 'basicAuth' => true, 'cors' => true, ], 'api.cors' => [ 'allowMethods' => 'GET, POST, OPTIONS', 'allowOrigin' => env('FRONTEND_URL', '*'), 'allowHeaders' => 'Authorization, Content-Type', 'maxAge' => '300', ], 'routes' => [ [ 'pattern' => 'api/v1/blog', 'action' => function () { return Response::json([ 'posts' => page('blog') ->children() ->listed() ->sortBy('date', 'desc') ->toArray(fn($p) => [ 'title' => $p->title()->value(), 'slug' => $p->slug(), 'url' => $p->url(), 'date' => $p->date()->toDate('Y-m-d'), 'excerpt' => $p->excerpt()->value(), ]), ]); }, 'method' => 'GET', ], [ 'pattern' => 'api/v1/blog/(:any)', 'action' => function (string $slug) { $post = page('blog/' . $slug); if (!$post) return Response::json(['error' => 'Not found'], 404); return Response::json([ 'title' => $post->title()->value(), 'content' => $post->text()->kirbytext()->value(), 'date' => $post->date()->toDate('Y-m-d'), ]); }, 'method' => 'GET', ], ], ]; מבטיחה נתונים טריים ללא פגיעה בביצועים.

מה כלול בהגדרת Kirby Headless?

• פריסת Kirby והגדרת config.php למצב headless
• בחירה והגדרה של ה-API (KQL או REST) עם אימות ו-CORS
• יצירת משתמש לקריאה בלבד עבור ה-API
• תיעוד API (נקודות קצה, דוגמאות בקשות)
• אינטגרציה עם ה-frontend שלך (React, Next.js, Vue)
• בדיקות ביצועים ואבטחה
• הדרכת הצוות שלך על שימוש ב-API (שעה אונליין)

לוחות זמנים וניסיון

הגדרת Kirby headless בסיסית אורכת 2 עד 4 ימים, תלוי במורכבות הפרויקט. העלות מחושבת באופן אישי. לצוות שלנו יש ניסיון של למעלה מ-8 שנים עם Kirby ויותר מ-15 פרויקטים headless שיושמו. אנו מבטיחים פעילות API יציבה ותיעוד מלא. החיסכון בתקציב בהשוואה לחלופות מגיע עד 30% בזכות הארכיטקטורה הקלה של Kirby. צור קשר כדי לדון בפרויקט שלך. קבל ייעוץ על הגדרת Kirby API. פנה אלינו, ונהפוך את Kirby שלך ל-backend headless חזק.