README

커스텀 테이블을 위한 유틸리티.

워드프레스 기능을 더 확장하기 위해 플러그인이나 테마는 고유의 테이블을 별도로 생성할 수 있습니다. 이 때 활용되는 상용구적인 패턴을 재활용할 수 있게 하기 위해 이 유틸리티를 제공합니다.

설정하기

예시:

use Bojaghi\inc\Custom_Tables;

new Custom_Tables(
    [ /*...*/ ], // Enter configuration array.    설정을 담은 배열을 넣거나.
    [ /*...*/ ], // Enter table definition array. 테이블 설정을 담은 배열을 넣거나.
)

/* OR */

new Custom_Tables(
    '/path/to/settings',  // Enter path to configuration file.    설정을 담은 파일 경로를 문자열로.
    '/path/to/table-def', // Enter path to table definition file. 테이블 설정을 담은 파일 경로를 문자열로.
)

이 객체는 가능한 액션과 필터의 콜백에서 생성하지 말고, 플러그인/테마 코드 실행시 생성되게 해 주세요.

설정 파일의 예제

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

return array(
    'version_name'      => 'my_version_name', // Optional
    'version'           => '1.0.0',           // Optional
    'is_theme'          => false,             // Optional, defaults to false.
    'main_file'         => __FILE__,          // Optional, defaults to blank.
    'activation'        => false,             // Optional, defaults to false. Create tables on activation.
    'deactivation'      => false,             // Optional, defaults to false. Delete tables on deactivation.
    'uninstall'         => false,             // Optional, defaults to false. Delete tables on uninstall.
    'suppress_errors'   => false,             // Optional, defaults to false.
    'enable_update_log' => true,              // Optional, defaults to true.
);

• version_name: 옵션에 저장할 데이터베이스 버전의 옵션 이름입니다. 다른 옵션과 충돌되지 않는 유일한 이름으로 지어주세요.
• version: 이 설정의 버전을 적어주세요. 기존 플러그인에 기록된 버전보다 이 버전이 높으면 테이블 업데이트를 진행합니다.
• is_theme: 이 코드가 테마에서 동작하는지, 플러그인에서 동작하는지를 지정합니다.
• mani_file: is_theme이 false인 경우, 플러그인의 메인 파일을 지정합니다.
• activation: 이 코드가 동작하는 테마가 선택되었을 때, 또는 플러그인이 활성화 되었을 때 테이블을 생성합니다.
• deactivation: 이 코드가 동작하는 테마가 다른 테마로 변경될 때, 또는 플러그인이 비활성화될 때 테이블을 삭제(주의!!) 합니다
• uninstall: 이 코드가 동작하는 테마, 또는 플러그인이 삭제될 때 테이블을 삭제(주의!!) 합니다.
• suppress_errors: $wpdb->suppress_error 파라미터를 조정합니다.
• enable_update_log: 테이블 업데이트를 진행할 때, 변경되는 내역을 기록합니다. 연속적으로 기록하지는 않고, 마지막 변경 내역만을 기록합니다.

테이블 설정 파일의 예제

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}


/**
 * How to create table
 *
 * This method uses dbDelta() function.
 *
 * Please keep in mind that dbDelta() is rather demanding:
 * - You must put each field on its own line in your SQL statement.
 * - You must have two spaces between the words PRIMARY KEY and the definition of your primary key.
 * - You must use the key word KEY rather than its synonym INDEX and you must include at least one KEY.
 * - KEY must be followed by a SINGLE SPACE then the key name then a space then open parenthesis with the field name
 *   then a closed parenthesis.
 * - You must not use any apostrophes or backticks around field names.
 * - Field types must be all lowercase.
 * - SQL keywords, like CREATE TABLE and UPDATE, must be uppercase.
 * - You must specify the length of all fields that accept a length parameter. int(11), for example.
 * - Use 'UNIQUE KEY', not just 'UNIQUE'. Likewise, use 'FULLTEXT KEY', and 'SPATIAL KEY'.
 *
 * @return array
 * @link   https://codex.wordpress.org/Creating_Tables_with_Plugins
 */

return array(
    array(
        'table_name'    => 'table_name',
        'table_comment' => '', // Optional, table comment
        'field'         => array(
            'id bigint(20) unsigned NOT NULL AUTO_INCREMENT',
            'name varchar(100) NOT NULL',
            'count bigint(20) unsigned NOT NULL',
        ),
        'index'         => array(
            'PRIMARY KEY  (id)',            // Two spaces after 'PRIMARY KEY'. 'PRIMARY KEY' 다음 두 개의 공백.
            'UNIQUE KEY uni_name (name)',   // Just as-is, from here.          여기부터는 그대로.
            'FULLTEXT KEY idx_name (name)',
            'KEY idx_count (count)',   
        ),  
        'engine'        => 'InnoDB', // Optional, defaults to 'InnoDB'.
        'charset'       => '',       // Optional, leave blank to use the default value of $wpdb.
        'collate'       => '',       // Optional, leave blank to use the default value of $wpdb.
    ),
    /* ... */
];

version_name, version의 의미

version_name, version이 설정되어 있으면 테이블 생성 후 옵션 테이블에 기록된 버전 version을 기록합니다. 이 때 옵션 이름으로 version_name을 사용합니다. 그러므로 이름은 고유한 값을 가질 수 있도록 해 주세요. version값으로 PHP version_compare() 함수가 인식할 수 있는 버전 문자열을 사용하세요.

예를 들어,

• 1.1.2
• 1.1.1-p.1 (1.1.2보다 이쪽이 높은 버전)
• 1.1.1-b.1 (1.1.2보다 이쪽이 낮은 버전)

이렇게 값이 설정되면 데이터베이스 업데이트 시, 굳이 플러그인을 활성화/비활성화 하지 않아도 자동으로 데이터베이스를 업그레이드 할 수 있습니다. 이 기능을 사용하지 않으려면 값을 비워 두거나 키-값 쌍을 삭제하세요.

플러그인, 테마 기반 구분

플러그인의 경우 main_file 값을 넣는 것이 좋습니다. 그래야 활성화/비활성화/삭제시 테이블 생성, 제거 작업이 가능합니다. 만약 테마 기반에서 실행한다면 is_theme 값을 참으로 설정해 둡니다. 그러면 main_file은 무시됩니다.

활성화/비활성화/삭제

아래는 모두 기본값이 false입니다.

• activation: 플러그인/테마 활성화 시 테이블을 자동으로 만듭니다.
• deactivation: 플러그인/테마 비활성화 시 테이블을 자동으로 삭제합니다.
• uninstall: 플러그인/테마 삭제 시 테이블을 자동으로 삭제합니다.

에러 표시하기

기본적으로 $wpdb의 suppress_errors가 false로 되어 있어 에러가 출력됩니다. 이를 보이지 않게 설정값에서 true로 설정할 수 있습니다.

보이지 않게 설정한 에러를 조사하기 위해서는 get_query_errors() 메소드를 사용할 수 있습니다.

업데이트 로그

version_name을 지정하고, enable_update_log 설정을 true로 설정하면 데이터베이스 업데이트 과정에서 생기는 테이블 변경 내역에 대한 정보를 옵션 테이블에 저장할 수 있습니다.

주의할 점으로 모든 내역이 처음부터 저장되는 것은 아닙니다. 가장 마지막에 실행된 업데이트 내용에 한해서만 저장됩니다. 첫번째 줄은 업데이트가 진행된 버전이입니다. 두번째 줄부터 dbDelta()가 변경한 내역을 한 줄에 하나씩 저장됩니다.