الفصل الخامس: تعلم YAML بالتفصيل

الآن سندخل إلى المرحلة التي تميز الشخص الذي يفهم YAML فعلاً عن الشخص الذي ينسخ ويلصق من الإنترنت.

معظم الناس يحفظون:

name: Laravel CI

لكنهم لا يعرفون:

ما هو name
ما هو Laravel CI
لماذا توجد :
لماذا لا توجد { }
لماذا لا توجد ;

نحن سنفهم كل حرف.

كيف يفكر YAML؟

قبل أي شيء يجب أن تعرف أن YAML عبارة عن:

Key: Value

أي:

مفتاح : قيمة

مثل القاموس.

مثال:

name: Ahmed

يفهمها YAML:

name = Ahmed

مثال:

age: 25

يفهمها:

age = 25

مثال:

city: Ankara

يفهمها:

city = Ankara

كل YAML تقريباً مبني على هذا المفهوم.

أولاً: القيم (Values)

أبسط قيمة

name: Laravel CI

دعنا نفككها حرفاً حرفاً.

name

هذا يسمى:

Key

أو:

Property

أو:

Attribute

هو اسم الحقل.

:

النقطتان لهما معنى مهم جداً.

تعني:

القيمة تبدأ هنا

بدون النقطتين:

❌

name Laravel CI

هذا خطأ.

يجب:

✅

name: Laravel CI

Laravel CI

هذه تسمى:

Value

القيمة المخزنة داخل المفتاح.

تمثيلها ذهنياً:

name
 │
 └── Laravel CI

أو:

{
  "name": "Laravel CI"
}

أنواع القيم

نص String

name: Laravel CI

app: CloudSoft

country: Turkey

كلها نصوص.

رقم Number

port: 3306

version: 8

workers: 10

هنا YAML يفهم أنها أرقام.

Boolean

القيم المنطقية.

ssl: true

debug: false

يفهمها:

صح
خطأ

Null

لا توجد قيمة.

password: null

أو:

password:

معناها:

لا توجد قيمة

مثال واقعي

application:
  name: CloudSoft
  version: 1.0
  debug: false

يفهمها YAML:

application
│
├── name = CloudSoft
├── version = 1.0
└── debug = false

ثانياً: القوائم Lists

القائمة تعني:

مجموعة عناصر

مثال حياتي:

لديك فروع Git:

main
develop
staging

كيف نكتبها؟

branches:
  - main
  - develop
  - staging

دعنا نفككها.

branches

اسم القائمة.

branches:

معناها:

سأبدأ قائمة اسمها branches

–

هذه الشرطة مهمة جداً.

تعني:

عنصر جديد داخل القائمة

مثال:

branches:
  - main

يفهمها YAML:

branches
└── main

مثال:

branches:
  - main
  - develop

يفهمها:

branches
├── main
└── develop

مثال أكبر:

branches:
  - main
  - develop
  - testing
  - production

تصبح:

branches
├── main
├── develop
├── testing
└── production

JSON المقابل:

{
  "branches": [
    "main",
    "develop",
    "testing",
    "production"
  ]
}

لماذا القوائم مهمة في GitHub Actions؟

ستراها دائماً.

مثال:

on:
  push:
    branches:
      - main
      - develop

المعنى:

شغل Workflow إذا حدث Push على:

main
أو
develop

قائمة تحتوي أرقام

ports:
  - 80
  - 443
  - 3306

تمثيلها:

ports
├── 80
├── 443
└── 3306

قائمة تحتوي كلمات

services:
  - nginx
  - mysql
  - redis

تمثيلها:

services
├── nginx
├── mysql
└── redis

ثالثاً: الكائنات Objects

وهذا الجزء هو أهم شيء لفهم GitHub Actions.

الكائن:

شيء يحتوي خصائص بداخله

مثال:

لدينا قاعدة بيانات.

قاعدة البيانات لها:

Host
Port
Username
Password

نكتب:

database:
  host: localhost
  port: 3306

دعنا نفككها.

database

اسم الكائن.

database:

معناها:

سأبدأ كائناً اسمه database

host

خاصية داخل الكائن.

host: localhost

تعني:

host = localhost

port

خاصية أخرى.

port: 3306

تعني:

port = 3306

الشجرة:

database
├── host
└── port

JSON:

{
  "database": {
    "host": "localhost",
    "port": 3306
  }
}

مثال أكبر

server:
  host: 192.168.1.10
  port: 80
  ssl: true

تمثيلها:

server
├── host
├── port
└── ssl

كائن داخل كائن

وهذا موجود كثيراً في GitHub Actions.

application:
  database:
    host: localhost
    port: 3306

الشجرة:

application
└── database
    ├── host
    └── port

لاحظ كيف أن:

المسافات = العلاقات

رابعاً: قائمة كائنات

هذه من أكثر الأشياء استخداماً في GitHub Actions.

مثال:

users:
  - name: Ahmed
    age: 25

  - name: Ali
    age: 30

تمثيلها:

users
├── Ahmed
│   └── 25
│
└── Ali
    └── 30

JSON:

{
  "users": [
    {
      "name": "Ahmed",
      "age": 25
    },
    {
      "name": "Ali",
      "age": 30
    }
  ]
}

أين سنرى هذا في GitHub Actions؟

في:

steps:

مثال:

steps:
  - name: Install Dependencies
    run: composer install

  - name: Run Tests
    run: php artisan test

كل عنصر داخل القائمة:

- name:

هو Object كامل.

خامساً: النصوص متعددة الأسطر

وهذه من أهم الأشياء في GitHub Actions.

مثال:

run: |
  composer install
  php artisan test

دعنا نفككها.

run

المفتاح.

run:

يعني:

نفذ أوامر

|

هذا الرمز يسمى:

Literal Block Scalar

لكن لا تحفظ الاسم.

احفظ وظيفته فقط.

معناه:

احتفظ بالأسطر كما هي

أي أن كل سطر بعده يعتبر جزءاً من النص.

مثال:

run: |
  echo "Hello"

  echo "World"

الناتج:

echo "Hello"

echo "World"

مثال GitHub Actions

run: |
  composer install
  php artisan migrate
  php artisan test

GitHub ينفذ فعلياً:

composer install

php artisan migrate

php artisan test

لماذا لا نكتبها كسطر واحد؟

بدلاً من:

- run: composer install

- run: php artisan migrate

- run: php artisan test

يمكن جمعها:

run: |
  composer install
  php artisan migrate
  php artisan test

الفرق بين | و >

هذا سؤال شائع جداً.

|

يحافظ على السطور.

message: |
  Hello
  World

الناتج:

Hello
World

>

يدمج السطور.

message: >
  Hello
  World

الناتج:

Hello World

في GitHub Actions ستستخدم:

في 95% من الحالات.

كيف يقرأ GitHub ملف YAML؟

مثال:

name: Laravel CI

on:
  push:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - run: composer install

      - run: php artisan test

GitHub يبني هذه الشجرة داخلياً:

name
└── Laravel CI

on
└── push

jobs
└── test
    ├── runs-on
    │   └── ubuntu-latest
    │
    └── steps
        ├── composer install
        └── php artisan test

وهنا تبدأ بفهم السر الحقيقي:

YAML ليس لغة برمجة.

YAML عبارة عن شجرة بيانات (Data Tree)، وGitHub Actions يقرأ هذه الشجرة ثم يحولها إلى Workflow حقيقية يتم تنفيذها على Runner. وفي الدرس القادم سنبدأ أول ملف GitHub Actions حقيقي ونحلله سطراً سطراً حتى تفهم كيف تتحول هذه الشجرة إلى Pipeline تعمل فعلياً.