KT CRUD

Při rozsáhlejších projektech je a pravděpodobně vždy bude potřeba rozšířit typy obsahu WordPressu o nějaké vlastní. Nemyslím tím jenom custom post_type – ale udělat například i databázový model. Poté je potřeba také tato data nějak z databáze číst, mazat, ukládat a přidávat. Pro tento účel vznikl abstraktní objekt KT CRUD (Create, Read, Update, Delete).

Související komponenty

Logika práce s objektem

Jedna tabulka v databázi odpovídá vždy jednomu CRUD Modelu.
Nikdy nepoužíváme KT CRUD – vždy je nutné připravit vlastní objekt, který KT CRUD dědí.
V nově založeném modelu je potřeba vydefinovat několik konstant.
V našem modelu je potřeba definovat a inicializovat sadu sloupců – pokud to nedělá mateřský objekt za nás.

Nezapomeňte, že se jedná o model – jeho umístění bude tedy v příslušné složce: …/yours/models/kt_wp_fw_crud_model.inc.php

Jak bude vypadat základní model

<?php

class KT_WP_FW_CRUD_Model extends KT_Crud
{
    const TABLE = "kt_wp_fw_crud_table";
    const PREFIX = "custom_crud_prefix";
    const FORM_PREFIX = "kt-crud-form-prefix";
    
    // sloupce v DB
    // jednotlivé názvy sloupců si také definujeme jako konstanty
    // Vždy je zde najdeme a nestane se nám, že bychom název popletli

    const ID_COLUMN = "id";
    const TITLE_COLUMN = "title";
    const DESCRIPTION_COLUMN = "description";
    const VISIBILITY_COLUMN = "visibility";

    public function __construct($rowId = null) {
        parent::__construct(
                self::TABLE, // Název naší tabulky
                self::ID_COLUMN, // Primární sloupec pro select na ID záznamu
                null, // Prefix sloupců, který nyní nebudeme používat
                $rowId // Případné ID záznamu
        );
    }

    // Vždy je nutné mít zavedenou abstraktní metodu initColumns
    // která zavede potřebnou kolekci sloupců.

    protected function initColumns() {
        $this->addColumn(self::ID_COLUMN, KT_CRUD_Column::INT);
        $this->addColumn(self::TITLE_COLUMN);
        $this->addColumn(self::DESCRIPTION_COLUMN);
        $this->addColumn(self::VISIBILITY_COLUMN, KT_CRUD_Column::INT);
    }
}

<?php

class KT_WP_FW_CRUD_Model extends KT_Crud

{

const TABLE = "kt_wp_fw_crud_table";

const PREFIX = "custom_crud_prefix";

const FORM_PREFIX = "kt-crud-form-prefix";

// sloupce v DB

// jednotlivé názvy sloupců si také definujeme jako konstanty

// Vždy je zde najdeme a nestane se nám, že bychom název popletli

const ID_COLUMN = "id";

const TITLE_COLUMN = "title";

const DESCRIPTION_COLUMN = "description";

const VISIBILITY_COLUMN = "visibility";

public function __construct($rowId = null) {

parent::__construct(

self::TABLE, // Název naší tabulky

self::ID_COLUMN, // Primární sloupec pro select na ID záznamu

null, // Prefix sloupců, který nyní nebudeme používat

$rowId // Případné ID záznamu

);

}

// Vždy je nutné mít zavedenou abstraktní metodu initColumns

// která zavede potřebnou kolekci sloupců.

protected function initColumns() {

$this->addColumn(self::ID_COLUMN, KT_CRUD_Column::INT);

$this->addColumn(self::TITLE_COLUMN);

$this->addColumn(self::DESCRIPTION_COLUMN);

$this->addColumn(self::VISIBILITY_COLUMN, KT_CRUD_Column::INT);

}

V rámci nového modelu je důležité vždy definovat několik konstant:

TABLE – Název tabulky, se kterou bude model při operacích komunikovat.
PREFIX – Prefix se používá jako identifikace modelu – pro slug stránky, indentifikace modelu, atd.
FORM_PREFIX – často používán jako prefix POSTu pro odeslání dat modelu.

Těchto několik konstant doporučujeme vždy definovat. Pokud je nevyplníte, nic se nestane. Budete ale poté odkázání vždy na string pro dané údaje, což je nepraktické a do budoucna velmi neefektivní.

Definice sloupců modelu

Každý model, který dětí svou základní strukturu z KT CRUD musí mít zavedenou abstraktní metodu initColumns() která zajišťuje nastavení všech sloupců, s kterými bude model pracovat.

addColumn($name, $type = KT_CRUD_Column::TEXT, $nullable = false)

Přidá do kolekce sloupců modelu nový model

$name – název sloupce v databází.
$type – datový typ vycházející z konstanty na KT CRUD Column.
$nullable – určuje, zda se může sloupec uložit jako NULL.

$model->addColumn("id", KT_CRUD_Column::INT, false);
// ...

1 2	$model->addColumn("id", KT_CRUD_Column::INT, false); // ...

Tímto způsobem je nutné přidat všechny sloupce, s kterými bude KT CRUD model dále pracovat – vše se zavádí v rámci abstraktní metody initColumns().

getColumnByName($name)

Pokud potřebujeme po definici sloupců získat instanci daného sloupce, můžeme využít tuto funkci.

$idColumn = $model->getColumnByName("title");
$idColumn->setValue("Hello world");

1 2	$idColumn = $model->getColumnByName("title"); $idColumn->setValue("Hello world");

Inicializace modelu

V rámci CRUD modelů je možné využívat dva „typy“ inicializace modelu.

Volám nový model a nevyužívám žádný parametr v konstruktoru.
Jako parametr konstruktoru předávám ID záznamu v tabulce, se kterým chci pracovat.

$model = new KT_WP_FW_CRUD_Model();
// Nyní v modelu nic není - žádná data. Pouze "prázdná" instance modelu

$model = new KT_WP_FW_CRUD_Model(1);
// Nyní jsou v modelu načtena data záznamu z tabulky s ID 1

$model = new KT_WP_FW_CRUD_Model();

// Nyní v modelu nic není - žádná data. Pouze "prázdná" instance modelu

$model = new KT_WP_FW_CRUD_Model(1);

// Nyní jsou v modelu načtena data záznamu z tabulky s ID 1

Základní operace s modelem

saveRow()

Funkce sama rozpozná, zda se má provést UPDATE nebo INSERT záznamu na základě toho, zda byla data modelu načtena z DB nebo se jedná o nový model bez existujícího ID.

// Model provede INSERT nového záznamu

$model = new KT_WP_FW_CRUD_Model();
$model->addNewColumnToData(self::TITLE_COLUMN, "Titulek záznamu");
$model->saveRow();

// Provede se UPDATE záznamu na ID 1

$model = new KT_WP_FW_CRUD_Model(1);
$model->addNewColumnToData(self::TITLE_COLUMN, "Změna titulku záznamu");
$model->saveRow();

// Model provede INSERT nového záznamu

$model = new KT_WP_FW_CRUD_Model();

$model->addNewColumnToData(self::TITLE_COLUMN, "Titulek záznamu");

$model->saveRow();

// Provede se UPDATE záznamu na ID 1

$model = new KT_WP_FW_CRUD_Model(1);

$model->addNewColumnToData(self::TITLE_COLUMN, "Změna titulku záznamu");

$model->saveRow();

deleteRow()

Provede DELETE daného záznamu, který byl načten z DB. Pokud záznam neexistuje, neprovede se žádná operace.

// Záznam s ID 1 bude trvale odstraněn

$model = new KT_WP_FW_CRUD_Model(1);
$model->deleteRow();

// Záznam s ID 1 bude trvale odstraněn

$model = new KT_WP_FW_CRUD_Model(1);

$model->deleteRow();

hasError()

Vrátí logickou hodnotu na základě toho, zda model při komunikaci s DB obdržel nějakou chybu a operace se neprovedla.

$model = new KT_WP_FW_CRUD_Model(1);
$model->saveRow();

// Vypíše chyby, které vznikly při komunikaci s DB
if($model->hasError()){
     $errors = $model->getErrors();
     foreach($errors as $error){
          echo $error;
     }
}

$model = new KT_WP_FW_CRUD_Model(1);

$model->saveRow();

// Vypíše chyby, které vznikly při komunikaci s DB

if($model->hasError()){

$errors = $model->getErrors();

foreach($errors as $error){

echo $error;

}

Funkce pro manipulaci dat

Model obsahuje základní sadu funkcí, kterou je možné využívat pro manipulaci, přidávání a změnu dat daného modelu.

addNewColumnValue( $name, $value = null )

Přidá hodnotu na název daného sloupce.

$model->addNewColumnValue(self::VISIBILITY_COLUMN, 0)
      ->addNewColumnValue(self::TITLE_COLUMN, "Název záznamu");

1 2	$model->addNewColumnValue(self::VISIBILITY_COLUMN, 0) ->addNewColumnValue(self::TITLE_COLUMN, "Název záznamu");

addNewColumnsToValue( array $columns )

Přidá hodnoty na příslušné sloupce. Pole je zadáváno ve tvaru $columnName => $columnValue. U funkce je důležité, že provádí merge dat. Můžete pomocí funkce přidávat části dat po částech bez toho, že byste přepsali již naplněná data. Dochází však k přepisu jednotlivých hodnot sloupců!

$model->addNewColumnsToValue(array(
                 self::TITLE_COLUMN => "Titulek záznamu",
                 self::DESCRIPTION_COLUMN => "Nějaký popisek záznamu",
                 self::VISIBILITY_COLUMN => 2
));

$model->addNewColumnsToValue(array(

self::TITLE_COLUMN => "Titulek záznamu",

self::DESCRIPTION_COLUMN => "Nějaký popisek záznamu",

self::VISIBILITY_COLUMN => 2

));

setData( array $data = array() )

Nastaví a přemaže všechna existující data daty novými – například i prázdným polem pro smazání všech údajů sloupců. Zde již neprobíhá merge dat, ale „tvrdý“ set jiné hodnoty.

$model->addNewColumnToData(self::TITLE_COLUMN, "Titulek záznamu);

// Nyní je ve sloupci title naše hodnota

$model->setData(array(
       self::VISIBILITY_COLUMN => 0
));

// Původní data a title byl přenastaven novou sadou hodnot, kde je definovaný
// Pouze sloupec visibility

$model->addNewColumnToData(self::TITLE_COLUMN, "Titulek záznamu);

// Nyní je ve sloupci title naše hodnota

$model->setData(array(

self::VISIBILITY_COLUMN => 0

));

// Původní data a title byl přenastaven novou sadou hodnot, kde je definovaný

// Pouze sloupec visibility

getColumnValue($column)

Vrátí hodnotu na daném názvu sloupce

$title = $model->getColumnValue(self::TITLE_COLUMN);
$description = $model->getColumnValue(self::DESCRIPTION_COLUMN);

// K datům se dá přistupovat i pomocí stringu; doporučujeme však využívat popsané
// Funkce, které k tomu byly připraveny.

$title = $model->title; // title = přesný název sloupce
$description = $model->description // description = přesný název sloupce

$title = $model->getColumnValue(self::TITLE_COLUMN);

$description = $model->getColumnValue(self::DESCRIPTION_COLUMN);

// K datům se dá přistupovat i pomocí stringu; doporučujeme však využívat popsané

// Funkce, které k tomu byly připraveny.

$title = $model->title; // title = přesný název sloupce

$description = $model->description // description = přesný název sloupce

getData()

Vrátí pole se všemi sloupci a hodnotami, které jsou v modelu nastaveny. V podobě $columnName => $columnValue.

$allData = $model->getData();

$title = $allData[self::TITLE_COLUMN];
...

$allData = $model->getData();

$title = $allData[self::TITLE_COLUMN];

...

Ostatní funkce

isInDatabase()

Po načtení modelu pomocí ID záznamu v inicializaci vrátí, zda záznam v DB skutečně existoval.

$model = new KT_WP_FW_CRUD_Model(545);

if(! $model->isInDatabase()){
     echo "Je nám líto, tento záznam v naší databázi neexistuje";
     return;
}

$model = new KT_WP_FW_CRUD_Model(545);

if(! $model->isInDatabase()){

echo "Je nám líto, tento záznam v naší databázi neexistuje";

return;

}

Ukázkový příklad modelu

Pro náš definovaný model by nám měla chybět ještě základní sada getterů a setterů pro získání jednotlivých dat. Můžeme využívat připravené funkce KT CRUD, ale pohodlnější, čistější a správné je, si jednotlivé „sloupce“ připravit ještě na modelu samotném.

class KT_WP_FW_CRUD_Model extends KT_Crud
{
    const TABLE = "kt_wp_fw_crud_table";
    const ORDER_COLUMN = self::TITLE_COLUMN;
    const PREFIX = "custom_crud_prefix";
    const FORM_PREFIX = "kt-crud-form-prefix";
    
    // sloupce v DB
    
    const ID_COLUMN = "id";
    const TITLE_COLUMN = "title";
    const DESCRIPTION_COLUMN = "description";
    const VISIBILITY_COLUMN = "visibility";

    public function __construct($rowId = null) {
        parent::__construct(
                self::TABLE, // Název naší tabulky
                self::ID_COLUMN, // Primární sloupec pro select na ID záznamu
                null, // Prefix sloupců, který nyní nebudeme používat
                $rowId // Případné ID záznamu
        );
    }
    
    // --- GETTERY a SETTERY ---------------
    
    // gettery
    public function getTitle(){
        return $this->getColumnValue(self::TITLE_COLUMN);
    }
    
    public function getDescription(){
        return $this->getColumnValue(self::DESCRIPTION_COLUMN);
    }
    
    public function getVisibility(){
        return $this->getColumnValue(self::VISIBILITY_COLUMN);
    }
    

    // settery
    public function setTitle( $title = null ){
        $this->addNewColumnToData(self::TITLE_COLUMN, $title);
    }
    
    public function setDescription( $description = null ){
        $this->addNewColumnToData(self::DESCRIPTION_COLUMN, $description);
    }
    
    public function setVisibility( $visibility = null ){
        $this->addNewColumnToData(self::VISIBILITY_COLUMN, $visibility);
    }

    /--- inicializace sloupců ------------------

    protected function initColumns() {
        $this->addColumn(self::ID_COLUMN, KT_CRUD_Column::INT);
        $this->addColumn(self::TITLE_COLUMN);
        $this->addColumn(self::DESCRIPTION_COLUMN);
        $this->addColumn(self::VISIBILITY_COLUMN, KT_CRUD_Column::INT);
    }
}

class KT_WP_FW_CRUD_Model extends KT_Crud

{

const TABLE = "kt_wp_fw_crud_table";

const ORDER_COLUMN = self::TITLE_COLUMN;

const PREFIX = "custom_crud_prefix";

const FORM_PREFIX = "kt-crud-form-prefix";

// sloupce v DB

const ID_COLUMN = "id";

const TITLE_COLUMN = "title";

const DESCRIPTION_COLUMN = "description";

const VISIBILITY_COLUMN = "visibility";

public function __construct($rowId = null) {

parent::__construct(

self::TABLE, // Název naší tabulky

self::ID_COLUMN, // Primární sloupec pro select na ID záznamu

null, // Prefix sloupců, který nyní nebudeme používat

$rowId // Případné ID záznamu

);

}

// --- GETTERY a SETTERY ---------------

// gettery

public function getTitle(){

return $this->getColumnValue(self::TITLE_COLUMN);

}

public function getDescription(){

return $this->getColumnValue(self::DESCRIPTION_COLUMN);

}

public function getVisibility(){

return $this->getColumnValue(self::VISIBILITY_COLUMN);

}

// settery

public function setTitle( $title = null ){

$this->addNewColumnToData(self::TITLE_COLUMN, $title);

}

public function setDescription( $description = null ){

$this->addNewColumnToData(self::DESCRIPTION_COLUMN, $description);

}

public function setVisibility( $visibility = null ){

$this->addNewColumnToData(self::VISIBILITY_COLUMN, $visibility);

}

/--- inicializace sloupců ------------------

protected function initColumns() {

$this->addColumn(self::ID_COLUMN, KT_CRUD_Column::INT);

$this->addColumn(self::TITLE_COLUMN);

$this->addColumn(self::DESCRIPTION_COLUMN);

$this->addColumn(self::VISIBILITY_COLUMN, KT_CRUD_Column::INT);

}

Jistě si všimnete, že nemáme getter a setter pro ID samotné. To definovat není potřeba, protože v konstruktoru jsme definovali primární název sloupce. CRUD vždy počítá alespoň s jedním sloupcem a proto má getId() a setId() připravené defaultně a odkazuje se na název právě privátního názvu sloupce.