wtorek, 2021-02-16

Obiekt mysqli_result

W przypadku sukcesu wykonania zapytania typu SELECT, SHOW, EXPLAIN i DESCRIBE metoda query() zwraca obiekt mysqli_result.

Wszystkie prezentowane w materiale metody i własności obiektu mysqli_result można przetestować, wstawiając kod przykładu do poniższego skryptu. Wykorzystana w przykładach tabela jest dostępna do pobrania.

<?php
  define('DBHOST', 'localhost');
  define('DBUSER', 'root');
  define('DBPASS', 'hasło');
  define('DBNAME', 'nazwa bazy');

  $mysqli = new mysqli(DBHOST, DBUSER, DBPASS, DBNAME);
  $result = $mysqli->query("SELECT fname, lname FROM names ORDER BY lname ASC LIMIT 2");

  /*
     TUTAJ WSTAW KOD PRZYKŁADÓW
  */

  $result->close();
  $mysqli->close();

?>

mysqli_result::fetch_object

Metoda fetch_object() zwraca wiersz wyników zapytania w postaci obiektu. Zazwyczaj jest wykonywana w pętli.

while ($row = $result->fetch_object()) {
  printf('%s %s<br>', $row->fname, $row->lname);
}

mysqli_result::fetch_row

Metoda fetch_row() zwraca wiersz wyników zapytania w postaci tablicy indeksowanej numerycznie. Zazwyczaj jest wykonywana w pętli.

while ($row = $result->fetch_row()) {
  printf('%s %s<br>', $row[0], $row[1]);
}

mysqli_result::fetch_assoc

Metoda fetch_assoc() zwraca wiersz wyników zapytania w postaci tablicy asocjacyjnej. Zazwyczaj jest wykonywana w pętli.

while ($row = $result->fetch_assoc()) {
  printf('%s %s<br>', $row['fname'], $row['lname']);
}

mysqli_result::fetch_all

Metoda fetch_all() pozwala na pobranie wyników zapytania zarówno jako tablicę indeksowaną numerycznie, tablicę asocjacyjną, jak i obie te formy jednocześnie. Może ona przyjmować trzy wartości parametru:

MYSQLI_NUM – jest to parametr domyślny, zwracana jest tablica indeksowana numerycznie;
MYSQLI_ASSOC – zwracana jest tablica asocjacyjna, kluczami w kolejnych rekordach są nazwy pól;
MYSQLI_BOTH – zwracana jest tablica, w której występują jednocześnie klucze będące nawami pól oraz klucze numeryczne.

Warto zwrócić uwagę, że metoda fetch_all() do pobrania wyników nie potrzebuje pętli, odbiera cały zbiór otrzymanych wierszy w jednym wywołaniu.

foreach($result->fetch_all(MYSQLI_ASSOC) as $x) {
  printf('%s %s<br>', $x['fname'], $x['lname']);
}

foreach($result->fetch_all(MYSQLI_NUM) as $x) {
  printf('%s %s<br>', $x[0], $x[1]);
}

$presons = $result->fetch_all(MYSQLI_BOTH);
print_r($presons);

/*
Array
(
  [0] => Array
    (
      [0] => Oren
      [fname] => Oren
      [1] => Aguilar
      [lname] => Aguilar
    )

  [1] => Array
    (
       [0] => Callum
       [fname] => Callum
       [1] => Barber
       [lname] => Barber
    )

)
*/

mysqli_result::fetch_array

Metoda fetch_array() zazwyczaj jest wykonywana w pętli. Może przyjmować podobne wartości parametrów jak powyżej prezentowana metoda fetch_all(). Są to MYSQLI_NUM, MYSQLI_ASSOC, MYSQLI_BOTH, zależy od nich forma zwracanego wyniku. Jako przykład zademonstrowano jedynie jedną z trzech możliwych opcji.

while ($row = $result->fetch_array(MYSQLI_ASSOC)) {
  printf('%s %s<br>', $row['fname'], $row['lname']);
}

mysqli_result::$num_rows

Własność mysqli_num_rows przechowuje wartość oznaczającą liczbę wierszy otrzymanych w wyniku zapytania.

printf('Liczba otrzymanych rekordów: %d<br>', $result->num_rows);

mysqli_result::fetch_field

Metoda fetch_field() zwraca obiekt zawierający definicję jednej kolumny zestawu wyników. Wywołana wielokrotnie odbierze informacje o wszystkich kolumnach w zestawie wyników.

while ($finfo = $result->fetch_field()) {
  print_r($finfo);
}
/*
stdClass Object
(
  [name] => fname
  [orgname] => fname
  [table] => names
  [orgtable] => names
  [def] => 
  [db] => x2x
  [catalog] => def
  [max_length] => 6
  [length] => 100
  [charsetnr] => 8
  [flags] => 4097
  [type] => 254
  [decimals] => 0
)
stdClass Object
(
  [name] => lname
  [orgname] => lname
  [table] => names
  [orgtable] => names
  [def] => 
  [db] => x2x
  [catalog] => def
  [max_length] => 7
  [length] => 100
  [charsetnr] => 8
  [flags] => 4097
  [type] => 254
  [decimals] => 0
)
*/

mysqli_result::$field_count

Własność field_count przechowuje wartość oznaczającą liczbę pól otrzymanych w wyniku zapytania SQL.

printf('Liczba pól: %d<br>', $result->field_count);

mysqli_result::$current_field

Własność current_field przechowuje aktualną pozycję pola wskaźnika wyniku (pozycję kursora pola używanego podczas ostatniego wywołania mysqli_fetch_field()).

while ($finfo = $result->fetch_field()) {
  printf("Kolumna %d:n", $result->current_field);
  printf("Nazwa:  %sn", $finfo->name);
  printf("Tabela: %sn", $finfo->table);
}

mysqli_result::data_seek

Metoda data_seek() przenosi wskaźnik do dowolnego wiersza wyniku.

$result->data_seek(2);
print_r($result->fetch_row());

/*
Array
(
    [0] => Oren
    [1] => Aguilar
)
*/

mysqli_result::fetch_field_direct

Metoda fetch_field_direct() informacje o definicji pola z określonego zestawu wyników. Jako argument przyjmuje numer pola (wiersze wyników liczone są od zera).

print_r($result->fetch_field_direct(1));
/*
stdClass Object
(
    [name] => lname
    [orgname] => lname
    [table] => names
    [orgtable] => names
    [def] => 
    [db] => x2x
    [catalog] => def
    [max_length] => 7
    [length] => 100
    [charsetnr] => 8
    [flags] => 4097
    [type] => 254
    [decimals] => 0
)
*/

mysqli_result::fetch_fields

Metoda fetch_fields() zwraca tablicę obiektów reprezentujących pola w wynikach zapytania.

Własności obiektu:

name – nazwa kolumny;
orgname – oryginalna nazwa kolumny (istotne w przypadku stosowania aliasu);
table – nazwa tabeli, z której pochodzi pole;
orgtable – oryginalna nazwa tabeli, z której pochodzi pole (istotne w przypadku stosowania aliasu);
max_length – maksymalna długość pola w zestawie wyników;
length – rozmiar pola w bajtach zgodnie ze strukturą tabeli;
charsetnr – numer zestawu znaków dla pola;
flags – flagi bitowe pola;
type – typ danych;
decimals – liczba miejsc dziesiętnych dla pól typu integer.

Lista flag stosowanych w definicjach kolumn MySQL:

NOT_NULL_FLAG 1;
PRI_KEY_FLAG 2;
UNIQUE_KEY_FLAG 4;
MULTIPLE_KEY_FLAG 8;
BLOB_FLAG 16;
UNSIGNED_FLAG 32;
ZEROFILL_FLAG 64;
BINARY_FLAG 128;
ENUM_FLAG 256;
AUTO_INCREMENT_FLAG 512;
TIMESTAMP_FLAG 1024;
SET_FLAG 2048;
NO_DEFAULT_VALUE_FLAG 4096;
ON_UPDATE_NOW_FLAG 8192;
NUM_FLAG 32768;
PART_KEY_FLAG 16384;
GROUP_FLAG 32768;
UNIQUE_FLAG 65536;
BINCMP_FLAG 131072;
GET_FIXED_FIELDS_FLAG (1 << 18);
FIELD_IN_PART_FUNC_FLAG (1 << 19);
FIELD_IN_ADD_INDEX (1 << 20);
FIELD_IS_RENAMED (1 << 21);
FIELD_FLAGS_STORAGE_MEDIA 22;
FIELD_FLAGS_STORAGE_MEDIA_MASK (3 << FIELD_FLAGS_STORAGE_MEDIA);
FIELD_FLAGS_COLUMN_FORMAT 24;
FIELD_FLAGS_COLUMN_FORMAT_MASK (3 << FIELD_FLAGS_COLUMN_FORMAT);
FIELD_IS_DROPPED (1 << 26);
EXPLICIT_NULL_FLAG (1 << 27);
FIELD_IS_MARKED (1 << 28);
NOT_SECONDARY_FLAG (1 << 29);
FIELD_IS_INVISIBLE (1 << 30).

print_r($result->fetch_fields());

/*
Array
(
    [0] => stdClass Object
        (
            [name] => fname
            [orgname] => fname
            [table] => names
            [orgtable] => names
            [def] => 
            [db] => x2x
            [catalog] => def
            [max_length] => 6
            [length] => 100
            [charsetnr] => 8
            [flags] => 4097
            [type] => 254
            [decimals] => 0
        )

    [1] => stdClass Object
        (
            [name] => lname
            [orgname] => lname
            [table] => names
            [orgtable] => names
            [def] => 
            [db] => x2x
            [catalog] => def
            [max_length] => 7
            [length] => 100
            [charsetnr] => 8
            [flags] => 4097
            [type] => 254
            [decimals] => 0
        )

)
*/

mysqli_result::field_seek

Metoda field_seek() ustawia wskaźnik wyniku na określone pole, jako argument pobiera numer pola, pola liczone są od zera.

$result->field_seek(1);
echo $result->fetch_field()->name; // lname

mysqli_result::free

Metody free(), close() oraz free_result() działają w ten sam sposób, zwalniają pamięć związaną z wynikiem. W poniższym przykładzie zostały zakomentowane, ponieważ po wywołaniu pierwszej z nich zbiór wyników przestaje istnieć i kolejne próby zwolnienia pamięci generują tylko ostrzeżenia (w szkieletowym skrypcie pod miejscem na kod przykładu wywołano metodę close()).

/*
$result->free();
$result->close();
$result->free_result();
*/

mysqli_result::$lengths

Własność lengths przechowuje w formie tablicy długości kolumn bieżącego wiersza w zestawie wyników.

$row = $result->fetch_row();
foreach ($result->lengths as $i => $val) {
  printf("Pole %d ma długość %2dn", $i+1, $val);
}

/*
Pole 1 ma długość  4
Pole 2 ma długość  7
*/