Membina dan Menjalankan Projek Phalcon

Apa itu Phalcon?

Phalcon merupakan sebuah kerangka kerja PHP sumber terbuka berprestasi tinggi yang dibangunkan sebagai sambungan C. Kaedah ini membolehkan Phalcon menggunakan sumber secara minimum tetapi mempercepatkan proses pelaksanaan aplikasi web PHP secara ketara, menjadikannya jauh lebih efisien berbanding kerangka tradisional. Phalcon mematuhi seni bina MVC (Model-View-Controller) dan menyediakan pelbagai komponen, seperti ORM (Object-Relational Mapping), enjin templat, penghalaan, caching, pengurus acara, dan banyak lagi — semua direka untuk membantu anda membina aplikasi web dan API yang mantap dengan pantas.

Ciri-ciri Utama & Kelebihan Phalcon

• Prestasi unggul: Dengan dijalankan sebagai sambungan C, Phalcon mengurangkan beban pemuatan dan analisis skrip PHP, menawarkan prestasi natif.
• Cekap sumber: Penggunaan memori yang minimum, sesuai untuk aplikasi yang memerlukan prestasi dan skalabiliti tinggi.
• Fungsi menyeluruh: Hampir semua komponen teras pembangunan web sudah tersedia secara terbina, mengurangkan kebergantungan pada pustaka pihak ketiga.
• Mudah digunakan: API yang konsisten dan dokumentasi komprehensif membolehkan pembangun baru atau berpengalaman memahami dengan cepat.
• Sangat terpisah: Komponen direka secara modular, membolehkan pembangun memilih atau mengganti komponen mengikut keperluan projek.
• Selamat: Menyediakan pelbagai komponen berkaitan keselamatan, seperti penapisan input dan perlindungan CSRF.

Phalcon adalah pilihan terbaik untuk membina aplikasi web dan API yang pantas serta mudah dikembangkan, terutamanya di mana kecekapan sumber dan laju menjadi faktor utama.

Membina dan Menjalankan Projek Phalcon dengan ServBay

ServBay adalah persekitaran pembangunan web tempatan untuk macOS yang sudah menyatukan pelbagai versi PHP, pangkalan data (MySQL, PostgreSQL, MongoDB, Redis) dan pelayan web seperti Caddy, Nginx, serta Apache — berserta alat pembangun lain. Dengan ServBay, anda boleh membina dengan mudah persekitaran lengkap untuk projek Phalcon anda.

Panduan ini akan membantu anda menggunakan persekitaran PHP dalam ServBay untuk membina projek Phalcon asas, menetapkan pelayan web supaya boleh diakses, dan menunjukkan cara integrasi dengan pangkalan data (MySQL) serta NoSQL (Redis).

Keperluan Awal

Pastikan perkara berikut tersedia sebelum memulakan:

1. ServBay telah dipasang dan berjalan: Pastikan ServBay sudah dipasang dan dihidupkan di sistem macOS anda.
2. Versi PHP yang diperlukan telah diaktifkan: Pastikan versi PHP yang anda ingin gunakan telah diaktifkan dalam ServBay.
3. Modul Phalcon telah diaktifkan: ServBay dilengkapi modul Phalcon, tetapi biasanya tidak diaktifkan secara lalai. Rujuk arahan di Cara Mengaktifkan Modul Phalcon ServBay untuk mengaktifkannya bagi versi PHP pilihan anda, kemudian mulakan semula servis PHP.
4. Composer boleh digunakan: ServBay sudah mempunyai Composer bawaannya, jadi tiada pemasangan tambahan diperlukan. Pastikan anda boleh menjalankan arahan composer di terminal.

Versi Phalcon dan DevTools yang Bersesuaian

Versi kerangka Phalcon dan alat pembangun (Phalcon DevTools) perlu serasi dengan versi PHP yang digunakan. Jadual di bawah menunjukkan padanan versi PHP, Phalcon dan DevTools yang disyorkan:

Versi PHP	Versi Phalcon Disyorkan	Phalcon DevTools Disyorkan	Nota
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 bermasalah pada PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (versi baik pulih)	Disyorkan gunakan versi komuniti untuk keserasian yang lebih baik.

Nota Penting: Untuk PHP 8.x dan ke atas, DevTools rasmi mungkin tidak serasi sepenuhnya. Guna versi baik pulih komuniti untuk pengalaman terbaik. Langkah pemasangan DevTools komuniti ditunjukkan dalam bahagian berikut.

Membina Projek Phalcon

Laluan simpan projek yang disyorkan

Untuk kemudahan pengurusan, ServBay mengesyorkan anda meletakkan projek web di direktori lalai /Applications/ServBay/www. Contoh dalam dokumen ini juga akan menggunakan laluan ini.

1. Masuk ke direktori web root dan cipta folder projek

   Buka terminal, masuk ke direktori root laman ServBay dan cipta folder projek Phalcon (misal servbay-phalcon-app):

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

2. Pasang Phalcon DevTools

   Phalcon DevTools ialah alat baris arahan untuk menjana kod, rangka projek, migrasi pangkalan data dan banyak lagi. Anda boleh pasang melalui Composer. Arahan berbeza mengikut versi PHP:

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

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • PHP 8.0, 8.1, 8.2, 8.3, 8.4 (Phalcon DevTools dev-master versi komuniti): Oleh sebab DevTools rasmi kurang serasi dengan PHP 8.x, gunakan versi komuniti. Tambahkan konfigurasi versi baik pulih ke fail composer.json dalam root projek /Applications/ServBay/www/servbay-phalcon-app:

     {
        "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 dalam folder projek (servbay-phalcon-app) dan fail boleh laku DevTools di vendor/bin/phalcon.

3. Menjana rangka projek dengan DevTools

   Gunakan DevTools untuk menghasilkan struktur asas projek Phalcon. Kod projek sebenar ditempatkan dalam subdirektori (contoh servbay-phalcon-app, nama lalai DevTools):

   vendor/bin/phalcon project servbay-phalcon-app

   Direktori baru /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app dan rangka lengkap projek akan diwujudkan.

4. Masuk ke direktori kod projek

   Tukar ke direktori kod projek untuk langkah-langkah seterusnya:

   cd servbay-phalcon-app

   Kini anda berada di /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Konfigurasi Persekitaran Projek

Konfigurasi projek Phalcon biasanya dilakukan dalam fail app/config/config.php, di mana anda tetapkan maklumat pangkalan data, laluan aplikasi dan tetapan penting lain.

1. Edit fail konfigurasi

   Buka /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php menggunakan editor kegemaran anda. Cari atau tambahkan bahagian konfigurasi pangkalan data. Pengguna lalai MySQL/MariaDB ServBay ialah root dengan kata laluan kosong — tetapi demi keselamatan, sangat disarankan untuk tetapkan kata laluan yang kuat. Contoh di bawah menggunakan password sebagai pengganti; pastikan anda menukar mengikut maklumat sebenar anda. Nama pangkalan data contoh servbay_phalcon_app (anda perlu cipta pangkalan data ini secara manual):

   return new \Phalcon\Config([
       // ... konfigurasi lain ...
       'database' => [
           'adapter' => 'Mysql', // atau 'Postgres' dan lain-lain
           'host' => '127.0.0.1',
           'username' => 'root', // Pengguna lalai ServBay
           'password' => 'password', // <-- Tukar kepada kata laluan anda
           'dbname' => 'servbay_phalcon_app', // <-- Tukar kepada nama pangkalan data anda
       ],
       // ... konfigurasi lain ...
   ]);

   Penting: Pastikan servis pangkalan data (MySQL/MariaDB) telah diaktifkan dalam ServBay dan butiran pengguna serta kata laluan adalah betul. Anda juga perlu cipta pangkalan data contoh (servbay_phalcon_app). Gunakan phpMyAdmin atau Adminer dalam ServBay untuk pengurusan pangkalan data dan pengguna.

Tetapan Pelayan Web (menggunakan Fungsi Laman ServBay)

Agar laman Phalcon boleh dicapai melalui pelayar web, gunakan fungsi Laman ServBay untuk tetapkan hos maya dan laluan akar web.

1. Buka ServBay
2. Masuk ke tetapan Laman: Cari dan klik pada pilihan 'Laman' di antara muka utama ServBay.
3. Tambah laman baru: Klik butang tambah laman.
   • Nama: Nama mudah dikenali, contohnya My First Phalcon Dev Site.
   • Domain: Masukkan domain yang akan digunakan di pelayar anda, contohnya servbay-phalcon-test.local (ServBay akan auto-resolve domain .local secara tempatan).
   • Jenis laman: Pilih PHP.
   • Versi PHP: Pilih versi PHP yang telah diaktifkan bersama modul Phalcon.
   • Laluan akar laman: Ini sangat penting. Fail masuk Phalcon (index.php) biasanya di dalam direktori public. Jadi, tetapkan akar laman kepada: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Simpan: Simpan konfigurasi laman baharu. ServBay akan mengaplikasi perubahan secara automatik dan mungkin memerlukan restart pelayan web (Caddy/Nginx).

Untuk panduan terperinci, rujuk Menambah Laman Pertama. ServBay akan mengurus resolve domain tempatan dan konfigurasi pelayan web.

Tambah Kod Contoh

Mari tambah kod mudah untuk uji projek berjaya berjalan.

1. Konfigurasi routing

   Edit /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php dan tambah routing mudah untuk laluan utama /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Definisi routing laluan utama '/' ke IndexController dan indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Tambah routing lain jika perlu ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Bina controller

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

   <?php
   namespace App\Controllers; // Pastikan namespace betul
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Tangani permintaan laluan utama '/'
       public function indexAction()
       {
           // Pulangkan string mudah sebagai respons
           return 'Hello ServBay!';
       }
   }

Akses Laman Web

Setelah fail disimpan, pastikan ServBay sedang berjalan. Buka pelayar web dan akses domain yang telah dikonfigurasikan:

https://servbay-phalcon-test.local

Jika semuanya betul, anda akan nampak "Hello ServBay!" dipaparkan.

Integrasi Pangkalan Data

Phalcon menawarkan lapisan abstraksi pangkalan data dan ORM yang lengkap. ServBay menyatukan pelbagai jenis pangkalan data untuk integrasi mudah. Di bawah ialah contoh MySQL dan Redis.

Contoh Pangkalan Data Relasi: MySQL

Contoh di bawah menunjukkan cara gunakan adapter pangkalan data Phalcon untuk menyambung ke MySQL ServBay dan melakukan operasi ringkas insert dan query.

1. Cipta struktur pangkalan data (menggunakan migrasi)

   DevTools menyokong migrasi pangkalan data untuk pengurusan versi schema.

   • Jana fail migrasi: Dalam folder projek kod, jalankan:

     vendor/bin/phalcon migration generate

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

   • Edit fail migrasi: Buka fail migrasi dan tambah kod 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 sama dengan fail migrasi
     {
         /**
          * 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 seperti padam jadual
             // $this->getConnection()->dropTable('users');
         }
     }

     Nota: Nama kelas (contoh UsersMigration_100) mesti sama dengan nama fail migrasi.

   • Laksana migrasi: Jalankan arahan berikut untuk cipta jadual di pangkalan data:

     vendor/bin/phalcon migration run

     Jika ada ralat, semak konfigurasi pangkalan data dalam app/config/config.php dan pastikan servis MySQL/MariaDB ServBay berjalan dengan baik.

2. Tetapan sambungan pangkalan data (dilakukan di atas)

   Pastikan bahagian 'database' dalam app/config/config.php mengikut seting ServBay (host: 127.0.0.1, port: 3306, user: root, password: ikut tetapan anda).

3. Tambah routing contoh

   Edit app/config/routes.php dan tambah routing untuk insert & query pengguna:

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

4. Implikasi operasi pangkalan data dalam controller

   Edit app/controllers/IndexController.php untuk tambah mysqlAddAction dan mysqlAction bagi operasi pangkalan data. Contoh di bawah:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Import adapter MySQL
   use Phalcon\Db\Enum; // Untuk fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Contoh tambah pengguna
       public function mysqlAddAction()
       {
           // Sambungan pangkalan data
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Tukar kata laluan anda
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Tambah rekod pengguna contoh
           $success = $connection->insert(
               'users', // Nama jadual
               ['ServBay Demo User', 'demo@servbay.test'], // Nilai
               ['name', 'email'] // Lajur
           );
   
           // Papar hasil
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Contoh query pengguna
       public function mysqlAction()
       {
            // Sambungan pangkalan data
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Tukar kata laluan anda
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Query 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: Penggunaan sambungan pangkalan data patut diuruskan sebagai servis dalam aplikasi sebenar menerusi dependency injection.

5. Ujian akses contoh

   • Lawati https://servbay-phalcon-test.local/mysql-add untuk tambah pengguna.
   • Kemudian ke https://servbay-phalcon-test.local/mysql untuk melihat data users dalam format JSON.

Contoh Pangkalan Data NoSQL: Redis

Contoh berikut menunjukkan cara menggunakan Redis dalam projek Phalcon sebagai cache.

1. Pastikan ekstensi Redis terpasang

   ServBay biasanya sudah sedia dengan ekstensi Redis untuk PHP. Pastikan versi PHP yang digunakan telah mengaktifkan ekstensi Redis.

2. Tetapkan sambungan Redis

   Tambahkan konfigurasi Redis ke dalam app/config/config.php. ServBay menjalankan Redis di 127.0.0.1:6379.

   return new \Phalcon\Config([
       // ... konfigurasi lain ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null, // Isi jika Redis dipasang dengan password
       ],
       // ... konfigurasi lain ...
   ]);

3. Tambah routing contoh Redis

   Edit fail app/config/routes.php dan tambah routing demo:

   <?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',
   ]);
   
   // Routing untuk demo Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implikasi Redis dalam controller

   Edit app/controllers/IndexController.php dan 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
   
   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 penggunaan Redis
       public function redisAction()
       {
           // Cipta instance SerializerFactory
           $serializerFactory = new SerializerFactory();
   
           // Pilihan konfigurasi Redis
           // Pastikan sama dengan bahagian 'cache' dalam config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'kata_laluan_redis_anda', // Jika Redis menggunakan password
           ];
   
           // Cipta instance Redis adapter
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // Cuba dapatkan data cache
   
           if ($cachedData === null) {
               // 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); // Simpan ke cache
               echo "Data stored in cache.";
           } else {
               // Data dijumpai dalam cache
               echo "Data found in cache: ";
           }
   
           // Paparkan data dari cache
           return $cachedData;
       }
   }

   Nota: Untuk aplikasi sebenar, caching patut diuruskan sebagai servis bagi kebolehgunaan menyeluruh.

5. Uji akses contoh

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

   • Akses pertama: "Data not found in cache, fetching from source...Data stored in cache." bersama "Data fetched from source: Hello Redis from ServBay!".
   • Akses seterusnya dalam tempoh cache akan paparkan "Data found in cache: " dan "Data fetched from source: Hello Redis from ServBay!" — bermakna data diambil dari Redis.

Soalan Lazim (FAQ)

• S: Laman menunjukkan 404 Not Found, apa yang patut dilakukan?
  • J: Pastikan "Root laman" dalam ServBay menghala ke direktori public projek Phalcon (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Semak juga pelayan web (Caddy/Nginx) dalam ServBay sudah berjalan dan domain telah di-resolve dengan betul.
• S: Ralat seperti modul Phalcon tidak ditemui (Class 'Phalcon\Mvc\Application' not found dan seumpamanya)?
  • J: Ini biasanya bermakna modul Phalcon belum diaktifkan pada versi PHP yang digunakan. Kembali ke antara muka ServBay dan pastikan versi PHP projek sudah aktif Phalcon; kemudian restart servis PHP. Rujuk Cara Aktifkan Modul Phalcon ServBay.
• S: Gagal menyambung dengan pangkalan data?
  • J: Semak tetapan sambungan pangkalan data dalam app/config/config.php (host, username, password, nama pangkalan data). Pastikan servis pangkalan data (MySQL/MariaDB) dalam ServBay sedang berjalan. Confirm pengguna mempunyai akses dan pangkalan data telah dicipta.

Rumusan

Menerusi ServBay, anda boleh membina persekitaran pembangunan tempatan yang sangat pantas untuk framework Phalcon dengan mudah. Panduan ini menunjukkan dari pembinaan rangka projek, seting pelayan web hingga integrasi dengan pangkalan data MySQL dan Redis. Pakej-pakej dan antara muka pengurusan yang disertakan sangat memudahkan konfigurasi — membolehkan anda tumpu sepenuhnya kepada pembangunan aplikasi Phalcon. Semoga panduan ini membantu anda memulakan pembangunan web yang cekap dengan ServBay dan Phalcon!