Uzyskiwanie dostępu do baz danych SQL Server przy pomocy PHP .png "Udostępnij na: Facebook")
Autor: Brian Swan
Opublikowano: 29 stycznia 2009
Zawartość strony
Streszczenie: Sterownik SQL Server 2005 Driver for PHP to wspierane przez firmę Microsoft rozszerzenie PHP 5, które zapewnia dostęp do danych SQL Server 2005 oraz SQL Server 2008.
Rozszerzenie zawiera interfejs służący do uzyskiwania dostępu do wszystkich edycji SQL Server 2005 oraz SQL Server 2008. Interfejs API SQL Server 2005 Driver for PHP oferuje kompleksowy mechanizm uzyskiwania dostępu do danych z wykorzystaniem PHP, a także wsparcie dla wielu dodatkowych funkcji m.in. uwierzytelniania systemu Windows, transakcji, powiązywania parametrów, przesyłania strumieniowego, dostępu do metadanych, puli połączeń czy obsługi błędów.
Niniejszy dokument prezentuje metody wykorzystania wybranych funkcji, dokonując szczegółowej analizy fragmentów przykładowej aplikacji wchodzącej w skład dokumentacji produktu SQL Server 2005 Driver for PHP w MSDN.
W tym dokumencie przyjęto założenie, że czytelnik umie programować w języku PHP, posiada komputer spełniający wymagania systemowe konieczne do zastosowania sterownika oraz zainstalował przykładową bazę danych AdventureWorks pobraną z witryny CodePlex.
Wprowadzenie
Sterownik Microsoft SQL Server 2005 Driver for PHP umożliwia programistom PHP uzyskiwanie dostępu do danych, które znajdują się w bazach danych SQL Server 2005 oraz SQL Server 2008. Sterownik oferuje wsparcie dla metod uwierzytelniania systemu Windows oraz SQL Server, transakcji, powiązywania parametrów, przesyłania strumieniowego, dostępu do metadanych, puli połączeń oraz obsługi błędów.
Niniejszy dokument ma na celu zaprezentowanie procesu ładowania i konfigurowania sterownika oraz omówienie metod stosowania wybranych funkcji. Do zademonstrowania scenariuszy programistycznych wykorzystane zostaną fragmenty przykładowej aplikacji, która wchodzi w skład dokumentacji produktu.
Więcej informacji na temat pełnej listy możliwości i funkcji sterownika znaleźć można w artykule API Reference w dokumentacji produktu SQL Server 2005 Driver for PHP w MSDN. Wszystkie funkcje sterownika charakteryzują się przedrostkiem sqlsrv.
Rozwiązanie SQL Server Driver for PHP do obsługi niskopoziomowej komunikacji z serwerem SQL Server wykorzystuje sterownik Microsoft SQL Server 2005 ODBC Driver.
W konsekwencji sterownik ten jest wspierany jedynie w systemach Windows. Firma Microsoft oferuje standardowe wsparcie dla tego sterownika. Jednak mimo iż jego kod źródłowy został udostępniony w witrynie codeplex.com, wspierana jest jedynie podpisana wersja sterownika pobrana z witryny MSDN.
Ładowanie sterownika
Sterownik SQL Server 2005 Driver for PHP można pobrać z Centrum pobierania Microsoft. Dostępne są dwa pliki .dll: php_sqlsrv.dll oraz php_sqlsrv_ts.dll. Pliki te zawierają odpowiednio wersję non-thread-safe sterownika (nieprzystosowaną do pracy w środowisku wielowątkowym) oraz wersję thread-safe (bezpieczną w środowisku wielowątkowym).
Procedura ładowania sterownika SQL Server 2005 Driver for PHP przypomina ładowanie dowolnego innego rozszerzenia PHP:
- Umieszczamy plik rozszerzenia (php_sqlsrv.dll lub php_sqlsrv_ts.dll) w katalogu rozszerzeń PHP. W przypadku uruchamiania wersji PHP, która nie jest przystosowana do pracy w środowisku wielowątkowym (php5.dll), używamy wersji non-thread-safe sterownika (php_sqlsrv.dll). Natomiast w przypadku uruchamiania wersji PHP o bezpiecznych wątkach (php5ts.dll) stosujemy wersję thread-safe (php_sqlsrv_ts.dll).
Modyfikujemy plik php.ini, dołączając do niego rozszerzenie.
W zależności od tego, którą wersję sterownika chcemy załadować (non-thread-safe bądź thread-safe), do sekcji Dynamic Extensions pliku php.ini dodajemy jedną z poniższych linii:
extension=php_sqlsrv.dll
-lub-
extension=php_sqlsrv_ts.dll
Rysunek 1 prezentuje bardziej szczegółowe informacje.
- Restartujemy serwer sieci Web.
Dodatkowe informacje zawiera artykuł Loading the Driver znajdujący się w dokumentacji produktu.
Konfiguracja sterownika
Sterownik SQL Server 2005 Driver for PHP posiada trzy opcje konfiguracyjne:
LogSubsystems
Służy do włączania lub wyłączania mechanizmu rejestrowania podsystemów. Domyślne ustawienie to SQLSRV_LOG_SYSTEM_OFF (rejestrowanie jest domyślnie wyłączone).
LogSeverity
Służy do określania, co chcemy przechwytywać po włączeniu mechanizmu rejestrowania. Domyślne ustawienie to SQLSRV_LOG_SEVERITY_ERROR (domyślnie po włączeniu mechanizmu rejestrowania przechwytywane są jedynie błędy).
WarningsReturnAsErrors
Domyślnie sterownik SQL Server 2005 Driver for PHP traktuje ostrzeżenia generowane przez funkcje sqlsrv jak błędy. Opcja WarningsReturnAsErrors pozwala zmienić to zachowanie. Domyślne ustawienie tej opcji to true (1).
Uwaga Istnieją wyjątki od tej reguły. Na przykład ostrzeżenie wygenerowane w wyniku zmiany kontekstu bazy danych nie jest traktowane jako błąd.
Dodatkowe informacje na ten temat tych opcji i ustawień zawiera artykuł Configuring the Driver znajdujący się w dokumentacji produktu.
Wartości dla tej opcji konfiguracyjnej można ustawiać w pliku php.ini lub w skrypcie PHP przy pomocy funkcji sqlsrv_configure. Poniższy rysunek prezentuje sekcję Dynamic Extensions pliku php.ini zmodyfikowaną tak, aby ładowana była wersja thread-safe sterownika, rejestrowana była aktywność wszystkich podsystemów oraz wszystkie zdarzenia (błędy, ostrzeżenia i powiadomienia), a mechanizm WarningsReturnAsErrors pozostał wyłączony.
.jpg)
Rysunek 1: Sekcja Dynamic Extensions pliku php.ini.
Dodatkowe informacje na ten temat sposobu modyfikowania domyślnych ustawień zawierają artykuły Logging Activity oraz How to: Configure Error and Warning Handling znajdujące się w dokumentacji produktu.
Jedna z metod pozwalających na upewnienie się, że sterownik jest załadowany oraz sprawdzenie ustawień konfiguracyjnych polega na uruchomieniu skryptu, który wywołuje funkcję phpinfo(). Aby osiągnąć ten cel, postępujemy zgodnie z poniższą instrukcją:
Otwieramy plik tekstowy i wklejamy do niego następujący kod:
<?php phpinfo(); ?>
- Zapisujemy plik pod nazwą info.php w katalogu głównym serwera sieci Web.
- Otwieramy przeglądarkę oraz stronę http://localhost/info.php.
- Odnajdujemy sekcję sqlsrv znajdującą się w dolnej części strony wynikowej.
Poniższy rysunek prezentuje sekcję sqlsrv strony phpinfo(). Dane wynikowe świadczą o tym, że sterownik jest załadowany, a ustawienia konfiguracyjne mają wartości domyślne.
.jpg)
Rysunek 2: Sekcja sqlsrv strony phpinfo().
Tworzenie połączenia
Funkcja sqlsrv_connect służy do nawiązania połączenia z serwerem. Zaprezentowany poniżej kod (pochodzący z przykładowej aplikacji wchodzącej w skład dokumentacji produktu) służy do nawiązania połączenia z lokalnym serwerem oraz ustawienia bazy danych AdventureWorks:
$serverName = "(local)";
$connectionOptions = array("Database"=>"AdventureWorks");
/* Łączenie przy użyciu uwierzytelniania systemu Windows. */
$conn = sqlsrv_connect( $serverName, $connectionOptions);
if( $conn === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
Domyślnie funkcja sqlsrv_connect nawiązuje połączenie przy pomocy uwierzytelniania systemu Windows. W większości scenariuszy oznacza to, że do połączenia się z serwerem wykorzystywana jest tożsamość procesu serwera sieci Web lub tożsamość wątku (jeśli serwer sieci Web wykorzystuje personifikację), a nie tożsamość użytkownika końcowego.
Funkcja sqlsrv_connect akceptuje dwa parametry: $serverName oraz $connectionOptions (opcjonalny).
$serverName – Jest to obowiązkowy parametr służący do określenia nazwy serwera, z którym chcemy się połączyć. W powyższym kodzie nawiązywane było połączenie z lokalnym serwerem. Ten parametr można wykorzystać również do określania instancji SQL Server lub numeru portu. Na przykład:
$serverName = "myServer\instanceName";
-lub-
$serverName = "myServer, 1521";
- $connectionOptions - Jest to opcjonalny parametr stanowiący tablicę par klucz-wartość, które służą do określania opcji połączenia. W tym przykładzie skonfigurowana została baza danych AdventureWorks. Inne opcje to między innymi ConnectionPooling, Encrypt, UID oraz PWD. Dodatkowe informacje zawiera artykuł sqlsrv_connect znajdujący się w dokumentacji produktu.
Uwaga Aby zalogować się na serwerze przy użyciu uwierzytelniania SQL Server, należy skonfigurować opcje UID oraz PWD w parametrze $connectionOptions.
Dodatkowe informacje na ten temat tworzenia połączenia zawiera artykuł Connecting to the Server, który znaleźć można w dokumentacji produktu.
Uwaga Funkcja FormatErrors, która została zaprezentowana w niniejszym przykładzie, stanowi niestandardową funkcję służącą do formatowania danych wyjściowych błędu. Zostanie ona opisana w dalszej części tego artykułu zatytułowanej Obsługa błędów i ostrzeżeń.
Pule połączeń
Sterownik SQL Server 2005 Driver for PHP został zaprojektowany tak, aby wykorzystywać obsługę puli połączeń ODBC. Domyślnie pula połączeń jest włączona.
Po połączeniu się z serwerem sterownik próbuje wykorzystać połączenie z puli. Jeśli równoważne połączenie nie zostanie odnalezione, tworzone jest nowe połączenie, które zostaje następnie dodane do puli. Sterownik określa, czy połączenia są równoważne, porównując ciągi połączeń. Wywołanie funkcji sqlsrv_close dla połączenia powoduje zwrócenie go do puli. Jednak jeśli połączenie zostało stworzone z wykorzystaniem atrybutu ConnectionPooling o wartości false (patrz: część artykułu zatytułowana Tworzenie połączenia), wywołanie funkcji sqlsrv_close powoduje jego zamknięcie.
Uwaga Sterownik zleca serwerowi zresetowanie połączenia przed pierwszym wykonaniem kwerendy z wykorzystaniem połączenia pobranego z puli. Zresetowanie połączenia powoduje przywrócenie jego oryginalnego stanu m.in. usunięcie wszelkich tymczasowych obiektów oraz wycofanie oczekujących transakcji.
Dodatkowe informacje zawiera artykuł Connection Pooling znajdujący się w dokumentacji produktu.
Wykonywanie kwerend
Sterownik SQL Server 2005 Driver for PHP oferuje dwa sposoby wykonywania kwerend: funkcję sqlsrv_query lub kombinację funkcji sqlsrv_prepare oraz sqlsrv_execute.
Funkcja sqlsrv_query przygotowuje i realizuje instrukcję przy użyciu jednego wywołania i najbardziej przydaje się do jednorazowego wykonywania kwerend. Alternatywna metoda wykonywania kwerend (metoda odpowiednia w przypadku wielokrotnego uruchamiania kwerendy z wykorzystaniem różnych wartości parametrów) stanowi kombinację funkcji sqlsrv_prepare oraz sqlsrv_execute. Metoda ta oddziela fazę przygotowania instrukcji od fazy jej wykonania i składa się z dwóch osobnych wywołań funkcji. Dodatkowe informacje zawiera artykuł Comparing Execution Functions, który znaleźć można w dokumentacji produktu.
Ogólny szablon wykorzystania dowolnej z tych metod wymaga zrealizowania następujących zadań przed wywołaniem funkcji sqlsrv_query lub sqlsrv_prepare / sqlsrv_execute:
- Nawiązania połączenia z serwerem (patrz: część artykułu zatytułowana Tworzenie połączenia)
- Zdefiniowania instrukcji Transact-SQL
- Dostarczenia tablicy wartości parametrów (konieczne jedynie w przypadku sparametryzowanych kwerend)
- Ustawienia opcji połączenia (opcjonalnie)
Następujący kod (pochodzący z przykładowej aplikacji znajdującej się w dokumentacji produktu) demonstruje zastosowanie funkcji sqlsrv_query:
$tsql = "SELECT ProductID, Name, Color, Size, ListPrice
FROM Production.Product
WHERE Name LIKE '%' + ? + '%' AND ListPrice > 0.0";
$params = array( $_REQUEST['query'] );
$getProducts = sqlsrv_query( $conn, $tsql, $params);
if ( $getProducts === false)
{ die( FormatErrors( sqlsrv_errors() ) ); }
Funkcje sqlsrv_query oraz sqlsrv_prepare akceptują cztery parametry: $conn, $tsql, $params (opcjonalny) oraz $options (opcjonalny, niewykorzystany w tym przykładzie).
- $conn – Wymagany parametr stanowi zasób połączenia PHP stworzony przy użyciu funkcji sqlsrv_connect (patrz: część artykułu zatytułowana Tworzenie połączenia).
- $tsql – Wymagany parametr zawiera ciąg, który definiuje kwerendę Transact-SQL. Znaki zapytania (?) pełnią rolę symboli zastępczych parametrów.
$params – Opcjonalny parametr stanowi tablicę wartości, które odpowiadają (w kolejności) symbolom zastępczym parametrów (znakom zapytania) w kwerendzie zdefiniowanej przy pomocy parametru $tsql. Każda z wartości w tablicy $params może stanowić wartość literalną (np. 5), zmienną PHP (np. $myVar) lub tablicę o następującej strukturze:
array($value [, $direction [, $phpType [, $sqlType]]])
Powyższa tablica służy do określenia wartości parametru, jego kierunku (w przypadku gdy parametr jest przekazywany do procedury składowanej), typu PHP oraz typu SQL Server wartości przesyłanej na serwer. Dodatkowe informacji na temat tej tablicy zawiera część artykułu zatytułowana Przesyłanie obrazów na serwer. Aby dowiedzieć się więcej, warto zajrzeć do artykułów Using Directional Parameters, How to: Send Data as a Stream oraz How to: Specify SQL Server Data Types znajdujących się w dokumentacji produktu.
- $options – Opcjonalny parametr (niezademonstrowany w tym przykładzie) stanowi tablicę asocjacyjną, która służy do ustawiania właściwości kwerendy. Wspierane są dwa klucze: QueryTimeout oraz SendStreamParamsAtExec. Klucz QueryTimeout ustawia wyrażony w sekundach maksymalny dopuszczalny czas działania kwerendy. Klucz SendStreamParamsAtExec określa, czy wszystkie dane strumieniowe mają być przesyłane w czasie wykonania kwerendy lub czy do ich przesłania konieczne są kolejne wywołania funkcji sqlsrv_send_stream_data. Dodatkowe informacje zawiera artykuł How to: Send Data as a Stream.
Pobieranie danych z serwera
Ogólna procedura pobierania danych przy pomocy sterownika SQL Server 2005 Driver for PHP wymaga zdefiniowania i wykonania kwerendy (patrz: część artykułu zatytułowana Wykonywanie kwerend), a następnie zastosowania jednej z trzech możliwości pobierania danych ze zbioru wynikowego:
Uwaga Wymienione funkcje zapewniają jednokierunkowy dostęp do wierszy w zbiorze wynikowym.
Rozważając wybór jednej z powyższych opcji, warto wziąć pod uwagę następujące fakty:
- Funkcje sqlsrv_fetch_array oraz sqlsrv_fetch_object pobierają cały wiersz danych do pamięci skryptu. Takie podejście może być niewskazane, gdy wiersze zawierają dużo danych.
- O typie danych zwracanych przez funkcje sqlsrv_fetch_array oraz sqlsrv_fetch_object decydują domyślne typy danych PHP przypisywane przez sterownik. Dodatkowe informacje zawiera artykuł Default PHP Data Types znajdujący się w dokumentacji produktu.
- Stosując kombinację funkcji sqlsrv_fetch oraz sqlsrv_get_field, można określić typ PHP zwracanych danych, a także zadecydować o przesyłaniu danych w postaci strumienia.
Aby dowiedzieć się więcej na temat możliwości pobierania danych, warto zajrzeć do artykułu Comparing Data Retrieval Functions, który znajduje się w dokumentacji produktu.
Natomiast dodatkowe informacje na ten temat pobierania danych przy użyciu sterownika SQL Server 2005 Driver for PHP zawiera artykuł Retrieving Data znajdujący się w dokumentacji produktu.
Pobieranie danych w postaci tablicy
W tej części artykułu przeanalizujemy fragment kodu przykładowej aplikacji, który służy do pobierania danych w postaci tablicy. Pojedyncze wiersze są pobierane ze zbioru wynikowego przy pomocy funkcji sqlsrv_fetch_array. Każdy kolejny wiersz stanowi tablicę asocjacyjną, która jest następnie przekazywana do niestandardowej funkcji PopulateProductsTable kontynuującej przetwarzanie:
$productCount = 0;
while( $row = sqlsrv_fetch_array( $getProducts, SQLSRV_FETCH_ASSOC))
{
PopulateProductsTable( $row );
$productCount++;
}
Funkcja sqlsrv_fetch_array akceptuje dwa parametry $stmt oraz $fetchType (opcjonalny):
- Parametr $stmt stanowi zasób instrukcji PHP stworzony przy pomocy funkcji sqlsrv_query lub sqlsrv_execute (patrz: część artykułu zatytułowana Wykonywanie kwerend).
- Parametr $fetchType (opcjonalny) stanowi zdefiniowaną przez sterownik stałą, która określa typ zwracanej tablicy: asocjacyjna, numeryczna lub obie. Odpowiadające im stałe to w kolejności: SQLSRV_FETCH_ASSOC, SQLSRV_FETCH_NUMERIC oraz SQLSRV_FETCH_BOTH. Domyślnie zwracana jest tablica zawierająca oba typy indeksów.
Pobieranie obrazów
W tej sekcji przeanalizujemy kod przykładowej aplikacji, który służy do pobierania obrazu z serwera. Zaprezentowany fragment kodu odpowiada za: wykonanie kwerendy pobierającej obraz z serwera, zdefiniowanie metody akceptującej binarny strumień danych oraz umieszczenie danych na stronie sieci Web przy pomocy funkcji PHP fpassthru:
/* Pobranie obrazu produktu dla danego ID produktu. */
$tsql = "SELECT LargePhoto
FROM Production.ProductPhoto AS p
JOIN Production.ProductProductPhoto AS q
ON p.ProductPhotoID = q.ProductPhotoID
WHERE ProductID = ?";
$params = array($_REQUEST['productId']);
/* Wykonanie kwerendy. */
$stmt = sqlsrv_query($conn, $tsql, $params);
if( $stmt === false )
{
echo "Error in statement execution.</br>";
die( print_r( sqlsrv_errors(), true));
}
/* Pobranie obrazu jako strumienia binarnego. */
$fieldIndex = 0;
$getAsType = SQLSRV_PHPTYPE_STREAM(SQLSRV_ENC_BINARY);
if ( sqlsrv_fetch( $stmt ) )
{
$image = sqlsrv_get_field( $stmt, $fieldIndex, $getAsType);
fpassthru($image);
}
else
{
echo "Error in retrieving data.</br>";
die(print_r( sqlsrv_errors(), true));
}
Powyższy kod definiuje sparametryzowaną kwerendę Transact-SQL ($tsql), określa wartość parametru ($params) i wykonuje kwerendę przy pomocy funkcji sqlsrv_query (patrz: część artykułu zatytułowana Wykonywanie kwerend). Zbiór wynikowy jest przetwarzany przy użyciu funkcji sqlsrv_fetch, która przygotowuje do odczytu kolejny wiersz w zbiorze wynikowym. Dalej następuje wywoływanie funkcji sqlsrv_get_field, która służy do odczytywania pojedynczego pola z aktywnego wiersza. Funkcja sqlsrv_fetch pobiera jeden parametr (w tym przykładzie $stmt), który stanowi zasób PHP stworzony przy pomocy funkcji sqlsrv_query lub sqlsrv_execute. Funkcja sqlsrv_get_field akceptuje trzy parametry: $stmt, $fieldIndex oraz $getAsType (opcjonalny):
- Parametr $stmt stanowi zasób PHP odpowiadający wykonywanej instrukcji. Następny (lub pierwszy) wiersz jest udostępniany funkcji sqlsrv_get_field poprzez przekazanie parametru $stmt do funkcji sqlsrv_fetch.
- Parametr $fieldIndex określa indeks pola do pobrania. Numeracja indeksów rozpoczyna się od zera.
- Parametr $getAsType (opcjonalny) służy do określania typu PHP zwracanych danych (oraz typu kodowania, jak w tym przypadku). W przypadku niedostarczenia tego parametru o typie danych decyduje domyślny typ PHP. Dodatkowe informacje zawiera artykuł Default PHP Data Types znajdujący się w dokumentacji produktu.
Natomiast aby dowiedzieć się więcej na temat pobierania obrazów oraz dużych/binarnych danych, warto zajrzeć do artykułu Retrieving Data as a Stream znajdującego się w dokumentacji produktu.
Połączenie funkcji sqlsrv_fetch oraz sqlsrv_get_field może posłużyć nie tylko do pobierania danych w postaci strumienia, ale także określania typu PHP zwracanych danych. Dodatkowe informacje zawiera artykuł How to: Specify PHP Data Types znajdujący się w dokumentacji produktu.
Przesyłanie danych na serwer
Ogólna procedura przesyłania danych na serwer obejmuje wykonanie odpowiedniej kwerendy Transact-SQL (takiej jak kwerenda UPDATE lub INSERT) przy pomocy funkcji sqlsrv_query lub kombinacji funkcji sqlsrv_prepare oraz sqlsrv_execute (patrz: część artykułu zatytułowana Wykonywanie kwerend). Na przykład zaprezentowany poniżej kod (pochodzący z przykładowej aplikacji znajdującej się w dokumentacji produktu) służy do przesłania na serwer recenzji produktu przy pomocy kombinacji funkcji sqlsrv_prepare oraz sqlsrv_execute:
/*Dołączenie recenzji, aby mogła ona zostać otworzona w postaci strumienia.*/
$comments = "data://text/plain,".$_REQUEST['comments'];
$stream = fopen( $comments, "r" );
$tsql = "INSERT INTO Production.ProductReview (ProductID,
ReviewerName,
ReviewDate,
EmailAddress,
Rating,
Comments)
VALUES (?,?,?,?,?,?)";
$params = array($_REQUEST['productid'],
$_REQUEST['name'],
date("Y-m-d"),
$_REQUEST['email'],
$_REQUEST['rating'],
$stream);
/* Przygotowanie oraz wykonanie instrukcji. */
$insertReview = sqlsrv_prepare($conn, $tsql, $params);
if( $insertReview === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
/* Domyślnie wszystkie dane strumienia są przesyłane w czasie wykonania kwerendy */
if( sqlsrv_execute($insertReview) === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
Funkcja sqlsrv_prepare ma takie same parametry jak funkcja sqlsrv_query (patrz: część artykułu zatytułowana Wykonywanie kwerend). Funkcja sqlsrv_execute pobiera jeden parametr (w tym przykładzie $insertReview), który stanowi zasób PHP określający instrukcję przygotowaną do wykonania.
Uwaga Kwerenda wykorzystana w tym przykładzie mogła zostać uruchomiona przy pomocy funkcji sqlsrv_query. Zasadniczo zaleca się wykonywanie pojedynczych kwerend przy pomocy funkcji sqlsrv_query. Jednak w tym przykładzie zastosowano funkcje sqlsrv_prepare oraz sqlsrv_execute w celu zaprezentowania wspólnego wykorzystania tych funkcji).
Niniejszy przykład demonstruje możliwości sterownika w zakresie obsługi strumieni. Komentarze klienta ($comments) są otwierane w postaci strumienia tekstowego ($stream), który stanowi parametr kwerendy. Domyślnie wszystkie dane strumienia są przesyłane na serwer w momencie wykonania kwerendy. Jednak sterownik oferuje również opcję, która umożliwia przesyłanie na serwer do 8KB danych strumienia jednocześnie. Więcej informacji znaleźć można w zaprezentowanym poniżej akapicie zatytułowanym Przesyłanie obrazów na serwer lub artykule How to: Send Data as a Stream znajdującym się w dokumentacji produktu.
Dodatkowe informacje na ten temat przesyłania danych na serwer przy pomocy sterownika SQL Server 2005 Driver for PHP zawiera artykuł Updating Data znajdujący się w dokumentacji produktu.
Przesyłanie obrazów na serwer
W tej sekcji przeanalizujemy fragment kodu przykładowej aplikacji, który odpowiada za przesłanie obrazu na serwer w postaci strumienia binarnego. Następujący kod otwiera obraz w postaci strumienia, a następnie przesyła plik na serwer (we fragmentach o maksymalnym rozmiarze 8KB):
/*Dołączenie recenzji, aby mogła ona zostać otworzona w postaci strumienia.*/
$comments = "data://text/plain,".$_REQUEST['comments'];
$stream = fopen( $comments, "r" );
$tsql = "INSERT INTO Production.ProductReview (ProductID,
ReviewerName,
ReviewDate,
EmailAddress,
Rating,
Comments)
VALUES (?,?,?,?,?,?)";
$params = array($_REQUEST['productid'],
$_REQUEST['name'],
date("Y-m-d"),
$_REQUEST['email'],
$_REQUEST['rating'],
$stream);
/* Przygotowanie oraz wykonanie instrukcji. */
$insertReview = sqlsrv_prepare($conn, $tsql, $params);
if( $insertReview === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
/* Domyślnie wszystkie dane strumienia są przesyłane w czasie wykonania kwerendy */
if( sqlsrv_execute($insertReview) === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
Jak wspomniano w poprzednim przykładzie, ogólna procedura przesyłania danych na serwer obejmuje wykonanie odpowiedniej kwerendy Transact-SQL (takiej jak instrukcja UPDATE lub INSERT). Ten przykład różni się od poprzedniego w następujący sposób:
Typy są określane w tablicy $params. Typ PHP musi zostać zdefiniowany, aby sterownik zinterpretował dane jako strumień binarny. Natomiast dzięki określeniu typu SQL Server serwer może odpowiednio zinterpretować przychodzące dane.
Dodatkowe informacje znaleźć można w artykułach How to: Specify PHP Data Types oraz How to: Specify SQL Server Data Types znajdujących się w dokumentacji produktu.
- Parametr $options jest wykorzystywany podczas wywoływania funkcji sqlsrv_prepare. Domyślne podejście, które zakłada przesyłanie wszystkich danych na serwer w czasie wykonania kwerendy, zostaje wyłączone poprzez ustawienie wartości 0 w kluczu "SendStreamParamsAtExec" w parametrze $options. Gdy mechanizm ten jest wyłączony, aby przesłać dane strumienia na serwer, należy po wykonaniu kwerendy wywołać funkcję sqlsrv_send_stream data (patrz następny podpunkt).
- Funkcja sqlsrv_send_stream data służy do przesyłania danych na serwer w pakietach o maksymalnym rozmiarze 8KB. Wyłączenie domyślnego podejścia polegającego na przesyłaniu wszystkich danych strumienia naraz oraz zastosowanie funkcji sqlsrv_send_stream_data do przesyłania danych strumienia zwiększa możliwości aplikacji. Na przykład pozwala na prezentowanie użytkownikom paska postępu w trakcie pobierania dużego obrazu.
Przechodzenie przez grupy zbiorów wynikowych
Sterownik SQL Server 2005 Driver for PHP oferuje funkcję sqlsrv_next_result, która służy do jednokierunkowego przechodzenia po zbiorze wynikowym zwróconym przez kwerendy wsadowe lub procedury składowane. Ta funkcja przygotowuje do odczytu kolejny zbiór wynikowy, licznik wierszy lub parametr wyjściowy aktywnej instrukcji.
Poniższy kod demonstruje, w jaki sposób można wykorzystać funkcję sqlsrv_next_result do przemieszczania się po zbiorze wynikowym. Kod został pobrany z przykładowej aplikacji znajdującej się w dokumentacji produktu i następuje tuż po fragmencie kodu zaprezentowanym w poprzednim przykładzie. Instrukcja $uploadPic odpowiada kwerendzie wsadowej w poprzednim przykładzie. Zaprezentowany kod przechodzi do kolejnego wyniku w tej instrukcji i wykorzystuje pobraną wartość do wykonania kwerendy, która powiązuje nowy identyfikator ProductPhotoID z identyfikatorem ProductID:
/*Pominięcie otwartego (pierwszego) zbioru wynikowego (rows affected). */
$next_result = sqlsrv_next_result($uploadPic);
if( $next_result === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
/* Przejście do następnego wiersza w zbiorze wynikowym. */
if( sqlsrv_fetch($uploadPic) === false)
{ die( FormatErrors( sqlsrv_errors() ) ); }
/* Pobieranie pierwszego pola – identyfikatora z instrukcji INSERT. */
$photoID = sqlsrv_get_field($uploadPic, 0);
/* Pozwiązywanie nowego photoID z productID. */
$tsql = "UPDATE Production.ProductProductPhoto
SET ProductPhotoID = ?
WHERE ProductID = ?";
$params = array($photoID, $_REQUEST['productid']);
if( sqlsrv_query($conn, $tsql, $params) === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
Wymagany parametr funkcji sqlsrv_next_result to zasób PHP odpowiadający aktywnej instrukcji. Nie trzeba wywoływać funkcji sqlsrv_next_result, aby uzyskać dostęp do pierwszego wiersza w zbiorze wynikowym. Funkcja zwraca null, gdy zbiór wynikowy zwrócony przez instrukcję nie zawiera już żadnych wierszy.
Dodatkowe informacje na temat przetwarzania zbioru wynikowego zawierają artykuły How to: Work with Multiple Result Sets oraz How to: Detect Empty Result Sets znajdujące się w dokumentacji produktu.
Obsługa błędów i ostrzeżeń
Sterownik SQL Server 2005 Driver for PHP oferuje funkcję sqlsrv_errors, która służy do pobierania informacji o błędach oraz ostrzeżeniach. Jeśli w czasie wykonywania dowolnej funkcji sqlsrv pojawi się błąd, funkcja zwróci wartość false, a szczegółowe informacje o błędzie zostaną dodane do kolekcji błędów. Funkcja sqlsrv_errors zapewnia dostęp do tej kolekcji.
Uwaga Domyślnie ostrzeżenia są traktowane jak błędy, jednak istnieją pewne wyjątki, a mianowicie ostrzeżenia odpowiadające wartościom SQLSTATE 01000, 01001, 01003 oraz 01S02. Domyślne zachowanie można zmodyfikować tak, aby ostrzeżenia nie były traktowane jak błędy. Dodatkowe informacje znaleźć można w artykule How to: Configure Error and Warning Handling znajdującym się w dokumentacji produktu oraz w sekcji zatytułowanej Konfigurowanie sterownika.
Ogólna procedura wykorzystania funkcji sqlsrv_errors polega na sprawdzeniu wartości zwracanej przez funkcję sqlsrv, a następnie odpowiednim obsłużeniu błędów. Poniższy kod stanowiący fragment przykładowej aplikacji, która schodzi w skład dokumentacji produktu, demonstruje zastosowanie tej procedury:
if( sqlsrv_execute($insertReview) === false )
{ die( FormatErrors( sqlsrv_errors() ) ); }
Funkcja sqlsrv_errors zwraca kolekcję tablic, po jednej tablicy dla każdego napotkanego błędu. Każda tablica zawiera szczegółowe informacje o błędzie. Niestandardowa funkcja FormatErrors znajdująca się w przykładowej aplikacji dokonuje iteracji po kolekcji tablic i wyświetla po prostu informacje o błędach:
function FormatErrors( $errors )
{
/* Wyświetlanie błędów. */
echo "Error information: <br/>";
foreach ( $errors as $error )
{
echo "SQLSTATE: ".$error['SQLSTATE']."<br/>";
echo "Code: ".$error['code']."<br/>";
echo "Message: ".$error['message']."<br/>";
}
}
Do analizowania w PHP wartości zwracanej przez funkcję sqlsrv najlepiej jest użyć operatora potrójnego znaku równości (===). Wynika to z tego, że wszystkie funkcje sqlsrv zwracają wartość false w przypadku wystąpienia błędu i w związku z tym warto wykorzystać potrójny operator równości w celu wymuszenia literalnego porównania. Na przykład funkcja sqlsrv_fetch może zwrócić wartość null, gdy zbiór wynikowy nie zawiera żadnych dodatkowych wierszy. W tej sytuacji zastosowanie podwójnego operatora równości (==) w celu sprawdzenia błędu ($result == false) spowodowałoby zwrócenie wartości true i niepożądane działanie programu.
Dodatkowe informacje zawiera artykuł Handling Errors and Warnings znajdujący się w dokumentacji produktu.
Zasoby
Dostępne są następujące materiały, które mogą pomóc w rozwijaniu aplikacji z wykorzystaniem sterownika SQL Server 2005 Driver for PHP:
Wnioski
Sterownik SQL Server 2005 Driver for PHP zapewnia szybki i solidny dostęp do danych SQL Server z wykorzystaniem języka PHP. Sterownik korzysta z technologii Microsoft oraz PHP (takich jak uwierzytelnianie systemu Windows, pule połączeń ODBC oraz strumienie PHP), umożliwiając tworzenie zaawansowanych aplikacji PHP.
Dodatkowe informacje: