Mencipta dan Menjalankan Projek Phalcon

Apa Itu Phalcon?

Phalcon ialah kerangka kerja web PHP sumber terbuka yang berprestasi tinggi, dibangunkan sebagai ekstensi C. Pendekatan unik ini membolehkan Phalcon menggunakan sumber yang sangat minimum dan menawarkan kelajuan eksekusi yang sangat pantas, mengatasi kebanyakan kerangka PHP tradisional. Phalcon mengamalkan pola seni bina MVC (Model-View-Controller) serta menyediakan pelbagai komponen kaya seperti ORM (Object Relational Mapping), enjin templat, routing, caching, pengurusan acara dan banyak lagi bagi membolehkan pembangun membina aplikasi web dan API berkuasa dengan cepat dan cekap.

Ciri-Ciri Utama & Kelebihan Phalcon

• Prestasi Hebat: Beroperasi sebagai ekstensi C, Phalcon mengelakkan kos parsing dan pemuatan skrip PHP dan menawarkan prestasi setaraf native.
• Cekap Sumber: Penggunaan memori yang sangat rendah, sesuai untuk aplikasi yang memerlukan prestasi tinggi dan boleh diskala.
• Ciri-ciri Lengkap: Merangkumi kebanyakan komponen teras untuk pembangunan aplikasi web, mengurangkan kebergantungan kepada pustaka pihak ketiga.
• Mudah Digunakan: Menyediakan API yang jelas, konsisten serta dokumentasi yang terperinci, membolehkan pembangun baru untuk memahami dengan mudah.
• Sangat Modular: Setiap komponen direka bentuk secara berdikari; anda bebas memilih atau menggantikan komponen mengikut keperluan projek.
• Selamat: Menyediakan pelbagai komponen berkaitan keselamatan seperti penapisan input, perlindungan CSRF dan lain-lain.

Phalcon ialah pilihan ideal untuk membangunkan aplikasi web dan API yang berprestasi tinggi serta boleh diskala, terutamanya bagi projek yang mementingkan kepantasan dan kecekapan penggunaan sumber.

Mencipta & Menjalankan Projek Phalcon Menggunakan ServBay

ServBay ialah persekitaran pembangunan web tempatan untuk macOS yang dioptimumkan, menggabungkan pelbagai versi PHP, pangkalan data (seperti MySQL, PostgreSQL, MongoDB, Redis) dan pelayan web (Caddy, Nginx, Apache), bersama alat pembangun lain. Dengan ServBay, anda boleh menyediakan dan mengurus persekitaran yang diperlukan untuk projek Phalcon dengan mudah.

Panduan ini akan membimbing anda mencipta projek Phalcon asas menggunakan persekitaran PHP ServBay, konfigurasikan pelayan web agar boleh diakses, serta demonstrasi bagaimana untuk integrasi pangkalan data berhubung (MySQL) dan pangkalan data NoSQL (Redis).

Prasyarat

Sebelum bermula, pastikan anda memenuhi syarat berikut:

1. ServBay Telah Dipasang dan Dijalankan: Pastikan ServBay telah berjaya dipasang dan dijalankan di macOS anda.
2. Versi PHP Yang Diperlukan Telah Diaktifkan: Dalam ServBay, pastikan versi PHP yang anda akan gunakan telah diaktifkan.
3. Modul Phalcon Telah Diaktifkan: ServBay menyertakan modul Phalcon secara lalai, tetapi ia mungkin tidak diaktifkan secara automatik. Sila aktifkan ekstensi Phalcon untuk versi PHP berkaitan mengikut dokumentasi Cara Mengaktifkan Modul Phalcon ServBay dan mulakan semula servis PHP.
4. Composer Telah Sedia Digunakan: ServBay menyediakan Composer secara terbina dalam, jadi anda tidak perlu memasang secara berasingan. Pastikan anda boleh menggunakan arahan composer dalam terminal.

Pelbagai Versi Phalcon dan DevTools

Versi kerangka kerja Phalcon dan alat pembangun (Phalcon DevTools) mesti serasi dengan versi PHP yang anda gunakan. Jadual berikut memaparkan hubungan padanan antara versi PHP yang biasa digunakan dengan versi Phalcon dan DevTools yang disarankan:

Versi PHP	Versi Phalcon Disyorkan	Versi Phalcon DevTools Disyorkan	Catatan
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1 (atau 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (rasmi)	DevTools rasmi mungkin mempunyai isu keserasian di PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (repositori fix)	Disyorkan guna versi komuniti-fix untuk keserasian yang lebih baik.

PERHATIAN: Untuk PHP 8.x ke atas, DevTools rasmi mungkin tidak serasi sepenuhnya. Sangat digalakkan guna versi fix yang disediakan komuniti. Langkah menggunakan versi fix melalui Composer akan diterangkan lanjut.

Membina Projek Phalcon

Cadangan Lokasi Simpanan Laman Web

Bagi memudahkan pengurusan, ServBay mencadangkan semua projek laman web diletakkan di direktori root lalai /Applications/ServBay/www. Demonstrasi ini juga akan menggunakan direktori tersebut.

1. Masuk ke Direktori Root Laman & Cipta Folder Projek

   Buka terminal, navigasi ke root laman ServBay dan cipta folder baru (cth. servbay-phalcon-app):

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

2. Pasang Phalcon DevTools

   Phalcon DevTools adalah set alat baris arahan bagi membantu pembangun menjana kod, struktur projek, migrasi pangkalan data dan sebagainya. Pasangkan mengikut versi PHP yang anda pilih:

   • Untuk PHP 5.6, 7.0, 7.1 (Phalcon DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • Untuk PHP 7.2, 7.3, 7.4 (Phalcon DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • Untuk PHP 8.0, 8.1, 8.2, 8.3, 8.4 (DevTools dev-master versi fix): Disebabkan isu keserasian DevTools rasmi dengan PHP 8.x, anda perlu gunakan versi komuniti. Tambah konfigurasi repositori berikut ke composer.json dalam direktori projek:

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     Kemudian, jalankan:

     composer update

   Composer akan mencipta direktori vendor di root projek, dan fail boleh laksana DevTools akan berada di vendor/bin/phalcon.

3. Guna Phalcon DevTools untuk Hasilkan Rangka Projek

   Jalankan perintah berikut untuk membina rangka asas projek (struktur sebenar kod diletakkan dalam subdirektori):

   vendor/bin/phalcon project servbay-phalcon-app

   Ini akan mewujudkan direktori baru /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app dengan struktur penuh projek Phalcon.

4. Navigasi ke Direktori Kod Projek

   Selepas rangka projek dijana, masuk ke direktori kod projek:

   cd servbay-phalcon-app

   Anda kini berada di /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Konfigurasi Persekitaran Projek

Konfigurasi utama Phalcon biasanya dibuat dalam fail app/config/config.php. Pastikan bahagian sambungan pangkalan data dan tetapan utama telah diisi.

1. Edit Fail Konfigurasi

   Gunakan editor kod untuk buka fail /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php. Cari atau tambahkan bahagian konfigurasi pangkalan data. Pengguna lalai MySQL/MariaDB ServBay ialah root dengan kata laluan kosong, namun anda sangat digalakkan menetapkan kata laluan kukuh pada pengeluaran. Gantikan password dan nama pangkalan data dengan maklumat sebenar anda.

   return new \Phalcon\Config([
       // ... konfigurasi lain ...
       'database' => [
           'adapter' => 'Mysql', // Atau 'Postgres' dsb
           'host' => '127.0.0.1',
           'username' => 'root', // Pengguna root ServBay
           'password' => 'password', // <-- Gantikan dengan kata laluan anda
           'dbname' => 'servbay_phalcon_app', // <-- Namakan pangkalan data anda
       ],
       // ... konfigurasi lain ...
   ]);

   Penting: Pastikan servis pangkalan data (cth. MySQL/MariaDB) telah dimulakan di ServBay dan maklumat pengguna serta kata laluan sepadan dengan konfigurasi ini. Pangakalan data servbay_phalcon_app juga perlu dicipta secara manual, gunakan phpMyAdmin atau Adminer jika perlu.

Konfigurasi Pelayan Web (Melalui Fungsi “Laman Web” ServBay)

Untuk mengakses projek Phalcon di pelayar, gunakan fungsi Laman Web di ServBay untuk menambah virtual host yang menunjuk ke direktori awam projek.

1. Buka Aplikasi ServBay
2. Pergi ke Tetapan 'Laman Web': Dalam antaramuka utama ServBay, klik tab 'Laman Web'.
3. Tambah Laman Baru:
   • Nama: Cth. My First Phalcon Dev Site
   • Domain: Cth. servbay-phalcon-test.local. (ServBay akan menguruskan resolusi .local ke peranti anda.)
   • Jenis Laman: Pilih PHP
   • Versi PHP: Pilih versi yang dipasang dan diaktifkan modul Phalcon.
   • Root Laman Web: Wajib, tunjuk ke public — /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Simpan: Selesaikan konfigurasi dan simpan. ServBay akan memproses perubahan, termasuk restart pelayan web jika perlu.

Rujuk Tambah Laman Web Pertama untuk langkah lebih terperinci. Selepas konfigurasi, domain .local serta tetapan pelayan web akan diuruskan oleh ServBay secara automatik.

Menambah Kod Contoh

Mari kita tambah kod ringkas untuk menyemak operasi projek ini.

1. Konfigurasi Routing

   Edit fail /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php, tambah routing mudah untuk root /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Tetapkan laluan lalai, padankan '/' ke IndexController:indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... boleh tambah routing lain di sini ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Cipta Controller

   Edit (atau cipta baru jika perlu) fail /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php, tambah method indexAction:

   <?php
   namespace App\Controllers; // Pastikan namespace betul
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Kendali permintaan ke '/'
       public function indexAction()
       {
           // Hantar respon ringkas
           return 'Hello ServBay!';
       }
   }

Akses Laman Web

Selepas semua fail disimpan, pastikan ServBay berjalan. Buka pelayar web anda dan lawati domain yang telah dikonfigurasi di ServBay:

https://servbay-phalcon-test.local

Jika konfigurasi betul, anda akan dapat melihat output Hello ServBay! di pelayar.

Integrasi Pangkalan Data

Phalcon menawarkan lapisan abstraksi pangkalan data dan ORM yang kukuh. Dengan integrasi pangkalan data pelbagai servis dalam ServBay, gabungkannya dengan projek Phalcon jadi sangat mudah. Contoh di bawah menggunakan MySQL dan Redis.

Contoh Pangkalan Data Relasi: MySQL

Demonstrasi menghubungkan, memasukkan dan mengambil data menggunakan adapter MySQL Phalcon dengan servis MySQL ServBay.

1. Cipta Struktur Pangkalan Data (Migrasi)

   Phalcon DevTools menyokong migrasi untuk pengurusan versi strukutur pangkalan data.

   • Hasilkan Fail Migrasi: Dalam direktori kod projek:

     vendor/bin/phalcon migration generate

     Ini akan cipta fail migrasi baru di migrations dengan nama seperti YYYYMMDDHHMMSS_MigrationName.php.

   • Edit Fail Migrasi: Ubahsuai method morph untuk tentukan struktur jadual users:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Nama kelas mesti selaras dengan fail
     {
         /**
          * Jalankan migrasi
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * Undur migrasi
          *
          * @return void
          */
         public function down()
         {
             // Pilihan: Logik rollback, cth. hapus jadual
             // $this->getConnection()->dropTable('users');
         }
     }

     Nota: Kelas dalam fail (cth. UsersMigration_100) mesti padan dengan nama fail migrasi.

   • Laksanakan Migrasi: Laksana perintah berikut untuk cipta jadual users dalam pangkalan data:

     vendor/bin/phalcon migration run

     Jika menghadapi isu sambungan, semak konfigurasi pada app/config/config.php serta servis MySQL/MariaDB telah dijalankan di ServBay.

2. Konfigurasi Sambungan Pangkalan Data (Sudah Selesai di Bahagian Awal)

   Pastikan konfigurasi 'database' dalam app/config/config.php betul (lalai: host 127.0.0.1, port 3306, pengguna root, kata laluan mengikut tetapan anda).

3. Tambah Routing Contoh

   Edit app/config/routes.php, tambah routing untuk operasi data pengguna:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Tambah routing untuk memasukkan data pengguna
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Tambah routing untuk memaparkan data pengguna
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Laksanakan Operasi Pangkalan Data dalam Controller

   Edit app/controllers/IndexController.php. Tambah method mysqlAddAction dan mysqlAction:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Import adapter MySQL
   use Phalcon\Db\Enum; // Untuk konstanta fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Contoh masukkan data pengguna
       public function mysqlAddAction()
       {
           // Dapatkan sambungan DB dari container atau (seperti di sini) cipta langsung
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Gantikan dengan kata laluan sebenar anda
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Masukkan rekod pengguna contoh
           $success = $connection->insert(
               'users', // nama jadual
               ['ServBay Demo User', '[email protected]'], // nilai
               ['name', 'email'] // kolum
           );
   
           // Paparkan hasil
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Contoh paparan data pengguna
       public function mysqlAction()
       {
            // Sambungan DB
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Gantikan dengan kata laluan sebenar anda
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Ambil semua pengguna
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Output dalam format JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Nota: Dalam aplikasi sebenar, digalakkan mendaftarkan sambungan DB sebagai servis dalam DI container, bukan cipta baru di setiap action.

5. Akses Contoh

   • Layari https://servbay-phalcon-test.local/mysql-add untuk menambah pengguna. Jika berjaya, anda akan nampak mesej "User added successfully."
   • Lawati https://servbay-phalcon-test.local/mysql untuk melihat data dalam format JSON.

Contoh Pangkalan Data NoSQL: Redis

Demonstrasi menggunakan Redis servis dalam Phalcon melalui ServBay, khususnya sebagai cache.

1. Pastikan Ekstensi Redis Dipasang

   Selalunya, paket PHP dalam ServBay sudah terbina dengan ekstensi Redis. Pastikan hanya diaktifkan untuk versi PHP yang digunakan (lazimnya, tidak perlu pemasangan manual).

2. Konfigurasi Sambungan Redis

   Tambahkan konfigurasi pada app/config/config.php. Servis Redis ServBay lalai beroperasi di 127.0.0.1:6379.

   return new \Phalcon\Config([
       // ... konfigurasi lain ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Index DB Redis, default 0
           'persistent' => false, // Guna sambungan persistent?
           'auth' => null, // Masukkan kata laluan jika Redis dipasang dengan password
       ],
       // ... konfigurasi lain ...
   ]);

3. Tambah Routing Demo Redis

   Edit fail app/config/routes.php dan tambah routing untuk demonstrasi cache:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // Tambah routing demo Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implementasi Redis Cache dalam Controller

   Edit fail app/controllers/IndexController.php, tambah method redisAction:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Import adapter Redis
   use Phalcon\Storage\SerializerFactory; // Import serializer factory
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Contoh cache Redis
       public function redisAction()
       {
           // Cipta factory serializer
           $serializerFactory = new SerializerFactory();
   
           // Pilihan konfigurasi Redis, pastikan selaras dengan 'cache' dalam config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'kata_laluan_redis_anda', // jika perlu
           ];
   
           // Cipta adapter Redis
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               // Jika tiada data dalam cache
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Data stored in cache.";
           } else {
               // Jika data ada dalam cache
               echo "Data found in cache: ";
           }
   
           // Return data cache (atau baru dikemas kini)
           return $cachedData;
       }
   }

   Nota: Praktis sebenar ialah daftar cache ke dalam container servis DI, supaya boleh diakses seluruh aplikasi.

5. Akses Contoh

   Layari https://servbay-phalcon-test.local/redis:

   • Akses pertama akan memaparkan "Data not found in cache, fetching from source...Data stored in cache." dan "Data fetched from source: Hello Redis from ServBay!".
   • Akses selepas itu (dalam tempoh cache) akan memaparkan "Data found in cache: " dan "Data fetched from source: Hello Redis from ServBay!" menandakan data diambil dari cache Redis.

Soalan Lazim (FAQ)

• S: Laman menunjukkan 404 Not Found, apa yang patut dibuat?
  • J: Pastikan tetapan “root laman web” di ServBay menunjuk ke direktori public Phalcon (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Sahkan pelayan web (Caddy/Nginx) dijalankan dengan baik dan domain setempat berfungsi.
• S: Ralat modul Phalcon tidak dijumpai (cth. Class 'Phalcon\Mvc\Application' not found)?
  • J: Ini bermakna ekstensi Phalcon tidak diaktifkan untuk versi PHP berkenaan. Aktifkan melalui antaramuka ServBay dan restart servis PHP. Rujuk Cara Aktifkan Modul Phalcon ServBay.
• S: Sambungan pangkalan data gagal?
  • J: Semak konfigurasi app/config/config.php — host, username, password dan nama pangkalan data. Pastikan servis MySQL/MariaDB dijalankan di ServBay, pengguna mempunyai akses serta pangkalan data sudah dicipta.

Kesimpulan

ServBay memudahkan tugas menyediakan persekitaran pembangunan tempatan berprestasi tinggi untuk kerangka kerja Phalcon. Panduan ini menerangkan proses lengkap dari penciptaan rangka projek, konfigurasi pelayan web, hingga integrasi dengan MySQL dan Redis. Dengan integrasi alat bina dalam dan antaramuka pengurusan yang mudah, anda boleh lebih fokus kepada pembangunan aplikasi menggunakan Phalcon tanpa beban pengurusan persekitaran. Semoga panduan ini membantu anda memulakan pembangunan web yang cekap menggunakan ServBay dan Phalcon!