Khai báo tập tin .install

Submitted by thehong on Thu, 08/23/2007 - 14:28

Tập tin .install sẽ được gọi khi module được kích hoạt/gỡ bỏ/nâng cấp. Người phát triển thường sử dụng nó để cài đặt/xóa bỏ/chỉnh sửa các bảng dữ liệu và các thông tin cần thiết. Các tập tin .install cũng được gọi đến khi cập nhật các module được nâng cấp lên phiên bản mới hơn.

Xây dựng kịch bản cài đặt

Các câu lệnh được xử lý phải nằm trong hàm hook_install(). Thí dụ sau đây tạo một bảng dữ liệu cho module:

<?php
// nodereference.install <--- tên tập tin phải trùng với tên của module

function nodereference_install() {
  switch ($GLOBALS['db_type']) {
    case 'mysql':
    case 'mysqli':
      // the {tablename} syntax is so multisite installs can add a
      // prefix to the table name as set in the settings.php file
      db_query("CREATE TABLE {node_field_nodereference_data} (
          vid int unsigned NOT NULL default '0',
          field_name varchar(32) NOT NULL default '',
          delta int unsigned NOT NULL default '0',
          field_nid int unsigned NOT NULL default '0',
          PRIMARY KEY  (vid,field_name,delta)
        ) /*!40100 DEFAULT CHARACTER SET utf8 */;");
      break;

    case 'pgsql':
      db_query("CREATE TABLE {node_field_nodereference_data} (
          vid serial CHECK (vid >= 0),
          field_name varchar(32) NOT NULL default '',
          delta integer NOT NULL default '0' CHECK (delta >= 0),
          field_nid integer NOT NULL default '0' CHECK (field_nid >= 0),
          PRIMARY KEY  (vid, field_name, delta)
        )");

      // Pgsql requires keys and indexes to be defined separately.
      // It's important to name the index as {tablename}_fieldname_idx
      // (the trailing _idx!) so update scripts can be written easily
      db_query("CREATE INDEX {node_field_nodereference_data}_field_name_idx
                ON {my_table} (field_name)");
      break;
  }
}
?>

Xây dựng kịch bản tháo gỡ

Tương tự như các câu lệnh cài đặt, các câu lệnh gỡ bỏ được đặt trong tập tin .install và được khai báo trong hàm hook_uninstall(). Hàm này sẽ được gọi đến khi người điều hành gỡ bỏ module ra khỏi hệ thống. Thường được sử dụng để làm xóa bỏ các dữ liệu mà module này tạo ra trong quá trình được sử dụng. Thí dụ:

<?php
function nodereference_install() {
  db_query("DROP TABLE {node_field_nodereference_data}");
}
?>

Viết script nâng cấp module

Nhu cầu thực tế, các module cần được nâng cấp (chức năng, sửa lỗi, ...). Việc thay đổi cấu trúc các bảng dữ liệu, nếu cần, được thực hiện rất đơn giản, qua các hàm nâng cấp.

Cách đặt tên hàm

Tên của các hàm nâng cấp được định nghĩa dạng hook_update_x(). Trong đó, x mà một số nguyên dương. Số x, nên được đặt theo thứ tự tăng dần, từ 1. Thí dụ, bạn viết script nâng cấp module từ phiên bản 1.0 lên 2.0, thì hàm nâng cấp đầu tiên nên được đặt là hook_update_1(). Sau đó, bạn lại viết script nâng cấp module lên phiên bản 2.1, hàm nâng cấp khi đó, nên là hook_update_2(), ...

Cách định nghĩa hàm

Hàm của bạn sẽ phải trả về một mảng các chuỗi SQL, hệ thống thực hiện các câu truy vấn dựa trên mảng này. Thí dụ:

<?php
// example.install

function example_update_1() {
  $items = array();
  $items[] = update_sql("ALTER TABLE {example} ADD new_column text");
  $items[] = update_sql("ALTER TABLE {example} DROP old_column");
  return $items;
}


function example_update_2() {
  $items = array();
  $items[] = update_sql("ALTER TABLE {example} ADD new_column text2");
  return $items;
}

?>

Chú ý

Nếu bạn viết tập tin .install cho module của bạn trong khi nó đã được cài đặt, thì các hàm cài đặt/nâng cấp sẽ không có tác dụng khi bạn tắt/mở module đó.