تثبيت وتكوين Sculpin في بيئة ServBay

نظرة عامة

Sculpin هو مولّد مواقع ساكنة قوي ومرن يعتمد على PHP، وهو مثالي لبناء المدونات، مواقع الوثائق، أو أي مشروع يتطلب تحويل المحتوى الديناميكي (مثل قوالب Twig وملفات Markdown) إلى صفحات HTML ساكنة عالية الأداء. يعتمد Sculpin على Composer لإدارة الاعتمادات، ويستخدم مكونات Symfony ليمنح المطورين بيئة تطوير موثوقة ومألوفة.

ServBay هو بيئة تطوير ويب محلية مصممة خصيصًا لنظام macOS، مدمج بها العديد من الحزم الشائعة مثل PHP، Composer، قواعد البيانات (MySQL, PostgreSQL, MongoDB, Redis)، خوادم الويب (Caddy, Nginx) وغيرها، كما توفر واجهة رسومية سهلة للإدارة. باستخدام ServBay، يمكنك تبسيط إعداد بيئة تطوير Sculpin بشكل كبير على macOS، لا سيما عند التعامل مع إصدارات PHP، إدارة الاعتماديات، وإعداد خادم الويب.

في هذا الدليل، سنشرح بالتفصيل كيفية تثبيت وتكوين Sculpin داخل ServBay، وإعداد موقع ويب للتطوير المحلي.

حالات الاستخدام

• بناء مدونة ساكنة عالية الأداء باستخدام تقنية PHP.
• توليد مواقع وثائق ساكنة لمشاريع أو منتجات مفتوحة المصدر.
• إنشاء صفحات تسويقية أو مواقع شركات ساكنة بسرعة ودون الحاجة لقواعد بيانات خلفية.
• الاستفادة من محرك قوالب Twig وكتابة المحتوى بـ Markdown للاستمتاع بسرعة وأمان المواقع الساكنة.

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

1. أن يكون ServBay مثبتًا ويعمل على نظام macOS لديك. ServBay يوفر بيئة PHP اللازمة، مدير الاعتمادات Composer، وخوادم الويب (Caddy أو Nginx).
2. معرفة أساسية بالتعامل مع سطر الأوامر.
3. معرفة مفاهيم أساسية عن PHP، Composer وMarkdown.

خطوات تثبيت Sculpin

إليك الخطوات التفصيلية لتثبيت وتكوين Sculpin داخل بيئة ServBay:

الخطوة 1: إنشاء مجلد المشروع

أولاً، أنشئ مجلد مشروع جديد داخل مجلد الجذر الخاص بالمواقع لـ ServBay (/Applications/ServBay/www). سنستخدم اسم المشروع التجريبي servbay-sculpin-app.

افتح الطرفية ونفذ الأوامر التالية:

cd /Applications/ServBay/www
mkdir servbay-sculpin-app
cd servbay-sculpin-app

سيحتوي هذا المجلد على ملفات مشروع Sculpin الخاص بك.

الخطوة 2: إنشاء مشروع Sculpin باستخدام Composer

يأتي ServBay مزودًا مسبقًا بـ Composer، لذلك لا حاجة لتثبيته يدويًا. يمكنك استخدام أمر composer مباشرة في الطرفية.

سنستخدم قالب مدونة Sculpin الرسمي للانطلاق بسرعة. من داخل مجلد servbay-sculpin-app الذي أنشأته للتو، نفذ الأمر التالي:

composer create-project sculpin/sculpin-blog-skeleton .

سيقوم هذا الأمر بتحميل قالب مدونة Sculpin وجميع اعتماديته عبر Composer وتثبيتها داخل المجلد الحالي (.).

الخطوة 3: إعداد موقع ServBay

لكي تتمكن من الوصول إلى موقع Sculpin الخاص بك عبر خادم الويب في ServBay (Caddy أو Nginx)، عليك إضافة إعداد جديد لموقعك في ServBay.

1. افتح تطبيق ServBay: شغّل الواجهة الرسومية لتطبيق ServBay.
2. اذهب إلى تبويب "المواقع": انقر على تبويب "المواقع" في شريط التنقل داخل نافذة ServBay.
3. أضف موقعًا جديدًا: انقر زر "+" أسفل اليسار لإضافة إعداد موقع جديد.
4. أكمل بيانات الموقع:
   • الاسم (Name): أدخل اسمًا سهلاً للتعرف عليه، مثل My Sculpin Site.
   • النطاق (Domain): أدخل اسم النطاق الذي تود الوصول إليه محليًا، مثل servbay-sculpin.local. سيقوم ServBay تلقائيًا بإعداد解析 محلي لهذا النطاق وإصدار شهادة SSL (باستخدام CA خاص بServBay).
   • نوع الموقع (Type): اختر PHP، حيث أن Sculpin تطبيق PHP.
   • إصدار PHP (PHP Version): اختر إصدار PHP المرغوب (ServBay يدعم عدة إصدارات؛ اختر إصدارًا متوافقًا مع Sculpin ويفضّل الأحدث).
   • المجلد الجذر للموقع (Document Root): هذه الخطوة مهمة. يقوم Sculpin بتوليد ملفات HTML الساكنة داخل مجلد output_dev أو output_prod بحسب البيئة. للتطوير المحلي، اجعل مجلد الجذر يشير إلى مجلد تطوير الموقع: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. احفظ الإعدادات: بعد إدخال المعلومات، انقر على "حفظ". سيقوم ServBay تلقائيًا بتطبيق الإعدادات الجديدة على خادم الويب. غالبًا لن تحتاج لإعادة تشغيل خدمة ServBay يدويًا.

الخطوة 4: بناء موقع Sculpin

بعد إعداد الموقع في ServBay، حان الوقت لجعل Sculpin يولد الملفات الساكنة.

من الطرفية، تأكد أنك لا تزال داخل مجلد المشروع /Applications/ServBay/www/servbay-sculpin-app ثم نفّذ الأمر التالي لتثبيت الاعتماديات (لو طبقت الخطوة 2 بالفعل قد لا يكون هذا ضروريًا، لكن يوصى بتنفيذه للتأكد من تثبيت كل الاعتماديات):

composer install

ثم، نفذ أمر توليد الموقع:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: مسار الملف التنفيذي لـ Sculpin المثبت عبر Composer.
• generate: هذا هو الأمر الذي يقوم Sculpin عبره بتوليد الموقع الساكن. حيث يقرأ من مجلد source ويولد ملفات HTML في مجلد الإخراج (افتراضيًا output_dev).
• --watch: هذا الخيار يجعل Sculpin يراقب أي تغييرات في مجلد source، ويعيد بناء الموقع تلقائيًا عند وجود تعديلات، وهو أمر عملي جدًا خلال التطوير.

عندما تظهر لك رسالة "Sculpin has generated your site!" أو رسالة مشابهة، فهذا يعني أن الملفات الساكنة تم توليدها ووضعها في مجلد output_dev.

الخطوة 5: زيارة موقعك المحلي

الآن أصبح بإمكانك تصفح موقع Sculpin عبر اسم النطاق الذي أعددته في ServBay.

افتح متصفح الويب واذهب إلى النطاق الذي أعددته في الخطوة 3:

https://servbay-sculpin.local

بما أن مجلد الجذر للموقع يشير إلى output_dev وأنت تشغّل أمر sculpin generate --watch، يمكنك مراجعة أي تعديل تجريه فورًا من خلال عنوان الموقع. توليد شهادة SSL تلقائي من ServBay يوفر لك اتصال HTTPS آمن في بيئة التطوير.

تطوير المواقع باستخدام Sculpin

بعد تثبيت وتكوين Sculpin بنجاح في بيئة ServBay، يمكنك البدء في بناء موقعك الساكن. فيما يلي الخطوات الأساسية لبدء التطوير:

لمحة عن هيكل مشروع Sculpin

إلمامك بهيكل مشروع Sculpin سيساعدك بشكل كبير عند التطوير:

servbay-sculpin-app/
├── app/                # إعدادات التطبيق والتخزين المؤقت
├── output_dev/         # مجلد الإخراج للبيئة التطويرية (جذر الموقع موجه إليه عبر ServBay)
├── output_prod/        # مجلد الإخراج لبيئة الإنتاج
├── source/             # ملفات مصدر الموقع (محتوى Markdown، قوالب Twig، موارد ثابتة، إلخ)
│   ├── _layouts/       # ملفات تخطيطات Twig
│   ├── _posts/         # تدوينات المدونة بصيغة Markdown
│   ├── assets/         # الموارد الساكنة (CSS, JS, صور وغيرها)
│   └── index.md        # ملف الصفحة الرئيسية (Markdown)
├── vendor/             # اعتمادات مُدارة عبر Composer
├── sculpin.yml         # ملف التكوين الرئيسي لـ Sculpin
├── composer.json       # ملف تعريف اعتمادات Composer
└── ...ملفات أخرى

غالبية عملياتك اليومية ستدور في مجلد source.

إنشاء تدوينة جديدة

لإضافة تدوينة جديدة إلى مدونتك، فقط أنشئ ملف Markdown جديد داخل source/_posts، عادة باتباع الصيغة YYYY-MM-DD-slug.md.

على سبيل المثال، أنشئ ملفًا جديدًا باسم 2024-06-06-my-first-post.md:

---
title: "أول تدوينة لي"
date: 2024-06-06
tags: [شرح, Sculpin, ServBay]
---

# أول تدوينة لي

هذا هو محتوى أول مقال لي باستخدام Sculpin. أشارك هنا خبرتي مع ServBay وSculpin.

يمكنك كتابة المحتوى هنا باستخدام تنسيق Markdown.

## عنوان فرعي

قائمة:
- عنصر 1
- عنصر 2

بمجرد الحفظ، ولأن أمر sculpin generate --watch يعمل، سيكتشف Sculpin التغيير تلقائيًا ويعيد بناء الموقع. حدّث المتصفح عند الانتقال إلى https://servbay-sculpin.local لترى المقال الجديد.

إنشاء صفحة جديدة

لإضافة صفحة منفصلة (مثلاً "من نحن")، أنشئ ملف Markdown جديد في مجلد source، مثل about.md:

---
title: "من نحن"
layout: page.html.twig # تحديد قالب التخطيط المستخدم
---

# دليل ServBay Sculpin

هذه الصفحة تشرح كيفية بناء المواقع الساكنة باستخدام ServBay وSculpin.

بعد الحفظ، سينشئ Sculpin ملف output_dev/about/index.html (إذا تم إعداد عناوين صديقة). يمكنك زيارة هذه الصفحة محليًا عبر https://servbay-sculpin.local/about/.

تخصيص الأنماط والبرمجيات

توضع الموارد الساكنة (مثل ملفات CSS وجافاسكريبت) عادةً في source/assets. يمكنك تحرير هذه الملفات حسب رغبتك.

مثلاً، عدل ملف source/assets/css/style.css لتغيير تصميم الموقع.

خلال عملية التوليد، ستُنسخ هذه الموارد تلقائيًا إلى مجلد الإخراج. وأي تعديل تقوم به سيُكتشف عبر خيار --watch ويعاد بناء الموقع.

بناء نسخة للإنتاج

بعد إتمامك لتطوير الموقع، عليك توليد نسخة الإنتاج. عادةً، بناء الإنتاج يتضمن تحسينات مثل تصغير الملفات وغيرها.

لبناء نسخة الإنتاج نفذ الأمر التالي:

vendor/bin/sculpin generate --env=prod

سيُخرج هذا الأمر ملفات الموقع إلى مجلد output_prod. يمكنك رفع محتوى هذا المجلد لأي خدمة استضافة مواقع ساكنة (GitHub Pages, Netlify, Vercel أو خادمك الخاص).

إذا أردت معاينة نسخة الإنتاج باستخدام ServBay، فقط غير إعداد "المجلد الجذر" في إعداد الموقع ليشير إلى /Applications/ServBay/www/servbay-sculpin-app/output_prod، ثم احفظ الإعدادات وعاين الموقع بالنطاق نفسه.

ملاحظات مهمة

• تأكد أن ServBay يعمل وأن الموقع الذي أعددته نشط.
• تحقق من تشغيل أمر sculpin generate --watch في الطرفية كي يتم تحديث الموقع تلقائيًا أثناء التطوير.
• افحص إعدادات ServBay للتأكد من أن "المجلد الجذر للموقع" يشير لمجلد الإخراج المناسب (عادةً output_dev أثناء التطوير).
• يصدر ServBay شهادات SSL تلقائيًا للنطاقات من نوع .local، لكن نظام تشغيلك ربما يحتاج إلى الوثوق بـ ServBay User CA. ارجع إلى دليل ServBay لمزيد من التفاصيل.

الأسئلة الشائعة (FAQ)

س: عدّلت ملفات الموقع لكن التغييرات لا تظهر؟

ج: تأكد أنك تشغّل أمر vendor/bin/sculpin generate --watch ضمن مجلد المشروع وأنه لم يتوقف بسبب خطأ. راقب مخرجات الطرفية عن وجود أي رسائل خطأ. ثم جرب مسح ذاكرة المتصفح المؤقتة أو تصفح الموقع في وضع التصفح الخاص.

س: تظهر لي رسالة خطأ SSL عند زيارة https://servbay-sculpin.local؟

ج: ذلك بسبب كون شهادة SSL المصدّرة لنطاق .local هي شهادة موقعة ذاتيًا. عليك أن تجعل نظام التشغيل يثق بـ ServBay User CA باتباع تعليمات دليل ServBay.

س: كيف أغيّر إصدار PHP؟

ج: يمكنك تثبيت وإدارة عدة إصدارات PHP من تبويب "الحزم" داخل تطبيق ServBay. ثم عدل إعدادات موقع Sculpin من تبويب "المواقع" واختر إصدار PHP المطلوب ثم احفظ التغييرات.

س: ما هي أنظمة القوالب وأنواع الوسوم المدعومة في Sculpin؟

ج: يستخدم Sculpin محرك القوالب Twig افتراضيًا، ويدعم بشكل واسع محتوى Markdown.

الخلاصة

بفضل البيئة المدمجة التي يوفرها ServBay، أصبح تثبيت وتكوين مولّد المواقع الساكنة Sculpin على macOS أمراً سهلاً وسريعاً. وجود PHP وComposer مثبتين مسبقًا، إلى جانب سهولة إعداد خوادم الويب وشهادات SSL تلقائية، يجعل تطوير مواقع Sculpin على البيئة المحلية أكثر سلاسة. باتباعك هذا الدليل، يمكنك إنشاء بيئة تطوير Sculpin بسرعة، وبناء ومعاينة مشاريعك بأعلى كفاءة. استفد من إمكانيات Sculpin القوية وتكاملها السلس مع ServBay، وركز على صناعة محتوى مميز دون الانشغال بإعدادات البيئة المعقدة.