כיצד לשלב את Supabase עם Laravel עבור מסדי נתונים ואחסון

אינפורמטק דיגיטל » Recursos » כיצד לשלב את Supabase עם Laravel עבור מסדי נתונים ואחסון

אם אתם עובדים עם Laravel ומחויבים ל- תכנות backend ואתה מרגיש כמו לעשות את הקפיצה למסד נתונים PostgreSQL מנוהל ומודרני כמו Supabaseבטח שמתם לב שלא מספיק רק לשנות כמה משתנים בקובץ .env. ישנם פרטי חיבור, סכמות, אימות ואחסון קבצים שאם מוזנחים, עלולים להוביל לשגיאות די מסתוריות.

יתר על כן, כאשר אתם רוצים ללכת צעד קדימה ולהשתמש Supabase כאחסון קבצים כאשר משלבים את המערכת עם מערכת האחסון של Laravel, הדברים נהיים קצת יותר מורכבים: מפתחות שירות, דליים, נקודות קצה, מנהלי התקנים מותאמים אישית של Flysystem וכו'. החדשות הטובות הן שניתן לשלב הכל - מסד הנתונים, האחסון וטיפול ב-UUID - בצורה די נקייה.

חיבור Laravel למסד הנתונים Supabase

הצעד הראשון הוא ליצור פרויקט Laravel פעיל ולקשר אותו למסד הנתונים Postgres שמספק Supabase. לשם כך, אתם זקוקים לסביבה עם PHP ו-Composer עודכנו וליצור פרויקט חדש או להשתמש בפרויקט קיים. מהקונסול, פשוט צור את הפרויקט באמצעות פקודת Laravel הטיפוסית ולאחר מכן התחל להגדיר את החיבור.

לאחר שיש לכם את שלד הפרויקט, השלב הרגיל הוא להתקין מערכת אימות פשוטה. Laravel Breeze משתלב היטב מכיוון שהוא כולל תבניות להב ותהליך התחברות ורישום בסיסיזה מאפשר לך לוודא במהירות שחיבור מסד הנתונים שלך מוגדר כראוי ושאתה יכול ליצור משתמשים ללא בעיות.

כדי לקבל את פרטי החיבור, התחבר לפאנל Supabase שלך ​​וצר פרויקט מסד נתונים חדש (ניתן לעשות זאת ישירות מ- מסד נתונים חדש(אשר מפנה לאשף). אם עדיין אין לך חשבון, תראה תחילה את מסך ההרשמה; אם כבר יש לך אחד, תעבור ישירות להגדרות הפרויקט ולקטע שבו תוכל לבדוק את מחרוזת החיבור.

בתוך דף הפרויקט, במקטע החיבור, תמצא כפתור כמו "חבר" או דומה. כשתלחצו עליו, Supabase יציג לכם מספר פורמטים של מחרוזות חיבור (URI, פרמטרים בודדים וכו'). העתיקו את ה-URI המלא, אך זכרו שעליכם... להחליף את הסיסמה עבור זה שאתה משתמש בו בפועל במסד הנתונים, מכיוון שלעתים קרובות מוצג קוד ברירת מחדל או מציין מיקום.

עם מידע זה, עליך לעבור לקובץ ה-.env של פרויקט Laravel שלך ולעדכן את המשתנים DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME ו-DB_PASSWORD, או להגדיר את המשתנה DATABASE_URL אם אתה מעדיף להשתמש בפורמט המחרוזת המלאה. המטרה היא שהכל יצביע אל... אשכול פוסטגרס של Supabase ולא למארח המקומי שלך.

הגדרת מנהל ההתקן של Postgres וסכימת Supabase ב-Laravel

ב-Laravel, קובץ המפתח לתצורת מסד הנתונים הוא config/database.phpלמרות שניתן להשתמש ישירות במנהל ההתקן pgsql שמגיע עם ה-framework, בעבודה עם Supabase מקובל להחיל כמה התאמות נוספות, במיוחד בנוגע לסכמות ואפשרויות ספציפיות ל-Postgres.

תצורה אופיינית עבור Postgres ב-Laravel עשויה להיראות כך, בתוך מערך החיבורים, תחת המפתח pgsql:

'pgsql' => ,

המפתח כאן טמון בפרמטר נתיב_חיפושכברירת מחדל, Supabase משתמש בסכימה הציבורית, שהיא זו שנחשפת דרך ממשקי ה-API שלו. אם ברצונך לשמור על אפליקציית Laravel שלך נפרדת מסכימה זו ולמנוע התנגשויות בין טבלאות או מדיניות, מומלץ מאוד לשנות את ה-search_path לסכימה שלך, לדוגמה. laravel, כפי שרואים בדוגמה הקודמת.

בדרך זו, הגירות וטבלאות שנוצרו על ידי הפרויקט שלך ייווצרו בסכימה חלופית זו ולא באופן ציבורי. הפרדה זו הופכת את הניהול לקל הרבה יותר. כללי אבטחה, RLS וגישה מלוח Supabase בלי לדרוך על שום דבר שאסור לך ולשמור על מבנה מסד הנתונים מאורגן.

לאחר שתתאים את קובץ התצורה, תוכל להפעיל את ההגירות באמצעות פקודות Laravel הרגילות. פעולה זו תיצור את טבלאות האימות וכל טבלה אחרת שהגדרת. אם הכל מוגדר כהלכה, הפקודות יפעלו כנגד סופרבייס פוסטגרס בלי שתצטרכו לעשות שום דבר אחר.

לאחר השלמת ההגירות, הפעל את שרת הפיתוח עם `artisan serve` ונסה לרשום ולהתחבר משתמשים. אם לא מופיעות שגיאות חיבור או הגירה, פירוש הדבר ש-Laravel פועל. תקשורת נכונה עם Supabase ואתה יכול המשך לבנות את הלוגיקה העסקית שלך בדרך כלל.

שימוש בדרייבר ספציפי של Supabase ב-Laravel

למרות שמנהל ההתקן הסטנדרטי של pgsql עובד, יש חבילה שמוסיפה א מנהל התקן מסד נתונים של supabase עבור Laravel, והרחבת התנהגות PostgreSQL עם שיפורים שימושיים מאוד, במיוחד בנוגע לטיפול בעמודות UUID ולאופן שבו שאילתות בנויות.

חבילה זו, המופצת בשם prahsys/laravel-supabase, מותקנת דרך Composer ורושמת דרייבר נוסף בשם supabase שניתן להשתמש בו בקובץ config/database.php. באופן פנימי, היא מבוססת על דרייבר Postgres של Laravel, אך משלבת הגדרות ודקדוקי חיפוש מותאם במיוחד לסביבת Supabase הספציפית.

לאחר ההתקנה, תוכל להצהיר משהו כמו הבא בתוך מדור חיבורים:

'connections' => ,
    // otras conexiones...
],

היתרון בשימוש בדרייבר זה הוא שעדיין מקבלים את כל העוצמה של מנוע Postgres, אך הוא גם מטפל באופן אוטומטי בפרטים עדינים מסוימים של Supabase, במיוחד כשעובדים עם... UUIDs כמפתחות ראשיים או שדות קשרזה מונע את הצורך לכתוב ידנית הליהוק עבור כל שאילתה מסובכת.

החבילה תוכננה גם להתאים היטב לגרסאות מודרניות של המסגרת ו-PHP, ומציעה תאימות רשמית עם לארוול 10.x, 11.x, 12.x ועם PHP מגרסה 8.1 ואילך, כמו גם כל מסד נתונים סטנדרטי של PostgreSQL, כולל כמובן Supabase.

כדי להבטיח שהכל יעבוד כראוי, החבילה כוללת חבילת בדיקות אוטומטיות. ניתן להריץ את הבדיקות באמצעות הפקודה `composer test`, שתשתמש במסד נתונים SQLite בזיכרון לצורך מהירות, או להכין קובץ `.env.testing` המצביע על ה-Supabase שלכם ולהריץ את `composer test-supabase` כדי לאמת את ההתנהגות בסביבה אמיתית. פוסטגרס מרוחק.

ניהול UUID ב-Supabase וב-Laravel

ל-Supabase יש ייחודיות עם עמודות UUID: אם תנסה להשוות UUID ישירות עם מחרוזת טקסט ללא עיבוד טקסט, השאילתה עשויה... להיכשל או להחזיר תוצאות בלתי צפויותבמערכת Postgres "רגילה" ניתן לפתור זאת באמצעות הטלות גלובליות או אופרטורים מותאמים אישית, אך ב-Supabase התאמות אישיות גלובליות אלו אינן מותרות.

זה מרמז מאשר חקירה ישירה של הסגנון:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

זה לא יעבוד כפי שניתן לצפות. עם זאת, אם תבצעו את הליהוק המפורש:

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

השאילתה הצליחה. הבעיה היא שב-Laravel, כשכותבים שאילתות עם Eloquent או בונה השאילתות, לא רוצים לעבור לשים CAST בכל מקוםכאן נכנס לתמונה הדרייבר supabase מהחבילה הנ"ל, שדואג להוסיף את ההטלות האלה עבורכם.

כאשר מנהל ההתקן הזה פעיל, תוכל לבצע שאילתות נפוצות כמו:

$user = User::find($uuidString);
$user = User::where('id', $uuidString)->first();
$users = User::whereIn('id', )->get();

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

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

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

אם אתם רוצים שליטה טובה יותר על אילו עמודות נחשבות ל-UUID, החבילה מציעה את התכונה עמודות castUuid עבור מודלי Eloquent שלך. פשוט השתמש בו במחלקת model והגדר מערך מוגן של עמודות נוספות:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

תכונה זו עושה שלושה דברים חשובים: היא כוללת את המפתח הראשי כ-UUID כברירת מחדל, והיא מוסיפה כל עמודה שאתה מצהיר עליה במאפיין. עמודות$uuid ומעביר מידע זה לבונה השאילתות כדי שיידע היכן להחיל את ההשלכות. לפיכך, כל גישה לנתונים הכוללת UUIDs הופכת עקבי ואוטומטי.

למקרים מתקדמים אף יותרניתן לרשום גלאי עמודות UUID מותאם אישית. באמצעות חבילת PostgresGrammar, ניתן לציין פונקציית callback אשר, בהתבסס על שם העמודה או הקשר השאילתה, מחליטה האם יש להתייחס אליה כ-UUID. לדוגמה:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

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

שילוב Supabase Storage כמערכת קבצים ב-Laravel

בנוסף למסד הנתונים, פרויקטים רבים צריכים לאחסן תמונות, מסמכים או קבצים אחרים שהועלו על ידי משתמשים. Supabase כולל שירות אחסון מבוסס דליים שניתן למנף כ... דיסק Laravel באמצעות Flysystemלמטרה זו, קיים מתאם ספציפי המאפשר להתייחס ל-Supabase Storage כאל עוד דרייבר בתוך config/filesystems.php.

החבילה המדוברת מספקת מתאם Flysystem שמשתלב בצורה שקופה עם מערכת האחסון של המסגרת. היא עומדת בדרישות המינימליות של PHP >= 8.1, Laravel 10.x או 11.x ואת סיומת ה-PHP fileinfo (ext-fileinfo), אשר Laravel כבר ממליצה עליה לטיפול בקבצים. ההתקנה מתבצעת באמצעות Composer, ולאחר הכללתה, כל שעליכם לעשות הוא להגדיר את דיסק ה-supabase בתצורה.

בתיק config/filesystems.phpבתוך דיסקי המערך, תוסיף משהו דומה לפרטים הבאים:

'supabase' => ,
    ],
    'signedUrlExpires' => 60 * 60 * 24,
],

פרמטר הדלי הוא בדרך כלל פשוט ה- שם דלי האחסון שיצרת בחלונית Supabase (לדוגמה, myapp-file-uploads). נקודת הקצה היא כתובת ה-URL הבסיסית של שירות האחסון של הפרויקט, הנראית גם בחלק המתאים של החלונית, ובדרך כלל נגזרת מכתובת ה-URL והאזור של הפרויקט.

האפשרות `public` מציינת האם תוכן הדלי יטופל כציבורי כברירת מחדל. אם `true`, המתאם ייצור כתובות URL נגישות ללא חתימה מיוחדת; אם `false`, האפשרות `defaultUrlGeneration` נכנסת לתמונה, שיכולה לאלץ יצירת כתובות URL חתומות עם זמן תפוגה שצוין על ידי `signedUrlExpires`. תצורה זו מאפשרת לך לאזן את העומס. בטיחות ונוחות בהתאם לסוג הקבצים שאתה מטפל בהם.

כתובת ה-URL הכללית של הדיסק בדרך כלל נשארת ריק כך שהמתאם יגזור אותה אוטומטית מנקודת הקצה. עליך לגעת בה רק אם אתה משתמש ב- פרוקסי או CDN ביניים ואתה רוצה שהנתיבים שנוצרו יצביעו לדומיין זה במקום לדומיין Supabase המקורי.

פתרון בעיות של שגיאות העלאה והבנת המפתח לאחסון Supabase

בעיה נפוצה למדי בעת ניסיון להעלות קבצים ל-Supabase Storage מ-Laravel היא קבלת הודעות כמו "לא ניתן לכתוב קובץ במיקום: העלאות/..."זה בדרך כלל מצביע על כך שלמרות שמנהל ההתקן מוגדר, Supabase דוחה את פעולת הכתיבה עקב הרשאות לא מספיקות או מפתח שתצורתו נקבעה באופן שגוי.

בדיסק supabase של config/filesystems.php, התצורה מציינת שימוש "מפתח מורשה" בשדה המפתח, תוך ציון מפורש שמפתח לקריאה בלבד לא יעבוד. משמעות הדבר היא שעליך להשתמש במפתח שירות שיש לו הרשאות כתיבה על הדלי, לא רק במפתח API ציבורי המיועד ללקוח או מפתח המיועד לתאימות S3 ללא הרשאות שינוי.

בחלונית Supabase, בתוך מקטע תצורת ה-API והאחסון, תמצאו גם את המפתחות האנונימיים וגם את תפקיד_שירות או שווה ערךאלו הם אלה עם הרשאות מורחבות. זהו מפתח השירות הזה, ולא זה הציבורי, שעליך להציב במשתנה SUPABASE_SECRET_ACCESS_KEY, שאותו מנהל ההתקן יקרא לאחר מכן דרך env('SUPABASE_SECRET_ACCESS_KEY').

אם ביצעת בדיקה עם מפתח S3 מתצורת האחסון או עם מפתחות ה-API הגנריים מהפרויקט, סביר מאוד שלאותם אישורים אין הרשאה לכתוב לדלי הספציפי, מה שגורם לשגיאת כתיבה. שינוי ערך המפתח ל- מפתח שירות תקף עם הרשאות כתיבה ועל ידי אישור שהדלי קיים ונכתב כהלכה, הבעיה בדרך כלל נפתרת.

בנוסף למפתח, חשוב לוודא שהדלי המוגדר ב-SUPABASE_STORAGE_BUCKET תואם בדיוק לזה שנוצר בממשק Supabase, תוך התחשבות באותיות גדולות וקטנות, ושנקודת הקצה תואמת את כתובת ה-URL הנכונה עבור מופע האחסון הזה. פרט כגון תו נוסף או דומיין שגוי יכול למנוע מהמתאם לפעול. לאתר את היעד האמיתי של הקבצים.

זרימת עבודה עם Laravel Breeze, Blade ו-Supabase Storage

לאחר שהגדרתם את מסד הנתונים והאחסון שלכם, הצעד הטבעי הבא הוא לשלב הכל עם שלכם ממשק Laravel Breeze ותבניות Bladeבדרך זו, משתמשים יכולים להירשם, לאמת ולהעלות קבצים ל-Supabase מבלי לעזוב את המערכת האקולוגית של Laravel.

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

if ($request->hasFile('file')) {
    $path = $request->file('file')
        ->store('uploads', 'supabase');
}

קוד זה אומר ללרבל להשתמש בדיסק supabase והנח את הקובץ בתוך תיקיית ההעלאות הווירטואלית בתוך הדלי שהוגדר. אם המפתח ונקודת הקצה נכונים, הקובץ יועלה לאחסון Supabase, ותוכל לאחזר את הנתיב שלו או ליצור כתובות URL ציבוריות או חתומות באמצעות שיטות אחסון סטנדרטיות.

היתרון של גישה זו הוא שהאפליקציה שלך שומרת על ממשק יחיד לאחסון, ללא קשר אם היא משתמשת בדיסק מקומי, Amazon S3, Supabase או שירות נתמך אחר. החלפת ספקים מצטמצמת ל... התאם את config/filesystems.php ומשתני הסביבה, מבלי לגעת בלוגיקה העסקית.

על ידי שילוב זה עם Blade ו-Breeze, תוכלו להציע טפסי העלאה, רשימות קבצים וקישורי הורדה המשולבים במלואם בחוויית המשתמש של האפליקציה שלכם. יתר על כן, הגישה מבוססת ה-bucket והמדיניות של Supabase Storage מאפשרת לכם למנף את... בקרות גישה וכללי אבטחה כדי להגדיר מה כל משתמש יכול לראות או להוריד.

כל המערכת האקולוגית הזו של חבילות, דרייברים ותצורות מאפשרת ל-Laravel לעבוד בנוחות רבה עם Supabase, הן בהיבט של נתונים רלציוניים עם Postgres והן ב... אחסון קבצים וניהול UUIDעל ידי התאמה נכונה של המפתחות, הסכמות והמנהלי התקנים, משיגים אינטגרציה מוצקה מאוד אשר מונעת רבות מהטעויות האופייניות המתרחשות בעת ניסיון לחבר את שתי הפלטפורמות באופן ידני וללא שכבות הסיוע הללו.

חיבור Laravel עם Supabase עבור מסד נתונים ואחסון, מינוף מנהל ההתקן הייעודי של Supabase לניהול חלק של UUIDs, ושימוש במתאם Flysystem לאחסון מאפשרים לך לבנות יישומים מודרניים שבהם כל התשתית המורכבת מקופלת מאחורי הקלעים של ה-API הנקי של Laravel, החל מתהליכי הגירה ואימות ועד העלאת קבצים ל-buckets מאובטחים.