Membuat dan Menjalankan Projek Symfony

ServBay ialah persekitaran pembangunan web tempatan yang direka khusus untuk macOS dan Windows, mengintegrasikan pelbagai runtime seperti PHP, Node.js, Python, Go, Java, serta pangkalan data seperti MySQL, PostgreSQL, MongoDB, dan Redis. Ia turut menyokong pelayan web Apache dan Caddy. Panduan ini akan menerangkan secara terperinci cara menggunakan ServBay untuk membina dan menjalankan projek Symfony dengan cepat di macOS dan Windows.

Apakah itu Symfony?

Symfony ialah sebuah rangka kerja web PHP sumber terbuka yang dibangunkan oleh SensioLabs. Ia bertujuan membekalkan pembangun dengan set alat yang efisien, fleksibel, dan kaya fungsi untuk membina aplikasi web moden dan API. Symfony mematuhi amalan terbaik web standard serta menawarkan pelbagai komponen seperti routing, enjin templat (Twig), pengurusan borang, autentikasi, dependency injection dan lain-lain, menjadikan tugas pembangunan web harian menjadi lebih mudah dan mantap.

Ciri Utama dan Kelebihan Symfony

• Reka bentuk modular: Teras Symfony ialah perpustakaan komponen yang boleh digunakan semula; pembangun bebas memilih dan menggunakannya mengikut keperluan untuk membina aplikasi ringan atau berat.
• Prestasi tinggi: Dengan seni bina yang dioptimumkan, mekanisme cache yang efisien, dan sokongan terhadap ciri terkini PHP, Symfony memberikan prestasi yang cemerlang.
• Komuniti sokongan kuat: Disokong komuniti pembangun yang besar, pelbagai Bundle (plugin) pihak ketiga, dan dokumentasi yang terperinci, memudahkan penyelesaian masalah.
• Kelenturan: Mudah diintegrasikan dengan pelbagai pustaka dan sambungan pihak ketiga, sesuai untuk projek dari pelbagai skala dan tahap kerumitan.
• Stabil dan mudah diselenggara: Mematuhi standard pengekodan dan corak reka bentuk yang baik, aplikasi yang dibina menjadi mudah untuk diuji, diselenggara dan diperluaskan.

Symfony sesuai untuk membangunkan projek web daripada API kecil hinggalah sistem perusahaan berskala besar.

Membuat dan Menjalankan Projek Symfony dengan ServBay

ServBay membekalkan semua sokongan persekitaran yang diperlukan untuk menjalankan projek Symfony, termasuk versi PHP yang relevan, Composer, pelayan web, pangkalan data dan servis cache. Bahagian ini akan membimbing anda menggunakan kemudahan ServBay untuk membuat dan mengkonfigurasi projek Symfony baharu.

Prasyarat

Sebelum memulakan, pastikan perkara berikut telah dipenuhi:

1. ServBay telah dipasang: Anda sudah memasang dan menjalankan ServBay di macOS. Jika belum, rujuk Panduan Pemasangan ServBay.
2. ServBay berfungsi dengan baik: Servis teras ServBay (seperti Caddy atau Apache dan mana-mana pangkalan data yang diperlukan) sedang berjalan.
3. Asas pengetahuan: Anda mempunyai pengetahuan asas berkenaan PHP, Composer dan konsep asas Symfony.

Membuat Projek Symfony

ServBay mencadangkan agar semua projek laman web anda ditempatkan dalam direktori /Applications/ServBay/www, bagi memudahkan pengenalan dan pengurusan projek oleh ServBay.

1. Sahkan Composer tersedia

   Composer telah tersedia dan diintegrasikan dengan ServBay sewaktu pemasangan, serta sudah diset pada laluan persekitaran. Anda boleh sahkan dengan menjalankan composer --version di terminal.

2. Cipta direktori projek

   Buat direktori baharu dalam direktori root laman web untuk projek Symfony anda:

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

3. Cipta projek Symfony dengan Composer

   Masuk ke direktori projek, gunakan Composer untuk menghasilkan rangka kerja Symfony berasaskan website-skeleton (rupa asas dengan kebergantungan aplikasi web tradisional):

   cd /Applications/ServBay/www/servbay-symfony-app
   composer create-project symfony/website-skeleton .

   Selepas perintah ini dijalankan, Composer akan memuat turun fail teras Symfony dan kebergantungannya ke direktori semasa.

Konfigurasi Permulaan

Konfigurasi utama projek Symfony biasanya dikawal melalui pembolehubah lingkungan (environment variable) yang disimpan dalam fail .env di root projek.

1. Konfigurasi pembolehubah lingkungan (.env)

   Buka fail .env di root projek anda. Fail ini mengandungi tetapan seperti maklumat sambungan pangkalan data, kunci aplikasi dan lain-lain. Edit atau tambah konfigurasi mengikut keperluan anda.

   Pastikan tetapan berikut dikemaskini atau diubah mengikut persekitaran ServBay anda:

   # Contoh fail .env
   APP_ENV=dev # Persekitaran pembangunan
   APP_SECRET=your_secret_key # Ganti dengan rentetan rawak unik untuk keselamatan
   
   # Maklumat sambungan pangkalan data (contoh guna MySQL, penjelasan lanjut di bawah)
   # DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=8.0&charset=utf8mb4"
   # DATABASE_URL="postgresql://db_user:db_password@127.0.0.1:5432/db_name?serverVersion=13&charset=utf8"
   # DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"

   Gantikan your_secret_key dengan rentetan rawak yang selamat. Akaun pangkalan data lalai ServBay selalunya root dengan kata laluan password (pastikan tukar untuk produksi). Sebagai contoh, gunakan servbay_symfony_app sebagai nama pangkalan data.

Konfigurasi Pelayan Web (Laman ServBay)

Agar projek Symfony boleh diakses melalui pelayar, anda perlu tetapkan laman web maya menggunakan fungsi "Laman Web" ServBay. Direktori root web Symfony ialah public/ dalam projek.

Buka panel kawalan ServBay, navigasi ke tetapan "Laman Web" (atau "Host" untuk versi lama), dan tambah laman web baharu dengan tetapan berikut:

• Nama (Name): Nama yang mudah dikenal pasti, contoh My Symfony Dev Site.
• Domain (Domain): Nama domain pembangunan tempatan, contoh servbay-symfony-test.local. ServBay akan selaraskan kepada tempatan secara automatik.
• Jenis laman web (Website Type): Pilih PHP.
• Versi PHP (PHP Version): Pilih versi PHP yang serasi dengan projek Symfony anda, disyorkan versi stabil terkini ServBay seperti 8.3.
• Root laman web (Website Root): Penting! Untuk projek Symfony, root mesti merujuk pada direktori public/ projek: /Applications/ServBay/www/servbay-symfony-app/public.

Simpan dan terapkan perubahan. ServBay akan mengemaskini konfigurasi pelayan web secara automatik, serta menghasilkan dan mempercayai sijil SSL untuk domain tempatan anda, membolehkan akses langsung dengan HTTPS.

Langkah lebih terperinci rujuk Tambah Laman Web Pertama dalam ServBay.

Tambah Kod Contoh Asas

Untuk menguji konfigurasi laman web anda, tambahkan satu routing dan pengawal ringkas supaya laman mengeluarkan teks pada root path.

1. Konfigurasi routing (config/routes.yaml)

   Edit fail config/routes.yaml, tambah tetapan untuk routing root / dan hubungkan pada method pengawal bernama index:

   # config/routes.yaml
   index:
       path: /
       controller: App\Controller\DefaultController::index

2. Cipta pengawal (src/Controller/DefaultController.php)

   Dalam direktori src/Controller/, cipta fail PHP baru DefaultController.php dengan kod berikut:

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   
   class DefaultController
   {
       /**
        * @Route("/", name="index")
        */
       public function index(): Response
       {
           // Kembalikan respons HTTP ringkas
           return new Response('Hello ServBay and Symfony!');
       }
   }

   Kod di atas menghasilkan kelas pengawal DefaultController dengan method index yang dihubungkan ke path root / melalui anotasi @Route("/"). Bila root pathname diakses, method ini akan memaparkan respon teks "Hello ServBay and Symfony!".

Akses Laman Web

Sekarang, buka pelayar web anda dan lawati domain yang dikonfigurasi di ServBay: https://servbay-symfony-test.local. Jika semuanya betul, anda akan lihat output berikut:

Hello ServBay and Symfony!

Ini menandakan projek Symfony anda sudah berjaya dijalankan melalui pelayan web ServBay. ServBay melaraskan konfigurasi HTTPS secara automatik, jadi sebaiknya akses menggunakan https://.

Contoh Pangkalan Data & Cache

Symfony lazimnya menggunakan Doctrine ORM untuk pangkalan data berrelasi, dan komponen Symfony Cache untuk pengurusan cache dan pangkalan data NoSQL. ServBay menyediakan pelbagai servis pangkalan data dan extension PHP, membolehkan penggunaan mudah dalam projek Symfony.

Contoh Pangkalan Data Berrelasi (Doctrine ORM)

ServBay menyokong MySQL dan PostgreSQL. Berikut cara mengkonfigurasi dan gunakan kedua-dua jenis pangkalan data dalam Symfony.

1. Konfigurasi sambungan pangkalan data

   Dalam fail .env di root projek, uncomment dan edit DATABASE_URL mengikut jenis pangkalan data digunakan.

   • Untuk MySQL: Akaun lalai MySQL ServBay ialah root, kata laluan password, port 3306. Laraskan mengikut tetapan ServBay anda.

     # .env
     DATABASE_URL="mysql://root:password@127.0.0.1:3306/servbay_symfony_app?serverVersion=8.0&charset=utf8mb4"

   • Untuk PostgreSQL: Akaun lalai PostgreSQL ServBay ialah root, kata laluan password, port 5432.

     # .env
     DATABASE_URL="postgresql://root:password@127.0.0.1:5432/servbay_symfony_app?serverVersion=13&charset=utf8"

   Pastikan servis MySQL atau PostgreSQL dijalankan melalui panel ServBay.

2. Cipta pangkalan data

   Jika pangkalan data servbay_symfony_app belum ada, anda boleh cipta secara manual melalui pengurus pangkalan data (seperti phpMyAdmin atau pgAdmin di panel ServBay) atau guna arahan Symfony:

   php bin/console doctrine:database:create

3. Cipta Entity dan migration

   Entity Doctrine digunakan untuk mewakili jadual pangkalan data. Gunakan Maker Bundle untuk menjana Entity dan migration.

   • Cipta Entity (contoh User):

     php bin/console make:entity User

     Tambah medan seperti name (string) dan email (string, unique=yes) mengikut arahan.
   • Cipta migration: Janakan migration berdasarkan perubahan Entity:

     php bin/console make:migration

     Migration baru akan dicipta dalam direktori src/Migrations, mengandungi arahan SQL untuk jadual users.

4. Laksanakan migration

   Jalankan migration untuk terapkan skema pada pangkalan data anda:

   php bin/console doctrine:migrations:migrate

5. Tambah contoh operasi pangkalan data

   Edit src/Controller/DefaultController.php untuk menambah routing dan method contoh penggunaan Doctrine bagi menulis dan membaca data. Inject EntityManagerInterface untuk interaksi pangkalan data.

   Pastikan konstruktor DefaultController menerima EntityManagerInterface:

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface; // Import EntityManagerInterface
   use App\Entity\User; // Import User entity
   use Symfony\Component\HttpFoundation\JsonResponse; // Untuk respon JSON
   
   class DefaultController
   {
       private $entityManager;
   
       // Inject EntityManagerInterface
       public function __construct(EntityManagerInterface $entityManager)
       {
           $this->entityManager = $entityManager;
       }
   
       /**
        * @Route("/", name="app_index")
        */
       public function index(): Response
       {
           return new Response('Hello ServBay and Symfony!');
       }
   
       // ... method lain ...
   }

   Seterusnya, tambah routing berikut dalam config/routes.yaml:

   # config/routes.yaml
   # ... routing lain ...
   mysql_add_user:
       path: /mysql-add-user # atau /pgsql-add-user mengikut pangkalan data
       controller: App\Controller\DefaultController::addUser
   mysql_get_users:
       path: /mysql-users # atau /pgsql-users
       controller: App\Controller\DefaultController::getUsers

   Tambah method berikut dalam src/Controller/DefaultController.php:

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface;
   use App\Entity\User;
   use Symfony\Component\HttpFoundation\JsonResponse; // Import JsonResponse
   
   class DefaultController
   {
       private $entityManager;
   
       public function __construct(EntityManagerInterface $entityManager)
       {
           $this->entityManager = $entityManager;
       }
   
       /**
        * @Route("/", name="app_index")
        */
       public function index(): Response
       {
           return new Response('Hello ServBay and Symfony!');
       }
   
       /**
        * @Route("/add-user", name="app_add_user")
        */
       public function addUser(): Response
       {
           $user = new User();
           // Data contoh berkaitan jenama ServBay
           $user->setName('ServBay Demo User');
           $user->setEmail('demo-user@servbay.test');
   
           // Persista objek (sedia untuk disimpan)
           $this->entityManager->persist($user);
           // Laksanakan penulisan data
           $this->entityManager->flush();
   
           return new Response('User berjaya ditambah!');
       }
   
       /**
        * @Route("/get-users", name="app_get_users")
        */
       public function getUsers(): JsonResponse
       {
           // Ambil semua entiti User dari pangkalan data
           $users = $this->entityManager->getRepository(User::class)->findAll();
   
           // Tukar ke array untuk JsonResponse
           $usersArray = [];
           foreach ($users as $user) {
               $usersArray[] = [
                   'id' => $user->getId(),
                   'name' => $user->getName(),
                   'email' => $user->getEmail(),
               ];
           }
   
           // Kembalikan respons JSON
           return new JsonResponse($usersArray);
       }
   }

6. Uji fungsi

   • Layari https://servbay-symfony-test.local/add-user untuk menambah pengguna.
   • Layari https://servbay-symfony-test.local/get-users untuk melihat senarai pengguna (dalam format JSON).

Contoh Cache & Pangkalan Data NoSQL (Symfony Cache)

ServBay telah mendukung Redis dan Memcached, berserta extension PHP yang bersesuaian, membolehkan penggunaan langsung melalui Symfony Cache.

1. Konfigurasi sambungan cache

   Tetapkan sambungan cache dalam fail .env.

   • Memcached: Port lalai ialah 11211.

     # .env
     # ... konfigurasi lain ...
     CACHE_DSN=memcached://127.0.0.1:11211

     Pastikan servis Memcached dijalankan di ServBay.
   • Redis: Port lalai ialah 6379.

     # .env
     # ... konfigurasi lain ...
     CACHE_DSN=redis://127.0.0.1:6379
     # Sekiranya Redis perlukan kata laluan (lalai ServBay tiada), gunakan:
     # CACHE_DSN=redis://:your_password@127.0.0.1:6379

     Pastikan servis Redis dijalankan melalui panel ServBay.

2. Tambah contoh penggunaan cache

   Edit src/Controller/DefaultController.php, tambah routing dan method contoh penggunaan Symfony Cache yang berinteraksi dengan Memcached atau Redis. Inject CacheInterface.

   Pastikan konstruktor DefaultController menerima parameter CacheInterface:

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface;
   use App\Entity\User;
   use Symfony\Component\HttpFoundation\JsonResponse;
   use Symfony\Contracts\Cache\CacheInterface; // Import CacheInterface
   
   class DefaultController
   {
       private $entityManager;
       private $cache; // Property cache
   
       // Inject CacheInterface dalam konstruktor
       public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
       {
           $this->entityManager = $entityManager;
           $this->cache = $cache; // Set cache
       }
   
       // ... method lain ...
   }

   Tambah routing baharu dalam config/routes.yaml:

   # config/routes.yaml
   # ... routing lain ...
   cache_example:
       path: /cache-example
       controller: App\Controller\DefaultController::cacheExample

   Tambah method berikut pada src/Controller/DefaultController.php:

   <?php
   // src/Controller/DefaultController.php
   namespace App\Controller;
   
   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Routing\Annotation\Route;
   use Doctrine\ORM\EntityManagerInterface;
   use App\Entity\User;
   use Symfony\Component\HttpFoundation\JsonResponse;
   use Symfony\Contracts\Cache\CacheInterface;
   use Symfony\Component\Cache\Item\ItemInterface; // Import ItemInterface
   
   class DefaultController
   {
       private $entityManager;
       private $cache;
   
       public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
       {
           $this->entityManager = $entityManager;
           $this->cache = $cache;
       }
   
       // ... method lain ...
   
       /**
        * @Route("/cache-example", name="app_cache_example")
        */
       public function cacheExample(): Response
       {
           // Cuba dapatkan data dari cache
           $cacheItem = $this->cache->get('my_symfony_cache_key', function (ItemInterface $item) {
               // Callback jika cache tidak ada
               $item->expiresAfter(3600); // Simpan cache selama sejam
   
               // Simulasi proses berat (contoh query database)
               $data = "Data dihasilkan pada " . date('Y-m-d H:i:s');
   
               // Kembali data untuk disimpan dalam cache
               return $data;
           });
   
           // $cacheItem ialah data dalam cache jika ada, atau data baru
           $output = "Daripada Cache: " . $cacheItem;
   
           return new Response($output);
       }
   }

3. Uji cache

   • Layari https://servbay-symfony-test.local/cache-example. Kali pertama dipanggil, callback dijalankan dan data disimpan dalam cache. Lawatan seterusnya akan terus membaca dari Memcached atau Redis selagi cache belum luput.

Soalan Lazim (FAQ)

S: Saya lawati https://servbay-symfony-test.local tetapi laman hilang atau keluar ralat 500, apa perlu buat?

J: Semak perkara berikut:

1. Pastikan ServBay sedang berjalan dan servis laman web (Caddy atau Apache) telah dimulakan.
2. Periksa tetapan "Laman Web" ServBay: domain servbay-symfony-test.local mesti betul, dan root laman web tepat ke /Applications/ServBay/www/servbay-symfony-app/public.
3. Rujuk log projek Symfony (var/log/dev.log) untuk maklumat ralat lanjut.
4. Jalankan composer install di direktori projek untuk pastikan semua kebergantungan dipasang.
5. Pastikan versi PHP yang digunakan serasi dengan projek Symfony.

S: Kenapa tidak boleh sambung pangkalan data?

J: Semak perkara berikut:

1. Pastikan servis pangkalan data (MySQL atau PostgreSQL) telah dimulakan dalam panel ServBay.
2. Periksa tetapan DATABASE_URL dalam .env (pengguna, kata laluan, host 127.0.0.1, port MySQL 3306/PostgreSQL 5432 dan nama pangkalan data).
3. Pastikan pengguna dan kata laluan betul (lalai atau yang telah diubah).
4. Pastikan pangkalan data servbay_symfony_app telah wujud.

S: Kenapa php bin/console tidak boleh dijalankan?

J: Pastikan terminal aktif dalam direktori /Applications/ServBay/www/servbay-symfony-app, dan PHP ServBay telah dikonfigurasi ke PATH sistem (ServBay akan set ini secara automatik). Anda boleh semak dengan which php untuk pastikan PHP dari ServBay digunakan.

Rumusan

Dalam panduan ini, anda telah berjaya menggunakan ServBay untuk membina, mengkonfigurasi dan menjalankan projek Symfony asas di macOS. ServBay menyediakan semua komponen utama pembangunan Symfony (PHP, Composer, pelayan web, pangkalan data, cache), serta memudahkan proses konfigurasi, membolehkan anda terus mula membina aplikasi. Anda boleh memperluas projek asas ini untuk menguasai lebih banyak ciri Symfony dan memanfaatkan perkhidmatan tambahan yang disediakan oleh ServBay.